# 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

# Repeat --labels to combine multiple selectors across occurrences
atmos helm apply --affected --labels cost-center=platform --labels 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.
- **`--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 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.

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.