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
- Create
extensions/<name>/ui/andextensions/<name>/backend/ - Register the extension via
window.extensionsAPIinindex.tsx - Build the Go backend HTTP server
- Add deployment manifests in
deploy/extensions/<name>/ - Add proxy config in
deploy/argocd/proxy-extensions.json - Add RBAC in
hack/setup-argocd.sh - Add to
EXTENSIONSlist in the Makefile - Update
examples/demo-app/with test resources - Update documentation in
services/docs/
Next
- UI Extensions: React/TypeScript extension guide
- Backend Services: Go backend guide
- Design System: visual design reference