Skip to content
Documentation Background

Extending Argo CD

Argo CD renders manifests with Helm, Kustomize, and Jsonnet, and shows them in a fixed web interface. Both have extension points. A config management plugin (CMP) renders manifests with any tool, and the UI accepts CSS, banners, and React components.


A CMP is a program that the repo server calls to turn a source directory into Kubernetes manifests. Reach for one when a tool Argo CD does not know must render the manifests (Tanka, cdk8s, a custom script), or when a built-in tool needs behavior Argo CD does not expose. Rendering tools covers the built-in options.

A plugin runs as a sidecar container in the argocd-repo-server Pod. The sidecar holds the tools and the plugin configuration, and the repo server talks to it over a socket. The design has three benefits:

  • Tools and their dependencies stay out of the Argo CD image, so a plugin cannot conflict with Argo CD’s own binaries
  • Upgrading Argo CD does not mean rebuilding a customized image
  • Each plugin has its own image and release cycle

Behavior is described in a ConfigManagementPlugin manifest. It looks like a Kubernetes object, but it is not a custom resource. It is a file read by the sidecar and is never applied to the cluster.

apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
name: kustomize-helm # must be unique within the Argo CD instance
spec:
version: v1.0 # optional, then Applications must name kustomize-helm-v1.0
init: # optional, runs before generate in the source directory
command: [sh, -c]
args: ['echo "preparing" >&2']
generate: # required, stdout must be only Kubernetes objects
command: [sh, -c]
args: ["kustomize build --enable-helm"]
discover: # optional, auto-matches Applications to this plugin
fileName: "kustomization.yaml"
SectionBehavior
initRuns in the source directory before each generation. Its output is ignored, a non-zero exit fails the generation. Use it to download chart dependencies
generateRuns in the source directory. Standard output must be only YAML or JSON Kubernetes objects. Write logs to standard error, which is shown in the UI on failure, so keep secrets out of it
discoverRules that match a plugin to Applications without naming it. With none, the plugin applies only when an Application names it
parametersAnnouncements that make settings editable in the UI (see below)
preserveFileModeKeeps the repository files’ Unix permissions in the sidecar. Defaults to false, since it lets repository executables run. Enable it only for trusted plugins
provideGitCredsLets the plugin request the repo server’s Git credentials. Defaults to false

A discovery rule is one of three kinds, and only the first one present is used: fileName (a glob matched in the source directory), find.glob (a glob that supports **), or find.command (run from the repository root, a match is exit code 0 with non-empty output).

A pipe in generate can hide a failing tool. A command such as kustomize build . | cat exits 0 even when kustomize fails, and with automated pruning a blank result removes the Application’s resources. Use set -o pipefail or avoid the pipe.

Put the configuration in a ConfigMap under the key plugin.yaml (baking it into the sidecar image also works, but a ConfigMap keeps environment-specific settings out of the image):

apiVersion: v1
kind: ConfigMap
metadata:
name: kustomize-helm-plugin
namespace: argocd
data:
plugin.yaml: |
apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
name: kustomize-helm
spec:
generate:
command: [sh, -c]
args: ["kustomize build --enable-helm"]

Then add a container to the repo server Deployment:

containers:
- name: kustomize-helm
image: registry.example.com/tools/kustomize-helm:1.0 # an image that contains kustomize and helm
command: [/var/run/argocd/argocd-cmp-server] # the CMP server that ships with Argo CD
securityContext:
runAsNonRoot: true
runAsUser: 999 # must match the repo server so it can read checkouts
volumeMounts:
- mountPath: /var/run/argocd # supplies the argocd-cmp-server binary
name: var-files
- mountPath: /home/argocd/cmp-server/plugins # socket the repo server uses to call the plugin
name: plugins
- mountPath: /home/argocd/cmp-server/config/plugin.yaml
subPath: plugin.yaml
name: kustomize-helm-plugin
- mountPath: /tmp # a private volume, not the repo server's
name: cmp-tmp
volumes:
- name: kustomize-helm-plugin
configMap:
name: kustomize-helm-plugin
- name: cmp-tmp
emptyDir: {}

Three requirements decide whether the plugin loads:

  1. The entrypoint is /var/run/argocd/argocd-cmp-server.
  2. The container runs as user ID 999.
  3. The configuration file is at /home/argocd/cmp-server/config/plugin.yaml.

