Kubernetes operator for Inference Gateway, built with controller-runtime and kubebuilder conventions. Go 1.27+.
All workflows run through Task (task --list for the full set):
task build- regenerate manifests/code, format, vet, buildbin/manager.task test- unit/integration tests via envtest (excludes e2e), writescover.out.task test:coverage-internal/controllercoverage - prints total, writescover.html.task test:e2e- Ginkgo e2e against a local k3d cluster (requiresctlptl+k3d).task lint-golangci-lint.task generate- regenerate deepcopy code after API changes.task manifests- regenerate CRDs, RBAC, andmanifests/install.yaml+crds.yaml.task run- run the controller locally fromcmd/main.go.
task test fetches envtest binaries and the Gateway API + agent-sandbox CRDs, so it needs network on first run (fetched copies land in test/crds/, gitignored). go build/go test run offline.
api/v1alpha1/- CRD types (gateway_types.go,agent_types.go,mcp_types.go,orchestrator_types.go,gpu_types.go), the shared workloadPodSpec(pod_types.go, not a CRD, no reconciler), plus generated deepcopy.internal/controller/- reconcilers, one per CRD, with matching*_test.go.internal/gpu/- external GPU allocation providers behind a shared interface (currently RunPod).internal/providers/- shared provider list (see below).config/- kustomize bases.manifests/- generated release artifacts (committed).test/e2e/- Ginkgo suites.examples/- runnable samples.
- Go: tabs,
gofmt/goimports. YAML/Markdown: two-space indent, LF, trailing newline (.editorconfig). - Import order (
gci) and named imports (importas) are enforced (.golangci.yml): standard library,github.com/onsi(ginkgo/gomega), third-party,github.com/inference-gateway/*, then this module. Every non-stdlib import must be named -k8s.io/api/<group>/<version>andapimachinery/pkg/apis/<group>/<version>derive<group><version>(corev1,metav1), everything else its last path element. Kubebuilder aliasesctrl,apierrors,utilruntime,clientgoscheme,gwapiv1,corev1alpha1are pinned. Fix withgolangci-lint fmtandgolangci-lint run --fix. - Write self-explanatory code: clear names and small, single-purpose functions carry the intent. If a block needs a comment to be understood, extract it into a well-named function or variable.
- No inline comments inside function bodies.
- Doc comments on functions and types are at most 5 lines: what it does and why, not how.
- No comments above modules, packages, or files: no Go package doc comment above the
packageline, no Rust//!crate or module docs, no Python module docstring, no TypeScript@fileoverviewor@moduleblock, no file header. - Document a struct, class, or record once above its declaration, not on each member. If a field needs explaining, rename it or fold the explanation into the type's doc comment.
- Prefer named constants or enums over magic numbers and strings. A bare literal is fine only where its meaning is obvious at a glance (0, 1, an empty string).
- Tool directives are not comments and stay where the tool needs them (lint suppressions, build tags, compiler pragmas, code generation markers).
- Exception - the Apache 2.0 license header (
hack/boilerplate.go.txt) stays at the top of Go files. It is a license notice, not documentation, and controller-gen stamps it into generated code. - Exception - field doc comments in
api/v1alpha1/*_types.gostay on each field. controller-gen turns them into the CRDdescriptionfields thatkubectl explainshows. - No semicolons in documentation prose (Markdown files, doc comments): split the sentence or use a dash instead.
- Examples (
examples/directories, README snippets) are short and focused: one feature per example, the fewest lines that show it, and the exact command to run it. - Every example must run as written. Verify it against the
tokenlessmock gateway, or against a real model such asollama_cloud/glm-5.3-flashwhen the mock cannot cover it. Fix or delete an example that does not run. - Keep API types in
api/v1alpha1/*_types.go, reconcilers ininternal/controller/*_controller.go, tests alongside. - Run
task fmt,task vet, andtask lintbefore submitting. The opt-in pre-commit hook (task precommit:activate) also regenerates manifests/deepcopy and runstask test, and fails if regeneration leaves unstaged changes - commit generated output together with the API change. - Add/update tests when changing reconciliation behavior, CRD schemas, defaults, or validation.
internal/providers/zz_generated_providers.go is generated from the canonical inference-gateway/schemas OpenAPI enum. To add/remove a provider, run task generate:providers and commit the result. task verify-shared-types fails on drift. ProviderSpec.Name has no CRD enum - validation is runtime via providers.IsSupported (case-insensitive).
When offline, the drift test skips locally but hard-fails in CI. Hand-edit the file (alphabetical, gofmt-clean) and let CI run the real check. Quick offline check: go test ./internal/providers/ -run 'TestIsSupported|TestSupportedProvidersHasNoDuplicates' -v.
semantic-release + conventional commits. Subjects like feat(gateway): add route weighting, fix(agent): resolve status update error, docs: update install example. For API changes, commit regenerated output from task generate and task manifests.
The operator image tag lives in config/environments/prod/kustomization.yaml (images[].newTag), which task manifests renders into manifests/install.yaml. At release time the local semantic-release plugin .github/semantic-release/pin-operator-image.cjs rewrites both to the released version and @semantic-release/git commits them, so the release tag (and an ArgoCD path: manifests install pinned to it) runs that release's image while task manifests still reproduces the committed manifest exactly. Self-check: node .github/semantic-release/pin-operator-image.cjs. The pinned semantic-release dependencies live next to it in .github/semantic-release/package.json. The release workflow installs them with npm install --prefix .github/semantic-release.
Never commit secrets in samples or manifests - use Kubernetes Secrets. Keep local cluster config out of the repo. Verify generated CRDs/install manifests before release-facing changes.