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.
Config management plugins
Section titled “Config management plugins”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
The plugin configuration file
Section titled “The plugin configuration file”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/v1alpha1kind: ConfigManagementPluginmetadata: name: kustomize-helm # must be unique within the Argo CD instancespec: 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"| Section | Behavior |
|---|---|
init | Runs in the source directory before each generation. Its output is ignored, a non-zero exit fails the generation. Use it to download chart dependencies |
generate | Runs 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 |
discover | Rules that match a plugin to Applications without naming it. With none, the plugin applies only when an Application names it |
parameters | Announcements that make settings editable in the UI (see below) |
preserveFileMode | Keeps the repository files’ Unix permissions in the sidecar. Defaults to false, since it lets repository executables run. Enable it only for trusted plugins |
provideGitCreds | Lets 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.
Installing the sidecar
Section titled “Installing the sidecar”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: v1kind: ConfigMapmetadata: name: kustomize-helm-plugin namespace: argocddata: 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-tmpvolumes:- name: kustomize-helm-plugin configMap: name: kustomize-helm-plugin- name: cmp-tmp emptyDir: {}Three requirements decide whether the plugin loads:
- The entrypoint is
/var/run/argocd/argocd-cmp-server. - The container runs as user ID 999.
- 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.
Using the plugin from an Application
Section titled “Using the plugin from an Application”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 versionAn Application uses at most one plugin. Use plugin: {} when you rely on discovery and need to set nothing else.
Example: Kustomize with Helm inflation
Section titled “Example: Kustomize with Helm inflation”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 pathapiVersion: kustomize.config.k8s.io/v1beta1kind: KustomizationhelmCharts:- name: cert-manager repo: https://charts.jetstack.io version: v1.21.3 releaseName: cert-manager namespace: cert-manager valuesInline: crds: enabled: truepatches:- target: kind: Deployment name: cert-manager patch: |- apiVersion: apps/v1 kind: Deployment metadata: name: cert-manager spec: template: spec: priorityClassName: system-cluster-criticalWithout 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.
Environment variables and parameters
Section titled “Environment variables and parameters”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_REGIONParameters 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.
Operating plugins
Section titled “Operating plugins”- 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_TIMEOUTon the sidecar (90 seconds by default). Raise both for slow generators. - Exclude
.git/*from the stream sent to plugins withreposerver.plugin.tar.exclusionsinargocd-cmd-params-cmto speed up generation. - Plugins defined in
argocd-cm(configManagementPlugins) were removed in Argo CD 2.8. Sidecars are the only mechanism.
UI customization
Section titled “UI customization”Banner
Section titled “Banner”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 bothCustom CSS
Section titled “Custom CSS”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-cmdata: ui.cssurl: "./custom/my-styles.css"# argocd-styles-cmdata: my-styles.css: | .top-bar__title { color: #fff !important; } div.top-bar__left-side { background: #c0392b; }# argocd-server Deployment, container and pod spec excerptsvolumeMounts:- mountPath: /shared/app/custom name: stylesvolumes:- name: styles configMap: name: argocd-styles-cmThe 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.
Default views and small settings
Section titled “Default views and small settings”| Setting | Effect |
|---|---|
pref.argocd.argoproj.io/default-view annotation on an Application | Opens the details page in tree, pods, network, or list |
pref.argocd.argoproj.io/default-pod-sort annotation | Groups the pods view by node, parentResource, or topLevelResource |
application.allowedNodeLabels in argocd-cm | Shows chosen node labels, such as the zone, in the pods view |
help.download.<os>-<arch> in argocd-cm | Adds CLI download buttons for other platforms on the Help page |
UI extensions
Section titled “UI extensions”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.
| Type | Registration method | Appears as |
|---|---|---|
| Resource tab | registerResourceExtension(component, group, kind, tabTitle) | An extra tab in the side panel of a matching resource |
| System level | registerSystemLevelExtension(component, title, path, icon) | A new item in the left navigation with a full page |
| Status panel | registerStatusPanelExtension(component, title, id) | A widget in the Application’s summary bar, optionally with a flyout |
| Application tab | A resource tab with group argoproj.io and kind Application | An 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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
Repo server Pod shows 1/2 ready or crash-loops | The sidecar command, user, or plugin.yaml path is wrong | Check the three requirements, and read the sidecar logs |
| The plugin is not found, or never matches | The name omits the -<version> suffix, or no discovery rule matches | Use <name>-<version> or fix the discover rule |
| Manifest generation fails with a parse error | generate printed something other than Kubernetes objects to standard output | Send logs to standard error |
| Edits to the plugin have no effect | The ConfigMap is cached by the Pod, or a failed result is cached in Redis | Restart the repo server, then Hard Refresh the Application |
| Generation times out | The command exceeds the repo server timeout or ARGOCD_EXEC_TIMEOUT | Raise server.repo.server.timeout.seconds, controller.repo.server.timeout.seconds, and the sidecar variable |
| An Application is pruned empty after a plugin failure | A pipe in generate swallowed the error | Use set -o pipefail |
no matches for kind "ConfigManagementPlugin" | The configuration was applied to the cluster as a CRD | Place it in the sidecar instead |
| Custom CSS is ignored | The path is outside /shared/app, or ui.cssurl is wrong | Mount under /shared/app/<dir> and use a relative ui.cssurl |
| A UI extension does not appear | The file name does not match extension*.js, or argocd-server was not restarted | Rename the file and restart the server |