Give the sidecar its own /tmp volume. Sharing the repo server’s volume weakens the isolation that protects against path traversal. In a Helm installation, the chart’s repoServer.extraContainers, repoServer.volumes, and related values add the container and volumes.

Verify with kubectl get pods -n argocd -l app.kubernetes.io/component=repo-server. The Pod should report 2/2 ready containers.

Name the plugin, or leave the name out so that the discovery rules select it:

spec:
source:
repoURL: https://git.example.com/org/config.git
targetRevision: main
path: apps/web
plugin:
name: kustomize-helm # or <name>-<version> when the plugin sets a version

An Application uses at most one plugin. Use plugin: {} when you rely on discovery and need to set nothing else.

Kustomize can render a Helm chart through the helmCharts field and then apply overlays and patches to the result, which needs both the kustomize and helm binaries in the sidecar image. That is useful for a community chart that exposes too few values. Building it needs the flag --enable-helm, which Argo CD supports as a global Kustomize build option in argocd-cm, but a global change affects every Application and may be out of reach for a team. A plugin enables the flag for chosen Applications only.

# kustomization.yaml in the Application's path
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
helmCharts:
- name: cert-manager
repo: https://charts.jetstack.io
version: v1.21.3
releaseName: cert-manager
namespace: cert-manager
valuesInline:
crds:
enabled: true
patches:
- target:
kind: Deployment
name: cert-manager
patch: |-
apiVersion: apps/v1
kind: Deployment
metadata:
name: cert-manager
spec:
template:
spec:
priorityClassName: system-cluster-critical

Without the plugin, an Application on this path fails manifest generation (failed to generate manifest for source 1 of 1), because the default Kustomize build lacks the flag. With plugin.name: kustomize-helm, the sidecar runs kustomize build --enable-helm and the Application syncs.

A plugin sees the sidecar’s own environment, Argo CD’s build variables (ARGOCD_APP_NAME, ARGOCD_APP_NAMESPACE, ARGOCD_APP_REVISION, KUBE_VERSION, KUBE_API_VERSIONS), and what the Application sets. Variables from the Application are given in spec.source.plugin.env and arrive with the prefix ARGOCD_ENV_, so users cannot overwrite sensitive variables:

plugin:
env:
- name: TARGET_REGION
value: eu-west-1 # the plugin reads $ARGOCD_ENV_TARGET_REGION

Parameters are the structured alternative. They can be a string, an array, or a map, and they can be announced to the UI so users can edit them in the Application’s Parameters tab. A parameter set in spec.source.plugin.parameters reaches the plugin in two forms: a JSON list in ARGOCD_APP_PARAMETERS, and one variable per value with the prefix PARAM_ (a string example-param becomes PARAM_EXAMPLE_PARAM, an array adds an index such as PARAM_NAME_0, a map adds the key path).

Announcing parameters only fills the UI. Defaults shown there are not sent to the plugin, so the plugin must apply the same defaults itself when a parameter is unset.

spec:
parameters:
static: # shown for every Application using this plugin
- name: values-files
title: Helm values files
collectionType: array
array: [values.yaml]
dynamic: # computed per Application from its source files
command: [echo, '[{"name": "image-tag", "string": "1.4.2"}]']

