calico / operator

# CLAUDE.md

Operational guidance for the operator, which builds out of this directory. Repo-wide rules live in the root `.claude/CLAUDE.md`.

## Project Overview

Kubernetes operator (built with operator-sdk/controller-runtime) that manages the lifecycle of Calico and Calico Enterprise installations. Each component (compliance, networking, apiserver, etc.) gets its own CRD, controller, and status manager. New components default to the `calico-system` namespace. Controllers interact through the Kubernetes API.

## Common Commands

### Build & Test
```bash
make build                              # Build operator binary
make ut                                 # Unit tests (Ginkgo v2), UT_DIR defaults to ./pkg
make ut UT_DIR=.                        # Unit tests across every package
make ut UT_DIR=./pkg/render             # Run tests in a specific package
make ut UT_DIR=./pkg/render GINKGO_FOCUS="description"   # Focus by Ginkgo description
make image                              # Build Docker image
```

### Code Generation (required after API/CRD changes)
```bash
make gen-files          # Regenerate CRD manifests and deepcopy methods (controller-gen)
```

### Linting & Formatting
```bash
make static-checks      # golangci-lint
make format-check       # Check gofmt compliance
make fix-changed        # Auto-format changed files
```

### Local Development
```bash
make kind-cluster-create                  # Create local kind dual-stack cluster
export KUBECONFIG=../hack/test/kind/kind-kubeconfig.yaml
make create-tigera-operator-namespace
go run ./cmd/main.go --enable-leader-election=false
make kind-cluster-destroy                 # Tear down
```

### Other
```bash
make mod-tidy           # go mod tidy
make dirty-check        # Verify no uncommitted generated changes
make test-crds          # Validate CRD schemas
```

## Architecture

### Key Packages
- **`api/v1/`** — CRD type definitions (Installation, APIServer, Compliance, Manager, Monitor, LogStorage, etc.). Uses kubebuilder markers for code generation.
- **`pkg/controller/<component>/`** — Reconciliation loops. Each controller watches its CRD and dependent resources, then calls into the render package.
- **`pkg/render/`** — Generates Kubernetes manifests (Deployments, Services, RBAC, etc.) for each component. This is where the bulk of resource creation logic lives.
- **`pkg/controller/status/`** — TigeraStatus reporting. All controllers report status here for user-facing feedback.
- **`pkg/components/`** — Component image references. `calico.go` is hand-written and takes every version from ldflags; see `CALICO_LDFLAGS` in the Makefile. A variant supplies its own images through `RegisterVariant`.
- **`pkg/crds/`** — Bundled CRD YAML files (operator, calico, enterprise). Regenerated by `make gen-files`.
- **`pkg/common/validation/`** — CRD validation logic.
- **`pkg/tls/`** — Certificate management utilities.
- **`test/`** — Functional/integration tests (run against a local kind cluster with `make fv`).
- **`config/`** — Kustomize overlays and sample CRs. Component versions are build inputs, not files.

### Adding New Components
```bash
# New CRD + API types:
operator-sdk create api --group=operator.tigera.io --version=v1 --kind=<Kind> --resource --namespaced=false
# New controller only:
operator-sdk create api --group=operator.tigera.io --version=v1 --kind=<Kind> --controller
# Then regenerate:
make gen-files
```
After `gen-files`, verify the scope of existing resources wasn't changed to "Namespaced".

## Design Principles & Documentation Map

Read the relevant doc before working in these areas:

| Task | Read |
|------|------|
| Architecture & design rationale (the "why") | [`DESIGN.md`](DESIGN.md) |
| API design & changing CRD types in `api/v1` (principles, conventions, checklist) | [`docs/api_design.md`](docs/api_design.md) |
| Common dev procedures (run, test, debug) | [`docs/common_tasks.md`](docs/common_tasks.md) |

## Build Environment
- Tests and builds run in a containerized environment (`calico/go-build`) by default
- CGO enabled on amd64, disabled for other architectures
- Multi-arch support: amd64, arm64, ppc64le, s390x

More agent context in projectcalico/calico

13 other files this repository gives its agents.