argo-cd/docs/operator-manual/declarative-setup.md

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
  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

See application.yaml for additional fields

!!! warning By default, deleting an application will not perform a cascade delete, thereby deleting its resources. You must add the finalizer if you want this behaviour - which you may well not want.

metadata:
  finalizers:
    - resources-finalizer.argocd.argoproj.io

Application of Applications

You can create an application that creates other applications, which in turn can create other applications. This allows you to declaratively manage a group of applications that can be deployed and configured in concert.

See cluster bootstrapping.

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
  namespace: argocd
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
  namespaceResourceBlacklist:
  - 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 the argocd-cm config map. Each repository must have url field and, depending on whether you connect using HTTPS or SSH, usernameSecret and passwordSecret (for HTTPS) or sshPrivateKeySecret (for SSH).

Example for HTTPS:

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

Example for SSH:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  repositories: |
    - url: git@github.com:argoproj/my-private-repository
      sshPrivateKeySecret:
        name: my-secret
        key: sshPrivateKey    

!!! tip The Kubernetes documentation has instructions for creating a secret containing a private key.

Repository Credentials (v1.1+)

If you want to use the same credentials for multiple repositories, you can use repository.credentials:

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

Argo CD will only use the credentials if you omit usernameSecret, passwordSecret, and sshPrivateKeySecret fields (insecureIgnoreHostKey is ignored).

A credential may be match if it's URL is the prefix of the repository's URL. The means that credentials may match, e.g in the above example both https://github.com/argoproj and https://github.com would match. Argo CD selects the first one that matches.

!!! tip Order your credentials with the most specific at the top and the least specific at the bottom.

A complete example.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  repositories: |
    # this has it's own credentials
    - url: https://github.com/argoproj/private-repo
      passwordSecret:
        name: private-repo-secret
        key: password
      usernameSecret:
        name: private-repo-secret
        key: username
      sshPrivateKeySecret:
        name: private-repo-secret
        key: sshPrivateKey
    - url: https://github.com/argoproj/other-private-repo
    - url: https://github.com/otherproj/another-private-repo    
  repository.credentials: |
    # this will be used for the second repo
    - url: https://github.com/argoproj
      passwordSecret:
        name: other-private-repo-secret
        key: password
      usernameSecret:
        name: other-private-repo-secret
        key: username
      sshPrivateKeySecret:
        name: other-private-repo-secret
        key: sshPrivateKey
    # this will be used for the third repo
    - url: https://github.com
      passwordSecret:
        name: another-private-repo-secret
        key: password
      usernameSecret:
        name: another-private-repo-secret
        key: username
      sshPrivateKeySecret:
        name: another-private-repo-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.

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-secret
  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
  namespace: argocd
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=v1.0.1

# 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