panxiao81/postgresql-tenant-operator

Fork 0

Files

T

panxiao81 0def13f0c7

docs: 确立规格先行开发流程

2026-09-10 02:41:45 +00:00

15 KiB

Raw Blame History

postgresql-tenant-operator - AI Agent Guide

Specification-Driven Development

Use specification-driven development for every new feature and externally observable behavior change: decide and document the contract before writing implementation code.
Create or update the relevant specification first. It must define scope, non-goals, observable behavior, validation, failure semantics, security boundaries, and acceptance criteria at the level needed for a human to make the pending decisions.
Stop after the specification reaches a reviewable state and ask the user to approve it before implementing the behavior. Approval of a plan, issue, or earlier specification does not imply approval of materially new decisions.
Derive tests from the approved acceptance criteria, then implement the smallest vertical slice that makes those tests pass. Keep specification, tests, and implementation traceable to one another.
If implementation exposes an ambiguity or requires changing the approved behavior, stop, update the specification, and request review again before continuing.
Keep specifications focused on contracts and decisions. Do not prematurely freeze internal Go package structure, function names, or SQL details unless they are part of the contract.

Human-Reviewable Changes

Break every feature into small, coherent changes that a human can review independently.
Keep each change focused on one behavior or decision; do not mix unrelated refactors, formatting churn, dependency updates, or cleanup into a feature change.
Keep the project buildable and its relevant tests passing after each change whenever practical. Add or update focused tests alongside the behavior they verify.
Present generated files together with the source API or marker change that produced them, and call out generated diffs explicitly instead of treating them as separate design work.
Prefer a sequence of narrow vertical slices over one large implementation. Summarize the intent, observable behavior, and verification for each slice so a human can review it before the next slice grows on top of it.
A pull request may contain multiple small commits. Align each commit with one coherent, independently reviewable change.
When a change reaches a suitable commit boundary, ask the user whether to create the commit before committing it. Do not accumulate unrelated completed changes merely to reduce the number of commits.
Always stop and ask the user before opening or submitting a pull request. Approval to create commits or push a branch does not imply approval to create a pull request.

Project Structure

Single-group layout (default):

cmd/main.go                    Manager entry (registers controllers/webhooks)
api/<version>/*_types.go       CRD schemas (+kubebuilder markers)
api/<version>/zz_generated.*   Auto-generated (DO NOT EDIT)
internal/controller/*          Reconciliation logic
internal/webhook/*             Validation/defaulting (if present)
config/crd/bases/*             Generated CRDs (DO NOT EDIT)
config/rbac/role.yaml          Generated RBAC (DO NOT EDIT)
config/samples/*               Example CRs (edit these)
Makefile                       Build/test/deploy commands
PROJECT                        Kubebuilder metadata Auto-generated (DO NOT EDIT)

Multi-group layout (for projects with multiple API groups):

api/<group>/<version>/*_types.go       CRD schemas by group
internal/controller/<group>/*          Controllers by group
internal/webhook/<group>/<version>/*   Webhooks by group and version (if present)

Multi-group layout organizes APIs by group name (e.g., batch, apps). Check the PROJECT file for multigroup: true.

To convert to multi-group layout:

Run: kubebuilder edit --multigroup=true
Move APIs: mkdir -p api/<group> && mv api/<version> api/<group>/
Move controllers: mkdir -p internal/controller/<group> && mv internal/controller/*.go internal/controller/<group>/
Move webhooks (if present): mkdir -p internal/webhook/<group> && mv internal/webhook/<version> internal/webhook/<group>/
Update import paths in all files
Fix path in PROJECT file for each resource
Update test suite CRD paths (add one more .. to relative paths)

Critical Rules

Never Edit These (Auto-Generated)

config/crd/bases/*.yaml - from make manifests
config/rbac/role.yaml - from make manifests
config/webhook/manifests.yaml - from make manifests
**/zz_generated.*.go - from make generate
PROJECT - from kubebuilder [OPTIONS]

