# atmos kubernetes diff

Check what would change in the cluster before you deploy. `diff` renders the
component, asks Kubernetes to validate the update with server-side dry run,
and reports which objects would be created, changed, or left alone.

**Configure Kubernetes Components**

`diff` uses the same stack inputs as deployment: `provider`, `paths`,
`manifests`, `vars`, `env`, Auth, hooks, and dependencies.

Stack Configuration[Read more](/stacks/components/kubernetes)

## Usage

```shell
atmos kubernetes diff <component> --stack <stack>
atmos kubernetes diff --affected --base origin/main
```

`diff` renders the final manifests, sends each object through Kubernetes
server-side dry-run apply, reads the live object through the dynamic client,
normalizes volatile metadata, and reports whether each object would be created,
changed, or left unchanged.

The command does not require the `kubectl` binary and does not run `kubectl diff`.

## Example

```shell
atmos kubernetes diff argocd -s plat-ue2-dev
```

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

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

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

Example output (each created or changed object is followed by its unified diff;
`no-change` objects and `Secret` objects show only the action line):

```diff
create v1/Namespace argocd
--- a/v1/Namespace_argocd.yaml
+++ b/v1/Namespace_argocd.yaml
@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: argocd
changed apps/v1/Deployment argocd/argocd-server
@@ -8,7 +8,7 @@
   replicas: 2
-  image: argocd-server:2.10.0
+  image: argocd-server:2.11.0
no-change v1/Service argocd/argocd-server
```

When run in CI (`ci.enabled: true`), the same diff is also written to the job summary as a
collapsible **Kubernetes Diff** block. See [Job Summaries](/ci/job-summaries). `Secret` objects
are omitted from the diff so their data is never printed or written to the summary.

## Flags

- **`--stack`, `-s` (optional)**
  Atmos stack. Required when diffing a named component; not required with 
  `--all`
  /
  `--affected`
  /
  `--tags`
  /
  `--labels`
   bulk selection.
- **`--all` (optional)**
  Diff all Kubernetes components in dependency order.
- **`--affected` (optional)**
  Diff 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 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.

## Try it out

Requires Docker or Podman and network access. Use the local Kubernetes emulator and stop it when finished. Diff reports pending changes with a nonzero exit status.

```shell
atmos emulator up kubernetes -s dev
atmos kubernetes diff demo -s dev --identity local-k3s
atmos emulator down kubernetes -s dev
```