Declarative Setup

Argo CD applications, projects and settings can be defined declaratively using Kubernetes manifests.

Quick Reference

Name Kind Description
argocd-cm.yaml ConfigMap General Argo CD configuration
argocd-secret.yaml Secret Password, Certificates, Signing Key
argocd-rbac-cm.yaml ConfigMap RBAC Configuration
application.yaml Application Example application spec
project.yaml AppProject Example project spec

Applications

The Application CRD is the Kubernetes resource object representing a deployed application instance in an environment. It is defined by two key pieces of information:

  • source reference to the desired state in git (repository, revision, path, environment)
  • destination reference to the target cluster and namespace.

A minimal Application spec is as follows:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
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

See application.yaml for additional fields

Projects

The AppProject CRD is the Kubernetes resource object representing a logical grouping of applications. It is defined by the following key pieces of information:

  • sourceRepos reference to the repositories that applications within the project can pull manifests from.
  • destinations reference to clusters and namespaces that applications within the project can deploy into.
  • roles list of entities with definitions of their access to resources within the project.

An example spec is as follows:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: my-project
spec:
  description: Example Project
  # Allow manifests to deploy from any git repos
  sourceRepos:
  - '*'
  # Only permit applications to deploy to the guestbook namespace in the same cluster
  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, except for ResourceQuota, LimitRange, NetworkPolicy
  clusterResourceWhitelist:
  - group: ''
    kind: ResourceQuota
  - group: ''
    kind: LimitRange
  - group: ''
    kind: NetworkPolicy
  roles:
  # A role which provides 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
  # A role which provides sync privileges to only the guestbook-dev application, e.g. to provide
  # sync privileges to a CI system
  - name: ci-role
    description: Sync privileges for guestbook-dev
    policies:
    - p, proj:my-project:ci-role, applications, sync, my-project/guestbook-dev, allow
    # NOTE: JWT tokens can only be generated by the API server and the token is not persisted
    # anywhere by Argo CD. It can be prematurely revoked by removing the entry from this list.
    jwtTokens:
    - iat: 1535390316

Repositories

Repository credentials are stored in secret. Use following steps to configure a repo:

  1. Create secret which contains repository credentials. Consider using bitnami-labs/sealed-secrets to store encrypted secret definition as a Kubernetes manifest.

  2. Register repository in argocd-cm config map. Each repository must have url field and usernameSecret, passwordSecret or sshPrivateKeySecret.

Example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
data:
  repositories: |
    - url: https://github.com/argoproj/my-private-repository
      passwordSecret:
        name: my-secret
        key: password
      usernameSecret:
        name: my-secret
        key: username
      sshPrivateKeySecret:
        name: my-secret
        key: sshPrivateKey

Clusters

Cluster credentials are stored in secrets same as repository credentials but does not require entry in argocd-cm config map. Each secret must have label argocd.argoproj.io/secret-type: cluster and name which is following convention: <hostname>-<port>.

The secret data must include following fields:

  • name - cluster name
  • server - cluster api server url
  • config - JSON representation of following data structure:
# Basic authentication settings
username: string
password: string
# Bearer authentication settings
bearerToken: string
# IAM authentication configuration
awsAuthConfig:
    clusterName: string
    roleARN: string
# Transport layer security configuration settings
tlsClientConfig:
    # PEM-encoded bytes (typically read from a client certificate file).
    caData: string
    # PEM-encoded bytes (typically read from a client certificate file).
    certData: string
    # Server should be accessed without verifying the TLS certificate
    insecure: boolean
    # PEM-encoded bytes (typically read from a client certificate key file).
    keyData: string
    # ServerName is passed to the server for SNI and is used in the client to check server
    # ceritificates against. If ServerName is empty, the hostname used to contact the
    # server is used.
    serverName: string

Cluster secret example:

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

Helm Chart repositories

Non standard Helm Chart repositories have to be registered under the helm.repositories key in the argocd-cm ConfigMap. Each repository must have url and name fields. For private Helm repos you may need to configure access credentials and HTTPS settings using usernameSecret, passwordSecret, caSecret, certSecret and keySecret fields.

Example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
data:
  helm.repositories: |
    - url: https://storage.googleapis.com/istio-prerelease/daily-build/master-latest-daily/charts
      name: istio.io
    - url: https://argoproj.github.io/argo-helm
      name: argo
      usernameSecret:
        name: my-secret
        key: username
      passwordSecret:
        name: my-secret
        key: password
      caSecret:
        name: my-secret
        key: ca
      certSecret:
        name: my-secret
        key: cert
      keySecret:
        name: my-secret
        key: key

Resource Exclusion

Resources can be excluded from discovery and sync so that ArgoCD is unaware of them. For example, events.k8s.io and metrics.k8s.io are always excluded. Use cases:

  • You have temporal issues and you want to exclude problematic resources.
  • There are many of a kind of resources that impacts ArgoCD's performance.
  • Restrict ArgoCD's access to certain kinds of resources, e.g. secrets. See security.md#cluster-rbac.

To configure this, edit the argcd-cm config map:

kubectl edit configmap argocd-cm -n argocdconfigmap/argocd-cm edited

Add resource.exclusions, e.g.:

apiVersion: v1
data:
  resource.exclusions: |
    - apiGroups:
      - "*"
      kinds:
      - "*"
      clusters:
      - https://192.168.0.20
kind: ConfigMap

The resource.exclusions node is a list of objects. Each object can have:

  • apiGroups A list of globs to match the API group.
  • kinds A list of kinds to match. Can be "*" to match all.
  • cluster A list of globs to match the cluster.

If all three match, then the resource is ignored.

Notes:

  • Quote globs in your YAML to avoid parsing errors.
  • Invalid globs result in the whole rule being ignored.
  • If you add a rule that matches existing resources, these will appear in the interface as OutOfSync.

SSO & RBAC

  • SSO configuration details: SSO
  • RBAC configuration details: RBAC

Manage Argo CD using Argo CD

Argo CD is able to manage itself since all settings are represented by Kubernetes manifests. The suggested way is to create Kustomize based application which uses base Argo CD manifests from https://github.com/argoproj/argo-cd and apply required changes on top.

Example of kustomization.yaml:

bases:
- github.com/argoproj/argo-cd//manifests/cluster-install?ref=v0.10.6

# additional resources like ingress rules, cluster and repository secrets.
resources:
- clusters-secrets.yaml
- repos-secrets.yaml

# changes to config maps
patchesStrategicMerge:
- overlays/argo-cd-cm.yaml

The live example of self managed Argo CD config is available at https://cd.apps.argoproj.io and with configuration stored at argoproj/argoproj-deployments.

NOTE: You will need to sign-in using your github account to get access to https://cd.apps.argoproj.io