Kustomize

Deploy applications using Kustomize with Argo CD

Argo CD natively supports Kustomize for declarative configuration management. When a kustomization.yaml file is detected in your repository, Argo CD automatically uses Kustomize to render manifests.

Basic Application

Define a Kustomize application in the declarative GitOps way:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kustomize-example
spec:
  project: default
  source:
    path: examples/helloWorld
    repoURL: 'https://github.com/kubernetes-sigs/kustomize'
    targetRevision: HEAD
  destination:
    namespace: default
    server: 'https://kubernetes.default.svc'

Configuration Options

namePrefix · string

Overrides the namePrefix in kustomization.yaml

nameSuffix · string

Overrides the nameSuffix in kustomization.yaml

images · array

List of Kustomize image overrides

replicas · array

List of Kustomize replica overrides

commonLabels · object

String map of additional labels to apply

commonAnnotations · object

String map of additional annotations to apply

namespace · string

Kubernetes resources namespace

patches · array

List of Kustomize patches that support inline updates

components · array

List of Kustomize components

Inline Patches

Apply patches directly in the Application manifest without modifying repository files:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kustomize-inline-guestbook
  namespace: argocd
spec:
  destination:
    namespace: test1
    server: https://kubernetes.default.svc
  project: default
  source:
    path: kustomize-guestbook
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: master
    kustomize:
      patches:
        - target:
            kind: Deployment
            name: guestbook-ui
          patch: |-
            - op: replace
              path: /spec/template/spec/containers/0/ports/0/containerPort
              value: 443

Inline patches work well with ApplicationSets to dynamically customize applications per cluster without maintaining separate overlays.

Components

Kustomize components encapsulate resources and patches together for modular configuration:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: application-kustomize-components
spec:
  source:
    path: examples/application-kustomize-components/base
    repoURL: https://github.com/my-user/my-repo
    targetRevision: main
    kustomize:
      components:
        - ../component
      ignoreMissingComponents: true

ignoreMissingComponents · boolean

Prevents kustomize from failing when components don’t exist locally

Custom Kustomize Versions

Configure multiple Kustomize versions and specify per application:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  kustomize.path.v3.5.1: /custom-tools/kustomize_3_5_1
  kustomize.path.v3.5.4: /custom-tools/kustomize_3_5_4

Then reference in your Application:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
spec:
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: kustomize-guestbook
    kustomize:
      version: v3.5.4

Build Options

Provide build options to kustomize build:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  kustomize.buildOptions: --load-restrictor LoadRestrictionsNone
  kustomize.buildOptions.v4.4.0: --output /tmp

Environment Variables

Enable environment variable substitution in annotations:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook-app
  namespace: argocd
spec:
  project: default
  destination:
    namespace: demo
    server: https://kubernetes.default.svc
  source:
    path: kustomize-guestbook
    repoURL: https://github.com/argoproj/argocd-example-apps
    targetRevision: HEAD
    kustomize:
      commonAnnotationsEnvsubst: true
      commonAnnotations:
        app-source: ${ARGOCD_APP_NAME}

Use build environment variables to access context like ARGOCD_APP_NAME, ARGOCD_APP_NAMESPACE, and ARGOCD_APP_REVISION.

Setting Namespace

Use spec.source.kustomize.namespace to set namespaces directly with Kustomize:

spec:
  source:
    kustomize:
      namespace: my-namespace

If both spec.destination.namespace and spec.source.kustomize.namespace are set, Argo CD will use the Kustomize namespace value.

Private Remote Bases

Remote bases inherit credentials from the Application’s repository configuration. They must use the same credentials to work properly.

CLI Usage

Set Kustomize version via CLI:

argocd app set <appName> --kustomize-version v3.5.4