Never Remove Scaffold Markers

Do NOT delete // +kubebuilder:scaffold:* comments. CLI injects code at these markers.

Keep Project Structure

Do not move files around. The CLI expects files in specific locations.

Always Use CLI Commands

Always use kubebuilder create api and kubebuilder create webhook to scaffold. Do NOT create files manually.

E2E Tests Require an Isolated Kind Cluster

The e2e tests are designed to validate the solution in an isolated environment (similar to GitHub Actions CI). Ensure you run them against a dedicated Kind cluster (not your “real” dev/prod cluster).

After Making Changes

After editing *_types.go or markers:

make manifests  # Regenerate CRDs/RBAC from markers
make generate   # Regenerate DeepCopy methods

After editing *.go files:

make lint-fix   # Auto-fix code style
make test       # Run unit tests

CLI Commands Cheat Sheet

Create API (your own types)

kubebuilder create api --group <group> --version <version> --kind <Kind>

Deploy Image Plugin (scaffold to deploy/manage ANY container image)

Generate a controller that deploys and manages a container image (nginx, redis, memcached, your app, etc.):

# Example: deploying memcached
kubebuilder create api --group example.com --version v1alpha1 --kind Memcached \
  --image=memcached:alpine \
  --plugins=deploy-image.go.kubebuilder.io/v1-alpha

Scaffolds good-practice code: reconciliation logic, status conditions, finalizers, RBAC. Use as a reference implementation.

Create Webhooks

# Validation + defaulting
kubebuilder create webhook --group <group> --version <version> --kind <Kind> \
  --defaulting --programmatic-validation

# Conversion webhook (for multi-version APIs)
kubebuilder create webhook --group <group> --version v1 --kind <Kind> \
  --conversion --spoke v2

Controller for Core Kubernetes Types

# Watch Pods
kubebuilder create api --group core --version v1 --kind Pod \
  --controller=true --resource=false

# Watch Deployments
kubebuilder create api --group apps --version v1 --kind Deployment \
  --controller=true --resource=false

Controller for External Types (e.g., from other operators)

Watch resources from external APIs (cert-manager, Argo CD, Istio, etc.):

# Example: watching cert-manager Certificate resources
kubebuilder create api \
  --group cert-manager --version v1 --kind Certificate \
  --controller=true --resource=false \
  --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 \
  --external-api-domain=io \
  --external-api-module=github.com/cert-manager/cert-manager

Note: Use --external-api-module=<module>@<version> only if you need a specific version. Otherwise, omit @<version> to use what's in go.mod.

Webhook for External Types

# Example: validating external resources
kubebuilder create webhook \
  --group cert-manager --version v1 --kind Issuer \
  --defaulting \
  --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 \
  --external-api-domain=io \
  --external-api-module=github.com/cert-manager/cert-manager

Testing & Development

make test              # Run unit tests (uses envtest: real K8s API + etcd)
make run               # Run locally (uses current kubeconfig context)

Tests use Ginkgo + Gomega (BDD style). Check suite_test.go for setup.

Deployment Workflow

# 1. Regenerate manifests
make manifests generate

# 2. Build & deploy
export IMG=<registry>/<project>:tag
make docker-build docker-push IMG=$IMG  # Or: kind load docker-image $IMG --name <cluster>
make deploy IMG=$IMG

# 3. Test
kubectl apply -k config/samples/

# 4. Debug
kubectl logs -n <project>-system deployment/<project>-controller-manager -c manager -f

API Design

