Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Applications and Projects

Argo CD Sources and Destinations: Git, Helm, OCI and Clusters

Learn every kind of Argo CD source (plain directory, Helm, Kustomize, plugins, OCI) and destination (in-cluster, external cluster, namespace), how tool detection works and how revisions resolve.

An Application answers two questions: where do the manifests come from and where should they go. The first is the source, the second the destination. Both have more variety than the first examples suggest. This lesson lists the choices so you can pick the right one for each workload.

The YAML below is real Argo CD configuration but cannot run on this site. The runnable blocks are stand-ins (a tool detector and a revision resolver) that illustrate the logic in JavaScript.

Source types

Argo CD supports several ways of turning a repository path into Kubernetes objects. If you do not say which one to use, it detects the tool from the files in path:

Files found in path Detected tool
Chart.yaml Helm
kustomization.yaml (or .yml, Kustomization) Kustomize
Neither Directory of plain YAML/JSON (and Jsonnet)

You can also force one with a tool block under source.

Directory

YAML
source:
  repoURL: https://github.com/example/config.git
  targetRevision: main
  path: apps/hello
  directory:
    recurse: true
    include: '*.yaml'
    exclude: 'tests/*'

recurse: true includes subdirectories (off by default). include and exclude are glob patterns to filter files. Jsonnet files are also supported through directory.jsonnet.

Helm

YAML
source:
  repoURL: https://charts.example.com
  chart: nginx
  targetRevision: 15.4.0
  helm:
    releaseName: web
    valueFiles:
      - values-production.yaml
    parameters:
      - name: replicaCount
        value: "3"

Use chart instead of path for a chart from a Helm repository. A chart stored in Git uses path. Helm, Kustomize and Config Management covers the details in its own chapter.

Kustomize

YAML
source:
  repoURL: https://github.com/example/config.git
  targetRevision: main
  path: apps/shop/overlays/production
  kustomize:
    namePrefix: prod-
    images:
      - registry.example.com/shop/web:1.8.2

OCI registries

Helm charts (and with newer releases, other manifest artifacts) can be stored in an OCI registry. Use an oci:// URL, for example repoURL: oci://registry.example.com/charts with chart and targetRevision.

Config management plugins

For tools Argo CD does not know (cdk8s, Tanka, your own generators) a config management plugin runs as a sidecar container to the repo server and prints manifests. Reach for it only when Helm, Kustomize and plain YAML cannot do the job.

Multiple sources

sources: combines several. A common use is a chart from a Helm repository plus a values file from your Git repository, referenced with ref:

YAML
sources:
  - repoURL: https://charts.example.com
    chart: nginx
    targetRevision: 15.4.0
    helm:
      valueFiles:
        - $values/envs/production/nginx.yaml
  - repoURL: https://github.com/example/config.git
    targetRevision: main
    ref: values

Revisions: what does targetRevision accept?

  • A branch (main): the latest commit on it is used; the app follows the branch.
  • A tag (v1.8.2): fixed, unless the tag is moved.
  • A commit SHA: completely fixed and the most reproducible.
  • HEAD: the default branch's tip.
  • For Helm charts: an exact version, or a semver range (1.*, ~1.2.0, >=1.0.0 <2.0.0).

For production, pin to a tag or a SHA that the promotion process updates.

Stand-in: tool detection and revision kinds

This model detects the tool from a list of file names and classifies a revision string.

JS Stand-in: detect tool and revision

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Destinations

YAML
destination:
  server: https://kubernetes.default.svc   # the cluster Argo CD runs in
  namespace: shop

or

YAML
destination:
  name: production-eu                       # a registered cluster by name
  namespace: shop
  • In-cluster (https://kubernetes.default.svc) is always registered. Argo CD's own service account is used.
  • External clusters are registered with argocd cluster add <kubeconfig-context>, which creates a service account in the target cluster and stores its token in a Secret in Argo CD (Multi-cluster and ApplicationSets is covered later).
  • namespace is the default namespace for namespaced resources that do not specify one. A manifest with its own metadata.namespace is applied there instead (if the project permits), which is why hard-coded namespaces are best avoided.
  • Cluster-scoped resources (Namespaces, ClusterRoles, CRDs) ignore namespace and need permission through the AppProject.

Stand-in: where will each resource land?

This model resolves the namespace for a few resources the way the rules above describe.

JS Stand-in: namespace resolution

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A path contains Chart.yaml and no other hint. Which tool does Argo CD use?

    A Chart.yaml triggers Helm detection.
  2. 2. Which targetRevision is the most reproducible?

    A SHA never moves. Branches and HEAD follow new commits; a range floats within limits.
  3. 3. What is the in-cluster destination server URL?

    That in-cluster service address always points at the cluster Argo CD runs in.
  4. 4. When would you use spec.sources with a ref?

    A ref names a source so another source can reference its files, for example with $values/.

Summary

  • Sources: plain directory, Helm, Kustomize, OCI artifacts and config management plugins.
  • Argo CD detects the tool from the files unless you configure one explicitly.
  • targetRevision can be a branch, tag, SHA, HEAD or (for charts) a version range; pin for production.
  • Destinations are a cluster (server or name) plus a namespace.
  • Hard-coded namespaces override the destination; cluster-scoped resources need project permission.

Next: AppProjects