> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## 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:

```yaml theme={null}
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"
```

<ParamField path="metadata.name" type="string" required>
  Unique name for the plugin within the Argo CD instance
</ParamField>

<ParamField path="spec.version" type="string">
  Plugin version. If specified, use `<name>-<version>` in Application spec
</ParamField>

<ParamField path="spec.init" type="object">
  Optional command to initialize the source directory before generation
</ParamField>

<ParamField path="spec.generate" type="object" required>
  Command to generate Kubernetes manifests. Must output valid YAML or JSON to stdout.
</ParamField>

<ParamField path="spec.discover" type="object">
  Discovery rules to automatically match Applications to this plugin
</ParamField>

### 2. Place Configuration in Sidecar

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

**Option A: ConfigMap**

```yaml theme={null}
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**

```dockerfile theme={null}
WORKDIR /home/argocd/cmp-server/config/
COPY plugin.yaml ./
```

### 3. Register Plugin Sidecar

Add sidecar to `argocd-repo-server`:

```yaml theme={null}
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
```

<Note>
  **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)
</Note>

## Discovery Configuration

Plugins can automatically match Applications using discovery rules:

### File Name Pattern

```yaml theme={null}
spec:
  discover:
    fileName: "kustomization.yaml"
```

### Glob Pattern (with nested directories)

```yaml theme={null}
spec:
  discover:
    find:
      glob: "**/Chart.yaml"
```

### Command-Based Discovery

```yaml theme={null}
spec:
  discover:
    find:
      command: [sh, -c, 'find . -name env.yaml']
```

<Info>
  Only one discovery method should be specified. Evaluated in order: `fileName`, `find.glob`, `find.command`.
</Info>

## Using a Plugin with an Application

### Auto-Discovery

Let the plugin match based on discovery rules:

```yaml theme={null}
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:

```yaml theme={null}
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

```yaml theme={null}
spec:
  source:
    plugin:
      env:
        - name: FOO
          value: bar
        - name: REV
          value: test-$ARGOCD_APP_REVISION
```

<Warning>
  User-supplied env vars are prefixed with `ARGOCD_ENV_` to prevent setting sensitive variables.
</Warning>

### 3. Parameters

```yaml theme={null}
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:

```yaml theme={null}
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

```yaml theme={null}
spec:
  preserveFileMode: true
```

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

### Provide Git Credentials

```yaml theme={null}
spec:
  provideGitCreds: true
```

<Warning>
  Only enable for trusted plugins. Shares repository credentials with the plugin.
</Warning>

## Timeouts

Configure timeouts to prevent long-running commands:

```yaml theme={null}
# argocd-cmd-params-cm ConfigMap
data:
  server.repo.server.timeout.seconds: "120"
  controller.repo.server.timeout.seconds: "120"
```

```yaml theme={null}
# Plugin sidecar
env:
  - name: ARGOCD_EXEC_TIMEOUT
    value: "120s"
```

<Tip>
  If repo server timeout > 90s, also increase `ARGOCD_EXEC_TIMEOUT` on the sidecar.
</Tip>

## Debugging Plugins

<Steps>
  <Step title="Check sidecar is running">
    ```bash theme={null}
    kubectl get pod -l app.kubernetes.io/component=repo-server -n argocd
    ```

    Verify two containers are running.
  </Step>

  <Step title="Enable debug logging">
    Set `--loglevel=debug` flag on sidecar and write to stderr.
  </Step>

  <Step title="Hard refresh the Application">
    CMP errors are cached in Redis. Always hard refresh when developing.
  </Step>

  <Step title="Restart repo-server after config changes">
    ConfigMap changes require pod restart to take effect.
  </Step>
</Steps>

## Plugin Performance

Exclude unnecessary files from being sent to the plugin:

```yaml theme={null}
# argocd-cmd-params-cm
data:
  reposerver.plugin.tar.exclusions: ".git/*;.github/*;docs/*"
```

<Tip>
  Use Go's filepath.Match syntax. Exclude `.git/*` to significantly speed up manifest generation.
</Tip>

## Example Plugins

Check out [official example plugins](https://github.com/argoproj/argo-cd/tree/master/examples/plugins) for:

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

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Audit Plugin Code" icon="magnifying-glass">
    Review all plugin code before installation. Plugins have significant system access.
  </Card>

  <Card title="Minimal Images" icon="shield">
    Use minimal base images with only required tools to reduce attack surface.
  </Card>

  <Card title="Input Sanitization" icon="filter">
    Always sanitize and escape user input in plugin commands.
  </Card>

  <Card title="Separate Volumes" icon="folder-tree">
    Use separate tmp volumes for each plugin to prevent path traversal attacks.
  </Card>
</CardGroup>