From b9f605b9f87947f4d0ae30aaf8ecd7e3b0d72d7f Mon Sep 17 00:00:00 2001 From: Anthony Byrne Date: Tue, 21 Oct 2025 15:52:35 -0400 Subject: [PATCH 1/2] Update CLAUDE.md with tooling and RBAC guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added sections on: - Controller-gen version management - Boilerplate and container tools - Testing workflow - RBAC model (ClusterRole vs namespace-scoped Roles) These additions provide essential context for development work. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4a2275db..9e413f87 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -92,4 +92,57 @@ make yaml-validate - The operator runs with elevated permissions across multiple namespaces: `openshift-cloud-ingress-operator`, `openshift-ingress`, `openshift-ingress-operator`, `openshift-kube-apiserver`, `openshift-machine-api` - Testing requires careful setup due to dependencies on cloud infrastructure and OpenShift-specific resources - Manual testing instructions are provided in README.md for fleet deployments -- The project uses generated includes from boilerplate conventions for consistent build processes \ No newline at end of file +- The project uses generated includes from boilerplate conventions for consistent build processes + +## Code Generation and Tooling + +### Controller-Gen Version + +Ensure your local `controller-gen` version matches the version used to generate existing CRDs. Check the version annotation in `deploy/crds/*.yaml` files: +```yaml +annotations: + controller-gen.kubebuilder.io/version: v0.x.y +``` + +**Installing the correct version:** +```bash +go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.x.y +controller-gen --version # Verify installation +``` + +### Boilerplate and Container Tools + +The project uses OpenShift boilerplate for standardized builds: +- `make boilerplate-update` - Sync with latest boilerplate changes +- `make container-generate` - Run code generation in containerized environment +- `make container-validate` - Full validation in containerized environment + +Container-based commands ensure consistency with CI/CD pipelines. + +### Testing Workflow + +**Before committing changes:** +```bash +make generate # Generate CRDs and code +make generate-check # Verify no unintended changes +make go-test # Run unit tests +make validate # Full validation (boilerplate + generated files) +make yaml-validate # Validate YAML configurations +``` + +## RBAC Model + +The operator uses a **split RBAC model**: + +### ClusterRole (cluster-scoped resources) +Located in `deploy/20_cloud-ingress-operator.ClusterRole.yaml`: +- Cluster-level resources: `clusterversions`, `infrastructures`, `apiservers`, `dnses` +- Read-only or limited write access + +### Namespace-scoped Roles +Located in `deploy/20_cloud-ingress-operator.Role.yaml` and `resources/*.Role.yaml`: +- Secrets (only in `openshift-cloud-ingress-operator` namespace for cloud credentials) +- Services, ConfigMaps, Pods in specific namespaces +- Full CRUD operations within scoped namespaces + +**Key Principle:** The operator is designed to work with namespace-scoped access to sensitive resources. Avoid granting cluster-wide permissions for resources like Secrets. \ No newline at end of file From a14c30763393a64d2880392e242fc2b2eb30a7f1 Mon Sep 17 00:00:00 2001 From: Anthony Byrne Date: Tue, 21 Oct 2025 16:32:27 -0400 Subject: [PATCH 2/2] Add cache configuration guidance to CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents when and how to add resource types to the cache configuration to avoid RBAC errors when accessing new Kubernetes resources. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9e413f87..2fa60666 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -145,4 +145,17 @@ Located in `deploy/20_cloud-ingress-operator.Role.yaml` and `resources/*.Role.ya - Services, ConfigMaps, Pods in specific namespaces - Full CRUD operations within scoped namespaces -**Key Principle:** The operator is designed to work with namespace-scoped access to sensitive resources. Avoid granting cluster-wide permissions for resources like Secrets. \ No newline at end of file +**Key Principle:** The operator is designed to work with namespace-scoped access to sensitive resources. Avoid granting cluster-wide permissions for resources like Secrets. + +## Cache Configuration + +When adding code that accesses new Kubernetes resource types via `client.Get()` or `client.List()`, add them to the cache configuration in `main.go` (ByObject map) to avoid "is forbidden...at the cluster scope" RBAC errors. + +**Pattern:** +```go +&ResourceType{}: { + Namespaces: namespaces, +}, +``` + +**Currently configured:** IngressController, PublishingStrategy, APIScheme, Service, Secret, Machine, MachineSet, ControlPlaneMachineSet, Deployment \ No newline at end of file