Skip to content

AGENTS.md

Latest commit

 

History

History
418 lines (316 loc) · 14.7 KB

AGENTS.md

File metadata and controls

418 lines (316 loc) · 14.7 KB
Raw

AGENTS.md - AI Coding Assistant Briefing

This document serves as a comprehensive briefing for AI coding assistants working with the operator-controller repository. It covers the WHAT, WHY, and HOW of contributing to this codebase.

Architecture Overview

operator-controller is the central component of Operator Lifecycle Manager (OLM) v1, extending Kubernetes with APIs to install and manage cluster extensions. The project follows a microservices architecture with two main binaries:

operator-controller

  • manages ClusterExtension and ClusterObjectSet CRDs
  • resolves bundles from configured source
  • unpacks bundles and renders manifests from them
  • applies manifests with phase-based rollouts
  • monitors extension lifecycle

catalogd

  • manages user-defined ClusterCatalog resources to make references catalog metadata available to the cluster.
  • unpacks and serves operator catalog content via HTTP.
  • serves catalog metadata to clients in the cluster that need to use or present information about the contents of the catalog. For example, operator-controller queries catalogd for available bundles.

Tech Stack

Languages:

  • Go: The Go version used by the project often lags the latest upstream available version in order to give integrators the ability to consume the latest versions of OLMv1 without being required to also consume the latest versions of Go.
  • Runtime Platform: Linux containers (multi-arch: amd64, arm64, ppc64le, s390x)
  • Developer Platform: Generally macOS and Linux. It is important that all shell commands used in Makefiles and other helper scripts work on both Linux and macOS.

Core Frameworks:

  • Kubernetes: client-go, api, apimachinery
  • controller-runtime
  • operator-framework/api: For OLMv0 API types that are relevant to OLMv1
  • operator-registry For file-based catalog (FBC) processing
  • Helm: helm-operator-plugins (which depends on helm itself)

Key Dependencies:

  • cert-manager
  • boxcutter (package-operator.run)

Container Base:

  • Base image: gcr.io/distroless/static:nonroot
  • User: 65532:65532 (non-root)

Build Tags:

  • containers_image_openpgp - required for image handling

Tools (managed via .bingo/):

  • controller-gen, golangci-lint, goreleaser, helm, kind, kustomize, mockgen, setup-envtest, operator-sdk

Test Mocking:

  • gomock (go.uber.org/mock): Used for generated mock implementations. //go:generate mockgen directives live in internal/testutil/mock/generate.go (external and internal exported interfaces) and at interface definitions for internal unexported interfaces (source mode). Run make generate-mocks to regenerate. All interface mocks should be gomock-generated. Test fakes that return preconfigured values without interaction verification (e.g., FakePuller, FakeCache in image/fakes.go) are not mocks and stay hand-written.

Build & Test Commands

Build

# Build for local platform
make build

# Build for Linux (required for docker)
make build-linux

# Build docker images
make docker-build

# Full release build
make release

Test

# Unit tests (uses ENVTEST)
make test-unit

# E2E tests
make test-e2e                      # Standard features
make test-experimental-e2e         # Experimental features
make test-extension-developer-e2e  # Extension developer workflow

# E2E tests in parallel (runs standard and experimental on separate KIND clusters)
# Recommended when machine has enough resources (4+ CPU cores, 8+ GB RAM) for faster feedback
make -j2 test-e2e test-experimental-e2e
# Linux prerequisite: sudo sysctl fs.inotify.max_user_instances=512

# Regression tests
make test-regression

# All (non-upgrade, non-experimental) tests
make test

Iterative E2E Development

# Set up a persistent e2e cluster (does not tear down after tests)
make e2e-setup                     # Standard features
make experimental-e2e-setup        # Experimental features

# Run e2e scenarios against the running cluster
make e2e/install                              # All scenarios in install.feature
make e2e/install/Install                      # Scenarios starting with "Install"
make "e2e/install/Install latest"             # Exact prefix with spaces
make e2e/install E2E_TIMEOUT=30m              # Override timeout
make e2e/install KUBECONFIG=~/.kube/config    # Override kubeconfig

# Run against experimental cluster (override KUBECONFIG)
make e2e/install/Install KUBECONFIG=.kubeconfig/operator-controller-experimental-e2e.kubeconfig

# Tear down the e2e cluster when done
make e2e-teardown                  # Standard cluster
make experimental-e2e-teardown     # Experimental cluster

Linting & Verification

# Run golangci-lint
make lint

# Run helm lint
make lint-helm

# Verify all generated code is up-to-date
make verify

