Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (70 loc) · 4.37 KB

AGENTS.md

File metadata and controls

96 lines (70 loc) · 4.37 KB

resource-broker

Kubernetes operator for multi-cluster resource brokering. Kubebuilder v4, multigroup layout. Built on sigs.k8s.io/multicluster-runtime.

Read the org-wide AGENTS.md for general conventions. Read CONTRIBUTING.md for contribution workflow.

Commands

  • make check — codegen + lint + test + test-e2e (CI gate)
  • make test — unit tests
  • make test TEST_ARGS="-run TestName" — single unit test
  • make test-e2e — e2e tests (uses envtest)
  • make test-e2e TEST_ARGS="-run TestName" — single e2e test
  • make codegen — regenerate CRDs, RBAC, DeepCopy from API types
  • make lint / make lint-fix — golangci-lint v2
  • make build — build broker binary
  • make build-operator — build operator binary
  • make run — run broker locally (debug logging)
  • make run-operator — run operator locally (debug logging)
  • make examples — run all example walkthroughs
  • make help — list all targets

Structure

api/              CRD types, grouped by domain
  broker/         AcceptAPI, Migration, MigrationConfiguration
  generic/        Cross-cloud APIs (databases, networking, storage, compute, etc.)
  example/        Example CRDs (Certificate, VM)
  operator/       Broker operator CRD
cmd/              Entrypoints
  main.go         resource-broker
  operator/       resource-broker-operator
pkg/              Core logic
  broker/         Reconcilers (acceptapi, generic, migration)
  sync/           Resource copy and condition tracking
  conditions/     Status condition utilities
  kubernetes/     Annotation and map helpers
config/           Kustomize manifests (CRDs, RBAC, deployment)
test/             E2e tests and test utilities
examples/         Runnable walkthroughs (certs, kcp-certs, platform-mesh)
contrib/kcp/      kcp-specific Dockerfile and config

Architecture

Three cluster roles: coordination, consumer, provider. Two separate binaries: operator (single-cluster, manages Broker CRD, deploys broker) and broker manager (multi-cluster, runs reconcilers).

Reconciliation Flow

  1. Consumer resource created → consumer watch triggers GenericReconciler
  2. decorateInConsumer() adds finalizer + annotations
  3. providerAcceptsObj() queries AcceptAPI registry (in-memory map protected by lock)
  4. Resource copied to provider with hashed cluster prefix in name (SanitizeClusterName() → 12-char hex) to avoid multi-consumer collisions
  5. Provider watch triggers via providerEventHandler which maps back to consumer using annotations
  6. Status synced back to consumer via status subresource, with prefixes stripped by StatusTransformer
  7. Related resources (declared in status.relatedResources) copied to consumer with owner references

Provider Churn

If AcceptAPI no longer matches, reconciler sets new-provider-cluster annotation, syncs to new provider, waits for readiness, then deletes from old provider.

Migration

Staged state machine: Unknown → Pending → InitialInProgress → InitialCompleted → CutoverInProgress → CutoverCompleted. Each stage deploys template resources and evaluates CEL expressions against them before progressing.

Key Annotations (control plane)

  • broker.platform-mesh.io/consumer-cluster, consumer-name — origin tracking
  • broker.platform-mesh.io/provider-cluster — current provider
  • broker.platform-mesh.io/new-provider-cluster — migration target

Constants

  • Cluster prefixes: consumer, provider, coordination (pkg/broker/broker.go)
  • Finalizers: broker.platform-mesh.io/acceptapi-finalizer, broker.platform-mesh.io/generic-finalizer
  • AcceptAPI filters: ValueIn (enum), Boundary (min/max), Suffix (string suffix) — keys use dot notation for nested spec fields

Code Conventions

Tests: testify (require/assert). E2e: controller-runtime envtest.

Run make codegen after any change to api/ types. Run make lint-fix before committing.

Git

Conventional Commits: feat:, fix:, chore(deps):, ci:, refactor:, test:, docs:

Never add AI attribution to commits or PRs.

Do Not

  • Edit zz_generated.deepcopy.go — generated by controller-gen
  • Edit config/*/crd/*.yaml directly — generated by make manifests
  • Add tool-specific instruction files (CLAUDE.md, .cursorrules, etc.) — use this file
  • Commit without running make codegen after API type changes