ArgoCD Configuration
After installing the ArgoPlane Helm chart, you need to configure ArgoCD to route extension requests, mount custom styles, and load UI bundles. The chart deploys backends and generates ConfigMaps with all the config you need. This page walks through wiring it up.
How ArgoCD extensions work
ArgoCD extensions have three layers:
- UI bundle (JavaScript): registers tabs, panels, or pages via
window.extensionsAPI. ArgoCD loads any file matchingextension*.jsfrom/tmp/extensions/inside the argocd-server pod. - Proxy routing (
argocd-cm): maps/extensions/<name>/*requests to a backend service URL. - RBAC (
argocd-rbac-cm): grants roles permission to invoke specific extensions.
The Helm chart handles layer 2 and 3 via ConfigMaps. Layer 1 (UI bundles) needs an init container or sidecar on argocd-server.
Step 1: Enable proxy extensions
Tell ArgoCD to enable the proxy extension mechanism:
kubectl -n argocd patch cm argocd-cmd-params-cm --type merge
-p '{"data":{"server.enable.proxy.extension":"true"}}' Step 2: Add proxy routing
The chart generates argoplane-proxy-config with the correct routing entries. Merge them into argocd-cm:
kubectl -n argocd patch cm argocd-cm --type merge -p '{
"data": {
"extension.config.metrics": "services:\n- url: http://argoplane-metrics-backend.argocd.svc:8080\n",
"extension.config.networking": "services:\n- url: http://argoplane-networking-backend.argocd.svc:8082\n",
"extension.config.logs": "services:\n- url: http://argoplane-logs-backend.argocd.svc:8083\n",
"extension.config.vulnerabilities": "services:\n- url: http://argoplane-vulnerabilities-backend.argocd.svc:8084\n",
"extension.config.events": "services:\n- url: http://argoplane-events-backend.argocd.svc:8085\n",
"extension.config.alerts": "services:\n- url: http://argoplane-alerts-backend.argocd.svc:8086\n"
}
}' Each entry routes /extensions/<name>/* to the corresponding backend service. ArgoCD validates the user’s auth token before proxying.
Step 3: Configure RBAC
ArgoCD v3 requires explicit RBAC for extensions. The chart generates argoplane-rbac-config with policies. View them:
kubectl -n argocd get cm argoplane-rbac-config
-o jsonpath='{.data.argoplane-policy.csv}' Add the output to your argocd-rbac-cm ConfigMap’s policy.csv field:
p, role:admin, extensions, invoke, metrics, allow
p, role:admin, extensions, invoke, networking, allow
p, role:admin, extensions, invoke, logs, allow
p, role:admin, extensions, invoke, vulnerabilities, allow
p, role:admin, extensions, invoke, events, allow
p, role:admin, extensions, invoke, alerts, allow
p, role:developer, extensions, invoke, metrics, allow
p, role:developer, extensions, invoke, logs, allow
p, role:developer, extensions, invoke, vulnerabilities, allow
p, role:developer, extensions, invoke, events, allow
p, role:developer, extensions, invoke, alerts, allow Namespace authorization
ArgoCD’s RBAC decides who may invoke an extension. On top of that, every ArgoPlane backend enforces namespace scoping on its data endpoints:
- Each request must carry the
Argocd-Application-Nameheader innamespace:nameformat. ArgoCD’s proxy sets it automatically; requests without it get a403. - The backend fetches that Application from the Kubernetes API and builds the set of namespaces it manages: the destination namespace plus every namespace in
status.resources. Resources in theargoproj.iogroup are skipped, so an app-of-apps does not gain access to the ArgoCD namespace through its child Application CRs. The events, networking and vulnerabilities backends cache the Application for 10 seconds, because one UI refresh sends several requests. - If the requested namespace is not in that set, the backend returns
403 namespace not managed by this application.
The result: a user can only pull metrics, logs, flows, vulnerabilities, or events for namespaces their Application actually deploys to, even if they craft requests by hand.
This relies on the identity headers coming from argocd-server. A pod that reaches a backend Service directly could set them itself. The Helm chart therefore deploys a NetworkPolicy that admits traffic to the backends only from pods labeled app.kubernetes.io/name: argocd-server (and the chart’s own test pods). If your argocd-server pods carry different labels, set networkPolicy.argocdServerSelector. If you deploy with the dev manifests or Kustomize instead of the chart, add an equivalent policy yourself.
Multi-cluster ArgoCD
The networking backend reads from the cluster it runs in, and so do the events and vulnerabilities backends unless you enable the mode described below. If one ArgoCD deploys to several clusters, an app targeting cluster X with namespace payments would otherwise see this cluster’s payments namespace, which may belong to another team.
Set CLUSTER_NAME, CLUSTER_SERVER or both on those backends to name the cluster they read from. The backend then rejects apps whose spec.destination points elsewhere with 403 application deploys to a cluster this backend does not serve. An app matches if its destination.name equals CLUSTER_NAME or its destination.server equals CLUSTER_SERVER (a trailing slash is ignored). Apps often set only one of the two, so set both. With neither set, the check is off.
extensions:
events:
env:
CLUSTER_NAME: "in-cluster"
CLUSTER_SERVER: "https://kubernetes.default.svc" To serve several clusters this way, run one backend per cluster and list each in the proxy config with a cluster: { name | server } entry, so ArgoCD routes every app to the backend for its cluster. The check then catches requests that reach the wrong one.
One backend for every cluster (events, vulnerabilities)
The events and vulnerabilities backends can instead read from whichever cluster an Application deploys to, so a single instance beside ArgoCD serves them all. Each reads the cluster Secrets ArgoCD already maintains and builds a client per destination.
It is off by default and enabled per backend; a single-cluster install is unaffected either way. The example enables it for vulnerabilities; the same two values under events do the same there.
extensions:
vulnerabilities:
env:
MULTI_CLUSTER: "true"
rbac:
namespacedRules:
- apiGroups: [""]
resources: ["secrets"]
verbs: ["list"] MULTI_CLUSTER and CLUSTER_NAME/CLUSTER_SERVER are mutually exclusive. If you have followed the section above and pinned the backend to one cluster, an app targeting any other is rejected with 403 application deploys to a cluster this backend does not serve before the lookup ever runs. Remove those two variables when enabling MULTI_CLUSTER.
list returns full Secret data exactly as get does. Each backend with the grant can therefore read everything in the ArgoCD namespace: argocd-secret, every repository credential, and every registered cluster's credentials, which are usually cluster-admin. That is a privilege escalation path.
server.secretkey in argocd-secret signs ArgoCD tokens, so anyone who gets code execution in the backend, or tricks it into reading for them, can mint an ArgoCD admin token and deploy anything to every cluster ArgoCD manages. Keeping the rule namespaced only keeps workload Secrets elsewhere out of reach. Enable it only on the backends that need it, keep the chart's NetworkPolicy in place so only argocd-server can reach them, and restrict who can exec into their pods or change their images as tightly as you do for argocd-server.
Supported cluster Secret auth:
| Method | Supported |
|---|---|
bearerToken | Yes |
execProviderConfig running argocd-k8s-auth gcp | Yes |
awsAuthConfig (EKS) | No, returns an error |
Client certificates (certData/keyData) | No, returns an error |
Basic auth (username/password) | No, returns an error |
proxyUrl, tlsClientConfig.serverName | No, rejected rather than ignored |
On GKE, each backend authenticates as its own service account. It does not inherit the application-controller’s identity, so give its ServiceAccount a Workload Identity binding and RBAC on each spoke (reusing ArgoCD’s own GSA is the shortest path, but the binding still has to name this ServiceAccount).
Resolved clients are cached for five minutes, so a rotated credential or an unregistered cluster takes effect within that window rather than at the next restart.
Metrics and logs are different: they often query a Prometheus and Loki shared by several clusters. Set CLUSTER_LABEL (and optionally CLUSTER_MAP) on those two backends to scope every query to the Application’s destination cluster. See “Cluster filter” on the Metrics extension page.
An empty tab on a spoke app does not mean all clear. Metrics and Logs show a spoke only if it ships to the Prometheus and Loki those backends query, and Networking always reads the Hubble Relay and API server of the cluster it runs on. Without that, a spoke app’s tabs are empty because no data reaches the backend, not because the workload is quiet.
What the backends need
To look up Applications, each backend runs with a ServiceAccount bound to a ClusterRole granting get on applications.argoproj.io:
rbac:
rules:
- apiGroups: ["argoproj.io"]
resources: ["applications"]
verbs: ["get"] The Helm chart creates this by default (serviceAccount.create: true plus the rbac.rules block on every extension). No action needed for a standard install.
Step 4: Load UI extension bundles
ArgoCD discovers UI extensions by scanning /tmp/extensions/ for files matching extension*.js. The recommended approach for production is an init container that copies bundles from a ConfigMap or OCI image.
Option A: Init container with ConfigMap (recommended)
Package your built extension bundles into a ConfigMap, then use an init container to copy them into the shared /tmp/extensions/ volume.
1. Create a ConfigMap from the built bundles:
kubectl -n argocd create configmap argoplane-ui-extensions
--from-file=extension-metrics.js=extensions/metrics/ui/dist/extension-metrics.js
--from-file=extension-logs.js=extensions/logs/ui/dist/extension-logs.js
--from-file=extension-networking.js=extensions/networking/ui/dist/extension-networking.js
--dry-run=client -o yaml | kubectl apply --server-side -f - 2. Patch argocd-server with an init container and shared volume:
kubectl -n argocd patch deployment argocd-server --type json -p '[
{
"op": "add",
"path": "/spec/template/spec/volumes/-",
"value": {
"name": "argoplane-extensions",
"configMap": {
"name": "argoplane-ui-extensions"
}
}
},
{
"op": "add",
"path": "/spec/template/spec/initContainers",
"value": [{
"name": "copy-argoplane-extensions",
"image": "busybox:1.36",
"command": ["sh", "-c",
"cp /extensions-src/*.js /tmp/extensions/"
],
"volumeMounts": [
{
"name": "argoplane-extensions",
"mountPath": "/extensions-src",
"readOnly": true
},
{
"name": "extensions",
"mountPath": "/tmp/extensions"
}
]
}]
}
]' Why an init container instead of a direct volume mount? ArgoCD expects files directly in /tmp/extensions/, but ConfigMap volume mounts create a directory structure with symlinks. The init container flattens the files into the expected location. It also allows combining extensions from multiple sources.
Option B: Init container with OCI image
For production, use the pre-built ArgoPlane UI extensions image as an init container. The image contains all UI bundles and a script that selectively copies only the ones you enable.
spec:
template:
spec:
initContainers:
- name: argoplane-extensions
image: ghcr.io/natrontech/argoplane-ui-extensions:v0.1.0
env:
- name: ENABLED_EXTENSIONS
value: "metrics,logs,argoplane"
volumeMounts:
- name: extensions
mountPath: /tmp/extensions
containers:
- name: argocd-server
volumeMounts:
- name: extensions
mountPath: /tmp/extensions
volumes:
- name: extensions
emptyDir: {} The ENABLED_EXTENSIONS env var is a comma-separated list of extension names. Only matching UI bundles (extension-<name>.js) are copied to /tmp/extensions/. If you omit the env var entirely, all bundles are copied (backwards compatible).
This approach is cleaner for CI/CD pipelines: build once, tag with version, deploy via image reference.
Loading only enabled UI bundles
When you disable an extension backend via extensions.<name>.enabled: false in the Helm chart, the proxy routing, RBAC, and backend Deployment are all skipped. However, the UI bundle is separate: it lives in the init container image and gets loaded into ArgoCD independently.
Without the ENABLED_EXTENSIONS filter, disabled extensions still show tabs and panels in ArgoCD. They appear broken (empty or error state) because there’s no backend to serve data. To prevent this, set ENABLED_EXTENSIONS on the init container to match your enabled backends.
For example, if you only enable metrics and logs:
extensions:
metrics:
enabled: true
logs:
enabled: true
networking:
enabled: false
vulnerabilities:
enabled: false
events:
enabled: false
alerts:
enabled: false Set the init container env to:
env:
- name: ENABLED_EXTENSIONS
value: "metrics,logs,argoplane" Always include argoplane in the list. It’s the consolidation extension that combines all enabled extension tabs into a single unified “ArgoPlane” tab. If you use branding, also add argoplane-links.
Option C: kubectl cp (development only)
For local development, copy bundles directly into the running pod:
ARGOCD_POD=$(kubectl -n argocd get pods
-l app.kubernetes.io/name=argocd-server
-o jsonpath='{.items[0].metadata.name}')
kubectl exec -n argocd $ARGOCD_POD -- mkdir -p /tmp/extensions
for ext in metrics networking logs vulnerabilities events alerts; do
kubectl cp extensions/$ext/ui/dist/extension-$ext.js
argocd/$ARGOCD_POD:/tmp/extensions/extension-$ext.js
done Step 5: Custom styles (optional)
The Helm chart can deploy a ConfigMap with the ArgoPlane CSS theme and login wallpaper. Enable it with argocd.styles.enabled=true.
1. Tell ArgoCD where to find the CSS:
kubectl -n argocd patch cm argocd-cm --type merge
-p '{"data":{"ui.cssurl":"./custom/argoplane.css"}}' 2. Mount the styles ConfigMap into argocd-server:
kubectl -n argocd patch deployment argocd-server --type json -p '[
{
"op": "add",
"path": "/spec/template/spec/volumes/-",
"value": {
"name": "argoplane-styles",
"configMap": { "name": "argoplane-styles" }
}
},
{
"op": "add",
"path": "/spec/template/spec/containers/0/volumeMounts/-",
"value": {
"name": "argoplane-styles",
"mountPath": "/shared/app/custom"
}
}
]' ArgoCD serves files from /shared/app/custom/ at the relative URL ./custom/. The CSS transforms ArgoCD’s UI with ArgoPlane’s pixel-art aesthetic: flat design, warm grays, pastel orange accent.
Step 6: Branding (optional)
Enable argocd.branding.enabled=true to deploy the branding JS extension. Mount it:
kubectl -n argocd patch deployment argocd-server --type json -p '[
{
"op": "add",
"path": "/spec/template/spec/volumes/-",
"value": {
"name": "argoplane-branding",
"configMap": { "name": "argoplane-links" }
}
},
{
"op": "add",
"path": "/spec/template/spec/containers/0/volumeMounts/-",
"value": {
"name": "argoplane-branding",
"mountPath": "/tmp/extensions/branding",
"readOnly": true
}
}
]' Step 7: Restart argocd-server
After all patches:
kubectl -n argocd rollout restart deployment argocd-server
kubectl -n argocd rollout status deployment argocd-server Complete example: Kustomize overlay
For production, manage all ArgoCD patches as a Kustomize overlay instead of imperative kubectl commands.
Create argocd-patches/kustomization.yaml:
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: argocd
patches:
# Enable proxy extensions
- target:
kind: ConfigMap
name: argocd-cmd-params-cm
patch: |
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cmd-params-cm
data:
server.enable.proxy.extension: "true"
# Add proxy routing + CSS URL
- target:
kind: ConfigMap
name: argocd-cm
patch: |
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cm
data:
ui.cssurl: "./custom/argoplane.css"
extension.config.metrics: |
services:
- url: http://argoplane-metrics-backend.argocd.svc:8080
extension.config.networking: |
services:
- url: http://argoplane-networking-backend.argocd.svc:8082
extension.config.logs: |
services:
- url: http://argoplane-logs-backend.argocd.svc:8083
extension.config.vulnerabilities: |
services:
- url: http://argoplane-vulnerabilities-backend.argocd.svc:8084
extension.config.events: |
services:
- url: http://argoplane-events-backend.argocd.svc:8085
extension.config.alerts: |
services:
- url: http://argoplane-alerts-backend.argocd.svc:8086
# RBAC for extensions
- target:
kind: ConfigMap
name: argocd-rbac-cm
patch: |
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-rbac-cm
data:
policy.csv: |
p, role:admin, extensions, invoke, metrics, allow
p, role:admin, extensions, invoke, networking, allow
p, role:admin, extensions, invoke, logs, allow
p, role:admin, extensions, invoke, vulnerabilities, allow
p, role:admin, extensions, invoke, events, allow
p, role:admin, extensions, invoke, alerts, allow
p, role:developer, extensions, invoke, metrics, allow
p, role:developer, extensions, invoke, logs, allow
p, role:developer, extensions, invoke, vulnerabilities, allow
p, role:developer, extensions, invoke, events, allow
p, role:developer, extensions, invoke, alerts, allow
policy.default: role:admin
# Patch argocd-server with init container + volume mounts
- target:
kind: Deployment
name: argocd-server
patch: |
apiVersion: apps/v1
kind: Deployment
metadata:
name: argocd-server
spec:
template:
spec:
initContainers:
- name: argoplane-extensions
image: ghcr.io/natrontech/argoplane-ui-extensions:v0.1.0
env:
- name: ENABLED_EXTENSIONS
value: "metrics,networking,logs,vulnerabilities,events,alerts,argoplane"
volumeMounts:
- name: extensions
mountPath: /tmp/extensions
containers:
- name: argocd-server
volumeMounts:
- name: argoplane-styles
mountPath: /shared/app/custom
- name: argoplane-branding
mountPath: /tmp/extensions/branding
readOnly: true
volumes:
- name: argoplane-styles
configMap:
name: argoplane-styles
- name: argoplane-branding
configMap:
name: argoplane-links
- name: extensions
emptyDir: {} Apply with:
kubectl apply -k argocd-patches/ Complete example: ArgoCD Application (GitOps)
Deploy ArgoPlane and its ArgoCD configuration together as a single ArgoCD Application:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: argoplane
namespace: argocd
spec:
project: default
sources:
# ArgoPlane Helm chart (backends, ConfigMaps)
- repoURL: https://github.com/natrontech/argoplane
path: deploy/helm/argoplane
targetRevision: main
helm:
valueFiles:
- values-prod.yaml
# ArgoCD patches (proxy config, RBAC, init containers)
- repoURL: https://github.com/your-org/platform-config
path: argocd-patches
targetRevision: main
destination:
server: https://kubernetes.default.svc
namespace: argocd
syncPolicy:
automated:
prune: true
selfHeal: true ArgoCD v3 changes
Key changes in ArgoCD v3 that affect extension configuration:
| Change | Impact |
|---|---|
| Fine-grained RBAC | update/delete on applications no longer cascades to sub-resources. Grant update/* and delete/* explicitly if needed. |
| Logs RBAC enforced | Users need explicit logs, get permission. |
| Extensions require RBAC | Every extension needs p, role:<role>, extensions, invoke, <name>, allow. |
| Annotation-based tracking | Resource tracking uses annotations by default, not labels. |
| Health in Redis | Resource health is stored in Redis, not in Application status. |
| React 19 UI (v3.5+) | UI extensions must externalize react/jsx-runtime (exposed as window.ReactJSXRuntime). ArgoPlane bundles already do. Custom extensions built against older ArgoCD may fail to load until rebuilt. |