# Format code
make fmt

# Fix lint issues automatically
make fix-lint

Local Development

# Create kind cluster and deploy
make run                    # Standard manifest
make run-experimental       # Experimental manifest

# OR step by step:
make kind-cluster          # Create cluster
make docker-build          # Build images
make kind-load             # Load into kind
make kind-deploy           # Deploy manifests
make wait                  # Wait for ready

# Clean up
make kind-clean

Manifest Generation

# Generate CRDs and manifests
make manifests

# Update CRDs and reference docs (when Go-based API definitions change)
make update-crds crd-ref-docs

# Generate code (DeepCopy methods and mock implementations)
make generate

# Regenerate mock implementations only
make generate-mocks

Conventions & Patterns

Folder Structure

/
├── api/v1/                          # API definitions (CRD types)
├── cmd/                             # Main entry points
│   ├── operator-controller/         # Operator controller binary
│   └── catalogd/                    # Catalogd binary
├── internal/                        # Private implementation
│   ├── operator-controller/         # Operator controller internals
│   ├── catalogd/                    # Catalogd internals
│   └── shared/                      # Shared utilities
├── helm/                            # Helm charts
│   ├── olmv1/                       # Main OLM v1 chart
│   │   ├── base/                    # Base manifests & CRDs
│   │   ├── templates/               # Helm templates
│   │   └── values.yaml              # Default values
├── testdata/
│   └── prometheus/                  # kube-prometheus-stack values for e2e monitoring
├── test/                            # Test suites
│   ├── e2e/                         # End-to-end tests (see test/e2e/README.md)
│   ├── extension-developer-e2e/     # Extension developer tests
│   ├── upgrade-e2e/                 # Upgrade tests
│   └── regression/                  # Regression tests
├── docs/                            # Documentation (mkdocs)
├── hack/                            # Scripts and tools
├── config/samples                   # Example manifests for ClusterCatalog and ClusterExtension
├── manifests/                       # Generated manifests
├── .github/workflows/               # CI/CD workflows
├── OWNERS                           # Defines approver and reviewer groups
└── OWNERS_ALIASES                   # Defined group membership

Naming Conventions

  • Controllers: {resource}_controller.go
  • Tests: {name}_test.go
  • Internal packages: lowercase, no underscores
  • Generated files: zz_generated.*.go
  • CRDs: {group}.{domain}_{resources}.yaml

Core APIs

  • Primary CRDs:
    • ClusterExtension - declares desired extension installations
    • ClusterObjectSet - revision management (experimental)
    • ClusterCatalog - catalog source definitions
  • API domain: olm.operatorframework.io
    • This is the API group of our user-facing CRDs
    • This is also the domain that should be used in ALL label and annotation prefixes that are generated by OLMv1)
  • API version: v1

Feature Gates

Two manifest variants exist:

  • Standard: Production-ready features
  • Experimental: Features under development/testing (includes ClusterObjectSet API)

API Conventions

