Skip to main content
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us