Skip to content

AGENTS.md

Latest commit

 

History

History
221 lines (151 loc) · 7.93 KB

AGENTS.md

File metadata and controls

221 lines (151 loc) · 7.93 KB

AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Kong Operator is a Kubernetes Operator (Kubebuilder v4, multigroup layout) that manages Kong Gateway deployments and Kong Kubernetes Ingress Controllers. Domain: gateway-operator.konghq.com.

Build Commands

make build              # Full build: generate code + compile binary to bin/manager
make build.operator     # Build optimized binary only (no code generation)
make generate           # Full code generation (CRDs, deepcopy, mocks, docs, manifests, chart golden files)
make manifests          # Generate CRDs and RBAC manifests only
make tools              # Install all required development tools via mise

Linting

make lint               # Run Go linters (modules, golangci-lint)
make lint.all           # Full lint: Go + charts + GitHub Actions + markdown
make lint.api           # Lint Kubernetes API types
make lint.golangci-lint # Run golangci-lint linter for Go code
make go-fix             # Run go-fix on the codebase to ensure you're not using old or deprecated Go constructs.

CI runs make lint with GOLANGCI_LINT_FLAGS="--fix=false" (auto-fix is enabled locally but disabled in CI).

Testing

Unit Tests

make test.unit          # Run unit tests with verbose output
make test.unit.pretty   # Run unit tests with compact output
make test.unit.pretty GOTESTFLAGS="-run TestSpecificGatewayNN -count 1" # Run specific test

Envtest (Controller Tests with Simulated Kubernetes)

make test.envtest                                                    # Run envtest tests with standard verbose output
make test.envtest.pretty                                             # Run envtest tests with compact output
make test.envtest CLUSTER_VERSION=1.30                               # Run envtest tests with specific Kubernetes (apiserver) version
make test.envtest GOTESTFLAGS="-run TestSpecificGatewayNN -count 1"  # Run specific test from envtest suite

Integration Tests (Require Running Cluster)

make test.integration-ko                 # Kong Operator integration tests
make test.integration-bluegreen          # DataPlane upgrade/blue-green tests
make test.integration-validatingwebhook  # Webhook tests

CRD Validation Tests

make test.crds-validation        # Run the CRD validation tests. This uses envtest to run tests against real Kubernetes API server.
make test.crds-validation.pretty # Run the CRD validation tests with pretty output. This uses envtest to run tests against real Kubernetes API server.

### Other Tests

```bash
make test.conformance           # Gateway API conformance tests
make test.kongintegration       # Kong integration tests (uses testcontainers)
make test.e2e                   # End-to-end tests
make test.e2e.chainsaw          # Chainsaw-based E2E tests
make test.charts.golden         # Helm chart golden file tests
make test.charts.golden.update  # Update chart golden files

Test File Locations

  • Unit tests: *_test.go files next to source code
  • Envtest: test/envtest/
  • Integration: test/integration/
  • Conformance: test/conformance/
  • CRD validation: test/crdsvalidation/
  • E2E: test/e2e/
  • Mocks: test/mocks/ (generated by mockery)

Running Locally

make run                # Run operator locally via telepresence (installs CRDs, sets up RBAC)
make run.skaffold       # Run with skaffold for iterative development
make debug              # Run with delve debugger

Requires a Kubernetes cluster configured in KUBECONFIG and telepresence installed.

Architecture

Entry Point

cmd/main.go → modules/cli.Parse() → modules/manager.Run() → SetupControllers()

API Types (api/)

Kubernetes API definitions which are used to generate CRDs, deepcopy methods, clientsets, informers, listers, and documentation.

  • api/gateway-operator/v1beta1/ - DataPlane, ControlPlane, GatewayConfiguration
  • api/gateway-operator/v1alpha1/ - AIGateway (experimental), DataPlaneMetricsExtension
  • api/konnect/v1alpha1/, v1alpha2/ - Konnect integration
  • api/configuration/ - Kong configuration types
  • api/common/v1alpha1/ - Shared types (ControlPlaneRef, ObjectRef, KongTags)

Controllers (controller/)

Each implements SetupWithManager(ctx, mgr) and Reconcile(ctx, req):

  • dataplane/ - Manages Kong Gateway Deployments, Services, ConfigMaps
  • controlplane/ - Manages Kong Ingress Controller deployments
  • gateway/ - Implements Gateway API, creates DataPlane/ControlPlane
  • konnect/ - Konnect cloud synchronization
  • hybridgateway/ - Hybrid mode support
  • specialized/ - AIGateway and other specialized controllers

Core Modules (modules/)

  • manager/ - Controller-runtime setup, controller registration (controller_setup.go)
  • cli/ - Command-line flag parsing
  • admission/ - Validating/conversion webhooks

Documentation (docs/)

Documentation generated from the API definitions and CLI args.

Configuration manifests (config/)

Configuration files for deploying the operator (manifests, kustomize, etc).

  • /config/samples: Sample YAML manifests for deploying custom resources. These are tested in CI by applying against a real Kubernetes cluster.

Embedded Ingress Controller (ingress-controller/)

Contains the embedded Kong Kubernetes Ingress Controller code.

Helm chart (charts/kong-operator/)

Helm chart for deploying the operator.

GitHub CI definitions (.github/)

Code Conventions

Naming (Enforced by Linter)

  • Use DataPlane not Dataplane
  • Use ControlPlane not Controlplane
  • For ControlPlane types, use github.com/kong/kong-operator/internal/types package (aliased as gwtypes)

Required Import Aliases

See .golangci.yaml for the full list of required import aliases.

Blocked Packages

See .golangci.yaml for the full list of blocked packages and their alternatives.

Tool Management

Uses mise for tool versions. Tool versions defined in .tools_versions.yaml and .mise.toml. Tools are automatically downloaded as dependencies for each Makefile target that needs them.

make tools    # Install: controller-gen, kustomize, client-gen, golangci-lint, gotestsum, skaffold, yq, crd-ref-docs

Adding New CRDs

  1. Add to PROJECT file
  2. Annotate with +kubebuilder: markers for CRD generation
  3. Run make generate to regenerate CRDs, deepcopy, docs
  4. Run make test.charts.golden.update if chart templates change
  5. Add type specific CRD validation tests in test/crdsvalidation/

Development Workflow

Before Submitting Changes

  1. Run linting - make lint must pass (CI runs with --fix=false)

  2. Run unit tests - make test.unit for quick feedback

  3. Run envtest - make test.envtest for controller logic validation

  4. Regenerate code if needed - If you modified API types, CRDs, or anything that requires code generation:

    make generate           # Regenerates all generated code
make verify.generators  # Verify generated code is up-to-date (CI runs this)

  5. Update CHANGELOG.md - For significant changes, add release notes

Verify Before Commit

make lint                 # Linting passes
make test.unit            # Unit tests pass
make verify.generators    # Generated code is up-to-date

If Modifying API Types

When changing files in api/:

make generate             # Regenerate CRDs, deepcopy, docs, manifests
make test.charts.golden.update  # Update Helm chart golden files if CRDs changed
make verify.manifests     # Verify manifests are consistent

CI Workflow

Main test workflow: .github/workflows/tests.yaml:

  • Runs on PRs to all branches and pushes to main/release branches
  • Jobs: lint, verify, unit-tests, envtest-tests, CRDs validation, conformance-tests, integration tests
  • Uses mise for tool management
  • Kubernetes versions tested: defined in .github/supported_k8s_node_versions.yaml