Skip to content

AGENTS.md

Latest commit

 

History

History
90 lines (72 loc) · 4.42 KB

AGENTS.md

File metadata and controls

90 lines (72 loc) · 4.42 KB
Raw

AGENTS.md - heat-operator

For project description, deployment, configuration examples, and contributing guidelines, see README.md.

Tech stack

Layer Technology
Language Go (modules, multi-module workspace via go.work — local dev file, not committed to the repo)
Scaffolding Kubebuilder v4 + Operator SDK
CRD generation controller-gen (DeepCopy, CRDs, RBAC, webhooks)
Config management Kustomize
Packaging OLM bundle
Testing Ginkgo/Gomega + envtest (functional), KUTTL (integration)
Linting golangci-lint (.golangci.yaml)
CI Zuul (zuul.d/), Prow (.ci-operator.yaml), GitHub Actions

Custom Resources

Kind Purpose
Heat Top-level CR. Owns the database, keystone service, transport URL, and spawns sub-CRs for each service component.
HeatAPI Manages the Heat API deployment (httpd/WSGI).
HeatCfnAPI Manages the Heat CloudFormation-compatible API deployment.
HeatEngine Manages the engine service deployment (stack operations).

The Heat CR has defaulting and validating admission webhooks. Sub-CRs are created and owned by the Heat controller -- not intended to be created directly by users.

Directory structure

Maintenance rule: when directories are added, removed, or renamed, or when their purpose changes, update this table to match.

Directory Contents
api/v1beta1/ CRD types (heat_types.go, heatapi_types.go, heatcfnapi_types.go, heatengine_types.go), conditions, webhook markers
cmd/ main.go entry point
internal/controller/ Reconcilers: heat_controller.go, heatapi_controller.go, heatcfnapi_controller.go, heatengine_controller.go
internal/heat/ Heat-level resource builders (db-sync, common helpers)
internal/heatapi/ HeatAPI resource builders
internal/heatcfnapi/ HeatCfnAPI resource builders
internal/heatengine/ HeatEngine resource builders
internal/webhook/ Webhook implementation
templates/ Config files and scripts mounted into pods via OPERATOR_TEMPLATES env var
config/crd,rbac,manager,webhook/ Generated Kubernetes manifests (CRDs, RBAC, deployment, webhooks)
config/samples/ Example CRs (Kustomize overlays). Includes TLS and topology variants.
test/functional/ envtest-based Ginkgo/Gomega tests
test/kuttl/ KUTTL integration tests
hack/ Helper scripts (CRD schema checker, local webhook runner)
ci/ CI job definitions

Build commands

After modifying Go code, always run: make generate manifests fmt vet.

Do not hand-edit files under zz_generated* or config/crd/bases/ — they are generated by controller-gen.

Code style guidelines

  • Follow standard openstack-k8s-operators conventions and lib-common patterns.
  • Use lib-common modules for conditions, endpoints, TLS, storage, and other cross-cutting concerns rather than re-implementing them.
  • CRD types go in api/v1beta1/. Controller logic goes in internal/controller/. Resource-building helpers go in internal/heat* packages matching the CR they support.
  • Config templates are plain files in templates/ -- they are mounted at runtime via the OPERATOR_TEMPLATES environment variable.
  • Webhook logic is split between the kubebuilder markers in api/v1beta1/ and the implementation in internal/webhook/.

Testing

  • Functional tests use the envtest framework with Ginkgo/Gomega and live in test/functional/.
  • KUTTL integration tests live in test/kuttl/.
  • Run all functional tests: make test.
  • When adding a new field or feature, add corresponding test cases in test/functional/ and update fixture data accordingly.

Key dependencies