Config Management Plugins

Extend Argo CD with custom config management tools

Config Management Plugins (CMPs) allow you to use custom config management tools beyond Argo CD’s native support for Helm, Kustomize, and Jsonnet.

Plugins are granted a level of trust in the Argo CD system. Only install plugins from trusted sources and audit them for security risks.

When to Use Plugins

Use a Config Management Plugin when:

• You need a config management tool not natively supported by Argo CD
• Argo CD’s native tool support lacks a feature you need
• You want to customize manifest generation beyond standard tools

Plugin Architecture

Plugins run as sidecars to the argocd-repo-server component. When configured, the repo server delegates manifest generation to the plugin.

Installing a Plugin

1. Write the Plugin Configuration

Create a ConfigManagementPlugin manifest:

apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
  name: my-plugin
spec:
  version: v1.0
  init:
    command: [sh]
    args: [-c, 'echo "Initializing..."']
  generate:
    command: [sh, -c]
    args:
      - |
        echo '{"kind": "ConfigMap", "apiVersion": "v1", "metadata": { "name": "$ARGOCD_APP_NAME", "namespace": "$ARGOCD_APP_NAMESPACE"}}'
  discover:
    fileName: "./subdir/s*.yaml"

metadata.name · string · required

Unique name for the plugin within the Argo CD instance

spec.version · string

Plugin version. If specified, use <name>-<version> in Application spec

spec.init · object

Optional command to initialize the source directory before generation

spec.generate · object · required

Command to generate Kubernetes manifests. Must output valid YAML or JSON to stdout.

spec.discover · object

Discovery rules to automatically match Applications to this plugin

2. Place Configuration in Sidecar

The plugin config must be at /home/argocd/cmp-server/config/plugin.yaml.

Option A: ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-plugin-config
data:
  plugin.yaml: |
    apiVersion: argoproj.io/v1alpha1
    kind: ConfigManagementPlugin
    metadata:
      name: my-plugin
    spec:
      version: v1.0
      generate:
        command: [sh, -c, 'echo "..."']

Option B: Custom Image

WORKDIR /home/argocd/cmp-server/config/
COPY plugin.yaml ./

3. Register Plugin Sidecar

Add sidecar to argocd-repo-server:

containers:
  - name: my-plugin
    command: [/var/run/argocd/argocd-cmp-server]
    image: ubuntu
    securityContext:
      runAsNonRoot: true
      runAsUser: 999
    volumeMounts:
      - mountPath: /var/run/argocd
        name: var-files
      - mountPath: /home/argocd/cmp-server/plugins
        name: plugins
      - mountPath: /home/argocd/cmp-server/config/plugin.yaml
        subPath: plugin.yaml
        name: my-plugin-config
      - mountPath: /tmp
        name: cmp-tmp
volumes:
  - configMap:
      name: my-plugin-config
    name: my-plugin-config
  - emptyDir: {}
    name: cmp-tmp

Critical Requirements:

• Use /var/run/argocd/argocd-cmp-server as entrypoint
• Run as user 999
• Plugin config at /home/argocd/cmp-server/config/plugin.yaml
• Separate tmp volume from repo-server (security)

Discovery Configuration

Plugins can automatically match Applications using discovery rules:

File Name Pattern

spec:
  discover:
    fileName: "kustomization.yaml"

Glob Pattern (with nested directories)

spec:
  discover:
    find:
      glob: "**/Chart.yaml"

Command-Based Discovery

spec:
  discover:
    find:
      command: [sh, -c, 'find . -name env.yaml']

Only one discovery method should be specified. Evaluated in order: fileName, find.glob, find.command.

Using a Plugin with an Application

Auto-Discovery

Let the plugin match based on discovery rules:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
spec:
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
    plugin: {}

Explicit Plugin Name

Specify the plugin explicitly:

spec:
  source:
    plugin:
      name: my-plugin-v1.0

Environment Variables

Plugin commands have access to:

1. Standard Build Environment

• ARGOCD_APP_NAME
• ARGOCD_APP_NAMESPACE
• ARGOCD_APP_REVISION
• ARGOCD_APP_SOURCE_REPO_URL
• ARGOCD_APP_SOURCE_PATH
• ARGOCD_APP_SOURCE_TARGET_REVISION
• KUBE_VERSION
• KUBE_API_VERSIONS

2. Custom Environment Variables

spec:
  source:
    plugin:
      env:
        - name: FOO
          value: bar
        - name: REV
          value: test-$ARGOCD_APP_REVISION

User-supplied env vars are prefixed with ARGOCD_ENV_ to prevent setting sensitive variables.

3. Parameters

spec:
  source:
    plugin:
      parameters:
        - name: values-files
          array: [values-dev.yaml]
        - name: helm-parameters
          map:
            image.tag: v1.2.3

Parameters are available as:

• JSON in ARGOCD_APP_PARAMETERS
• Individual env vars: PARAM_VALUES_FILES_0=values-dev.yaml

Parameter Announcements

Inform the UI about available parameters:

spec:
  parameters:
    static:
      - name: string-param
        title: Description of the string param
        tooltip: Hover text
        required: false
        itemType: string
        collectionType: string
        string: default-value
      - name: array-param
        array: [default, items]
        collectionType: array
      - name: map-param
        map:
          some: value
        collectionType: map

Advanced Configuration

Preserve File Mode

spec:
  preserveFileMode: true

Only enable if you trust the plugin. Allows executable permissions which may be a security risk.

Provide Git Credentials

spec:
  provideGitCreds: true

Only enable for trusted plugins. Shares repository credentials with the plugin.

Timeouts

Configure timeouts to prevent long-running commands:

# argocd-cmd-params-cm ConfigMap
data:
  server.repo.server.timeout.seconds: "120"
  controller.repo.server.timeout.seconds: "120"

# Plugin sidecar
env:
  - name: ARGOCD_EXEC_TIMEOUT
    value: "120s"

If repo server timeout > 90s, also increase ARGOCD_EXEC_TIMEOUT on the sidecar.

Debugging Plugins

1. Check sidecar is running

   kubectl get pod -l app.kubernetes.io/component=repo-server -n argocd
   

   Verify two containers are running.

2. Enable debug logging

   Set --loglevel=debug flag on sidecar and write to stderr.

3. Hard refresh the Application

   CMP errors are cached in Redis. Always hard refresh when developing.

4. Restart repo-server after config changes

   ConfigMap changes require pod restart to take effect.

Plugin Performance

Exclude unnecessary files from being sent to the plugin:

# argocd-cmd-params-cm
data:
  reposerver.plugin.tar.exclusions: ".git/*;.github/*;docs/*"

Use Go’s filepath.Match syntax. Exclude .git/* to significantly speed up manifest generation.

Example Plugins

Check out official example plugins for:

• Custom templating tools
• External secret management
• Custom Helm wrappers
• Integration with other GitOps tools

Security Best Practices

Audit Plugin Code

Review all plugin code before installation. Plugins have significant system access.

Minimal Images

Use minimal base images with only required tools to reduce attack surface.

Input Sanitization

Always sanitize and escape user input in plugin commands.

Separate Volumes

Use separate tmp volumes for each plugin to prevent path traversal attacks.