🛠️ Argo CD x Kustomize Master Guide: Image Overrides and Version Pinning Techniques

Jun 16, 2026

—

When practicing GitOps in a Kubernetes environment, the most commonly used tool combination is Argo CD and Kustomize. However, during operations, you might encounter situations where you want to slightly change an image only in a specific environment, or where build results differ depending on the Kustomize version, leading to difficulties.

Today, we will thoroughly explore the specific locations and methods for overriding Kustomize image tags in an Argo CD Application, as well as how to ensure build stability by pinning a specific Kustomize version! 🚀

Hello! Today, we’ve prepared two key techniques to maximize operational efficiency when deploying Kustomize manifests via Argo CD. Invest just 10 minutes to upgrade your GitOps pipeline to the next level.

1. Where can Kustomize image tags be overridden? 🖼️

Typically, when using Kustomize, you define the images field in the kustomization.yaml file. However, with Argo CD, you can dynamically change images at the Application resource level without directly modifying the Git repository.

① Configuration in Argo CD Application Manifest (YAML)

This is the most recommended method. Declare the image information to be overridden in the spec.source.kustomize path of the Application resource.

📝 Code Example and Explanation

YAML

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-kustomize-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/my-infra.git
    targetRevision: HEAD
    path: overlays/production
    # This section defines Kustomize-related settings.
    kustomize:
      # Override image tags here.
      # Find the image name defined in kustomization.yaml and replace it with a new tag.
      images:
        - name: my-api-image         # Original image name
          newName: my-api-image     # (Optional) If changing the image name
          newTag: v2.0.0-release    # Specify new tag version 👈 Key!
  destination:
    server: https://kubernetes.default.svc
    namespace: prod

② Real-time changes via Argo CD CLI

This is useful when you want to change tags just before deployment in a CI pipeline (Jenkins, GitHub Actions, etc.).

Bash

# Command to immediately change the image tag of a specific application
argocd app set my-kustomize-app --kustomize-image my-api-image=v2.0.0-release

③ Changes in Argo CD Web UI

It is also possible through the user interface (UI).

Access Application -> Click PARAMETERS tab -> Modify images item in Kustomize section.

2. How to Pin a Specific Kustomize Version 📌

Argo CD uses its built-in Kustomize binary. However, if the version used locally differs from the internal Argo CD version, manifest rendering results may vary, leading to OutOfSync issues or deployment errors. There are two main ways to prevent this by pinning the version.

① Modifying Argo CD ConfigMap (argocd-cm) ⚙️

You can modify the Argo CD configuration file, argocd-cm, to specify the default Kustomize executable path to use. However, this method is only possible within the scope supported by Argo CD.

YAML

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  # Build options can be controlled via kustomize.buildOptions, etc.
  kustomize.buildOptions: "--load-restrictor LoadRestrictionsNone"

② Utilizing Custom Tooling (Sidecar Container) 📦

This is the most reliable and powerful method. You can attach a sidecar container with the desired Kustomize binary version installed to Argo CD’s repo-server, or customize the image to include a specific version.

📝 Argo CD Repo-Server Customization Example (Docker)

Dockerfile

# Use Argo CD official image as base
FROM argoproj/argocd:v2.8.4

# Switch to root privileges to proceed with installation
USER root

# Download a specific desired version of Kustomize (e.g., v5.0.0)
RUN curl -L https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv5.0.0/kustomize_v5.0.0_linux_amd64.tar.gz | tar -xz && 
    mv kustomize /usr/local/bin/kustomize-v5

# Switch back to argocd user
USER 999

Afterward, configure argocd-cm to use this custom binary or define and use a **Config Management Plugin (CMP)**.

3. Summary and Practical Checklist 📊


Task	Location / Method	Notes

—	—	—
Change Image Tag	Application Spec (spec.source.kustomize.images)	Allows separating tags per environment without Git modification
Temporary Image Change	Argo CD CLI / Web UI	Suitable for quick tests and manual deployments
Pin Kustomize Version	Install custom binary in argocd-repo-server	Ensures consistent build results (highly recommended)
Add Build Options	kustomize.buildOptions within argocd-cm	Used when adding flags (e.g., –enable-alpha-plugins)

—

🏁 Conclusion

Kustomize image overrides transform Argo CD into a true **’environment-specific configuration tool’**. Furthermore, the habit of explicitly pinning Kustomize versions fundamentally prevents the classic problem of “It works on my machine, but why not on the server?”

Choose the most appropriate override method for your project’s situation! 🛠️