ApplicationGroup

k8s.gitops.nyl/v1

Kubernetes GitOps Resources · Download JSON Schema · Usage guide

Selects Kubernetes Releases and defines their Argo CD Application, project, and namespace policies.

Literal metadata labels participate in target selection; the spec is rendered afterward. This is compiler configuration, not a workload manifest.

When needed

Required to select Release entry files and generate their workload Applications in Kubernetes GitOps.

If omitted

Nyl does not infer groups from directories or Release files. Without a selected, enabled ApplicationGroup, a target emits no workload Applications. Direct file rendering does not require an ApplicationGroup.

Example

apiVersion: k8s.gitops.nyl/v1
kind: ApplicationGroup
metadata:
  name: workloads
spec:
  applicationNamespace: argocd
  destinationNamespace: workloads
  projectTemplate:
    destinations:
      - namespace: workloads
        server: https://kubernetes.default.svc
  source:
    path: applications/workloads

Fields

Required means required within the containing object. Optional and nullable are distinct; contextual defaults and requirements are explained with each field.

Unknown fields are rejected.

apiVersion

Required · string

API group and version defining this resource.

const: "k8s.gitops.nyl/v1"

kind

Required · string

Resource kind within the API group.

const: "ApplicationGroup"

metadata

Required · object

Resource identity and metadata.

Unknown fields are rejected.

metadata.labels

Optional · object

Literal labels used for organization and target selection.

metadata.labels[key]

Optional · string

metadata.name

Required · string

Project-local identity, validated by the resource kind; remains static during discovery.

spec

Required · object

Configuration for this resource.

Unknown fields are rejected.

Choose exactly one variant:

• projectRef — Uses the named AppProjectDefinition, so the project can be shared between groups or managed outside Nyl.
• projectTemplate — Generates an AppProject for this group from the declared AppProject fields; omitted fields admit only what the group deploys.
• Neither — Generates an AppProject named after the group that admits only what it deploys: the target publication repository, the target Cluster with the group’s Release namespaces, and the resource kinds it renders.

spec.annotations

Optional · object

Annotations added to generated Applications.

spec.annotations[key]

Optional · string

spec.applicationDeletionPolicy

Optional · string

Argo CD Application finalizer policy: foreground cascade, background cascade, or orphan workloads.

default: "Foreground"

Allowed values:

Value	Meaning
"Foreground"	Cascade deletion in the foreground using the Argo CD resources finalizer.
"Background"	Cascade deletion in the background using the Argo CD background finalizer.
"Orphan"	Omit the finalizer and leave workload resources in place.

spec.applicationNameTemplate

Optional · string or null

