# 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.

**Configure Kubernetes Components**

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

Stack Configuration[Read more](/stacks/components/kubernetes)
atmos.yaml Configuration[Read more](/cli/configuration/components/kubernetes)

## Usage

```shell
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`](/cli/commands/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

```shell
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):

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

# Repeat --labels to combine multiple selectors across occurrences
atmos kubernetes deploy --affected --labels cost-center=platform --labels compliance=sox
```

## 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`:

```yaml
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:

```shell
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.

```yaml
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](/stacks/components/kubernetes#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 within one occurrence, and/or repeated for more, matches all): `--labels=cost-center=platform,compliance=sox` or `--labels cost-center=platform --labels compliance=sox`. Composes with `--all`/`--affected`/`--tags`; cannot be combined with a single component argument.