Installing Argo CD with Kustomize: when a patched base fits your cluster
A platform team that has to install Argo CD into its own infrastructure, with changes that can be reviewed and repeated, can use Kustomize over the official manifests. Kustomize with a remote base is one reliable way to do this, because the installation stays a short overlay in Git that points at upstream manifests and records only the changes your environment needs. The model is simple: the overlay declares the official install manifest as a remote resource, then applies patches for the things that differ in your cluster, such as the namespace. The Argo CD installation guide recommends this pattern and gives a specific example: for a custom namespace, patch /subjects/0/namespace in the ClusterRoleBinding so the binding still points at the namespace where Argo CD actually runs. Confirm that the manifest URL and the patch path match the release you intend to install before you commit the overlay.
Teams usually choose this approach over the Helm chart when they want the installed objects to match upstream YAML line for line and want every deviation visible as a patch in review. It fits when the platform team already manages cluster configuration with Kustomize and wants Argo CD handled the same way. It is less suited to teams that want Helm-style values for many options, and it differs from the core install, which omits the API server and UI. Keep in mind that Argo CD is licensed under the Apache License 2.0 with no paid edition from the project, so your cost is the engineering and operations work, not a license fee. The project also ships a new minor release four times a year and patches only its three most recent minor versions, so plan to bump the pinned remote version on that cadence.
Pinning matters more than the patch syntax. Reference a specific release tag in the remote URL rather than a moving branch, and record the version in the overlay's Git history so each upgrade is a reviewable diff. Before you apply, render the overlay with kustomize build and read the output, paying attention to the ClusterRoleBinding subjects, the namespace on every object and any ConfigMap changes. Ask your team to confirm two things in your environment: that the version you pin is still within the supported minor releases, and that any configuration map keys you set exist in the release you chose. Those checks turn a remote base from a convenience into a controlled change.
How Kustomize compares with Helm and plain manifests
Plain manifests need the least tooling: a team applies the release YAML and edits it directly. Kustomize asks for comfort with overlays, patches and remote bases, which is a small step up but still plain YAML with no templating language. Helm adds chart values, template rendering and release history, so it suits teams already running Helm across their platform. The question is less about which tool is best and more about which one your on-call engineers can read at 2 a.m.
- Plain manifests: lowest learning curve, but every customization is a hand edit to a file you own.
- Kustomize: patches are explicit and reviewable, which suits teams that prefer YAML over templates.
- Helm: strong fit where charts and values are already the standard for other workloads.
- Mixed skill sets: a team that knows only one tool will carry most of the maintenance load.
- Hiring and handover: ask who can explain each patch without reading the upstream release.
Check which tool your platform engineers already use daily, and whether that skill will still be present in the team during the next upgrade cycle.
Configuration needs decide how much variation you expect between environments. Kustomize handles a small set of known changes well, such as a custom namespace, a ConfigMap value or an image tag. Helm is built around a values file, which suits many environments that differ in ingress, SSO and resource settings. Plain manifests fit a single environment with few changes, but become hard to track once two or more clusters need different settings.
- Few, stable changes: Kustomize patches keep the diff small and visible.
- Many parameters across environments: a values-driven chart can reduce repeated edits, though values still need review.
- Single cluster, little change: plain manifests may be enough, with a short record of each edit.
- Settings that change in Git: Argo CD configuration, such as argocd-cm, is typically managed through the same files your team reviews.
- Repository and secret handling: decide where these live before choosing the route, since they affect every option.
List the settings that will differ between your environments and count how many of them will need review at each upgrade.
Upgrades are where the routes differ most in day-to-day work. With Kustomize, you point the remote base at a new release or pin a tag, then rerun the diff against your patches. Helm moves the version through a chart version and values, with release history kept by Helm. Plain manifests require you to reapply the new YAML and reconcile any hand edits. In every route, the release notes for the target version set the actual work, including breaking changes such as RBAC or resource tracking changes.
- Kustomize: an upgrade is a diff of the remote base plus your patches, which must still apply cleanly.
- Helm: chart and application versions can differ, so confirm which Argo CD version a chart release carries.
- Plain manifests: upgrades depend on careful reconciliation of edits made by hand.
- Version pinning: pin the release in every route, and check the project's patch support window before choosing a target.
- Breaking changes: read the upgrade notes for each minor version you cross, whichever route you use.
Before committing to a route, do a trial upgrade in a non-production cluster and time how long reconciling your patches takes.
Drift is the gap between what Git declares and what runs in the cluster. Each install route creates a different owner for that gap. A manual apply of plain manifests makes the cluster the source of truth unless someone commits every change. Kustomize and Helm both produce a rendered result that someone must compare against the live state. Once Argo CD manages its own installation, the question becomes whether a change to Argo CD goes through its Git-based review. The owner you name should be the team that answers for the configuration during an audit.
- Plain manifests: drift is often unnoticed unless someone runs a diff against the cluster.
- Kustomize: the overlay in Git is the record, and the live state should match its rendered output.
- Helm: release history records changes, but values can still be edited outside Git.
- Argo CD self-management: the installation itself can be placed under Argo CD sync, which narrows the drift gap.
- Ownership: name a platform team, not just a person, for every install file.
Ask who will receive the alert when the Argo CD installation drifts from Git, and confirm that team has access to the repository that holds the overlay.
How the remote base and patches fit together
A kustomization.yaml in your own repository can reference the official Argo CD install manifest as a remote resource, so the upstream YAML is never copied into your Git history. Your file lists that remote URL under resources and then adds patches on top. Kustomize builds the final manifest by applying those patches to the upstream objects at render time. The practical consequence is that your repository holds only the differences from upstream: the namespace, configuration map values and any other overrides you need. Keep the patch set small and give each patch file a name that states its purpose, such as clusterrolebinding-namespace.yaml or argocd-cm-patch.yaml, so a reviewer can see at a glance what diverges from the base during an upgrade.
The namespace change is the patch most teams need first, and it touches more than the Deployment. Installing into a namespace other than argocd means the ClusterRoleBinding must point its subject at that namespace, otherwise the service account the components run as is bound to the wrong place. The installation guide gives the patch path /subjects/0/namespace for this case, applied to the ClusterRoleBinding object. Confirm the exact target name and the current manifest structure against the release you pin, because the object names and subject layout can change between minor versions. Check the rendered output with kustomize build before applying it, and search that output for every reference to the default namespace so nothing is left pointing at argocd.
Pinning the remote URL to a specific release tag rather than a moving branch is what makes this layering safe to repeat. Each upgrade then becomes a deliberate change: bump the tag, rebuild, and review the diff of the patches against the new base. Upgrade notes for major versions, such as the Argo CD 2.14 to 3.0 upgrade notes, describe changes that can invalidate an old patch, so a patch that worked on one release may need rework on the next. Ask your team to name the owner of the patch set and to record which upstream tag each patch was written against.
Setting up a Kustomize install of Argo CD
This sequence takes you from an empty Git repository to a verified Argo CD installation built from the official manifests as a remote Kustomize base. Each step ends with a check you can run, so the install is confirmed before anyone depends on it.
Create a Git repository for the install overlay
Create a dedicated Git repository that holds only the Kustomize overlay for Argo CD, with a kustomization.yaml file at its root and no copies of the upstream manifests. Your platform or GitOps owner does this, and the repository should sit under the same access controls you apply to other cluster configuration. Commit the empty kustomization.yaml and confirm the repository is reachable from the machine where you will run kustomize build. Done means the file exists on the main branch and a clone of the repository works from your admin workstation.
Pin the remote manifest to a chosen release
In kustomization.yaml, reference the official install manifest as a remote resource and set the URL to a specific release tag rather than the stable or master branch, so the same input always produces the same output. Choose the tag from the Argo CD releases page and the release process documentation, and confirm the supported minor versions before you pick one. Record the chosen tag in your change ticket. Check it by running kustomize build against the overlay and confirming the output includes the expected Argo CD version in the image tags. Confirm the exact command and tag in your own environment before relying on them.
Add the namespace and ClusterRoleBinding patches
If you install into a namespace other than argocd, set the namespace field in the overlay and add a patch that changes the subject of the ClusterRoleBinding to point at your namespace. The installation guide recommends patching the namespace under /subjects/0/namespace in that binding, and the rest of the install must use the same namespace. Your platform engineer owns this patch because it grants cluster-wide permissions. Run kustomize build and search the output for the ClusterRoleBinding to confirm the subject namespace matches your choice in every place it appears.
Add ConfigMap and Secret patches
Create patch files for the settings you need at install time, such as the external URL in argocd-cm, command-line flags in argocd-cmd-params-cm, and RBAC rules in argocd-rbac-cm. Keep SSO client secrets and repository credentials out of these files and out of Git; manage them as Kubernetes Secrets through your secrets process. Note that repository definitions belong in Secrets, not in argocd-cm, for Argo CD 3.0 and later. Confirm the patches by building the overlay and checking that each ConfigMap in the output carries your values and that no plaintext credential appears anywhere in the rendered YAML.
Review the rendered output with kustomize build
Run kustomize build on the overlay and write the output to a file that a second person can review before anything touches a cluster. The reviewer checks the namespace, the image tags, the CRDs, the ClusterRoleBinding subject and the ConfigMap values against the change ticket. Diff the output against the previous release if you are upgrading. Done means the reviewer has approved the rendered file and the build completes with no errors or warnings about unknown fields.
Apply the overlay to the target cluster
Apply the reviewed output to the cluster you control, using the apply method your team standardizes on and the exact command documented for your chosen release. Confirm you are pointed at the intended cluster context before running it. Large CRDs may need server-side apply, so check the installation guide for your release before choosing the method. Done means the apply command finishes and reports the expected resources as created or configured, with no errors.
Verify pods, CRDs and the admin login path
Wait for the Argo CD pods in your namespace to reach the Running state, then list the Argo CD custom resource definitions and confirm the Application, ApplicationSet and AppProject definitions are present. Retrieve the initial admin password from its Secret, log in through the UI or argocd CLI, and confirm access. Plan to disable the built-in admin user with admin.enabled set to false once SSO or local users are configured, as the user management documentation recommends. Done means the pods are healthy, the CRDs exist, and you can sign in with the intended path.
Which patches to make and when each one fits
This table compares the patches you can layer over the official Argo CD manifests, the situation each one fits, what it changes and what happens if you skip it. Read each row as a decision: most installs need the namespace and admin decisions, while pinning and the repository Secret pattern apply to nearly every production setup.
| Patch | When it fits | What it changes | Risk if skipped |
|---|---|---|---|
| Custom namespace with ClusterRoleBinding subject patch | You run Argo CD outside the default argocd namespace and your platform standard requires a named namespace | Patches /subjects/0/namespace in the ClusterRoleBinding so the binding points at your namespace, as the installation guide recommends | The binding references the wrong namespace, so the controller may lack the cluster permissions it needs |
| argocd-cm settings | You need to set the external URL, SSO connectors, resource tracking or other general behavior | Changes general Argo CD configuration held in the argocd-cm ConfigMap; configure SSO here only before 3.0 removed repository entries from this map | Login links, SSO callbacks or tracking behavior default to values that do not match your environment |
| argocd-cmd-params-cm settings | You need to change server runtime parameters, such as TLS mode behind an ingress that terminates TLS | Sets server command parameters held in argocd-cmd-params-cm; confirm each key against the installation documentation for your version | The API server may expose or terminate TLS in a way your ingress design does not expect |
| Disable the admin user (admin.enabled set to false) | Only after local users or SSO sign-in is tested and at least one administrator can log in through it | Turns off the built-in admin account, as the user management documentation recommends once other access is configured | A shared built-in password remains a standing administrative login, and audit trails show a shared identity |
| Release reference pin | Every environment, so the manifests you apply match a version you have tested | Points the remote base at a specific Argo CD release tag instead of a floating reference; the project supports only the three most recent minor versions for patch releases | Re-applying the base later can silently upgrade Argo CD, and an older unpatched minor line may be left behind |
| Repository Secret pattern | Any installation on Argo CD 3.0 or later that connects Git repositories | Defines repositories as Kubernetes Secrets, because 3.0 removed repository configuration from argocd-cm | Repositories defined in the old ConfigMap location are not loaded, so applications fail to sync after upgrade |
| Upgrade-aware RBAC policy | You map SSO groups to Argo CD roles and upgrade from 2.14 or earlier | Uses the federated_claims.user_id claim for Dex-based RBAC and an explicit logs, get permission for log access, per the 3.0 upgrade notes | Users keep access they should lose, or lose log access they need, after the upgrade |
| Confirm each key against your version | Before every patch you add, for every version you pin | Verify configuration key names and defaults in the documentation for the exact release, since keys change between minor lines | A patch that is silently ignored leaves the default in force and gives no error at apply time |
Pinning versions and planning patch upgrades
A Kustomize overlay that points at the official manifests inherits whatever version those manifests carry, so the version becomes a deliberate input rather than a side effect. The four cards below cover how to fix that input, how to keep up with patch releases, how to read upgrade notes before crossing a minor boundary, and how to rehearse the change in a non-production cluster first.
Pin the tag, not the branch
Reference the remote manifest by a specific release tag in the resources URL of your overlay, rather than a branch such as stable or master. A moving reference means two clusters built from the same Git commit can receive different Argo CD versions, and a sync can change the control plane without a reviewed change. Record the tag in the overlay's Git history so each upgrade appears as a diff that reviewers can read. Confirm that your change process accepts tag-based references and that your Git host restricts who can edit the overlay.
Track the patch window
The Argo CD release process ships a minor release four times a year, and only the three most recent minor versions receive patch releases. Your pinned version therefore has a shelf life. Subscribe to the GitHub releases feed and note the date each minor line leaves the patch window, so an unsupported version becomes a scheduled upgrade rather than an emergency. Patch releases within a minor line are the lowest-risk changes to take, and they should be scheduled on a regular cadence agreed with your operations team.
Review upgrade notes before moving
Crossing a major boundary changes behavior that a Kustomize patch will not catch. The 2.14 to 3.0 upgrade notes, for example, limit update and delete RBAC to the application itself, require an explicit logs get permission for log access, and make annotation-based resource tracking the default. Repository definitions also moved out of the argocd-cm ConfigMap into Secrets, and Dex RBAC now uses the federated_claims.user_id claim. Read every upgrade note between your current and target version, then update the overlay's patches and RBAC bindings in the same change.
Rehearse the overlay in a test cluster
Apply the updated overlay to a non-production cluster that has the same namespace, SSO settings and repository secrets as production before changing production. Confirm that the ClusterRoleBinding patch still targets the right namespace, that argocd-cm and argocd-rbac-cm keys still exist in the new version, and that existing applications sync without unexpected OutOfSync states. Keep the previous tag available so rollback means reverting one commit and reapplying. Document the test results alongside the change record so reviewers can see what was verified and by whom.
Questions teams ask before installing Argo CD with Kustomize
How much effort does an in-house Argo CD install with Kustomize take?
The base install is small, but the effort grows with the decisions around it. The remote manifest is one resource, so the work is in the overlay: a custom namespace patch to the ClusterRoleBinding subject, configuration maps, pinned versions, and the cluster and Git layout that the overlay lives in. Effort rises with the number of clusters, the SSO design, the TLS and ingress choice, and how many people must review the change. Ask your team to list those decisions first, because they set the real size of the work.
Is a partner worth it for a first Argo CD installation?
A partner is worth considering when the install must be correct on the first attempt, for example when it sits in a regulated environment with change approval and audit evidence. A fixed-scope engagement puts the scope, deliverables and timeline in writing before work starts, so you can compare it with the cost of your own staff's time and the risk of rework. DeployOpen plans, implements and documents self-hosted platforms inside your own infrastructure, and it does not issue audit reports or certifications. Compare quotes on what they include: overlay design, SSO, handover documentation and a plan for upgrades.
What does the work need from our side?
The work needs access and decisions more than hardware. Typical requirements are:
- Admin access to the target clusters, with a named owner for the namespace and cluster-scoped objects
- A Git repository that holds your overlays, with a branch and review process your change board accepts
- A DNS name, certificate source and ingress controller decision
- Approval for the identity provider integration and for who receives admin rights
Confirm these before the start date, since waiting on them is a common cause of delay.
Can one engineer install Argo CD with Kustomize alone?
One experienced Kubernetes engineer can usually complete the first install, but safe operation needs a second person. Someone must own the overlay, and someone must review changes to the patches and pinned versions, because a mistake in the ClusterRoleBinding or a ConfigMap affects every application Argo CD manages. Plan a backup contact for upgrades and incidents, and record the install in your repository so the knowledge does not stay with one person.
How long before the installation is safe to run?
Safe to run means more than the pods being ready. It means the admin user is disabled once SSO or local users work, repositories are defined as Kubernetes Secrets, RBAC is tested with real users, and the overlay and version pins are reviewed and stored in Git. The duration depends on how many of those steps are new to your team and how long approvals take. Ask any partner to show the acceptance checks they will run and the handover documents they will deliver, and agree on those in the written scope.
What does it cost to keep Argo CD patched?
Patching is the recurring cost, and it is set by the release cadence. The Argo CD release process ships a minor release four times a year, and only the three most recent minor versions receive patch releases, so you must plan to move onto a supported minor version regularly. Each move requires reading the upgrade notes, testing the overlay against the new manifests, and rolling out to each cluster. Ask for these in a quote: the number of clusters, the test environment, who reviews the upgrade notes, and whether support is a retainer or ad hoc work.
When should we choose Helm instead of Kustomize?
Choose Helm when your team already manages releases with Helm charts, or when you need a large set of values-driven options that the chart exposes. Kustomize suits teams that want to keep the official manifests unchanged and apply a few explicit patches, which is what this approach does. The choice also affects how upgrades are reviewed, so compare how each option would handle your namespace change, your ConfigMaps and your version pins before you commit. See the sibling topic on the community Helm chart for the trade-offs in support and values.
How DeployOpen scopes and delivers an Argo CD install
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, so the Kustomize base, patches and configuration live in your Git repositories and your clusters. Each Argo CD install starts with a written scope agreed before any work begins.
How we scope
- Confirm the target clusters, namespace layout and whether Argo CD runs in its own namespace or a custom one.
- Agree which remote manifest version is pinned and how upgrades will be tested before promotion.
- Define the ConfigMap settings, RBAC and SSO expectations in the written scope, with fixed deliverables and timelines.
How we build
- Build the Kustomize overlay with the namespace and ClusterRoleBinding subject patches, keeping every change reviewable in Git.
- Validate rendered manifests in a non-production cluster and check that the admin account and repository Secrets behave as designed.
- Test the install against the planned sign-in path and confirm that the pinned version matches the supported patch release line.
How we hand over
- Deliver the overlay repository, a runbook for applying and rolling back the pinned version, and a record of every patch applied.
- Walk your platform team through the install steps, the version pinning policy and the upgrade checklist for the next minor release.
- Document open decisions, such as where the admin account is disabled, so your team can confirm them with its own security owners.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers once the install is in production.
- Retainer work can cover reviewing each new patch release on the supported minor lines before your team adopts it.
- Support scope is set in writing, so your team knows which upgrades, fixes and tests the retainer includes.
