kyverno

Imported from codacy-open-source-projects-scans/kyverno (AGENTS.md). Install upstream with npx skills add codacy-open-source-projects-scans/kyverno. Copyright stays with the author.

AGENTS.md — Kyverno

This file provides context for AI coding agents working on the Kyverno codebase.

Project Overview

Kyverno is a Kubernetes-native policy engine for security, compliance, automation, and governance through policy-as-code. It validates, mutates, generates, and cleans up Kubernetes resources using admission controls and background scans, and verifies container image signatures for supply chain security.

• Language: Go
• Module: github.com/kyverno/kyverno
• License: Apache 2.0
• Go version: See go.mod for the current version

Repository Structure

api/                  # Kubernetes API type definitions (CRDs)
  kyverno/            #   kyverno.io API group (v1, v1beta1, v2, v2alpha1, v2beta1)
  policyreport/       #   wgpolicyk8s.io API group
  reports/            #   reports.kyverno.io API group
cmd/                  # Entry points for all binaries
  kyverno/            #   Main admission controller
  kyverno-init/       #   Init container (kyvernopre) — pre-flight resource cleanup
  cli/                #   Kyverno CLI (kubectl-kyverno)
  cleanup-controller/ #   Cleanup controller
  reports-controller/ #   Reports controller
  background-controller/ # Background controller (generate/mutate existing)
  readiness-checker/  #   Readiness checker
  internal/           #   Shared internal cmd helpers
  tools/              #   Internal tooling (webhook-cleanup, etc.)
pkg/                  # Core library code
  engine/             #   Policy engine (rule evaluation, matching, context)
  webhooks/           #   Admission webhook handlers
  controllers/        #   Controller implementations
  cel/                #   CEL-based policy evaluation
  client/             #   Generated Kubernetes clientset, listers, informers
  clients/            #   Client wrappers with tracing/metrics
  config/             #   Runtime configuration
  toggle/             #   Feature flags
  logging/            #   Structured logging utilities
  metrics/            #   Prometheus metrics
  validation/         #   Policy validation logic
  autogen/            #   Auto-generation of rules for Pod controllers
  cosign/             #   Cosign image signature verification
  notary/             #   Notary image signature verification
  utils/              #   Shared utilities
ext/                  # Small standalone utility packages
charts/               # Helm charts
  kyverno/            #   Main Kyverno chart
  kyverno-policies/   #   Default policies chart
config/               # CRD manifests and install manifests
  crds/               #   Generated CRD YAML files
test/                 # Tests
  cli/                #   CLI test cases (kyverno test)
  conformance/        #   Conformance / e2e tests (chainsaw)
  fuzz/               #   Fuzz tests
  policy/             #   Policy test fixtures
docs/                 # Internal developer documentation
  dev/                #   API design, controllers, logging, feature flags, reports
scripts/              # Build and CI scripts
hack/                 # Code generation helpers

Build System

The project uses make extensively. Tools are auto-installed into .tools/ on first use.

Key Build Commands

Formatting & Linting

Linting is configured via .golangci.yml (golangci-lint v2). Enabled linters include gosec, misspell, paralleltest, unconvert, errname, importas, and others. The importas linter enforces specific import alias conventions — see .golangci.yml for the full alias rules.

Formatters enabled: gci, gofmt, gofumpt, goimports.

Pre-commit checklist (required for code changes):

• Run make imports fmt before committing.
• Run make imports-check fmt-check and ensure both pass.

Pre-PR checks (required before opening/updating a PR):

• Run make codegen-all-code then make verify-codegen.
• Run ./.tools/golangci-lint run (install first with make install-tools if needed).

Testing

• Unit tests: go test -race -covermode atomic -coverprofile coverage.out ./...
• CLI tests: Use kubectl-kyverno test against test fixtures in test/cli/
• Conformance/E2E tests: Use chainsaw in test/conformance/
• Fuzz tests: Located in test/fuzz/

Code Generation

Code generation is heavily used. Always run codegen after modifying API types.

Generated files follow these patterns:

• zz_generated.deepcopy.go — deep copy functions in API packages
• zz_generated.register.go — API type registrations
• pkg/client/ — generated clientset, listers, informers
• config/crds/ — generated CRD YAML manifests

Docker Images (ko)

Local Development with KinD

Override KIND_IMAGE for k8s version, KIND_NAME for cluster name.

Architecture

Kyverno runs as multiple controllers in a Kubernetes cluster:

• Admission Controller (cmd/kyverno/): The core component. Receives AdmissionReview requests, evaluates validate/mutate rules synchronously, and queues generate/audit rules for async processing. Also validates policies and configures webhooks.
• Background Controller (cmd/background-controller/): Handles generate and mutate-existing rules for existing resources via UpdateRequests.
• Reports Controller (cmd/reports-controller/): Creates policy reports from admission and background scans. Aggregates intermediary reports into PolicyReport/ClusterPolicyReport.
• Cleanup Controller (cmd/cleanup-controller/): Executes resource deletion based on CleanupPolicy/ClusterCleanupPolicy via CronJobs.
• Init Container (cmd/kyverno-init/): Runs pre-flight cleanup before the admission controller starts.
• CLI (cmd/cli/kubectl-kyverno/): Offline policy testing and validation tool.

Controller code is primarily in pkg/controllers/. Webhook handlers are in pkg/webhooks/. The policy engine is in pkg/engine/.

API Design Rules

• API types live in api/ with versioned packages
• API groups: kyverno.io, policies.kyverno.io, policyreport.io, reports.kyverno.io
• New resource types must NOT be added to kyverno.io/v1; use v2alpha1 and promote as they stabilize
• New attributes can be added without a new version
• Attributes cannot be deleted or modified in a version; deprecate and remove after 3 minor releases
• Newer API versions may reference older stable types, but not vice versa

Coding Conventions

• Import aliases: Enforced by importas linter. Key patterns:
  • github.com/kyverno/kyverno/api/<group>/<version> → <group><version> (e.g., kyvernov1)
  • k8s.io/api/<group>/<version> → <group><version> (e.g., corev1)
  • See .golangci.yml for the full alias table
• Logging: Uses logr with zerologr backend. Default level is 2. See docs/dev/logging/logging.md:
  • L0: Errors (with stack traces)
  • L2: Startup info, policy application results
  • L3: Variable evaluation, intermediate decisions
  • L4+: Debugging, execution path details
• Feature flags: Managed via the pkg/toggle package. Feature toggles are backed by environment variables and CLI flags. See docs/dev/feature-flags/README.md.
• CGO: Disabled (CGO_ENABLED=0)
• Generated code: Never edit files matching zz_generated.* or content in pkg/client/ manually. Run make codegen-all instead.

Pull Request Guidelines

• Provide proof manifests for maintainers to verify changes
• New/changed functionality requires a corresponding documentation issue/PR on the website repo
• Test changes with the Kyverno CLI; provide test manifests
• For e2e-testable changes, write conformance tests using chainsaw in test/conformance/
• Run make verify-codegen to ensure generated code is up to date before submitting

Useful References

• Development Guide — Full build, test, debug, and deploy instructions
• Contributing Guide — Contribution process and PR guidelines
• API Design — API versioning and extension rules
• Controllers Design — Controller list and internals
• Logging — Logging levels and conventions
• Feature Flags — How to add and use feature toggles
• Reports Design — Report architecture
• Kyverno Docs — User-facing documentation