Deployment

ArgoPlane ships as a Helm chart that deploys extension backends alongside ArgoCD. Enable the extensions you need, configure ArgoCD, done.

Prerequisites

ArgoCD v3.x installed and running
kubectl access to the cluster
Helm 3.x
Backend dependencies installed per extension:
- Metrics: Prometheus
- Backups: Velero
- Networking: Cilium with Hubble
- Logs: Loki with a log collector (e.g., Grafana Alloy)
- Vulnerabilities: Trivy Operator
- Events: No external dependency (reads Kubernetes Events API directly)

Install with Helm

helm install argoplane oci://ghcr.io/natrontech/charts/argoplane 
  --namespace argocd

Or from a local checkout:

helm install argoplane deploy/helm/argoplane/ 
  --namespace argocd

This deploys the metrics and backups extensions by default. Networking is disabled by default (requires Cilium).

After install, configure ArgoCD to route extension requests. See ArgoCD Configuration for the full walkthrough, or use the quick setup below.

Quick setup (all-in-one)

After helm install, run this to wire everything up:

# Enable proxy extensions + add routing
kubectl -n argocd patch cm argocd-cmd-params-cm --type merge 
  -p '{"data":{"server.enable.proxy.extension":"true"}}'

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.backups": "services:\n- url: http://argoplane-backups-backend.argocd.svc:8081\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"
  }
}'

# Grant RBAC
kubectl -n argocd patch cm argocd-rbac-cm --type merge -p '{
  "data": {
    "policy.csv": "p, role:admin, extensions, invoke, metrics, allow\np, role:admin, extensions, invoke, backups, allow\np, role:admin, extensions, invoke, networking, allow\np, role:admin, extensions, invoke, logs, allow\np, role:admin, extensions, invoke, vulnerabilities, allow\np, role:admin, extensions, invoke, events, allow\n"
  }
}'

# Restart to pick up changes
kubectl -n argocd rollout restart deployment argocd-server

For custom styles, branding, init containers, and Kustomize/GitOps examples, see ArgoCD Configuration.

Configuration

Enable/disable extensions

Each extension is a toggle in values.yaml:

extensions:
  metrics:
    enabled: true
    env:
      PROMETHEUS_URL: "http://prometheus:9090"
  backups:
    enabled: true
    env:
      VELERO_NAMESPACE: "velero"
      # Skip TLS verification for self-signed object storage certs
      # INSECURE_TLS: "true"
  networking:
    enabled: false
    env:
      HUBBLE_RELAY_URL: "hubble-relay.kube-system.svc:80"
  logs:
    enabled: false
    env:
      LOKI_URL: "http://loki.monitoring.svc:3100"
      # LOKI_TENANT_ID: ""  # For multi-tenant Loki
  vulnerabilities:
    enabled: false
    # No external URL needed; reads Trivy Operator CRDs via K8s API
  events:
    enabled: false
    # No external URL needed; reads Kubernetes Events API directly

Setting enabled: false skips the backend Deployment, Service, proxy routing, and RBAC for that extension. To also prevent the UI bundle from loading in ArgoCD, set the ENABLED_EXTENSIONS env var on the UI extensions init container. See Loading only enabled UI bundles for details.

Enable networking:

helm upgrade argoplane deploy/helm/argoplane/ 
  --namespace argocd 
  --set extensions.networking.enabled=true

Custom values file

For production, create a values-prod.yaml:

extensions:
  metrics:
    enabled: true
    image:
      repository: ghcr.io/natrontech/argoplane-metrics-backend
      tag: "v0.1.0"
    env:
      PROMETHEUS_URL: "http://prometheus-operated.monitoring.svc:9090"
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        memory: 256Mi

  backups:
    enabled: true
    image:
      repository: ghcr.io/natrontech/argoplane-backups-backend
      tag: "v0.1.0"

  networking:
    enabled: true
    image:
      repository: ghcr.io/natrontech/argoplane-networking-backend
      tag: "v0.1.0"