API changes in api/v1/*_types.go must follow the OpenShift API conventions in addition to upstream Kubernetes API conventions.

After modifying API types, run make generate manifests crd-ref-docs to regenerate DeepCopy/ApplyConfiguration code, CRDs, reference docs, and manifests. Run make lint-api-diff to validate changes against kube-api-linter.

Deprecating fields: Follow Go and OpenShift conventions (see openshift/api for examples):

type ExampleConfig struct {
	// value holds some value.
	Value string `json:"value"`
}

// Deprecated: structField is no longer used and will be removed in a future release.
// Explanation of why and what replaces it.
//
// +optional
StructField ExampleConfig `json:"structField,omitzero"`

// Deprecated: scalarField is no longer used and will be removed in a future release.
// Explanation of why and what replaces it.
//
// +optional
ScalarField string `json:"scalarField,omitempty"`
  • Use Deprecated: with capital D and colon (Go convention, recognized by godoc and staticcheck)
  • Use the lowercase JSON field name (camelCase) in doc comments, not the Go PascalCase identifier — doc comments are surfaced to end users via oc explain and generated API docs
  • Deprecated fields must be +optional, never +required
  • Do not use pointers for optional struct fields (OpenShift convention); use value types with omitzero
  • Use omitzero in the JSON tag for struct types, omitempty for scalar types (string, int, bool)
  • For intentional reads of deprecated fields (e.g. deprecation warnings), add //nolint:staticcheck with a reason

Git Workflows

Branching Strategy

  • Main branch: main (default, protected)
  • Release branches: release-v{MAJOR}.{MINOR} (e.g., release-v1.2)
  • Feature branches: Created from main, usually in forks, merged via PR

Commit Message Format

<High-level description>

<Detailed description>

PR Requirements

  • Must pass all CI checks (unit-test, e2e, sanity, lint)
  • Must have both approved and lgtm labels (from repository approvers and reviewers)
  • DCO sign-off required (Developer Certificate of Origin)
  • Reasonable title and description
  • Draft PRs: prefix with "WIP:" or use GitHub draft feature
  • PR title must use specific prefix based on the type of the PR:
    • ⚠ (:warning:, major/breaking change)
    • ✨ (:sparkles:, minor/compatible change)
    • 🐛 (:bug:, patch/bug fix)
    • 📖 (:book:, docs)
    • 🌱 (:seedling:, other)

CI Workflows

  • unit-test.yaml - Unit tests with coverage
  • e2e.yaml - Multiple e2e test suites (7 variants)
  • sanity.yaml - Verification, linting, helm linting
  • test-regression.yaml - Regression tests
  • go-apidiff.yaml - API compatibility checks
  • crd-diff.yaml - CRD compatibility verification
  • release.yaml - Automated releases on tags

Release Process

  • Semantic versioning: vMAJOR.MINOR.PATCH
  • Tags trigger automated release via goreleaser
  • Patch releases from release-v* branches
  • Major/minor releases from main branch
  • Creates multi-arch container images
  • Generates release manifests and install scripts

Boundaries (What Not to Touch)

Generated Files (require special process)

Schema Files:

  • /api/v1/zz_generated.deepcopy.go - Generated by controller-gen
  • /helm/olmv1/base/*/crd/standard/*.yaml - Standard CRDs (generated)
  • /helm/olmv1/base/*/crd/experimental/*.yaml - Experimental CRDs (generated)
  • Process: Modify types in /api/v1/*_types.go, then run make manifests

Generated Manifests:

  • /manifests/standard.yaml - Generated by make manifests
  • /manifests/experimental.yaml - Generated by make manifests
  • /manifests/standard-e2e.yaml - Generated by make manifests
  • /manifests/experimental-e2e.yaml - Generated by make manifests
  • Process: Modify Helm charts in /helm/olmv1/, then run `make manifests

Generated Docs:

  • /docs/api-reference/olmv1-api-reference.md - Generated by make crd-ref-docs
  • Process: Requires regeneration whenever API definitions change (api/*/*_types.go)

CI/CD & Project Metadata

Never modify without explicit permission:

  • /.github/workflows/*.yaml - CI pipelines (consult team)
  • /.goreleaser.yml - Release configuration
  • /Makefile - Core build logic (discuss changes first)
  • /go.mod - Dependencies (use make tidy, avoid Go version bumps without discussion)
  • /PROJECT - Kubebuilder project config
  • /OWNERS & /OWNERS_ALIASES - Maintainer lists
  • /mkdocs.yml - Documentation site config
  • /.bingo/*.mod - Tool dependencies (managed by bingo)
  • /.golangci.yaml - Linter configuration
  • /kind-config.yaml - Kind cluster config

Helm Charts (requires careful review)

  • /helm/olmv1/Chart.yaml - Chart metadata
  • /helm/olmv1/values.yaml - Default values
  • /helm/olmv1/templates/*.yaml - Chart templates

Security & Compliance

  • /DCO - Developer Certificate of Origin
  • /LICENSE - Apache 2.0 license
  • /codecov.yml - Code coverage config

Important Notes for AI Agents

  1. Never commit to main directly - always use PRs
  2. CRD changes require running make update-crds and may break compatibility
  3. API changes in /api/v1/ trigger CRD and CRD reference docs regeneration
  4. Generated files must be committed after running generators
  5. Helm changes require make manifests to update manifests
  6. Go version changes need community discussion (see CONTRIBUTING.md)
  7. Dependencies: 2-week cooldown policy for non-critical updates

Development Workflow

  1. Make changes to source code
  2. Run make verify to ensure generated code is updated
  3. Run make lint and make test-unit
  4. Commit both source and generated files
  5. CI will verify everything is in sync

Key Components to Understand

operator-controller:

  • ClusterExtension controller - manages extension installations
  • ClusterObjectSet controller - manages revision lifecycle
  • Resolver - bundle version selection
  • Applier - applies manifests to cluster
  • Content Manager - manages extension content

catalogd:

  • Catalog controllers - manage catalog unpacking
  • Storage - catalog storage backend
  • Server utilities - HTTP server for catalog content

Last Updated: 2025-12-10