{"owner":"open-policy-agent","repo":"gatekeeper","hasSkills":true,"totalSkillsCount":2,"totalTokensCount":3578,"categories":["plugin-manifest","root-instruction"],"hasMcp":false,"mcpConfig":null,"found":["test/gator/test/fixtures/manifests/different-extensions/README.md","AGENTS.md"],"skills":{"test/gator/test/fixtures/manifests/different-extensions/README.md":"This is the title\n==================================================\n\n## Header information\n\nPizza is a tasty food.  So are burritos.  I'd say you should combine them, put a pizza burrito is a calzone.\n\n","AGENTS.md":"# Agent Instructions for OPA Gatekeeper\n\n## Project Overview\nGatekeeper is a Kubernetes admission controller that provides policy-based governance for Kubernetes clusters using Open Policy Agent (OPA). It extends Kubernetes with **validation** and **mutation** capabilities through custom resources and webhooks. **Performance and security are the highest priorities** - admission controllers must minimize latency while maintaining strict security boundaries to protect cluster operations.\n\n## Architecture & Repository Overview\n\n**Core Components:**\n- **Controller Manager**: Main controller managing constraints, templates, and policies\n- **Admission Webhooks**: Validating and mutating admission controllers\n- **Audit System**: Periodic compliance checking for existing resources\n- **Mutation System**: Resource transformation capabilities\n- **External Data**: Integration with external data sources\n- **Gator CLI**: Policy testing and verification tool\n\n**Repository Details:**\n- **Size & Type:** Large-scale Go project (~165k lines) focused on Kubernetes admission control and policy governance with extensive test coverage\n- **Primary Language:** Go 1.24+ with Go modules\n- **Key Frameworks:** controller-runtime, OPA/Rego, Common Expression Language (CEL)\n- **Container Technology:** Docker with multi-stage builds using buildx\n- **Testing Stack:** Go test, BATS (Bash Automated Testing System), envtest for Kubernetes integration\n- **CI/CD:** GitHub Actions with comprehensive matrix testing across Kubernetes versions\n\n**Core Dependencies:**\n- **Kubernetes API server**: Tested against latest three versions\n- **controller-runtime**: Kubernetes controller framework\n- **OPA Frameworks/Constraint**: Policy evaluation engine and constraint framework\n- **cert-controller**: Automatic TLS certificate management and rotation\n\n## Key Development Workflows\n\n### Project Structure & Architecture\n\n**Core Directory Layout:**\n```\n├── apis/                              # Kubernetes API definitions (CRDs)\n│   ├── config/                        # Configuration CRDs (Config, Provider)\n│   ├── connection/                    # Connection CRDs for exporting violations\n│   ├── expansion/                     # Expansion template CRDs\n│   ├── gvkmanifest/                   # GVK manifest CRDs\n│   ├── mutations/                     # Mutation CRDs (Assign, AssignMetadata, ModifySet)\n│   ├── status/                        # Status tracking CRDs\n│   └── syncset/                       # Data synchronization CRDs\n├── cmd/                               # Command line tools\n│   ├── build/helmify/                 # Helm chart generation tool\n│   └── gator/                         # Gator CLI tool for policy testing\n├── main.go                            # main entry point\n├── pkg/                               # Core business logic\n│   ├── audit/                         # Audit functionality and violation tracking\n│   ├── cachemanager/                  # Cache management for constraint evaluation\n│   ├── controller/                    # Kubernetes controllers\n│   │   ├── config/                    # Config controller\n│   │   ├── configstatus/              # Config status controller\n│   │   ├── connectionstatus/          # Connection status controller\n│   │   ├── constraint/                # Constraint controller\n│   │   ├── constraintstatus/          # Constraint status controller\n│   │   ├── constrainttemplate/        # ConstraintTemplate controller\n│   │   ├── constrainttemplatestatus/  # ConstraintTemplate status controller\n│   │   ├── expansion/                 # Expansion controller\n│   │   ├── expansionstatus/           # Expansion status controller\n│   │   ├── export/                    # Export controller\n│   │   ├── externaldata/              # External data controller\n│   │   ├── mutators/                  # Mutators controller\n│   │   ├── mutatorstatus/             # Mutator status controller\n│   │   ├── sync/                      # Sync controller\n│   │   └── syncset/                   # Syncset controller\n│   ├── drivers/                       # Policy engine drivers (CEL)\n│   ├── expansion/                     # Template expansion engine\n│   ├── export/                        # Violation export functionality\n│   ├── externaldata/                  # External data provider integration\n│   ├── gator/                         # CLI implementation and testing utilities\n│   ├── instrumentation/               # Metrics and observability\n│   ├── logging/                       # Structured logging utilities\n│   ├── metrics/                       # Prometheus metrics\n│   ├── mutation/                      # Mutation engine and mutators\n│   ├── operations/                    # Administrative operations\n│   ├── readiness/                     # Health and readiness checks\n│   ├── syncutil/                      # Data synchronization utilities\n│   ├── target/                        # Target resource management\n│   ├── upgrade/                       # Version upgrade logic\n│   ├── util/                          # Shared utilities\n│   ├── version/                       # Version information\n│   ├── watch/                         # Resource watching utilities\n│   ├── webhook/                       # Admission webhook handlers\n│   │   ├── admission/                 # Main admission logic\n│   │   └── mutation/                  # Mutation webhook logic\n│   └── wildcard/                      # Wildcard matching utilities\n├── charts/                            # Helm charts for deployment\n├── config/                            # Kubernetes manifests and configuration\n│   ├── certmanager/                   # Certificate manager configuration\n│   ├── default/                       # Default deployment configuration\n│   ├── manager/                       # Manager deployment configuration\n│   └── webhook/                       # Webhook configuration\n├── deploy/                            # Deployment configurations and scripts\n├── docs/                              # Documentation and examples\n├── example/                           # Example policies and configurations\n├── hack/                              # Development scripts and utilities\n├── test/                              # Integration and e2e tests\n│   ├── bats/                          # BATS test scripts\n│   ├── externaldata/                  # External data provider tests\n│   └── testutils/                     # Test utilities and helpers\n├── third_party/                       # Third-party dependencies\n└── website/                           # Documentation website source\n```\n\n**Critical Configuration Files:**\n- **`.golangci.yaml`** - Linting configuration, specifies exact rules and versions\n- **`Makefile`** - Primary build system, all development commands defined here\n- **`go.mod`** - Go modules with specific version pinning for stability\n- **`main.go`** - Application entry point with webhook and controller setup\n\n**Key Integration Points:**\n- **OPA Frameworks:** `pkg/controller/constrainttemplate/` integrates constraint evaluation\n- **cert-controller:** `main.go` sets up automatic TLS certificate rotation\n- **Webhook Logic:** `pkg/webhook/admission/` handles policy evaluation during admission\n\n**Testing Infrastructure:**\n- **Unit Tests:** `*_test.go` files use testify/suite with envtest for Kubernetes APIs\n- **E2E Tests:** `test/bats/test.bats` with full cluster scenarios using kind\n- **Integration:** `pkg/controller/` tests use controller-runtime's envtest framework\n\n### Build & Development Workflow\n\n**Critical Prerequisites:**\n- **Always install Go 1.24.2 or later** - verified compatible version\n- **Docker with buildx support** - required for all builds\n\n**Essential Build Commands:**\n```bash\n# Complete build, lint, and test (primary development target)\nmake all                    # ~3-5 minutes, includes lint + test + manager\n\n# Individual components\nmake manager               # Build controller binary (~2 minutes)\nmake gator                 # Build CLI tool (~1 minute)\nmake lint                  # Lint code using golangci-lint v2.3.0 (~1 minute)\nmake native-test          # Run unit tests natively (~4 minutes)\nmake test                 # Run tests in Docker (~5 minutes)\nmake test-e2e            # End-to-end tests with BATS (~10-15 minutes)\nmake docker-build         # Build Docker images\nmake deploy               # Deploy to Kubernetes cluster\n```\n\n**Critical Build Issues & Solutions:**\n- **Empty test files cause lint failures** - remove any empty `.go` files in `pkg/` directories\n- **Docker buildx required** - standard docker build will fail, must use buildx\n- **Tool versions matter** - golangci-lint v2.3.0 specifically required\n\n**Development Environment Setup:**\n1. Install Go 1.24.2+ and Docker with buildx\n2. Clone with full dependency chain: `git clone --recurse-submodules`\n3. **Always run `make lint` before committing** - catches common issues\n5. Use `make native-test` for fast feedback during development\n\n### Testing Strategy\n\n**Test Types & Commands:**\n- **Unit Tests**: Go tests with testify/suite for component testing\n  ```bash\n  make native-test           # Fast, comprehensive unit testing (~4 minutes)\n  make test                 # Run tests in Docker container (~5 minutes)\n  ```\n- **Integration Tests**: Kubernetes controller integration tests using envtest\n- **E2E Tests**: Full cluster tests using BATS and Kind\n  ```bash\n  make test-e2e             # Requires kind cluster, tests real scenarios (~10-15 minutes)\n  ```\n- **Gator Tests**: Policy verification using gator CLI\n  ```bash\n  make test-gator           # Policy verification and CLI functionality\n  ```\n- **Performance Tests**: Webhook latency and throughput benchmarks\n  ```bash\n  make benchmark-test       # Generate performance metrics\n  ```\n\n**Testing Best Practices:**\n- **Always run `make native-test` before submitting changes** - fast feedback cycle\n- **Run `make test-e2e` for webhook/controller changes** - validates integration scenarios\n- **Use `make test-gator` for policy/CLI changes** - ensures policy functionality works correctly\n\n### Development Guidelines & Patterns\n\nMake sure that there is a new line at the end of any file you edit. This is a common convention in Go and many other programming languages.\n\n**CRD Development:**\n1. **API Definitions** (`apis/` directory): Use controller-gen markers, follow Kubernetes conventions\n2. **Controller Implementation** (`pkg/controller/` directory): Use controller-runtime patterns with reconciliation loops\n3. **Webhook Implementation** (`pkg/webhook/` directory): Separate validation/mutation logic with structured logging\n\n**Policy Development:**\n- **Constraint Templates**: Define reusable policy templates with parameters\n- **Constraints**: Instantiate templates with specific configuration\n- **Rego/CEL Policies**: Write efficient policies with proper error handling (prefer CEL for performance)\n\n**Code Standards:**\n- Follow Go conventions with gofmt/goimports\n- Use structured logging with logr interface\n- Implement error wrapping and context propagation\n- Use dependency injection for testability\n- Follow controller patterns with proper cleanup using finalizers\n\n### Security Considerations\n**Security is paramount** - every component must be designed with security-first principles:\n\n- **Critical**: Validate and sanitize all user inputs in admission webhooks\n- **Mandatory**: Implement strict RBAC with principle of least privilege\n- **Essential**: Use secure defaults for all configurations - never trust user input\n- **Required**: Audit and log all policy decisions and violations for security monitoring\n- **Must**: Ensure webhook certificates are properly managed and rotated\n- **Always**: Assume hostile input and implement defense in depth\n- **Never**: Expose sensitive data in logs, error messages, or responses\n\n### Performance Guidelines\n**Performance is critical** - admission controllers must be lightning fast to avoid blocking cluster operations:\n\n- **Critical**: Minimize webhook latency (target <100ms p99, <50ms p95)\n- **Mandatory**: Use efficient CEL over Rego for policy evaluation due to superior performance\n- **Essential**: Implement proper caching for frequently accessed data\n- **Required**: Monitor memory usage in long-running controllers\n- **Must**: Optimize Kubernetes API calls with proper batching\n- **Always**: Profile and benchmark code changes for performance impact\n- **Never**: Trade performance for convenience - cluster stability depends on speed\n\n### OPA Frameworks Integration\nGatekeeper heavily relies on the **OPA Frameworks/Constraint** library (`github.com/open-policy-agent/frameworks/constraint`) for core constraint and policy functionality:\n\n- **Constraint Client**: Provides the core constraint evaluation engine that processes ConstraintTemplates and Constraints\n- **Policy Drivers**: Supports both Rego and CEL policy engines through pluggable drivers\n- **Template Management**: Handles ConstraintTemplate compilation, validation, and CRD generation\n- **Review Processing**: Processes admission review requests against constraint policies\n- **Error Handling**: Provides structured error reporting for policy violations and system errors\n- **Instrumentation**: Built-in metrics and observability for constraint evaluation performance\n\n**Key Integration Points:**\n- `pkg/controller/constrainttemplate/`: Uses frameworks for template validation and CRD management\n- `pkg/webhook/admission/`: Leverages constraint client for policy evaluation during admission\n- `pkg/audit/`: Uses frameworks for periodic compliance checking of existing resources\n- `pkg/drivers/`: Integrates with frameworks' policy engine drivers (Rego/CEL)\n\n### Cert-Controller Integration\nGatekeeper uses **cert-controller** (`github.com/open-policy-agent/cert-controller`) for automatic TLS certificate management:\n\n- **Certificate Rotation**: Automatically generates and rotates TLS certificates for webhook endpoints\n- **CA Management**: Creates and maintains Certificate Authority for webhook validation\n- **Secret Management**: Manages Kubernetes secrets containing TLS certificates and keys\n- **Webhook Configuration**: Automatically updates webhook configurations with current CA bundles\n- **Readiness Integration**: Provides readiness checks to ensure certificates are valid before serving\n\n**Key Integration Points:**\n- `main.go`: Sets up CertRotator with webhook configuration and certificate settings\n- `pkg/webhook/policy.go`: Uses rotator for validating admission webhook TLS\n- `pkg/webhook/mutation.go`: Uses rotator for mutating admission webhook TLS\n\n### Common Patterns\n- Use `context.Context` for all long-running operations\n- Implement graceful shutdown handling\n- Use proper Kubernetes owner references for resource relationships\n- Follow the controller pattern with reconciliation loops\n- Implement proper cleanup using finalizers when needed\n\n### Communication Guidelines\nWhen contributing to Gatekeeper, maintain clear and human-friendly communication:\n\n**Code & Documentation:**\n- Write self-documenting code with meaningful variable and function names\n- Keep comments concise but informative - explain \"why\" not just \"what\"\n- Use clear, descriptive commit messages that explain the intent behind changes\n- Structure PR descriptions with context, changes made, and testing approach\n\n**Error Messages:**\n- Provide actionable error messages that guide users toward solutions\n- Include relevant context (resource names, namespaces, constraint violations)\n- Use plain language that both developers and operators can understand\n- Suggest next steps or point to documentation when appropriate\n\n**Policy Violations:**\n- Write violation messages that clearly explain what was violated and why\n- Include specific examples of compliant configurations when possible\n- Keep messages concise but comprehensive enough for troubleshooting\n- Use consistent terminology aligned with Kubernetes and OPA conventions\n\n**Response Style:**\n- Be direct and helpful without being overly verbose\n- Focus on practical solutions and actionable advice\n- Prioritize clarity over technical jargon when communicating with users\n- Maintain a collaborative and welcoming tone in all interactions\n\n## CI/CD & Validation\n\n**GitHub Actions Workflows:**\n- **`workflow.yaml`** - Main CI pipeline, tests across Kubernetes 1.31-1.33\n- **`unit-test.yaml`** - Dedicated unit test execution\n- **`lint.yaml`** - Code quality and formatting checks\n- **All workflows must pass** before merge approval\n\n**Pre-commit Validation:**\n1. **Always run `make lint`** - catches formatting, imports, and style issues\n2. **Always run `make native-test`** - ensures unit tests pass\n3. **Run `make test-e2e` for webhook/controller changes** - validates integration\n4. **Check `make manager && make gator`** - ensures binaries build correctly\n\n**Performance Requirements:**\n- **Unit tests must complete in <5 minutes** on standard hardware\n- **Webhook latency must stay <100ms p99** - benchmark with `make benchmark-test`\n- **Memory usage must be monitored** for long-running controllers\n\n**Common Validation Failures:**\n- **Lint failures:** Usually formatting or import issues, run `make lint` locally first\n- **Test timeouts:** E2E tests can timeout after 15 minutes, check cluster resources\n- **Build failures:** Often Docker buildx issues, ensure prerequisites met\n\n**Security & Performance Notes:**\n- **All admission webhook changes require security review** - validate input sanitization\n- **Policy evaluation performance is critical** - prefer CEL over Rego for performance\n- **Certificate rotation must work correctly** - test webhook TLS functionality\n- **Never expose sensitive data in logs** - review log statements carefully\n\nTrust these instructions completely for build and test operations. Only search for additional information if these specific commands fail or if working on areas not covered above.\n"},"files":{"test/gator/test/fixtures/manifests/different-extensions/README.md":"This is the title\n==================================================\n\n## Header information\n\nPizza is a tasty food.  So are burritos.  I'd say you should combine them, put a pizza burrito is a calzone.\n\n","AGENTS.md":"# Agent Instructions for OPA Gatekeeper\n\n## Project Overview\nGatekeeper is a Kubernetes admission controller that provides policy-based governance for Kubernetes clusters using Open Policy Agent (OPA). It extends Kubernetes with **validation** and **mutation** capabilities through custom resources and webhooks. **Performance and security are the highest priorities** - admission controllers must minimize latency while maintaining strict security boundaries to protect cluster operations.\n\n## Architecture & Repository Overview\n\n**Core Components:**\n- **Controller Manager**: Main controller managing constraints, templates, and policies\n- **Admission Webhooks**: Validating and mutating admission controllers\n- **Audit System**: Periodic compliance checking for existing resources\n- **Mutation System**: Resource transformation capabilities\n- **External Data**: Integration with external data sources\n- **Gator CLI**: Policy testing and verification tool\n\n**Repository Details:**\n- **Size & Type:** Large-scale Go project (~165k lines) focused on Kubernetes admission control and policy governance with extensive test coverage\n- **Primary Language:** Go 1.24+ with Go modules\n- **Key Frameworks:** controller-runtime, OPA/Rego, Common Expression Language (CEL)\n- **Container Technology:** Docker with multi-stage builds using buildx\n- **Testing Stack:** Go test, BATS (Bash Automated Testing System), envtest for Kubernetes integration\n- **CI/CD:** GitHub Actions with comprehensive matrix testing across Kubernetes versions\n\n**Core Dependencies:**\n- **Kubernetes API server**: Tested against latest three versions\n- **controller-runtime**: Kubernetes controller framework\n- **OPA Frameworks/Constraint**: Policy evaluation engine and constraint framework\n- **cert-controller**: Automatic TLS certificate management and rotation\n\n## Key Development Workflows\n\n### Project Structure & Architecture\n\n**Core Directory Layout:**\n```\n├── apis/                              # Kubernetes API definitions (CRDs)\n│   ├── config/                        # Configuration CRDs (Config, Provider)\n│   ├── connection/                    # Connection CRDs for exporting violations\n│   ├── expansion/                     # Expansion template CRDs\n│   ├── gvkmanifest/                   # GVK manifest CRDs\n│   ├── mutations/                     # Mutation CRDs (Assign, AssignMetadata, ModifySet)\n│   ├── status/                        # Status tracking CRDs\n│   └── syncset/                       # Data synchronization CRDs\n├── cmd/                               # Command line tools\n│   ├── build/helmify/                 # Helm chart generation tool\n│   └── gator/                         # Gator CLI tool for policy testing\n├── main.go                            # main entry point\n├── pkg/                               # Core business logic\n│   ├── audit/                         # Audit functionality and violation tracking\n│   ├── cachemanager/                  # Cache management for constraint evaluation\n│   ├── controller/                    # Kubernetes controllers\n│   │   ├── config/                    # Config controller\n│   │   ├── configstatus/              # Config status controller\n│   │   ├── connectionstatus/          # Connection status controller\n│   │   ├── constraint/                # Constraint controller\n│   │   ├── constraintstatus/          # Constraint status controller\n│   │   ├── constrainttemplate/        # ConstraintTemplate controller\n│   │   ├── constrainttemplatestatus/  # ConstraintTemplate status controller\n│   │   ├── expansion/                 # Expansion controller\n│   │   ├── expansionstatus/           # Expansion status controller\n│   │   ├── export/                    # Export controller\n│   │   ├── externaldata/              # External data controller\n│   │   ├── mutators/                  # Mutators controller\n│   │   ├── mutatorstatus/             # Mutator status controller\n│   │   ├── sync/                      # Sync controller\n│   │   └── syncset/                   # Syncset controller\n│   ├── drivers/                       # Policy engine drivers (CEL)\n│   ├── expansion/                     # Template expansion engine\n│   ├── export/                        # Violation export functionality\n│   ├── externaldata/                  # External data provider integration\n│   ├── gator/                         # CLI implementation and testing utilities\n│   ├── instrumentation/               # Metrics and observability\n│   ├── logging/                       # Structured logging utilities\n│   ├── metrics/                       # Prometheus metrics\n│   ├── mutation/                      # Mutation engine and mutators\n│   ├── operations/                    # Administrative operations\n│   ├── readiness/                     # Health and readiness checks\n│   ├── syncutil/                      # Data synchronization utilities\n│   ├── target/                        # Target resource management\n│   ├── upgrade/                       # Version upgrade logic\n│   ├── util/                          # Shared utilities\n│   ├── version/                       # Version information\n│   ├── watch/                         # Resource watching utilities\n│   ├── webhook/                       # Admission webhook handlers\n│   │   ├── admission/                 # Main admission logic\n│   │   └── mutation/                  # Mutation webhook logic\n│   └── wildcard/                      # Wildcard matching utilities\n├── charts/                            # Helm charts for deployment\n├── config/                            # Kubernetes manifests and configuration\n│   ├── certmanager/                   # Certificate manager configuration\n│   ├── default/                       # Default deployment configuration\n│   ├── manager/                       # Manager deployment configuration\n│   └── webhook/                       # Webhook configuration\n├── deploy/                            # Deployment configurations and scripts\n├── docs/                              # Documentation and examples\n├── example/                           # Example policies and configurations\n├── hack/                              # Development scripts and utilities\n├── test/                              # Integration and e2e tests\n│   ├── bats/                          # BATS test scripts\n│   ├── externaldata/                  # External data provider tests\n│   └── testutils/                     # Test utilities and helpers\n├── third_party/                       # Third-party dependencies\n└── website/                           # Documentation website source\n```\n\n**Critical Configuration Files:**\n- **`.golangci.yaml`** - Linting configuration, specifies exact rules and versions\n- **`Makefile`** - Primary build system, all development commands defined here\n- **`go.mod`** - Go modules with specific version pinning for stability\n- **`main.go`** - Application entry point with webhook and controller setup\n\n**Key Integration Points:**\n- **OPA Frameworks:** `pkg/controller/constrainttemplate/` integrates constraint evaluation\n- **cert-controller:** `main.go` sets up automatic TLS certificate rotation\n- **Webhook Logic:** `pkg/webhook/admission/` handles policy evaluation during admission\n\n**Testing Infrastructure:**\n- **Unit Tests:** `*_test.go` files use testify/suite with envtest for Kubernetes APIs\n- **E2E Tests:** `test/bats/test.bats` with full cluster scenarios using kind\n- **Integration:** `pkg/controller/` tests use controller-runtime's envtest framework\n\n### Build & Development Workflow\n\n**Critical Prerequisites:**\n- **Always install Go 1.24.2 or later** - verified compatible version\n- **Docker with buildx support** - required for all builds\n\n**Essential Build Commands:**\n```bash\n# Complete build, lint, and test (primary development target)\nmake all                    # ~3-5 minutes, includes lint + test + manager\n\n# Individual components\nmake manager               # Build controller binary (~2 minutes)\nmake gator                 # Build CLI tool (~1 minute)\nmake lint                  # Lint code using golangci-lint v2.3.0 (~1 minute)\nmake native-test          # Run unit tests natively (~4 minutes)\nmake test                 # Run tests in Docker (~5 minutes)\nmake test-e2e            # End-to-end tests with BATS (~10-15 minutes)\nmake docker-build         # Build Docker images\nmake deploy               # Deploy to Kubernetes cluster\n```\n\n**Critical Build Issues & Solutions:**\n- **Empty test files cause lint failures** - remove any empty `.go` files in `pkg/` directories\n- **Docker buildx required** - standard docker build will fail, must use buildx\n- **Tool versions matter** - golangci-lint v2.3.0 specifically required\n\n**Development Environment Setup:**\n1. Install Go 1.24.2+ and Docker with buildx\n2. Clone with full dependency chain: `git clone --recurse-submodules`\n3. **Always run `make lint` before committing** - catches common issues\n5. Use `make native-test` for fast feedback during development\n\n### Testing Strategy\n\n**Test Types & Commands:**\n- **Unit Tests**: Go tests with testify/suite for component testing\n  ```bash\n  make native-test           # Fast, comprehensive unit testing (~4 minutes)\n  make test                 # Run tests in Docker container (~5 minutes)\n  ```\n- **Integration Tests**: Kubernetes controller integration tests using envtest\n- **E2E Tests**: Full cluster tests using BATS and Kind\n  ```bash\n  make test-e2e             # Requires kind cluster, tests real scenarios (~10-15 minutes)\n  ```\n- **Gator Tests**: Policy verification using gator CLI\n  ```bash\n  make test-gator           # Policy verification and CLI functionality\n  ```\n- **Performance Tests**: Webhook latency and throughput benchmarks\n  ```bash\n  make benchmark-test       # Generate performance metrics\n  ```\n\n**Testing Best Practices:**\n- **Always run `make native-test` before submitting changes** - fast feedback cycle\n- **Run `make test-e2e` for webhook/controller changes** - validates integration scenarios\n- **Use `make test-gator` for policy/CLI changes** - ensures policy functionality works correctly\n\n### Development Guidelines & Patterns\n\nMake sure that there is a new line at the end of any file you edit. This is a common convention in Go and many other programming languages.\n\n**CRD Development:**\n1. **API Definitions** (`apis/` directory): Use controller-gen markers, follow Kubernetes conventions\n2. **Controller Implementation** (`pkg/controller/` directory): Use controller-runtime patterns with reconciliation loops\n3. **Webhook Implementation** (`pkg/webhook/` directory): Separate validation/mutation logic with structured logging\n\n**Policy Development:**\n- **Constraint Templates**: Define reusable policy templates with parameters\n- **Constraints**: Instantiate templates with specific configuration\n- **Rego/CEL Policies**: Write efficient policies with proper error handling (prefer CEL for performance)\n\n**Code Standards:**\n- Follow Go conventions with gofmt/goimports\n- Use structured logging with logr interface\n- Implement error wrapping and context propagation\n- Use dependency injection for testability\n- Follow controller patterns with proper cleanup using finalizers\n\n### Security Considerations\n**Security is paramount** - every component must be designed with security-first principles:\n\n- **Critical**: Validate and sanitize all user inputs in admission webhooks\n- **Mandatory**: Implement strict RBAC with principle of least privilege\n- **Essential**: Use secure defaults for all configurations - never trust user input\n- **Required**: Audit and log all policy decisions and violations for security monitoring\n- **Must**: Ensure webhook certificates are properly managed and rotated\n- **Always**: Assume hostile input and implement defense in depth\n- **Never**: Expose sensitive data in logs, error messages, or responses\n\n### Performance Guidelines\n**Performance is critical** - admission controllers must be lightning fast to avoid blocking cluster operations:\n\n- **Critical**: Minimize webhook latency (target <100ms p99, <50ms p95)\n- **Mandatory**: Use efficient CEL over Rego for policy evaluation due to superior performance\n- **Essential**: Implement proper caching for frequently accessed data\n- **Required**: Monitor memory usage in long-running controllers\n- **Must**: Optimize Kubernetes API calls with proper batching\n- **Always**: Profile and benchmark code changes for performance impact\n- **Never**: Trade performance for convenience - cluster stability depends on speed\n\n### OPA Frameworks Integration\nGatekeeper heavily relies on the **OPA Frameworks/Constraint** library (`github.com/open-policy-agent/frameworks/constraint`) for core constraint and policy functionality:\n\n- **Constraint Client**: Provides the core constraint evaluation engine that processes ConstraintTemplates and Constraints\n- **Policy Drivers**: Supports both Rego and CEL policy engines through pluggable drivers\n- **Template Management**: Handles ConstraintTemplate compilation, validation, and CRD generation\n- **Review Processing**: Processes admission review requests against constraint policies\n- **Error Handling**: Provides structured error reporting for policy violations and system errors\n- **Instrumentation**: Built-in metrics and observability for constraint evaluation performance\n\n**Key Integration Points:**\n- `pkg/controller/constrainttemplate/`: Uses frameworks for template validation and CRD management\n- `pkg/webhook/admission/`: Leverages constraint client for policy evaluation during admission\n- `pkg/audit/`: Uses frameworks for periodic compliance checking of existing resources\n- `pkg/drivers/`: Integrates with frameworks' policy engine drivers (Rego/CEL)\n\n### Cert-Controller Integration\nGatekeeper uses **cert-controller** (`github.com/open-policy-agent/cert-controller`) for automatic TLS certificate management:\n\n- **Certificate Rotation**: Automatically generates and rotates TLS certificates for webhook endpoints\n- **CA Management**: Creates and maintains Certificate Authority for webhook validation\n- **Secret Management**: Manages Kubernetes secrets containing TLS certificates and keys\n- **Webhook Configuration**: Automatically updates webhook configurations with current CA bundles\n- **Readiness Integration**: Provides readiness checks to ensure certificates are valid before serving\n\n**Key Integration Points:**\n- `main.go`: Sets up CertRotator with webhook configuration and certificate settings\n- `pkg/webhook/policy.go`: Uses rotator for validating admission webhook TLS\n- `pkg/webhook/mutation.go`: Uses rotator for mutating admission webhook TLS\n\n### Common Patterns\n- Use `context.Context` for all long-running operations\n- Implement graceful shutdown handling\n- Use proper Kubernetes owner references for resource relationships\n- Follow the controller pattern with reconciliation loops\n- Implement proper cleanup using finalizers when needed\n\n### Communication Guidelines\nWhen contributing to Gatekeeper, maintain clear and human-friendly communication:\n\n**Code & Documentation:**\n- Write self-documenting code with meaningful variable and function names\n- Keep comments concise but informative - explain \"why\" not just \"what\"\n- Use clear, descriptive commit messages that explain the intent behind changes\n- Structure PR descriptions with context, changes made, and testing approach\n\n**Error Messages:**\n- Provide actionable error messages that guide users toward solutions\n- Include relevant context (resource names, namespaces, constraint violations)\n- Use plain language that both developers and operators can understand\n- Suggest next steps or point to documentation when appropriate\n\n**Policy Violations:**\n- Write violation messages that clearly explain what was violated and why\n- Include specific examples of compliant configurations when possible\n- Keep messages concise but comprehensive enough for troubleshooting\n- Use consistent terminology aligned with Kubernetes and OPA conventions\n\n**Response Style:**\n- Be direct and helpful without being overly verbose\n- Focus on practical solutions and actionable advice\n- Prioritize clarity over technical jargon when communicating with users\n- Maintain a collaborative and welcoming tone in all interactions\n\n## CI/CD & Validation\n\n**GitHub Actions Workflows:**\n- **`workflow.yaml`** - Main CI pipeline, tests across Kubernetes 1.31-1.33\n- **`unit-test.yaml`** - Dedicated unit test execution\n- **`lint.yaml`** - Code quality and formatting checks\n- **All workflows must pass** before merge approval\n\n**Pre-commit Validation:**\n1. **Always run `make lint`** - catches formatting, imports, and style issues\n2. **Always run `make native-test`** - ensures unit tests pass\n3. **Run `make test-e2e` for webhook/controller changes** - validates integration\n4. **Check `make manager && make gator`** - ensures binaries build correctly\n\n**Performance Requirements:**\n- **Unit tests must complete in <5 minutes** on standard hardware\n- **Webhook latency must stay <100ms p99** - benchmark with `make benchmark-test`\n- **Memory usage must be monitored** for long-running controllers\n\n**Common Validation Failures:**\n- **Lint failures:** Usually formatting or import issues, run `make lint` locally first\n- **Test timeouts:** E2E tests can timeout after 15 minutes, check cluster resources\n- **Build failures:** Often Docker buildx issues, ensure prerequisites met\n\n**Security & Performance Notes:**\n- **All admission webhook changes require security review** - validate input sanitization\n- **Policy evaluation performance is critical** - prefer CEL over Rego for performance\n- **Certificate rotation must work correctly** - test webhook TLS functionality\n- **Never expose sensitive data in logs** - review log statements carefully\n\nTrust these instructions completely for build and test operations. Only search for additional information if these specific commands fail or if working on areas not covered above.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/open-policy-agent/gatekeeper/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Agent Instructions for OPA Gatekeeper\n\n## Project Overview\nGatekeeper is a Kubernetes admission controller that provides policy-based governance for Kubernetes clusters using Open Policy Agent (OPA). It extends Kubernetes with **validation** and **mutation** capabilities through custom resources and webhooks. **Performance and security are the highest priorities** - admission controllers must minimize latency while maintaining strict security boundaries to protect cluster operations.\n\n## Architecture & Repository Overview\n\n**Core Components:**\n- **Controller Manager**: Main controller managing constraints, templates, and policies\n- **Admission Webhooks**: Validating and mutating admission controllers\n- **Audit System**: Periodic compliance checking for existing resources\n- **Mutation System**: Resource transformation capabilities\n- **External Data**: Integration with external data sources\n- **Gator CLI**: Policy testing and verification tool\n\n**Repository Details:**\n- **Size & Type:** Large-scale Go project (~165k lines) focused on Kubernetes admission control and policy governance with extensive test coverage\n- **Primary Language:** Go 1.24+ with Go modules\n- **Key Frameworks:** controller-runtime, OPA/Rego, Common Expression Language (CEL)\n- **Container Technology:** Docker with multi-stage builds using buildx\n- **Testing Stack:** Go test, BATS (Bash Automated Testing System), envtest for Kubernetes integration\n- **CI/CD:** GitHub Actions with comprehensive matrix testing across Kubernetes versions\n\n**Core Dependencies:**\n- **Kubernetes API server**: Tested against latest three versions\n- **controller-runtime**: Kubernetes controller framework\n- **OPA Frameworks/Constraint**: Policy evaluation engine and constraint framework\n- **cert-controller**: Automatic TLS certificate management and rotation\n\n## Key Development Workflows\n\n### Project Structure & Architecture\n\n**Core Directory Layout:**\n```\n├── apis/                              # Kubernetes API definitions (CRDs)\n│   ├── config/                        # Configuration CRDs (Config, Provider)\n│   ├── connection/                    # Connection CRDs for exporting violations\n│   ├── expansion/                     # Expansion template CRDs\n│   ├── gvkmanifest/                   # GVK manifest CRDs\n│   ├── mutations/                     # Mutation CRDs (Assign, AssignMetadata, ModifySet)\n│   ├── status/                        # Status tracking CRDs\n│   └── syncset/                       # Data synchronization CRDs\n├── cmd/                               # Command line tools\n│   ├── build/helmify/                 # Helm chart generation tool\n│   └── gator/                         # Gator CLI tool for policy testing\n├── main.go                            # main entry point\n├── pkg/                               # Core business logic\n│   ├── audit/                         # Audit functionality and violation tracking\n│   ├── cachemanager/                  # Cache management for constraint evaluation\n│   ├── controller/                    # Kubernetes controllers\n│   │   ├── config/                    # Config controller\n│   │   ├── configstatus/              # Config status controller\n│   │   ├── connectionstatus/          # Connection status controller\n│   │   ├── constraint/                # Constraint controller\n│   │   ├── constraintstatus/          # Constraint status controller\n│   │   ├── constrainttemplate/        # ConstraintTemplate controller\n│   │   ├── constrainttemplatestatus/  # ConstraintTemplate status controller\n│   │   ├── expansion/                 # Expansion controller\n│   │   ├── expansionstatus/           # Expansion status controller\n│   │   ├── export/                    # Export controller\n│   │   ├── externaldata/              # External data controller\n│   │   ├── mutators/                  # Mutators controller\n│   │   ├── mutatorstatus/             # Mutator status controller\n│   │   ├── sync/                      # Sync controller\n│   │   └── syncset/                   # Syncset controller\n│   ├── drivers/                       # Policy engine drivers (CEL)\n│   ├── expansion/                     # Template expansion engine\n│   ├── export/                        # Violation export functionality\n│   ├── externaldata/                  # External data provider integration\n│   ├── gator/                         # CLI implementation and testing utilities\n│   ├── instrumentation/               # Metrics and observability\n│   ├── logging/                       # Structured logging utilities\n│   ├── metrics/                       # Prometheus metrics\n│   ├── mutation/                      # Mutation engine and mutators\n│   ├── operations/                    # Administrative operations\n│   ├── readiness/                     # Health and readiness checks\n│   ├── syncutil/                      # Data synchronization utilities\n│   ├── target/                        # Target resource management\n│   ├── upgrade/                       # Version upgrade logic\n│   ├── util/                          # Shared utilities\n│   ├── version/                       # Version information\n│   ├── watch/                         # Resource watching utilities\n│   ├── webhook/                       # Admission webhook handlers\n│   │   ├── admission/                 # Main admission logic\n│   │   └── mutation/                  # Mutation webhook logic\n│   └── wildcard/                      # Wildcard matching utilities\n├── charts/                            # Helm charts for deployment\n├── config/                            # Kubernetes manifests and configuration\n│   ├── certmanager/                   # Certificate manager configuration\n│   ├── default/                       # Default deployment configuration\n│   ├── manager/                       # Manager deployment configuration\n│   └── webhook/                       # Webhook configuration\n├── deploy/                            # Deployment configurations and scripts\n├── docs/                              # Documentation and examples\n├── example/                           # Example policies and configurations\n├── hack/                              # Development scripts and utilities\n├── test/                              # Integration and e2e tests\n│   ├── bats/                          # BATS test scripts\n│   ├── externaldata/                  # External data provider tests\n│   └── testutils/                     # Test utilities and helpers\n├── third_party/                       # Third-party dependencies\n└── website/                           # Documentation website source\n```\n\n**Critical Configuration Files:**\n- **`.golangci.yaml`** - Linting configuration, specifies exact rules and versions\n- **`Makefile`** - Primary build system, all development commands defined here\n- **`go.mod`** - Go modules with specific version pinning for stability\n- **`main.go`** - Application entry point with webhook and controller setup\n\n**Key Integration Points:**\n- **OPA Frameworks:** `pkg/controller/constrainttemplate/` integrates constraint evaluation\n- **cert-controller:** `main.go` sets up automatic TLS certificate rotation\n- **Webhook Logic:** `pkg/webhook/admission/` handles policy evaluation during admission\n\n**Testing Infrastructure:**\n- **Unit Tests:** `*_test.go` files use testify/suite with envtest for Kubernetes APIs\n- **E2E Tests:** `test/bats/test.bats` with full cluster scenarios using kind\n- **Integration:** `pkg/controller/` tests use controller-runtime's envtest framework\n\n### Build & Development Workflow\n\n**Critical Prerequisites:**\n- **Always install Go 1.24.2 or later** - verified compatible version\n- **Docker with buildx support** - required for all builds\n\n**Essential Build Commands:**\n```bash\n# Complete build, lint, and test (primary development target)\nmake all                    # ~3-5 minutes, includes lint + test + manager\n\n# Individual components\nmake manager               # Build controller binary (~2 minutes)\nmake gator                 # Build CLI tool (~1 minute)\nmake lint                  # Lint code using golangci-lint v2.3.0 (~1 minute)\nmake native-test          # Run unit tests natively (~4 minutes)\nmake test                 # Run tests in Docker (~5 minutes)\nmake test-e2e            # End-to-end tests with BATS (~10-15 minutes)\nmake docker-build         # Build Docker images\nmake deploy               # Deploy to Kubernetes cluster\n```\n\n**Critical Build Issues & Solutions:**\n- **Empty test files cause lint failures** - remove any empty `.go` files in `pkg/` directories\n- **Docker buildx required** - standard docker build will fail, must use buildx\n- **Tool versions matter** - golangci-lint v2.3.0 specifically required\n\n**Development Environment Setup:**\n1. Install Go 1.24.2+ and Docker with buildx\n2. Clone with full dependency chain: `git clone --recurse-submodules`\n3. **Always run `make lint` before committing** - catches common issues\n5. Use `make native-test` for fast feedback during development\n\n### Testing Strategy\n\n**Test Types & Commands:**\n- **Unit Tests**: Go tests with testify/suite for component testing\n  ```bash\n  make native-test           # Fast, comprehensive unit testing (~4 minutes)\n  make test                 # Run tests in Docker container (~5 minutes)\n  ```\n- **Integration Tests**: Kubernetes controller integration tests using envtest\n- **E2E Tests**: Full cluster tests using BATS and Kind\n  ```bash\n  make test-e2e             # Requires kind cluster, tests real scenarios (~10-15 minutes)\n  ```\n- **Gator Tests**: Policy verification using gator CLI\n  ```bash\n  make test-gator           # Policy verification and CLI functionality\n  ```\n- **Performance Tests**: Webhook latency and throughput benchmarks\n  ```bash\n  make benchmark-test       # Generate performance metrics\n  ```\n\n**Testing Best Practices:**\n- **Always run `make native-test` before submitting changes** - fast feedback cycle\n- **Run `make test-e2e` for webhook/controller changes** - validates integration scenarios\n- **Use `make test-gator` for policy/CLI changes** - ensures policy functionality works correctly\n\n### Development Guidelines & Patterns\n\nMake sure that there is a new line at the end of any file you edit. This is a common convention in Go and many other programming languages.\n\n**CRD Development:**\n1. **API Definitions** (`apis/` directory): Use controller-gen markers, follow Kubernetes conventions\n2. **Controller Implementation** (`pkg/controller/` directory): Use controller-runtime patterns with reconciliation loops\n3. **Webhook Implementation** (`pkg/webhook/` directory): Separate validation/mutation logic with structured logging\n\n**Policy Development:**\n- **Constraint Templates**: Define reusable policy templates with parameters\n- **Constraints**: Instantiate templates with specific configuration\n- **Rego/CEL Policies**: Write efficient policies with proper error handling (prefer CEL for performance)\n\n**Code Standards:**\n- Follow Go conventions with gofmt/goimports\n- Use structured logging with logr interface\n- Implement error wrapping and context propagation\n- Use dependency injection for testability\n- Follow controller patterns with proper cleanup using finalizers\n\n### Security Considerations\n**Security is paramount** - every component must be designed with security-first principles:\n\n- **Critical**: Validate and sanitize all user inputs in admission webhooks\n- **Mandatory**: Implement strict RBAC with principle of least privilege\n- **Essential**: Use secure defaults for all configurations - never trust user input\n- **Required**: Audit and log all policy decisions and violations for security monitoring\n- **Must**: Ensure webhook certificates are properly managed and rotated\n- **Always**: Assume hostile input and implement defense in depth\n- **Never**: Expose sensitive data in logs, error messages, or responses\n\n### Performance Guidelines\n**Performance is critical** - admission controllers must be lightning fast to avoid blocking cluster operations:\n\n- **Critical**: Minimize webhook latency (target <100ms p99, <50ms p95)\n- **Mandatory**: Use efficient CEL over Rego for policy evaluation due to superior performance\n- **Essential**: Implement proper caching for frequently accessed data\n- **Required**: Monitor memory usage in long-running controllers\n- **Must**: Optimize Kubernetes API calls with proper batching\n- **Always**: Profile and benchmark code changes for performance impact\n- **Never**: Trade performance for convenience - cluster stability depends on speed\n\n### OPA Frameworks Integration\nGatekeeper heavily relies on the **OPA Frameworks/Constraint** library (`github.com/open-policy-agent/frameworks/constraint`) for core constraint and policy functionality:\n\n- **Constraint Client**: Provides the core constraint evaluation engine that processes ConstraintTemplates and Constraints\n- **Policy Drivers**: Supports both Rego and CEL policy engines through pluggable drivers\n- **Template Management**: Handles ConstraintTemplate compilation, validation, and CRD generation\n- **Review Processing**: Processes admission review requests against constraint policies\n- **Error Handling**: Provides structured error reporting for policy violations and system errors\n- **Instrumentation**: Built-in metrics and observability for constraint evaluation performance\n\n**Key Integration Points:**\n- `pkg/controller/constrainttemplate/`: Uses frameworks for template validation and CRD management\n- `pkg/webhook/admission/`: Leverages constraint client for policy evaluation during admission\n- `pkg/audit/`: Uses frameworks for periodic compliance checking of existing resources\n- `pkg/drivers/`: Integrates with frameworks' policy engine drivers (Rego/CEL)\n\n### Cert-Controller Integration\nGatekeeper uses **cert-controller** (`github.com/open-policy-agent/cert-controller`) for automatic TLS certificate management:\n\n- **Certificate Rotation**: Automatically generates and rotates TLS certificates for webhook endpoints\n- **CA Management**: Creates and maintains Certificate Authority for webhook validation\n- **Secret Management**: Manages Kubernetes secrets containing TLS certificates and keys\n- **Webhook Configuration**: Automatically updates webhook configurations with current CA bundles\n- **Readiness Integration**: Provides readiness checks to ensure certificates are valid before serving\n\n**Key Integration Points:**\n- `main.go`: Sets up CertRotator with webhook configuration and certificate settings\n- `pkg/webhook/policy.go`: Uses rotator for validating admission webhook TLS\n- `pkg/webhook/mutation.go`: Uses rotator for mutating admission webhook TLS\n\n### Common Patterns\n- Use `context.Context` for all long-running operations\n- Implement graceful shutdown handling\n- Use proper Kubernetes owner references for resource relationships\n- Follow the controller pattern with reconciliation loops\n- Implement proper cleanup using finalizers when needed\n\n### Communication Guidelines\nWhen contributing to Gatekeeper, maintain clear and human-friendly communication:\n\n**Code & Documentation:**\n- Write self-documenting code with meaningful variable and function names\n- Keep comments concise but informative - explain \"why\" not just \"what\"\n- Use clear, descriptive commit messages that explain the intent behind changes\n- Structure PR descriptions with context, changes made, and testing approach\n\n**Error Messages:**\n- Provide actionable error messages that guide users toward solutions\n- Include relevant context (resource names, namespaces, constraint violations)\n- Use plain language that both developers and operators can understand\n- Suggest next steps or point to documentation when appropriate\n\n**Policy Violations:**\n- Write violation messages that clearly explain what was violated and why\n- Include specific examples of compliant configurations when possible\n- Keep messages concise but comprehensive enough for troubleshooting\n- Use consistent terminology aligned with Kubernetes and OPA conventions\n\n**Response Style:**\n- Be direct and helpful without being overly verbose\n- Focus on practical solutions and actionable advice\n- Prioritize clarity over technical jargon when communicating with users\n- Maintain a collaborative and welcoming tone in all interactions\n\n## CI/CD & Validation\n\n**GitHub Actions Workflows:**\n- **`workflow.yaml`** - Main CI pipeline, tests across Kubernetes 1.31-1.33\n- **`unit-test.yaml`** - Dedicated unit test execution\n- **`lint.yaml`** - Code quality and formatting checks\n- **All workflows must pass** before merge approval\n\n**Pre-commit Validation:**\n1. **Always run `make lint`** - catches formatting, imports, and style issues\n2. **Always run `make native-test`** - ensures unit tests pass\n3. **Run `make test-e2e` for webhook/controller changes** - validates integration\n4. **Check `make manager && make gator`** - ensures binaries build correctly\n\n**Performance Requirements:**\n- **Unit tests must complete in <5 minutes** on standard hardware\n- **Webhook latency must stay <100ms p99** - benchmark with `make benchmark-test`\n- **Memory usage must be monitored** for long-running controllers\n\n**Common Validation Failures:**\n- **Lint failures:** Usually formatting or import issues, run `make lint` locally first\n- **Test timeouts:** E2E tests can timeout after 15 minutes, check cluster resources\n- **Build failures:** Often Docker buildx issues, ensure prerequisites met\n\n**Security & Performance Notes:**\n- **All admission webhook changes require security review** - validate input sanitization\n- **Policy evaluation performance is critical** - prefer CEL over Rego for performance\n- **Certificate rotation must work correctly** - test webhook TLS functionality\n- **Never expose sensitive data in logs** - review log statements carefully\n\nTrust these instructions completely for build and test operations. Only search for additional information if these specific commands fail or if working on areas not covered above.\n","isInternal":false,"tokens":3535,"sizeBytes":18481},{"name":"README.md","path":"test/gator/test/fixtures/manifests/different-extensions/README.md","rawUrl":"https://raw.githubusercontent.com/open-policy-agent/gatekeeper/HEAD/test/gator/test/fixtures/manifests/different-extensions/README.md","title":"different-extensions Documentation","category":"plugin-manifest","format":"markdown","content":"This is the title\n==================================================\n\n## Header information\n\nPizza is a tasty food.  So are burritos.  I'd say you should combine them, put a pizza burrito is a calzone.\n\n","isInternal":false,"tokens":43,"sizeBytes":203}],"systemPromptSnippet":"<yakaai_skills repo=\"open-policy-agent/gatekeeper\">\n<!-- File: AGENTS.md (Tokens: ~3535 | Category: root-instruction) -->\n# Agent Instructions for OPA Gatekeeper\n\n## Project Overview\nGatekeeper is a Kubernetes admission controller that provides policy-based governance for Kubernetes clusters using Open Policy Agent (OPA). It extends Kubernetes with **validation** and **mutation** capabilities through custom resources and webhooks. **Performance and security are the highest priorities** - admission controllers must minimize latency while maintaining strict security boundaries to protect cluster operations.\n\n## Architecture & Repository Overview\n\n**Core Components:**\n- **Controller Manager**: Main controller managing constraints, templates, and policies\n- **Admission Webhooks**: Validating and mutating admission controllers\n- **Audit System**: Periodic compliance checking for existing resources\n- **Mutation System**: Resource transformation capabilities\n- **External Data**: Integration with external data sources\n- **Gator CLI**: Policy testing and verification tool\n\n**Repository Details:**\n- **Size & Type:** Large-scale Go project (~165k lines) focused on Kubernetes admission control and policy governance with extensive test coverage\n- **Primary Language:** Go 1.24+ with Go modules\n- **Key Frameworks:** controller-runtime, OPA/Rego, Common Expression Language (CEL)\n- **Container Technology:** Docker with multi-stage builds using buildx\n- **Testing Stack:** Go test, BATS (Bash Automated Testing System), envtest for Kubernetes integration\n- **CI/CD:** GitHub Actions with comprehensive matrix testing across Kubernetes versions\n\n**Core Dependencies:**\n- **Kubernetes API server**: Tested against latest three versions\n- **controller-runtime**: Kubernetes controller framework\n- **OPA Frameworks/Constraint**: Policy evaluation engine and constraint framework\n- **cert-controller**: Automatic TLS certificate management and rotation\n\n## Key Development Workflows\n\n### Project Structure & Architecture\n\n**Core Directory Layout:**\n```\n├── apis/                              # Kubernetes API definitions (CRDs)\n│   ├── config/                        # Configuration CRDs (Config, Provider)\n│   ├── connection/                    # Connection CRDs for exporting violations\n│   ├── expansion/                     # Expansion template CRDs\n│   ├── gvkmanifest/                   # GVK manifest CRDs\n│   ├── mutations/                     # Mutation CRDs (Assign, AssignMetadata, ModifySet)\n│   ├── status/                        # Status tracking CRDs\n│   └── syncset/                       # Data synchronization CRDs\n├── cmd/                               # Command line tools\n│   ├── build/helmify/                 # Helm chart generation tool\n│   └── gator/                         # Gator CLI tool for policy testing\n├── main.go                            # main entry point\n├── pkg/                               # Core business logic\n│   ├── audit/                         # Audit functionality and violation tracking\n│   ├── cachemanager/                  # Cache management for constraint evaluation\n│   ├── controller/                    # Kubernetes controllers\n│   │   ├── config/                    # Config controller\n│   │   ├── configstatus/              # Config status controller\n│   │   ├── connectionstatus/          # Connection status controller\n│   │   ├── constraint/                # Constraint controller\n│   │   ├── constraintstatus/          # Constraint status controller\n│   │   ├── constrainttemplate/        # ConstraintTemplate controller\n│   │   ├── constrainttemplatestatus/  # ConstraintTemplate status controller\n│   │   ├── expansion/                 # Expansion controller\n│   │   ├── expansionstatus/           # Expansion status controller\n│   │   ├── export/                    # Export controller\n│   │   ├── externaldata/              # External data controller\n│   │   ├── mutators/                  # Mutators controller\n│   │   ├── mutatorstatus/             # Mutator status controller\n│   │   ├── sync/                      # Sync controller\n│   │   └── syncset/                   # Syncset controller\n│   ├── drivers/                       # Policy engine drivers (CEL)\n│   ├── expansion/                     # Template expansion engine\n│   ├── export/                        # Violation export functionality\n│   ├── externaldata/                  # External data provider integration\n│   ├── gator/                         # CLI implementation and testing utilities\n│   ├── instrumentation/               # Metrics and observability\n│   ├── logging/                       # Structured logging utilities\n│   ├── metrics/                       # Prometheus metrics\n│   ├── mutation/                      # Mutation engine and mutators\n│   ├── operations/                    # Administrative operations\n│   ├── readiness/                     # Health and readiness checks\n│   ├── syncutil/                      # Data synchronization utilities\n│   ├── target/                        # Target resource management\n│   ├── upgrade/                       # Version upgrade logic\n│   ├── util/                          # Shared utilities\n│   ├── version/                       # Version information\n│   ├── watch/                         # Resource watching utilities\n│   ├── webhook/                       # Admission webhook handlers\n│   │   ├── admission/                 # Main admission logic\n│   │   └── mutation/                  # Mutation webhook logic\n│   └── wildcard/                      # Wildcard matching utilities\n├── charts/                            # Helm charts for deployment\n├── config/                            # Kubernetes manifests and configuration\n│   ├── certmanager/                   # Certificate manager configuration\n│   ├── default/                       # Default deployment configuration\n│   ├── manager/                       # Manager deployment configuration\n│   └── webhook/                       # Webhook configuration\n├── deploy/                            # Deployment configurations and scripts\n├── docs/                              # Documentation and examples\n├── example/                           # Example policies and configurations\n├── hack/                              # Development scripts and utilities\n├── test/                              # Integration and e2e tests\n│   ├── bats/                          # BATS test scripts\n│   ├── externaldata/                  # External data provider tests\n│   └── testutils/                     # Test utilities and helpers\n├── third_party/                       # Third-party dependencies\n└── website/                           # Documentation website source\n```\n\n**Critical Configuration Files:**\n- **`.golangci.yaml`** - Linting configuration, specifies exact rules and versions\n- **`Makefile`** - Primary build system, all development commands defined here\n- **`go.mod`** - Go modules with specific version pinning for stability\n- **`main.go`** - Application entry point with webhook and controller setup\n\n**Key Integration Points:**\n- **OPA Frameworks:** `pkg/controller/constrainttemplate/` integrates constraint evaluation\n- **cert-controller:** `main.go` sets up automatic TLS certificate rotation\n- **Webhook Logic:** `pkg/webhook/admission/` handles policy evaluation during admission\n\n**Testing Infrastructure:**\n- **Unit Tests:** `*_test.go` files use testify/suite with envtest for Kubernetes APIs\n- **E2E Tests:** `test/bats/test.bats` with full cluster scenarios using kind\n- **Integration:** `pkg/controller/` tests use controller-runtime's envtest framework\n\n### Build & Development Workflow\n\n**Critical Prerequisites:**\n- **Always install Go 1.24.2 or later** - verified compatible version\n- **Docker with buildx support** - required for all builds\n\n**Essential Build Commands:**\n```bash\n# Complete build, lint, and test (primary development target)\nmake all                    # ~3-5 minutes, includes lint + test + manager\n\n# Individual components\nmake manager               # Build controller binary (~2 minutes)\nmake gator                 # Build CLI tool (~1 minute)\nmake lint                  # Lint code using golangci-lint v2.3.0 (~1 minute)\nmake native-test          # Run unit tests natively (~4 minutes)\nmake test                 # Run tests in Docker (~5 minutes)\nmake test-e2e            # End-to-end tests with BATS (~10-15 minutes)\nmake docker-build         # Build Docker images\nmake deploy               # Deploy to Kubernetes cluster\n```\n\n**Critical Build Issues & Solutions:**\n- **Empty test files cause lint failures** - remove any empty `.go` files in `pkg/` directories\n- **Docker buildx required** - standard docker build will fail, must use buildx\n- **Tool versions matter** - golangci-lint v2.3.0 specifically required\n\n**Development Environment Setup:**\n1. Install Go 1.24.2+ and Docker with buildx\n2. Clone with full dependency chain: `git clone --recurse-submodules`\n3. **Always run `make lint` before committing** - catches common issues\n5. Use `make native-test` for fast feedback during development\n\n### Testing Strategy\n\n**Test Types & Commands:**\n- **Unit Tests**: Go tests with testify/suite for component testing\n  ```bash\n  make native-test           # Fast, comprehensive unit testing (~4 minutes)\n  make test                 # Run tests in Docker container (~5 minutes)\n  ```\n- **Integration Tests**: Kubernetes controller integration tests using envtest\n- **E2E Tests**: Full cluster tests using BATS and Kind\n  ```bash\n  make test-e2e             # Requires kind cluster, tests real scenarios (~10-15 minutes)\n  ```\n- **Gator Tests**: Policy verification using gator CLI\n  ```bash\n  make test-gator           # Policy verification and CLI functionality\n  ```\n- **Performance Tests**: Webhook latency and throughput benchmarks\n  ```bash\n  make benchmark-test       # Generate performance metrics\n  ```\n\n**Testing Best Practices:**\n- **Always run `make native-test` before submitting changes** - fast feedback cycle\n- **Run `make test-e2e` for webhook/controller changes** - validates integration scenarios\n- **Use `make test-gator` for policy/CLI changes** - ensures policy functionality works correctly\n\n### Development Guidelines & Patterns\n\nMake sure that there is a new line at the end of any file you edit. This is a common convention in Go and many other programming languages.\n\n**CRD Development:**\n1. **API Definitions** (`apis/` directory): Use controller-gen markers, follow Kubernetes conventions\n2. **Controller Implementation** (`pkg/controller/` directory): Use controller-runtime patterns with reconciliation loops\n3. **Webhook Implementation** (`pkg/webhook/` directory): Separate validation/mutation logic with structured logging\n\n**Policy Development:**\n- **Constraint Templates**: Define reusable policy templates with parameters\n- **Constraints**: Instantiate templates with specific configuration\n- **Rego/CEL Policies**: Write efficient policies with proper error handling (prefer CEL for performance)\n\n**Code Standards:**\n- Follow Go conventions with gofmt/goimports\n- Use structured logging with logr interface\n- Implement error wrapping and context propagation\n- Use dependency injection for testability\n- Follow controller patterns with proper cleanup using finalizers\n\n### Security Considerations\n**Security is paramount** - every component must be designed with security-first principles:\n\n- **Critical**: Validate and sanitize all user inputs in admission webhooks\n- **Mandatory**: Implement strict RBAC with principle of least privilege\n- **Essential**: Use secure defaults for all configurations - never trust user input\n- **Required**: Audit and log all policy decisions and violations for security monitoring\n- **Must**: Ensure webhook certificates are properly managed and rotated\n- **Always**: Assume hostile input and implement defense in depth\n- **Never**: Expose sensitive data in logs, error messages, or responses\n\n### Performance Guidelines\n**Performance is critical** - admission controllers must be lightning fast to avoid blocking cluster operations:\n\n- **Critical**: Minimize webhook latency (target <100ms p99, <50ms p95)\n- **Mandatory**: Use efficient CEL over Rego for policy evaluation due to superior performance\n- **Essential**: Implement proper caching for frequently accessed data\n- **Required**: Monitor memory usage in long-running controllers\n- **Must**: Optimize Kubernetes API calls with proper batching\n- **Always**: Profile and benchmark code changes for performance impact\n- **Never**: Trade performance for convenience - cluster stability depends on speed\n\n### OPA Frameworks Integration\nGatekeeper heavily relies on the **OPA Frameworks/Constraint** library (`github.com/open-policy-agent/frameworks/constraint`) for core constraint and policy functionality:\n\n- **Constraint Client**: Provides the core constraint evaluation engine that processes ConstraintTemplates and Constraints\n- **Policy Drivers**: Supports both Rego and CEL policy engines through pluggable drivers\n- **Template Management**: Handles ConstraintTemplate compilation, validation, and CRD generation\n- **Review Processing**: Processes admission review requests against constraint policies\n- **Error Handling**: Provides structured error reporting for policy violations and system errors\n- **Instrumentation**: Built-in metrics and observability for constraint evaluation performance\n\n**Key Integration Points:**\n- `pkg/controller/constrainttemplate/`: Uses frameworks for template validation and CRD management\n- `pkg/webhook/admission/`: Leverages constraint client for policy evaluation during admission\n- `pkg/audit/`: Uses frameworks for periodic compliance checking of existing resources\n- `pkg/drivers/`: Integrates with frameworks' policy engine drivers (Rego/CEL)\n\n### Cert-Controller Integration\nGatekeeper uses **cert-controller** (`github.com/open-policy-agent/cert-controller`) for automatic TLS certificate management:\n\n- **Certificate Rotation**: Automatically generates and rotates TLS certificates for webhook endpoints\n- **CA Management**: Creates and maintains Certificate Authority for webhook validation\n- **Secret Management**: Manages Kubernetes secrets containing TLS certificates and keys\n- **Webhook Configuration**: Automatically updates webhook configurations with current CA bundles\n- **Readiness Integration**: Provides readiness checks to ensure certificates are valid before serving\n\n**Key Integration Points:**\n- `main.go`: Sets up CertRotator with webhook configuration and certificate settings\n- `pkg/webhook/policy.go`: Uses rotator for validating admission webhook TLS\n- `pkg/webhook/mutation.go`: Uses rotator for mutating admission webhook TLS\n\n### Common Patterns\n- Use `context.Context` for all long-running operations\n- Implement graceful shutdown handling\n- Use proper Kubernetes owner references for resource relationships\n- Follow the controller pattern with reconciliation loops\n- Implement proper cleanup using finalizers when needed\n\n### Communication Guidelines\nWhen contributing to Gatekeeper, maintain clear and human-friendly communication:\n\n**Code & Documentation:**\n- Write self-documenting code with meaningful variable and function names\n- Keep comments concise but informative - explain \"why\" not just \"what\"\n- Use clear, descriptive commit messages that explain the intent behind changes\n- Structure PR descriptions with context, changes made, and testing approach\n\n**Error Messages:**\n- Provide actionable error messages that guide users toward solutions\n- Include relevant context (resource names, namespaces, constraint violations)\n- Use plain language that both developers and operators can understand\n- Suggest next steps or point to documentation when appropriate\n\n**Policy Violations:**\n- Write violation messages that clearly explain what was violated and why\n- Include specific examples of compliant configurations when possible\n- Keep messages concise but comprehensive enough for troubleshooting\n- Use consistent terminology aligned with Kubernetes and OPA conventions\n\n**Response Style:**\n- Be direct and helpful without being overly verbose\n- Focus on practical solutions and actionable advice\n- Prioritize clarity over technical jargon when communicating with users\n- Maintain a collaborative and welcoming tone in all interactions\n\n## CI/CD & Validation\n\n**GitHub Actions Workflows:**\n- **`workflow.yaml`** - Main CI pipeline, tests across Kubernetes 1.31-1.33\n- **`unit-test.yaml`** - Dedicated unit test execution\n- **`lint.yaml`** - Code quality and formatting checks\n- **All workflows must pass** before merge approval\n\n**Pre-commit Validation:**\n1. **Always run `make lint`** - catches formatting, imports, and style issues\n2. **Always run `make native-test`** - ensures unit tests pass\n3. **Run `make test-e2e` for webhook/controller changes** - validates integration\n4. **Check `make manager && make gator`** - ensures binaries build correctly\n\n**Performance Requirements:**\n- **Unit tests must complete in <5 minutes** on standard hardware\n- **Webhook latency must stay <100ms p99** - benchmark with `make benchmark-test`\n- **Memory usage must be monitored** for long-running controllers\n\n**Common Validation Failures:**\n- **Lint failures:** Usually formatting or import issues, run `make lint` locally first\n- **Test timeouts:** E2E tests can timeout after 15 minutes, check cluster resources\n- **Build failures:** Often Docker buildx issues, ensure prerequisites met\n\n**Security & Performance Notes:**\n- **All admission webhook changes require security review** - validate input sanitization\n- **Policy evaluation performance is critical** - prefer CEL over Rego for performance\n- **Certificate rotation must work correctly** - test webhook TLS functionality\n- **Never expose sensitive data in logs** - review log statements carefully\n\nTrust these instructions completely for build and test operations. Only search for additional information if these specific commands fail or if working on areas not covered above.\n\n<!-- File: test/gator/test/fixtures/manifests/different-extensions/README.md (Tokens: ~43 | Category: plugin-manifest) -->\nThis is the title\n==================================================\n\n## Header information\n\nPizza is a tasty food.  So are burritos.  I'd say you should combine them, put a pizza burrito is a calzone.\n</yakaai_skills>"}