How to Configure Argo CD for Kubernetes

To configure Argo CD for Kubernetes, you install the control plane via Kubernetes manifests, define target clusters in Application resources, and tune system behavior through the argocd-cm ConfigMap and supporting Secrets.

Argo CD is a declarative GitOps continuous delivery engine that runs inside a Kubernetes cluster and synchronizes the desired state stored in Git with the live state of your infrastructure. Configuration centers on a set of Kubernetes resources—primarily ConfigMaps and Secrets—that the Argo CD control plane reads at startup. Below is a complete guide to installing the core components, connecting clusters, and customizing the deployment according to the argoproj/argo-cd source code.

Installing the Argo CD Control Plane

The foundation of Argo CD configuration lives in manifests/namespace-install.yaml, which bundles the ServiceAccounts, RBAC roles, Deployments, and default ConfigMaps required to run the system.

Install the complete stack with a single command:

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/namespace-install.yaml

This manifest creates several critical configuration objects:

• argocd-cm – The main ConfigMap that holds global settings, resource customizations, and repository definitions (see lines 16–18 in namespace-install.yaml)
• argocd-cmd-params-cm – Supplies default CLI flag values for the server, repo-server, and application controller
• argocd-secret – Stores the admin password, TLS certificates, and Redis authentication credentials
• argocd-ssh-known-hosts-cm – Contains SSH host keys for Git over SSH operations

The manifest also provisions the ServiceAccounts (argocd-application-controller, argocd-server, etc.) and corresponding Roles that grant Argo CD pods the necessary permissions to read and write Kubernetes resources throughout the cluster.

Exposing the Argo CD UI

By default, the Argo CD API server is not exposed externally. You can access it through port-forwarding for initial setup:

kubectl -n argocd port-forward svc/argocd-server 8080:80

For production environments, expose the UI via an Ingress resource or change the argocd-server Service type to LoadBalancer.

Configuring Target Kubernetes Clusters

Argo CD uses Application custom resources to define what to deploy and where. The destination field specifies the target cluster and namespace.

In-Cluster Configuration

When Argo CD manages the same cluster where it is installed, use the internal Kubernetes DNS name:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/guestbook
    targetRevision: HEAD
    path: manifests
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

The Application CRD is watched by the argocd-application-controller deployment, which requires specific RBAC permissions defined in namespace-install.yaml (lines 73–96).

Remote Cluster Configuration

To manage external clusters, create a Secret containing a service account token from the remote cluster:

apiVersion: v1
kind: Secret
metadata:
  name: remote-cluster-secret
  namespace: argocd
type: Opaque
stringData:
  token: <BASE64-ENCODED-TOKEN>

Then reference the remote API server in your Application:

destination:
  server: https://<REMOTE-API-ADDRESS>
  namespace: production

Argo CD automatically uses the token from the Secret when connecting to the remote cluster URL.

Adding Git Repository Credentials

Argo CD can access public repositories without authentication. For private repositories, define credentials in the argocd-cm ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  repositories: |
    - url: git@github.com:myorg/private-repo.git
      type: git
      sshPrivateKey: |
        -----BEGIN OPENSSH PRIVATE KEY-----
        ...
        -----END OPENSSH PRIVATE KEY-----

Alternatively, use the CLI to add repositories interactively:

argocd repo add git@github.com:myorg/private-repo.git \
  --ssh-private-key ~/.ssh/id_rsa \
  --type git

This writes the configuration into argocd-cm as shown in lines 16–31 of namespace-install.yaml.

Customizing Resource Handling

Prevent Argo CD from triggering unnecessary syncs by configuring resource customizations in argocd-cm. To ignore the status field for all resources:

data:
  resource.customizations.ignoreResourceUpdates.all: |
    jsonPointers:
      - /status

These settings help reduce controller load by excluding noisy fields that change frequently but do not affect the desired state.

Enabling HTTPS and Single Sign-On

Secure the installation with TLS and external authentication:

• TLS Certificates – Populate the argocd-tls-certs-cm ConfigMap with your certificate and key data
• OIDC SSO – Configure the argocd-dex-server Deployment by adding a dex.config entry to argocd-cm, or use the argocd-dex-config ConfigMap when deploying via Helm

Verifying the Installation

Confirm the control plane is running and retrieve the initial admin password:

# Check pod status

kubectl -n argocd get pods

# Get admin password

kubectl -n argocd get secret argocd-secret \
  -o jsonpath="{.data.admin\.password}" | base64 -d

# Login via CLI

argocd login localhost:8080 --username admin --password <password>

Summary

• Install the control plane using manifests/namespace-install.yaml, which creates the essential argocd-cm, argocd-secret, and RBAC resources
• Configure clusters by defining Application resources with destination.server pointing to https://kubernetes.default.svc for in-cluster or external API endpoints for remote clusters
• Add credentials for private Git repositories via the repositories key in argocd-cm or through the argocd repo add CLI command
• Tune behavior using resource.customizations entries in argocd-cm to ignore specific JSON paths and reduce unnecessary sync operations
• Secure access by configuring TLS certificates in argocd-tls-certs-cm and integrating OIDC providers through the Dex server configuration

Frequently Asked Questions

Where is the Argo CD configuration stored?

Argo CD configuration is stored primarily in Kubernetes ConfigMaps and Secrets within the argocd namespace. The main ConfigMap argocd-cm contains global settings and repository definitions, while argocd-secret holds sensitive data like the admin password and TLS certificates. These resources are created by the namespace-install.yaml manifest and mounted into the relevant pods at startup.

How do I add a remote Kubernetes cluster to Argo CD?

To add a remote cluster, create a Secret containing a service account token from the remote cluster with sufficient permissions (typically cluster-admin), then reference the remote API server URL in your Application's destination.server field. Argo CD uses the token from the Secret to authenticate with the remote cluster's API server.

What is the difference between argocd-cm and argocd-cmd-params-cm?

The argocd-cm ConfigMap contains high-level Argo CD settings such as repository credentials, resource customizations, and OIDC configuration. The argocd-cmd-params-cm ConfigMap, in contrast, supplies default command-line flag values for the individual components (server, repo-server, and application controller), allowing you to tune runtime behavior without modifying Deployment manifests.

How do I configure Argo CD to ignore certain resource fields during sync?

Configure resource customizations in the argocd-cm ConfigMap using the resource.customizations.ignoreResourceUpdates key. Specify JSON pointers to fields that should be ignored, such as /status for all resources. This prevents Argo CD from triggering syncs when only those fields change, reducing unnecessary operations and controller load.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}