Atmos Kubernetes

Atmos Native Kubernetes Components

Use this skill for the native Kubernetes component type (components.kubernetes). It manages plain YAML/JSON manifests and Kustomize overlays through the Kubernetes Go SDK with server-side apply. No kubectl or kustomize binary is required. This is distinct from Helm chart deployment — see atmos-helm for charts, or atmos-helmfile for Helmfile-based releases.

This feature is experimental (IsExperimental() == true in cmd/kubernetes/kubernetes.go). kubectl/kustomize names describe manifest-processing behavior, not the CLI binaries.

Related Skills

Component Shape

Define Kubernetes objects under components.kubernetes in stack manifests:

components:
  kubernetes:
    argocd:
      provider: kustomize
      paths:
        - overlays/{{ .vars.cluster }}
      vars:
        namespace: argocd
        cluster: dev
      env:
        KUBECONFIG: /tmp/kubeconfig
      manifests:
        - apiVersion: v1
          kind: Namespace
          metadata:
            name: "{{ .vars.namespace }}"
      provision:
        default: cluster
        targets:
          cluster:
            kind: kubernetes
          deployment-repo:
            kind: git
            repository: deployments
            path: "clusters/{{ .vars.cluster }}/argocd"

Kubernetes components use the same stack sections as other component types — vars, env, auth, metadata, settings, dependencies, hooks, generate, source/provision, inheritance, and overrides. Kubernetes components do not support command — provider names describe manifest behavior, and Atmos never shells out to kubectl/kustomize.

Providers

Both providers are Go-SDK-based; neither requires the matching CLI binary installed.

Commands

All operation commands accept --all, --affected (with --base/--ref/--sha/--repo-path/ --clone-target-ref/--ssh-key/--ssh-key-password), and --include-dependents, matching atmos describe affected semantics. --all/--affected are mutually exclusive with a positional component argument. kubernetes aliases to k8s.

render output

render writes multi-document YAML to stdout by default. --output <file> writes a single file; --output-dir <dir> (with optional --split) writes one file per object (or manifest.yaml without --split). These flags only work rendering a single component — set component-level render.output for --all/--affected runs.

validate

Runs the same offline structural checks automatically before apply/deploy, so malformed manifests are rejected before anything reaches the cluster or a provision target. --server additionally requires a reachable cluster/kubeconfig and surfaces schema errors and missing CRDs authoritatively.

diff

atmos kubernetes diff does not shell out to kubectl diff. Secret objects are omitted from diff output and CI summaries.

Provision Targets (GitOps delivery)

By default apply/deploy applies to the cluster (kind: kubernetes). A component can instead publish rendered manifests to a Git deployment repository reconciled by Argo CD/Flux (kind: git):

git:
  repositories:
    deployments:
      uri: https://github.com/acme/deployments.git
      branch: main

components:
  kubernetes:
    argocd:
      provision:
        default: cluster                 # used when --target is omitted
        targets:
          cluster:
            kind: kubernetes
          deployment-repo:
            kind: git
            repository: deployments      # references git.repositories.<name>
            path: "clusters/{{ .vars.cluster }}/argocd"
            auth:
              identity: platform-admin   # optional; else the repository default
            commit:
              message: "Render {{ .vars.app_name }} for {{ .vars.stage }}"
              signing: auto              # auto | always | never

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

The git target clones (or fast-forwards), replaces the managed path with the rendered manifests, commits with provenance trailers (Atmos-Stack, Atmos-Component), and pushes. Re-delivering identical manifests is a clean no-op. Credentials come from Atmos Auth (GitHub STS) — never written into the manifests. Pull-request publishing is not yet supported. See atmos-git for the underlying mechanics.

Auth

Kubernetes operations use whatever kubeconfig/client configuration is visible to the Kubernetes Go client; Atmos Auth prepares that environment before the SDK client is created.

Local/ambient clusters:

auth:
  identities:
    local-k3s:
      kind: ambient

components:
  kubernetes:
    app:
      env:
        KUBECONFIG: /path/to/kubeconfig

EKS clusters — chain an aws/eks integration off an AWS identity to resolve the cluster and write kubeconfig before the Kubernetes command runs:

auth:
  identities:
    platform-admin:
      kind: aws
  integrations:
    prod/eks:
      kind: aws/eks
      via:
        identity: platform-admin
      spec:
        cluster:
          name: acme-prod-eks
          region: us-east-1
          kubeconfig:
            path: /tmp/acme-prod-kubeconfig
            update: replace

See atmos-aws-eks for the full aws/eks integration contract.

atmos.yaml Configuration

components:
  kubernetes:
    base_path: components/kubernetes    # default: components/kubernetes
    provider: kubectl                   # default provider: kubectl | kustomize
    auto_generate_files: false          # render component `generate:` before operations

Native CI Summaries

When ci.enabled: true and Atmos runs in a supported CI provider (e.g. GitHub Actions), Kubernetes commands write a compact Markdown job summary ($GITHUB_STEP_SUMMARY) — summaries only (no $GITHUB_OUTPUT, commit statuses, PR comments, or artifacts):

Hooks

Dotted lifecycle events: before/after × kubernetes.{render,plan,diff,apply,deploy,delete,validate}. plan normalizes to the diff lifecycle and deploy normalizes to the apply lifecycle for hook matching, so hooks written for either spelling match the equivalent operation.

components:
  kubernetes:
    argocd:
      hooks:
        notify:
          events:
            - after.kubernetes.apply
          command: echo "applied argocd"

Guidance

• Use validate (offline by default) before wiring --server dry-run checks that need a reachable cluster — it catches structural errors (bad apiVersion/kind, invalid metadata.name) for free.
• Use dependencies.components so --all/--affected apply objects across components in the right order.
• Use provision.targets with kind: git for GitOps delivery instead of ad hoc scripts that render and commit manifests manually.
• Prefer kustomize provider when component paths are Kustomize roots; use kubectl provider for plain manifest files/directories — both avoid needing the matching CLI binary installed.
• Remember Secret objects never appear in diff output or CI summaries — don't rely on diff/CI logs to review secret contents.