Generated workload Application name, as a template value expanded once per Release. It must contain at least one ${ expression }, evaluated with the target context plus release, the rendered Release; $${ writes a literal ${, and all other text, including {{ … }}, is literal. Defaults to the Release name; use target-qualified names such as ${ target.metadata.name }-${ release.metadata.name } when targets share an Argo CD namespace.

spec.applicationNamespace

Required · string

Namespace containing generated Argo CD Applications.

spec.destinationNamespace

Optional · string or null

Workload namespace override. Defaults to each Release namespace.

spec.enabled

Optional · boolean

Whether to render this selected group. Evaluated after target selection and may be templated.

default: true

spec.labels

Optional · object

Labels added to generated Applications.

spec.labels[key]

Optional · string

spec.namespace

Optional · object

Namespace creation and deletion policy for workload-owned namespaces.

default: {"create":true,"deletePolicy":"Confirm","prunePolicy":"Confirm"}

Unknown fields are rejected.

spec.namespace.create

Optional · boolean

Synthesize missing destination and additional Namespaces within the owning workload Application.

default: true

spec.namespace.deletePolicy

Optional · string

Namespace deletion policy when the owning Application is deleted.

default: "Confirm"

Allowed values:

Value	Meaning
"Automatic"	Allow pruning or deletion without additional restrictions.
"Confirm"	Require confirmation through the Argo CD Prune or Delete sync option.
"Retain"	Set the Argo CD Prune or Delete sync option to false.

spec.namespace.prunePolicy

Optional · string

Namespace pruning policy: Automatic, Confirm, or Retain.

default: "Confirm"

Allowed values:

Value	Meaning
"Automatic"	Allow pruning or deletion without additional restrictions.
"Confirm"	Require confirmation through the Argo CD Prune or Delete sync option.
"Retain"	Set the Argo CD Prune or Delete sync option to false.

spec.outputPath

Optional · string or null

Relative output directory beneath the target prefix. Defaults to the group name.

spec.projectRef

Optional · string or null

Project-local AppProjectDefinition identity. Mutually exclusive with projectTemplate; omitting both implies an AppProject named after this group that admits only what the group deploys.

spec.projectTemplate

Optional · object or null

Generated AppProject fields. Mutually exclusive with projectRef; declared fields are kept as written and omitted fields are derived from what the group deploys.

Unknown fields are rejected.

spec.projectTemplate.annotations

Optional · object

Annotations on the generated AppProject.

spec.projectTemplate.annotations[key]

Optional · string

spec.projectTemplate.clusterResourceBlacklist

Optional · array or null

Cluster-scoped resources the project denies.

spec.projectTemplate.clusterResourceBlacklist[]

Required · object

Unknown fields are rejected.

spec.projectTemplate.clusterResourceBlacklist[].group

Required · string

Kubernetes API group pattern, such as apiextensions.k8s.io or *.

spec.projectTemplate.clusterResourceBlacklist[].kind

Required · string

Kubernetes resource kind pattern.

spec.projectTemplate.clusterResourceBlacklist[].name

Optional · string or null

Optional resource name pattern.

spec.projectTemplate.clusterResourceWhitelist

Optional · array or null

Cluster-scoped resources the project admits. Omitted, the cluster-scoped kinds the group renders, including Namespaces Nyl creates for it; a declared list, including [], admits only its patterns plus Namespace permissions for the admitted namespaces when namespace creation is enabled. Deriving a whitelist requires each rendered kind’s scope, from a CRD rendered in the target or the Cluster’s recorded capabilities.

spec.projectTemplate.clusterResourceWhitelist[]

Required · object

Unknown fields are rejected.

spec.projectTemplate.clusterResourceWhitelist[].group

Required · string

Kubernetes API group pattern, such as apiextensions.k8s.io or *.

spec.projectTemplate.clusterResourceWhitelist[].kind

Required · string

Kubernetes resource kind pattern.

spec.projectTemplate.clusterResourceWhitelist[].name

Optional · string or null

Optional resource name pattern.

spec.projectTemplate.description

Optional · string or null

Project description.

spec.projectTemplate.destinationServiceAccounts

Optional · array or null

Service accounts used for sync per destination, as Argo CD spec.destinationServiceAccounts.

spec.projectTemplate.destinationServiceAccounts[]

Any value is allowed.

spec.projectTemplate.destinations

Optional · array or null

Permitted destinations. Omitted, the project admits the target workload Cluster with every effective Release namespace and additional namespace of the group. A declared list must admit every effective Release namespace and additional namespace on the target workload Cluster; a fixed destinationNamespace is added for that Cluster when no entry covers it.

spec.projectTemplate.destinations[]

Required · object

One Argo CD AppProject destination. At least one of server and name is required.

Unknown fields are rejected.

spec.projectTemplate.destinations[].name

Optional · string or null

Argo CD cluster name pattern.

spec.projectTemplate.destinations[].namespace

Required · string

Namespace pattern, such as apps, preview-*, or *.

spec.projectTemplate.destinations[].server

Optional · string or null

Cluster API server URL pattern, such as https://kubernetes.default.svc or *.

spec.projectTemplate.finalizers

Optional · array

Finalizers on the generated AppProject, such as resources-finalizer.argocd.argoproj.io.

spec.projectTemplate.finalizers[]

Required · string

spec.projectTemplate.labels

Optional · object

Labels on the generated AppProject.

spec.projectTemplate.labels[key]

Optional · string

spec.projectTemplate.name

Optional · string or null

Generated AppProject name; defaults to the ApplicationGroup name. Must be unambiguous across targets sharing an Argo CD namespace.

spec.projectTemplate.namespaceResourceBlacklist

Optional · array or null

Namespaced resources the project denies.

spec.projectTemplate.namespaceResourceBlacklist[]

Required · object

Unknown fields are rejected.

spec.projectTemplate.namespaceResourceBlacklist[].group

Required · string

Kubernetes API group pattern, such as apiextensions.k8s.io or *.

spec.projectTemplate.namespaceResourceBlacklist[].kind

Required · string

Kubernetes resource kind pattern.

spec.projectTemplate.namespaceResourceBlacklist[].name

Optional · string or null

Optional resource name pattern.

spec.projectTemplate.namespaceResourceWhitelist

Optional · array or null

Namespaced resources the project admits. Omitted, the namespaced kinds the group renders.

spec.projectTemplate.namespaceResourceWhitelist[]

Required · object

Unknown fields are rejected.

spec.projectTemplate.namespaceResourceWhitelist[].group

Required · string

Kubernetes API group pattern, such as apiextensions.k8s.io or *.

spec.projectTemplate.namespaceResourceWhitelist[].kind

Required · string

Kubernetes resource kind pattern.

spec.projectTemplate.namespaceResourceWhitelist[].name

Optional · string or null

Optional resource name pattern.

spec.projectTemplate.orphanedResources

Optional · any value

Orphaned resource monitoring, as Argo CD spec.orphanedResources.

spec.projectTemplate.permitOnlyProjectScopedClusters

Optional · boolean or null

Whether only clusters scoped to this project are admitted, as Argo CD spec.permitOnlyProjectScopedClusters.

spec.projectTemplate.roles

Optional · array or null

Project roles, as Argo CD spec.roles.

spec.projectTemplate.roles[]

Any value is allowed.

spec.projectTemplate.signatureKeys

Optional · array or null

GnuPG keys required to verify source commits, as Argo CD spec.signatureKeys.

spec.projectTemplate.signatureKeys[]

Any value is allowed.

spec.projectTemplate.sourceNamespaces

Optional · array or null

Namespaces whose Applications may use the project. applicationNamespace is always added.

spec.projectTemplate.sourceNamespaces[]

Required · string

spec.projectTemplate.sourceRepos

Optional · array or null

Permitted source repository URL patterns. Omitted, the project admits the target publication repository.

spec.projectTemplate.sourceRepos[]

Required · string

spec.projectTemplate.syncWindows

Optional · array or null

Sync windows, as Argo CD spec.syncWindows.

spec.projectTemplate.syncWindows[]

Any value is allowed.

spec.releaseCustomization

Optional · object

Limits on per-release Application overrides. Releases cannot expand the generated project or namespace policy.

default: {}

Unknown fields are rejected.

spec.releaseCustomization.allowedPaths

Optional · array

Dotted field globs admitted in Release Application overrides. * matches one segment; ** matches multiple segments. Core ownership fields remain protected.

spec.releaseCustomization.allowedPaths[]

Required · string

spec.releaseCustomization.allowedSyncOptions

Optional · array

Exact allowed values for Release spec.syncPolicy.+syncOptions overrides. Same-key values replace the generated option.

spec.releaseCustomization.allowedSyncOptions[]

Required · string

spec.releaseCustomization.deniedPaths

Optional · array

Dotted field globs forbidden in Release Application overrides. Deny takes precedence over allow.

spec.releaseCustomization.deniedPaths[]

Required · string

spec.sharedNamespaces

Optional · object

Explicit ownership by namespace name. Every consuming group must agree. Kubernetes bootstrap namespaces are externally owned unless explicitly delegated here.

spec.sharedNamespaces[key]

Optional · object

Explicit authorization and ownership for a namespace consumed by more than one generated workload Application.

Unknown fields are rejected.

spec.sharedNamespaces[key].owner

Required · object

The sole owner of a shared Namespace. Release and Dedicated owners identify the responsible ApplicationGroup.

Choose exactly one variant:

Release

Type: object

The selected workload Release owns the Namespace; other workloads must not render its Namespace object.

Unknown fields are rejected.

spec.sharedNamespaces[key].owner.applicationGroup

Required · string

ApplicationGroup owning the Namespace Application or selected workload Release.

spec.sharedNamespaces[key].owner.kind

Required · string

const: "Release"

spec.sharedNamespaces[key].owner.release

Required · string

Release name within the owning ApplicationGroup.

Dedicated

Type: object

Generate a dedicated Namespace Application under the selected group; workloads must not render this Namespace.

Unknown fields are rejected.

spec.sharedNamespaces[key].owner.applicationGroup

Required · string

ApplicationGroup owning the Namespace Application or selected workload Release.

spec.sharedNamespaces[key].owner.kind

Required · string

const: "Dedicated"

External

Type: object

The Namespace is externally owned. Nyl neither synthesizes nor accepts an authored Namespace object.

Unknown fields are rejected.

spec.sharedNamespaces[key].owner.kind

Required · string

const: "External"

spec.source

Optional · object or null

Release source selection. Omission derives applications/<group-name> for central groups or the containing directory for _application-group.yaml.

Unknown fields are rejected.

Choose exactly one variant:

• repositoryRef — Reads Releases from a checkout of the named GitRepository.
• repository — Reads Releases from a checkout of the inline coordinates declared here.
• Neither — Reads Releases from this project, at the declared path.

spec.source.commit

Optional · string or null

Full 40-character lowercase commit ID that is read, refreshed by nyl update source-locks.

spec.source.exclude

Optional · array

Relative file globs removed after inclusion.

spec.source.exclude[]

Required · string

spec.source.include

Optional · array

Relative candidate file globs. Only entries with a literal Release are rendered; attach other files using Release spec.include.

default: ["*.yaml","*.yml"]

spec.source.include[]

Required · string

spec.source.path

Required · string

Path in the repository. In this repository it follows the local path rule: relative to the directory containing nyl.toml, may begin with .. segments, or starts with / to name a path from the Git worktree root, and never leaves the worktree. In a remote repository it is relative to the checkout root, with an optional leading /.

spec.source.recursive

Optional · boolean

Whether source discovery descends into subdirectories.

default: true

spec.source.rendererConfig

Optional · object

Whether remote rendering uses central configuration or the remote project. Remote sessions cannot access secrets or the process environment.

default: {"mode":"Central"}

Unknown fields are rejected.

spec.source.rendererConfig.mode

Optional · string

Central uses platform configuration; Remote loads the remote project and requires a remote source.

default: "Central"

Allowed values:

Value	Meaning
"Central"	Use the central platform project configuration.
"Remote"	Load project configuration from the remote source checkout with restricted inputs.

spec.source.rendererConfig.projectPath

Optional · string or null

Remote project root, relative to the checkout. Defaults to .; valid only in Remote mode and must remain inside the checkout.

spec.source.repository

Optional · object or null

Inline repository coordinates to read from. Mutually exclusive with repositoryRef.

Unknown fields are rejected.

spec.source.repository.repoURL

Required · string

Git read URL. Source checkouts never publish to this repository.

spec.source.repositoryRef

Optional · object or null

Project-local gitops.nyl/v1 GitRepository to read from. Mutually exclusive with inline repository.

Unknown fields are rejected.

spec.source.repositoryRef.name

Required · string

Project-local name of the referenced resource; its kind and API group are determined by the containing field.

spec.source.revision

Optional · string or null

Human-readable branch or tag that nyl update source-locks resolves.

spec.syncPolicy

Optional · object or null

Workload Application sync policy. Generated Applications include apply-only-out-of-sync and server-side apply unless explicitly overridden.

Unknown fields are rejected.

spec.syncPolicy.automated

Optional · object or null

Presence enables automated synchronization unless enabled is false.

Unknown fields are rejected.

spec.syncPolicy.automated.enabled

Optional · boolean or null

Whether automated sync is enabled. Omission enables it when the automated block is present.

spec.syncPolicy.automated.prune

Optional · boolean

Allow Argo CD to prune resources removed from desired manifests.

default: false

spec.syncPolicy.automated.selfHeal

Optional · boolean

Allow Argo CD to repair live drift automatically.

default: false

spec.syncPolicy.syncOptions

Optional · array

Argo CD sync options. Generated Applications add ApplyOutOfSyncOnly=true and ServerSideApply=true unless an option with the same key is supplied.

spec.syncPolicy.syncOptions[]

Required · string