> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# Declarative Configuration Setup

> Configure Argo CD applications, projects, and settings using declarative Kubernetes manifests

## Overview

Argo CD applications, projects, and settings can be defined declaratively using Kubernetes manifests. These can be applied using `kubectl apply` without touching the `argocd` CLI tool.

<Warning>
  All Argo CD resources, including `Application` and `AppProject` specs, must be installed in the Argo CD namespace (by default `argocd`).
</Warning>

## Configuration Resources

### Atomic Configuration

These ConfigMaps and Secrets have a single supported resource name per type:

| Resource Name               | Kind      | Description                                   |
| --------------------------- | --------- | --------------------------------------------- |
| `argocd-cm`                 | ConfigMap | General Argo CD configuration                 |
| `argocd-rbac-cm`            | ConfigMap | RBAC configuration                            |
| `argocd-cmd-params-cm`      | ConfigMap | Environment variables configuration           |
| `argocd-tls-certs-cm`       | ConfigMap | Custom TLS certificates for Git repositories  |
| `argocd-ssh-known-hosts-cm` | ConfigMap | SSH known hosts data                          |
| `argocd-secret`             | Secret    | User passwords, signing keys, webhook secrets |

<Info>
  ConfigMap resources must be annotated with the label `app.kubernetes.io/part-of: argocd` for Argo CD to use them.
</Info>

### Multiple Configuration Objects

| Resource Type      | Description                |
| ------------------ | -------------------------- |
| `Application`      | Application specifications |
| `AppProject`       | Project specifications     |
| Repository Secrets | Repository credentials     |

Application and project names are unique within an Argo CD installation.

## Applications

The Application CRD represents a deployed application instance. It is defined by:

* **source**: Reference to desired state in Git (repository, revision, path)
* **destination**: Target cluster and namespace

### Basic Application

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
```

<Note>
  The namespace must match the namespace of your Argo CD instance (typically `argocd`).
</Note>

### Helm Application

For Helm repositories, use `chart` instead of `path`:

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-helm-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://argoproj.github.io/argo-helm
    chart: argo
    targetRevision: "1.0.0"
  destination:
    server: https://kubernetes.default.svc
    namespace: argo
```

### Cascading Deletion

Without the finalizer, deleting an Application won't delete its managed resources:

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
```

### Sync Policy

Configure automated sync:

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
      allowEmpty: false
    syncOptions:
    - CreateNamespace=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m
```

## Projects

The AppProject CRD defines a logical grouping of applications with:

* **sourceRepos**: Allowed Git repositories
* **destinations**: Allowed clusters and namespaces
* **roles**: RBAC roles for project access

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: my-project
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  description: Example Project
  
  # Allow manifests to deploy from any Git repos
  sourceRepos:
  - '*'
  
  # Only permit applications to deploy to the guestbook namespace
  destinations:
  - namespace: guestbook
    server: https://kubernetes.default.svc
  
  # Deny all cluster-scoped resources from being created, except for Namespace
  clusterResourceWhitelist:
  - group: ''
    kind: Namespace
  
  # Allow all namespaced-scoped resources to be created
  namespaceResourceBlacklist:
  - group: ''
    kind: ResourceQuota
  - group: ''
    kind: LimitRange
  - group: ''
    kind: NetworkPolicy
  
  roles:
  # Read-only access to all applications in the project
  - name: read-only
    description: Read-only privileges to my-project
    policies:
    - p, proj:my-project:read-only, applications, get, my-project/*, allow
    groups:
    - my-oidc-group
  
  # CI role with sync privileges
  - name: ci-role
    description: Sync privileges for guestbook-dev
    policies:
    - p, proj:my-project:ci-role, applications, sync, my-project/guestbook-dev, allow
    jwtTokens:
    - iat: 1535390316
```

<Warning>
  Projects that can deploy to the Argo CD namespace grant admin-level access. Carefully restrict RBAC access to such projects.
</Warning>

## Repositories

Repository credentials are stored in Secrets:

### HTTPS Repository

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/argoproj/private-repo
  password: my-password
  username: my-username
  project: my-project
```

### SSH Repository

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: git@github.com:argoproj/my-private-repository.git
  sshPrivateKey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...
    -----END OPENSSH PRIVATE KEY-----
```

## Clusters

Cluster credentials are stored in Secrets:

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: mycluster-secret
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: mycluster.example.com
  server: https://mycluster.example.com
  config: |
    {
      "bearerToken": "<authentication token>",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64 encoded certificate>"
      }
    }
```

## General Configuration

The `argocd-cm` ConfigMap contains general settings:

```yaml theme={null}
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-cm
    app.kubernetes.io/part-of: argocd
data:
  # Argo CD's externally facing base URL (required for SSO)
  url: https://argo-cd-demo.argoproj.io
  
  # Enables application status badge feature
  statusbadge.enabled: "true"
  
  # Enables anonymous user access
  users.anonymous.enabled: "false"
  
  # Specifies token expiration duration
  users.session.duration: "24h"
  
  # Application reconciliation timeout
  timeout.reconciliation: 120s
  
  # Allow in-cluster server address
  cluster.inClusterEnabled: "true"
  
  # Disable admin user
  admin.enabled: "false"
  
  # Add local users
  accounts.alice: apiKey, login
  accounts.bob: apiKey
```

## RBAC Configuration

The `argocd-rbac-cm` ConfigMap defines RBAC policies:

```yaml theme={null}
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-rbac-cm
    app.kubernetes.io/part-of: argocd
data:
  policy.csv: |
    # Grant team-alpha the ability to sync apps in my-project
    p, my-org:team-alpha, applications, sync, my-project/*, allow
    # Grant team-beta admin privileges
    g, my-org:team-beta, role:admin
  
  policy.default: role:readonly
  
  scopes: '[groups]'
```

## App of Apps Pattern

Create an application that creates other applications:

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-of-apps
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: apps
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
```

The `apps` directory contains multiple Application manifests that will be created.

## Best Practices

<CardGroup cols={2}>
  <Card title="Version Control" icon="code-branch">
    Store all declarative configurations in Git for auditability and GitOps workflows.
  </Card>

  <Card title="Use Finalizers" icon="trash-can">
    Always include the resources-finalizer for proper cascading deletion of application resources.
  </Card>

  <Card title="Project Scoping" icon="folder-tree">
    Use AppProjects to implement multi-tenancy and restrict resource access.
  </Card>

  <Card title="Automated Sync" icon="rotate">
    Configure sync policies for automated deployment and self-healing capabilities.
  </Card>
</CardGroup>