Developing Extensions

Every ArgoPlane extension follows the same pattern: a React/TypeScript UI bundle, a Go backend service, and ArgoCD proxy configuration.

Extension structure

extensions/<name>/
  ui/
    src/
      index.tsx          # Entry point, registers extension
      components/        # React components
      hooks/             # Custom React hooks
      types.ts           # TypeScript types
      api.ts             # Fetch calls to backend
    package.json
    webpack.config.js
    dist/
      extension-<name>.js  # Built bundle (IIFE)
  backend/
    cmd/server/
      main.go            # Entry point
    internal/
      ...                # Domain logic
    go.mod
    Dockerfile

Development workflow

Prerequisites

  • Node.js 20+ (UI extensions)
  • Go 1.26+ (backend services)
  • kind (local Kubernetes)
  • kubectl, helm

Local setup

# Full dev environment
make dev-infra

# Build all extensions
make build-extensions

# Deploy to local cluster
make setup-argocd

# Deploy demo app for testing
make deploy-example

Multi-cluster setup (optional)

make dev-infra gives you one cluster, where ArgoCD manages itself and every backend reads the cluster it runs on. That is the right default, but it never exercises the hub-spoke case: Application CRs live beside ArgoCD while the reports describing a workload live on the cluster running it.

To get that split, add a spoke:

# Hub plus spoke in one go
make dev-infra-multicluster

# Or add a spoke to a hub you already have
make spoke

# Remove just the spoke, leaving the hub alone
make spoke-delete

The spoke is a second kind cluster running Trivy Operator and a single demo Deployment from examples/demo-app/spoke/. It runs without Cilium, so it gets its own manifest rather than the hub’s demo workloads. It is registered with the hub’s ArgoCD as an ordinary cluster Secret, and a second Application (argoplane-demo-spoke) deploys to it.

That Application addresses its destination by name rather than server, on purpose: ArgoCD only sets the Argocd-Target-Cluster-URL header when an Application sets spec.destination.server, so a name-addressed destination is exactly the case a backend reading that header would get wrong. A backend has to resolve the destination from the Application itself.

make spoke also enables MULTI_CLUSTER on the events and vulnerabilities backends and grants them the Secret read they need, since neither belongs in a single-cluster setup. make spoke-delete reverts both. The spoke app’s Metrics, Logs and Networking tabs stay empty: those backends read the hub’s Prometheus, Loki and Hubble, and the spoke runs none of them.

The two Applications deploy to different namespaces on purpose (argoplane-demo on the hub, argoplane-demo-spoke on the spoke). Sharing one would mean a backend reading the wrong cluster still found reports with the right names, so the setup would look healthy while proving nothing. Apart from that they stay visible side by side, so the single-cluster and multi-cluster paths can be compared directly. make clean-all removes the spoke along with the hub.

Reports take a few minutes to appear after the spoke comes up:

kubectl --context kind-argoplane-dev-spoke get vulnerabilityreports -n argoplane-demo-spoke

Building a single extension

After editing UI code:

cd extensions/<name>/ui && npm run build
make load-extensions

After editing backend code:

make build-<name>
make load-<name>
make deploy-<name>

Checklist for new extensions

  1. Create extensions/<name>/ui/ and extensions/<name>/backend/
  2. Register the extension via window.extensionsAPI in index.tsx
  3. Build the Go backend HTTP server
  4. Add deployment manifests in deploy/extensions/<name>/
  5. Add proxy config in deploy/argocd/proxy-extensions.json
  6. Add RBAC in hack/setup-argocd.sh
  7. Add to EXTENSIONS list in the Makefile
  8. Update examples/demo-app/ with test resources
  9. Update documentation in services/docs/

Next