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.

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

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

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

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

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

The namespace must match the namespace of your Argo CD instance (typically argocd).

Helm Application

For Helm repositories, use chart instead of path:

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:

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:

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

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

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

Repositories

Repository credentials are stored in Secrets:

HTTPS Repository

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

apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: [e-mail]:argoproj/my-private-repository.git
  sshPrivateKey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...
    -----END OPENSSH PRIVATE KEY-----

Clusters

Cluster credentials are stored in Secrets:

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:

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:

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:

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

Version Control

Store all declarative configurations in Git for auditability and GitOps workflows.

Use Finalizers

Always include the resources-finalizer for proper cascading deletion of application resources.

Project Scoping

Use AppProjects to implement multi-tenancy and restrict resource access.

Automated Sync

Configure sync policies for automated deployment and self-healing capabilities.