argocd:
  namespace: argocd
  rbac:
    roles:
      - role: admin
        extensions: ["*"]
      - role: developer
        extensions: ["metrics", "backups"]

services:
  docs:
    enabled: true
    ingress:
      enabled: true
      className: nginx
      hosts:
        - host: docs.argoplane.io
          paths:
            - path: /
              pathType: Prefix
      tls:
        - secretName: argoplane-docs-tls
          hosts:
            - docs.argoplane.io

helm upgrade argoplane deploy/helm/argoplane/ 
  --namespace argocd 
  -f values-prod.yaml

What the chart deploys

For each enabled extension:

Resource	Name	Purpose
Deployment	`argoplane-<name>-backend`	Go HTTP backend
Service	`argoplane-<name>-backend`	Internal service
ServiceAccount	`argoplane-<name>-backend`	If RBAC rules are defined
ClusterRole	`argoplane-<name>`	If RBAC rules are defined
ClusterRoleBinding	`argoplane-<name>`	Binds role to ServiceAccount

Plus two ConfigMaps with the proxy and RBAC config you need to merge into ArgoCD.

Post-install: wire up ArgoCD

After helm install, you need to tell ArgoCD about the extensions. The chart generates two ConfigMaps with the configuration to merge.

1. Proxy routing

The chart creates argoplane-proxy-config with the extension routing entries. Merge them into argocd-cm:

# View what needs to be added
kubectl -n argocd get cm argoplane-proxy-config -o yaml

# Patch 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.backups": "services:\n- url: http://argoplane-backups-backend.argocd.svc:8081\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"
  }
}'

2. Enable proxy extensions

kubectl -n argocd patch cm argocd-cmd-params-cm --type merge 
  -p '{"data":{"server.enable.proxy.extension":"true"}}'

3. RBAC

The chart creates argoplane-rbac-config with the RBAC policies. Merge them into argocd-rbac-cm:

# View generated policies
kubectl -n argocd get cm argoplane-rbac-config -o yaml

Add the policies to your existing argocd-rbac-cm policy.csv field.

4. Restart ArgoCD

kubectl -n argocd rollout restart deployment argocd-server

Deploy via ArgoCD (GitOps)

ArgoPlane can deploy itself via ArgoCD. Store your values.yaml in a Git repo and create an ArgoCD Application:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argoplane
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/natrontech/argoplane
    path: deploy/helm/argoplane
    targetRevision: main
    helm:
      valueFiles:
        - values-prod.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Note

The proxy config and RBAC still need to be merged into ArgoCD's own ConfigMaps manually or via a separate mechanism. The chart generates the config but doesn't modify ArgoCD's ConfigMaps directly to avoid ownership conflicts.

Adding a new extension

To deploy a custom extension with the chart, add an entry to the extensions map in your values file:

extensions:
  my-custom-ext:
    enabled: true
    image:
      repository: my-registry/my-extension-backend
      tag: "1.0.0"
    port: 8090
    env:
      MY_CONFIG: "value"
    serviceAccount:
      create: true
    rbac:
      rules:
        - apiGroups: ["my-group.io"]
          resources: ["myresources"]
          verbs: ["get", "list", "watch"]

The chart will generate all required resources (Deployment, Service, ServiceAccount, ClusterRole, ClusterRoleBinding) and include the extension in the proxy and RBAC ConfigMaps.

Local development

For local development with kind, continue using the Makefile workflow:

make dev-infra           # kind cluster + ArgoCD + operators
make build-extensions    # build UI bundles
make build-backends      # build Docker images
make load-extensions     # load images into kind
make setup-argocd        # deploy to cluster

The Helm chart is for production and staging environments. The Makefile handles the dev-specific concerns (kind cluster, image loading, kubectl cp for UI bundles).

ArgoCD Configuration: detailed proxy routing and RBAC setup
CI/CD Pipeline: GitHub Actions workflows, release process, and container registry
Architecture: how extensions work under the hood