# How to Configure Argo CD for Kubernetes

> Learn how to configure Argo CD for Kubernetes by installing the control plane, defining clusters in Application resources, and tuning behavior via ConfigMaps and Secrets.

- Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd)
- Tags: how-to-guide
- Published: 2026-07-14

---

**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`](https://github.com/argoproj/argo-cd/blob/main/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:

```bash
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`](https://github.com/argoproj/argo-cd/blob/main/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:

```bash
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:

```yaml
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`](https://github.com/argoproj/argo-cd/blob/main/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:

```yaml
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:

```yaml
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:

```yaml
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:

```bash
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`](https://github.com/argoproj/argo-cd/blob/main/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:

```yaml
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:

```bash

# 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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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.