A dynamic command runs in the source directory and prints a JSON array in the same schema as static announcements.

  • A ConfigMap change reaches the sidecar only after the repo server Pod restarts.
  • The repo server caches plugin errors in Redis, so do a Hard Refresh after fixing a plugin.
  • Commands time out at the lesser of the repo server timeout (60 seconds by default) and ARGOCD_EXEC_TIMEOUT on the sidecar (90 seconds by default). Raise both for slow generators.
  • Exclude .git/* from the stream sent to plugins with reposerver.plugin.tar.exclusions in argocd-cmd-params-cm to speed up generation.
  • Plugins defined in argocd-cm (configManagementPlugins) were removed in Argo CD 2.8. Sidecars are the only mechanism.

A banner announces maintenance or changes at the top of every page. Set it in argocd-cm:

data:
ui.bannercontent: "Maintenance window on Saturday, 02:00 to 04:00 UTC"
ui.bannerurl: "https://status.example.com" # makes the banner a link
ui.bannerpermanent: "true" # users cannot dismiss it
ui.bannerposition: "top" # top (default), bottom, or both

Custom styles can brand an instance or tell instances apart. A red top bar on production prevents the mistake of changing the wrong environment. There are two delivery paths, both configured by ui.cssurl in argocd-cm.

A remote file:

data:
ui.cssurl: "https://assets.example.com/argocd.css"

A file mounted into argocd-server. Put the CSS in the optional ConfigMap argocd-styles-cm, mount it into a subdirectory of /shared/app, and point ui.cssurl at it relative to /shared/app:

# argocd-cm
data:
ui.cssurl: "./custom/my-styles.css"
# argocd-styles-cm
data:
my-styles.css: |
.top-bar__title { color: #fff !important; }
div.top-bar__left-side { background: #c0392b; }
# argocd-server Deployment, container and pod spec excerpts
volumeMounts:
- mountPath: /shared/app/custom
name: styles
volumes:
- name: styles
configMap:
name: argocd-styles-cm

The directory must sit under /shared/app, or the browser rejects the file for an incorrect MIME type. Class names come from the argo-ui project and can change between releases, so test overrides in the browser developer tools first.

SettingEffect
pref.argocd.argoproj.io/default-view annotation on an ApplicationOpens the details page in tree, pods, network, or list
pref.argocd.argoproj.io/default-pod-sort annotationGroups the pods view by node, parentResource, or topLevelResource
application.allowedNodeLabels in argocd-cmShows chosen node labels, such as the zone, in the pods view
help.download.<os>-<arch> in argocd-cmAdds CLI download buttons for other platforms on the Help page

The UI is a React application, so it can load additional components. An extension is a JavaScript file named extension*.js that sits in a directory under /tmp/extensions in the argocd-server Pod. It registers itself through the global window.extensionsAPI and uses the React global instead of bundling its own copy.

TypeRegistration methodAppears as
Resource tabregisterResourceExtension(component, group, kind, tabTitle)An extra tab in the side panel of a matching resource
System levelregisterSystemLevelExtension(component, title, path, icon)A new item in the left navigation with a full page
Status panelregisterStatusPanelExtension(component, title, id)A widget in the Application’s summary bar, optionally with a flyout
Application tabA resource tab with group argoproj.io and kind ApplicationAn extra tab on the Application itself
((window) => {
const component = () =>
React.createElement("div", { style: { padding: "10px" } }, "Runbooks for this application");
window.extensionsAPI.registerResourceExtension(
component, "argoproj.io", "Application", "Runbooks"
);
})(window);

Deliver the file in a ConfigMap mounted into /tmp/extensions, or use the Argo CD Extension Installer project to download extensions into the server at start-up. Restart argocd-server after changing the files. Extensions run in every user’s browser with that user’s session, so treat them as trusted code. Metrics dashboards embedded in the resource tab are a common community extension.


SymptomLikely causeFix
Repo server Pod shows 1/2 ready or crash-loopsThe sidecar command, user, or plugin.yaml path is wrongCheck the three requirements, and read the sidecar logs
The plugin is not found, or never matchesThe name omits the -<version> suffix, or no discovery rule matchesUse <name>-<version> or fix the discover rule
Manifest generation fails with a parse errorgenerate printed something other than Kubernetes objects to standard outputSend logs to standard error
Edits to the plugin have no effectThe ConfigMap is cached by the Pod, or a failed result is cached in RedisRestart the repo server, then Hard Refresh the Application
Generation times outThe command exceeds the repo server timeout or ARGOCD_EXEC_TIMEOUTRaise server.repo.server.timeout.seconds, controller.repo.server.timeout.seconds, and the sidecar variable
An Application is pruned empty after a plugin failureA pipe in generate swallowed the errorUse set -o pipefail
no matches for kind "ConfigManagementPlugin"The configuration was applied to the cluster as a CRDPlace it in the sidecar instead
Custom CSS is ignoredThe path is outside /shared/app, or ui.cssurl is wrongMount under /shared/app/<dir> and use a relative ui.cssurl
A UI extension does not appearThe file name does not match extension*.js, or argocd-server was not restartedRename the file and restart the server