Key markers for api/<version>/*_types.go:

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:scope=Namespaced
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=".status.conditions[?(@.type=='Ready')].status"

// On fields:
// +kubebuilder:validation:Required
// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:MaxLength=100
// +kubebuilder:validation:Pattern="^[a-z]+$"
// +kubebuilder:default="value"

Use metav1.Condition for status (not custom string fields)
Use predefined types: metav1.Time instead of string for dates
Follow K8s API conventions: Standard field names (spec, status, metadata)

Controller Design

RBAC markers in internal/controller/*_controller.go:

// +kubebuilder:rbac:groups=mygroup.example.com,resources=mykinds,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=mygroup.example.com,resources=mykinds/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=mygroup.example.com,resources=mykinds/finalizers,verbs=update
// +kubebuilder:rbac:groups=events.k8s.io,resources=events,verbs=create;patch
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete

Implementation rules:

Idempotent reconciliation: Safe to run multiple times
Re-fetch before updates: r.Get(ctx, req.NamespacedName, obj) before r.Update to avoid conflicts
Structured logging: log := log.FromContext(ctx); log.Info("msg", "key", val)
Owner references: Enable automatic garbage collection (SetControllerReference)
Watch secondary resources: Use .Owns() or .Watches(), not just RequeueAfter
Finalizers: Clean up external resources (buckets, VMs, DNS entries)

Logging

Follow Kubernetes logging message style guidelines:

Start from a capital letter
Do not end the message with a period
Active voice: subject present ("Deployment could not create Pod") or omitted ("Could not create Pod")
Past tense: "Could not delete Pod" not "Cannot delete Pod"
Specify object type: "Deleted Pod" not "Deleted"
Balanced key-value pairs

log.Info("Starting reconciliation")
log.Info("Created Deployment", "name", deploy.Name)
log.Error(err, "Failed to create Pod", "name", name)

Reference: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md#message-style-guidelines

Webhooks

Create all types together: --defaulting --programmatic-validation --conversion
When--forceis used: Backup custom logic first, then restore after scaffolding
For multi-version APIs: Use hub-and-spoke pattern (--conversion --spoke v2)
- Hub version: Usually oldest stable version (v1)
- Spoke versions: Newer versions that convert to/from hub (v2, v3)
- Example: --group crew --version v1 --kind Captain --conversion --spoke v2 (v1 is hub, v2 is spoke)

Learning from Examples

The deploy-image plugin scaffolds a complete controller following good practices. Use it as a reference implementation:

kubebuilder create api --group example --version v1alpha1 --kind MyApp \
  --image=<your-image> --plugins=deploy-image.go.kubebuilder.io/v1-alpha

Generated code includes: status conditions (metav1.Condition), finalizers, owner references, events, idempotent reconciliation.

Distribution Options

Option 1: YAML Bundle (Kustomize)

# Generate dist/install.yaml from Kustomize manifests
make build-installer IMG=<registry>/<project>:tag

Key points:

The dist/install.yaml is generated from Kustomize manifests (CRDs, RBAC, Deployment)
Commit this file to your repository for easy distribution
Users only need kubectl to install (no additional tools required)

Example: Users install with a single command:

kubectl apply -f https://raw.githubusercontent.com/<org>/<repo>/<tag>/dist/install.yaml

Option 2: Helm Chart

kubebuilder edit --plugins=helm/v2-alpha                      # Generates dist/chart/ (default)
kubebuilder edit --plugins=helm/v2-alpha --output-dir=charts  # Generates charts/chart/

For development:

make helm-deploy IMG=<registry>/<project>:<tag>          # Deploy manager via Helm
make helm-deploy IMG=$IMG HELM_EXTRA_ARGS="--set ..."    # Deploy with custom values
make helm-status                                         # Show release status
make helm-uninstall                                      # Remove release
make helm-history                                        # View release history
make helm-rollback                                       # Rollback to previous version

For end users/production:

helm install my-release ./<output-dir>/chart/ --namespace <ns> --create-namespace

Important: If you add webhooks or modify manifests after initial chart generation:

Backup any customizations in <output-dir>/chart/values.yaml and <output-dir>/chart/manager/manager.yaml
Re-run: kubebuilder edit --plugins=helm/v2-alpha --force (use same --output-dir if customized)
Manually restore your custom values from the backup

Publish Container Image

export IMG=<registry>/<project>:<version>
make docker-build docker-push IMG=$IMG

References

15 KiB Raw Blame History