# atmos helm apply

Install or upgrade a Helm release (`helm upgrade --install`) for a component in
a stack, using values resolved from your stack configuration. With `--target`,
`apply` instead delivers the rendered manifests to a provision target such as a
Git deployment repository.

## Usage

```shell
atmos helm apply <component> --stack <stack> [options]
```

Install or upgrade the release in the cluster:

```shell
atmos helm apply monitoring -s plat-ue2-dev
```

Apply a one-time image override without changing stack configuration:

```shell
atmos helm apply monitoring -s plat-ue2-dev -f incident-values.yaml --set image.tag=2026.09.09
```

Upgrade an existing release with an explicit production readiness and recovery policy:

```shell
atmos helm apply monitoring -s plat-ue2-dev \
  --on-failure=rollback \
  --cleanup-on-failure \
  --wait=watcher \
  --wait-for-jobs \
  --timeout=30m \
  --history-max=10
```

Deliver rendered manifests to a provision target instead of the cluster:

```shell
atmos helm apply monitoring -s plat-ue2-dev --target deployment-repo
```

Apply all or affected Helm components in dependency order:

```shell
atmos helm apply --all -s plat-ue2-dev
atmos helm apply --affected --base origin/main
```

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

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

# Combine multiple selectors in one comma-separated --labels value
atmos helm apply --affected --labels cost-center=platform,compliance=sox
```

In CI, bulk applies selected with `--all` or `--affected` write one aggregate GitHub job summary
after the dependency graph completes. It lists component status and Helm release metadata in stable
stack/component order and includes details for failures.

While a cluster apply is running, Atmos reports the selected install or upgrade operation, effective
wait policy, timeout, and elapsed-time heartbeats. Bulk output includes the component and stack on
every line so concurrent or dependency-ordered operations remain distinguishable. Progress is written
through the masked UI stream; chart hook container logs are not streamed automatically.

## Flags

- **`--stack`, `-s` (required)** — Atmos stack.
- **`--target` (optional)** — Provision target to deliver to (e.g. a Git deployment repository). Defaults to `provision.default`, otherwise the cluster.
- **`--dependency-update` (optional)** — Fetch declared chart dependencies when they are missing. This may access dependency repositories and update the chart's charts/ directory and lock file.
- **`-f` / `--values`, `--set`, `--set-string`, `--set-file`, `--set-json`, `--set-literal` (optional)** — Repeatable Helm-compatible value overrides for this apply. They override stack-resolved values only for this invocation. See runtime value overrides.
- **`--dry-run` (optional)** — Preview the install or upgrade without persisting release state or creating Kubernetes resources.
- **`--on-failure` (optional)** — Failure action for the selected operation: `uninstall` or `keep` for install; `rollback` or `keep` for upgrade. The explicit flag overrides stack configuration for this invocation.
- **`--cleanup-on-failure` (optional)** — Remove resources newly created during a failed upgrade, independently of rollback. Fails if the selected operation is install.
- **`--wait[=strategy]` (optional)** — Use `watcher`, `hookOnly`, or `legacy`. Passing `--wait` without a value selects `watcher`. Boolean values remain accepted temporarily but are deprecated.
- **`--wait-for-jobs` (optional)** — Wait for ordinary Jobs in the release manifest. Requires `watcher` or `legacy`.
- **`--timeout` (optional)** — Helm release-operation timeout, such as `10m` or `1h`. `0s` is explicitly unbounded.
- **`--history-max` (optional)** — Maximum retained release revisions for an upgrade. Defaults to `10`; `0` means unlimited. Fails if the selected operation is install.
- **`--no-hooks` (optional)** — Disable Helm chart hooks. Atmos lifecycle hooks are unaffected.
- **`--skip-crds` (optional)** — Skip CRD installation on a first install. Fails if the selected operation is upgrade.
- **`--server-side-apply[=auto|true|false]` (optional)** — Override the apply method for this operation. A bare `--server-side-apply` selects `true`. Omit to use the Helm default (server-side apply on install; the prior release's method on upgrade).
- **`--force-conflicts` (optional)** — Resolve server-side apply field-ownership conflicts by overwriting the contested fields and becoming their sole manager. Opt-in; use it for a single recovery apply without editing stack configuration.
- **`--all` (optional)** — Apply all Helm components in dependency order.
- **`--affected` (optional)** — Apply affected Helm components and their dependencies.
- **`--include-dependents` (optional)** — With `--affected`, include dependent Helm 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 in one flag value, matches all): `--labels=cost-center=platform,compliance=sox`. Composes with `--all`/`--affected`/`--tags`; cannot be combined with a single component argument.

Lifecycle flags apply only to direct Kubernetes delivery. Combining an explicit
lifecycle flag with an external `--target` fails instead of implying that Atmos
waited for or rolled back a GitOps deployment.

## Try it out

### helm

Copy the example into a new directory and make it your own:

```shell
atmos init examples/helm
cd helm
```

Requires Docker or Podman and network access. Deploy into the local Kubernetes emulator, then delete the release and stop the emulator.

```shell
atmos emulator up kubernetes -s dev
atmos helm apply demo -s dev --identity local-k3s
atmos helm delete demo -s dev --identity local-k3s
atmos emulator down kubernetes -s dev
```

- [Installation guide](/install)
- [Explore the example](/examples/helm)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)