Jsonnet

Use Jsonnet templates with Argo CD

Argo CD supports Jsonnet for templating Kubernetes manifests. Any file matching *.jsonnet in a directory application is treated as Jsonnet and evaluated to generate manifests.

Basic Jsonnet Application

Argo CD automatically detects Jsonnet files and evaluates them:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: jsonnet-app
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: jsonnet-guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: default

External Variables

Pass external variables to Jsonnet templates:

spec:
  source:
    directory:
      jsonnet:
        extVars:
          - name: app
            value: $ARGOCD_APP_NAME
          - name: environment
            value: production
          - name: replicas
            value: "3"

extVars · array

List of external variables passed to Jsonnet. Values are treated as strings.

Top-Level Arguments (TLAs)

Provide top-level arguments to Jsonnet:

spec:
  source:
    directory:
      jsonnet:
        tlas:
          - name: ns
            value: $ARGOCD_APP_NAMESPACE
          - name: clusterName
            value: production-cluster

tlas · array

List of top-level arguments passed to Jsonnet functions

Shared Libraries

Add shared library paths (e.g., vendor folders) relative to the repository root:

spec:
  source:
    directory:
      jsonnet:
        libs:
          - vendor
          - lib

libs · array

List of library paths available to Jsonnet imports

Complete Example

Application with all Jsonnet features:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: jsonnet-example
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/myrepo.git
    targetRevision: HEAD
    path: jsonnet-app
    directory:
      jsonnet:
        extVars:
          - name: app
            value: $ARGOCD_APP_NAME
          - name: environment
            value: production
        tlas:
          - name: ns
            value: $ARGOCD_APP_NAMESPACE
        libs:
          - vendor
  destination:
    server: https://kubernetes.default.svc
    namespace: production

Build Environment

Jsonnet applications have access to standard build environment variables:

• ARGOCD_APP_NAME - The application name
• ARGOCD_APP_NAMESPACE - The application namespace
• ARGOCD_APP_REVISION - The git revision being deployed
• ARGOCD_APP_SOURCE_REPO_URL - The source repository URL
• ARGOCD_APP_SOURCE_PATH - The path within the repository
• ARGOCD_APP_SOURCE_TARGET_REVISION - The target revision

Use these in external variables and TLAs with the $VARIABLE_NAME syntax.

CLI Usage

Configure Jsonnet via CLI:

# Add external variable
argocd app create APPNAME \
  --jsonnet-ext-var-str 'app=${ARGOCD_APP_NAME}'

# Add TLA
argocd app create APPNAME \
  --jsonnet-tla-str 'ns=${ARGOCD_APP_NAMESPACE}'

# Add library path
argocd app create APPNAME \
  --jsonnet-libs 'vendor'

Jsonnet Output

Argo CD evaluates Jsonnet and expects valid Kubernetes objects or arrays:

Single Object

{
  apiVersion: 'v1',
  kind: 'ConfigMap',
  metadata: {
    name: 'my-config',
    namespace: 'default'
  },
  data: {
    key: 'value'
  }
}

Use Jsonnet’s powerful templating features to reduce duplication and dynamically generate manifests based on parameters.