Skip to main content

atmos kubernetes deploy

Run a Kubernetes deployment using Atmos language. deploy is the workflow-friendly alias for applying a stack-configured Kubernetes component, useful when your automation treats Kubernetes resources as deployable services.

atmos kubernetes deploy --help
Configure Kubernetes Components

deploy uses the same stack and atmos.yaml settings as apply, including manifest paths, variables, credentials, hooks, and dependency ordering.

Usage​

atmos kubernetes deploy <component> --stack <stack>
atmos kubernetes deploy --affected --base origin/main --include-dependents

In v1, deploy is an alias of atmos kubernetes apply. It renders the final manifests and applies them through the Kubernetes Go SDK using server-side apply.

Use deploy when you want command language that matches an application deployment workflow. Use apply when you want command language that mirrors Kubernetes API behavior.

Example​

atmos kubernetes deploy argocd -s plat-ue2-dev

Deploy components filtered by tags or labels (composes with --all/--affected to narrow the selected set further):

atmos kubernetes deploy --all --tags production,tier-1
atmos kubernetes deploy --affected --labels cost-center=platform

Deployment repositories (GitOps)​

By default deploy/apply applies the rendered manifests to the cluster. A component can instead publish them to a Git deployment repository (the source-of-truth that Argo CD or Flux reconciles) by declaring delivery targets under provision.targets:

components:
  kubernetes:
    argocd:
      provision:
        default: cluster
        targets:
          cluster:
            kind: kubernetes
          deployment-repo:
            kind: git
            repository: deployments        # references git.repositories.<name>
            path: "clusters/{{ .vars.cluster }}/argocd"
            commit:
              message: "Render {{ .vars.app_name }} for {{ .vars.stage }}"

Selecting the git target renders the manifests once and commits them to the configured repository instead of applying to the cluster:

atmos kubernetes deploy argocd -s plat-ue2-dev --target=deployment-repo

When --target is omitted, provision.default is used, otherwise the cluster. Credentials for cloning and pushing come from Atmos Auth (GitHub STS), so no tokens are stored in the manifests.

File vs. directory delivery (split)​

A git target's path can be either a directory (one file per rendered object) or the exact name of a single output file. Set split on the target to control which:

split: true
path is a directory; every rendered object is written to its own generated filename inside it.
split: false
path is the exact output file; every rendered object is merged into one multi-document YAML file written to that path.
unset (default)

Inferred from path: if the last path segment looks like a manifest filename (matches /\.(ya?ml|json)$/i, e.g. kustomization.yaml), split defaults to false; otherwise it defaults to true, preserving the directory behavior every existing configuration already relies on.

components:
  kubernetes:
    argocd:
      provision:
        targets:
          deployment-repo:
            kind: git
            repository: deployments
            path: "kustomize/overlays/{{ .vars.environment }}/kustomization.yaml"
            # split is omitted here: the path ends in .yaml, so it is inferred
            # as split: false and written as a single file, not a directory.
            commit:
              message: "Render manifests for {{ .vars.environment }}"

See Generating a Kustomize component for GitOps for a complete walkthrough of this pattern.

Flags​

--stack, -s (optional)

Atmos stack. Required when deploying a named component; not required with --affected.

--target (optional)

Provision target to deliver to (a named provision.targets entry, e.g. a git deployment repository). Defaults to provision.default, otherwise the cluster.

--all (optional)

Deploy all Kubernetes components in dependency order.

--affected (optional)

Deploy affected Kubernetes components and their dependencies.
--include-dependents (optional)
With --affected, include dependent Kubernetes components.

--tags (optional)

Filter by tags (comma-separated, matches any): --tags=production,tier-1. Composes with --all/--affected to narrow the selected set further; cannot be combined with a single component argument.

--labels (optional)

Filter by labels (comma-separated key=value or key:value pairs, matches all): --labels=cost-center=platform,compliance=sox. Composes with --all/--affected/--tags; cannot be combined with a single component argument.