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:

  1. UI bundle (JavaScript): registers tabs, panels, or pages via window.extensionsAPI. ArgoCD loads any file matching extension*.js from /tmp/extensions/ inside the argocd-server pod.
  2. Proxy routing (argocd-cm): maps /extensions/<name>/* requests to a backend service URL.
  3. 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
Warning
Without explicit RBAC, users will see extension tabs but get 403 errors when loading data. Every role that should use extensions needs an `extensions, invoke` policy.

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-Name header in namespace:name format. ArgoCD’s proxy sets it automatically; requests without it get a 403.
  • 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 the argoproj.io group 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.

Warning
Enabling this makes the backend as sensitive as argocd-server. Kubernetes RBAC cannot filter Secrets by label, and 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:

MethodSupported
bearerTokenYes
execProviderConfig running argocd-k8s-auth gcpYes
awsAuthConfig (EKS)No, returns an error
Client certificates (certData/keyData)No, returns an error
Basic auth (username/password)No, returns an error
proxyUrl, tlsClientConfig.serverNameNo, 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.

Warning
If you set `serviceAccount.create: false` for an extension without providing an equivalent ServiceAccount and ClusterRole, the backend cannot read Applications and every data request fails with `403 unable to authorize namespace`.

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.

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"
        }
      ]
    }]
  }
]'
Note
The init container copies from the ConfigMap mount (read-only) to the `/tmp/extensions` emptyDir volume. ArgoCD's main container reads from the same emptyDir. This survives pod restarts because the ConfigMap is persistent.

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.

Note
The Helm chart's `helm install` output shows the exact `ENABLED_EXTENSIONS` value to use based on your `values.yaml` configuration.

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
Warning
Files in `/tmp/extensions/` are ephemeral. They are lost when the pod restarts. Use init containers (Option A or B) for anything beyond local development.

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
Note
Using multiple sources lets you keep the ArgoPlane chart separate from your organization's ArgoCD patches. The chart handles backends. Your config repo handles the ArgoCD integration.

ArgoCD v3 changes

Key changes in ArgoCD v3 that affect extension configuration:

ChangeImpact
Fine-grained RBACupdate/delete on applications no longer cascades to sub-resources. Grant update/* and delete/* explicitly if needed.
Logs RBAC enforcedUsers need explicit logs, get permission.
Extensions require RBACEvery extension needs p, role:<role>, extensions, invoke, <name>, allow.
Annotation-based trackingResource tracking uses annotations by default, not labels.
Health in RedisResource 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.

Troubleshooting