Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท Helm, Kustomize and Config Management

Directory Apps, Jsonnet and Config Management Plugins

Learn the other Argo CD config tools: plain YAML directories with include and exclude, Jsonnet with external variables, and sidecar config management plugins.

Helm and Kustomize cover most teams, but Argo CD supports more ways to produce manifests. This lesson covers plain directories, Jsonnet, and config management plugins (CMPs) for everything else, plus how Argo CD decides which tool to use.

Tool detection

When an Application has no explicit tool settings, the repo server inspects path:

  1. Chart.yaml present: Helm.
  2. kustomization.yaml (or .yml, Kustomization) present: Kustomize.
  3. Otherwise: directory, which reads .yaml, .yml, .json and .jsonnet files.

A plugin is used only when the Application names one or when the plugin's own discovery rule matches.

flowchart TD
  P["source.path"] --> A{"plugin set or discovered?"}
  A -- yes --> CMP["Config management plugin"]
  A -- no --> B{"Chart.yaml?"}
  B -- yes --> H["Helm"]
  B -- no --> C{"kustomization.yaml?"}
  C -- yes --> K["Kustomize"]
  C -- no --> D["Directory / Jsonnet"]

Detection order. Setting helm, kustomize, directory or plugin explicitly overrides it.

Plain directories

The simplest GitOps source is a folder of Kubernetes manifests:

YAML
spec:
  source:
    repoURL: https://git.example.com/platform/infra.git
    targetRevision: main
    path: manifests/monitoring
    directory:
      recurse: true
      include: "*.yaml"
      exclude: "{legacy/*,*.example.yaml}"
Field Meaning
recurse Also read subfolders (default is the top level only)
include A glob; only matching files are used
exclude A glob; matching files are skipped

A single file may contain several documents separated by ---. Use exclude to keep scratch or example files out of the cluster. Without recurse, a new subfolder is silently ignored, a common source of "why is it not deployed" confusion.

Jsonnet

Jsonnet is a data templating language that produces JSON. Argo CD evaluates .jsonnet files in a directory source and passes values in as external variables (extVars) or top-level arguments (tlas):

YAML
directory:
  jsonnet:
    extVars:
      - name: env
        value: prod
    tlas:
      - name: replicas
        value: "3"
        code: true
    libs:
      - vendor

A small Jsonnet file that uses them:

JSONNET
local env = std.extVar('env');
function(replicas=1) {
  apiVersion: 'v1',
  kind: 'ConfigMap',
  metadata: { name: 'settings-' + env },
  data: { replicas: std.toString(replicas) },
}

Jsonnet suits teams that want real functions and imports without a template DSL, but it has a smaller community than Helm. Use it when you already have Jsonnet libraries.

Config management plugins

A plugin lets you use any tool that can print Kubernetes manifests to standard output: cue, ytt, helmfile, SOPS wrappers, a custom script. Plugins run as sidecar containers of the repo-server pod and are described by a plugin.yaml:

YAML
apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
  name: my-generator
spec:
  version: v1.0
  init:
    command: [sh, -c, "echo preparing"]
  generate:
    command: [sh, -c]
    args:
      - |
        echo "{\"apiVersion\": \"v1\", \"kind\": \"ConfigMap\", \"metadata\": {\"name\": \"from-plugin\"}}"
  discover:
    fileName: "./plugin.marker"

The contract is simple: the generate command runs in the application's source directory and must print valid YAML or JSON (a list of resources, or documents separated by ---) to stdout. Anything on stdout that is not a manifest breaks the render, so send logs to stderr.

Use the plugin from an Application:

YAML
source:
  path: apps/custom
  plugin:
    name: my-generator-v1.0
    env:
      - name: TARGET_ENV
        value: prod
    parameters:
      - name: replicas
        string: "3"

env entries reach the plugin as environment variables prefixed with ARGOCD_ENV_. Structured parameters arrive in PARAM_* variables or as JSON in ARGOCD_APP_PARAMETERS. The sidecar also receives built-ins like ARGOCD_APP_NAME and ARGOCD_APP_NAMESPACE.

The older approach of defining plugins inside the argocd-cm ConfigMap was deprecated and then removed. Use sidecar plugins on current versions.

Weigh the cost: a plugin is code you must build, secure and upgrade, and it runs inside the repo server's trust boundary. Prefer Helm, Kustomize or Jsonnet unless you truly need something else.

Stand-in: a plugin contract checker

The runner cannot start sidecars, so this stand-in only models the stdout contract: output must parse as one or more manifests that each have apiVersion, kind and metadata.name.

Python Stand-in: validate plugin output

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A folder has Chart.yaml and kustomization.yaml and no explicit tool settings. Which tool does Argo CD use?

    Chart.yaml is checked first, so Helm wins.
  2. 2. Your manifests are in subfolders but only the top-level files deploy. What is the likely cause?

    Directory sources read only the top level unless recurse is true.
  3. 3. Where must a config management plugin print the generated manifests?

    Argo CD reads the plugin's stdout; extra log output there breaks parsing.
  4. 4. How do plugins run in current Argo CD versions?

    Sidecar plugins keep custom tools out of the main repo-server image.

Summary

  • Detection order is plugin, Helm, Kustomize, then directory.
  • Directory sources need recurse for subfolders and can filter with include and exclude.
  • Jsonnet takes extVars, tlas and libs.
  • Plugins are sidecars that print manifests to stdout; use them only when the standard tools do not fit.

Next: Multiple Sources and Value Files