gatekeeper-rhacm-integration

# Gatekeeper RHACM Integration Skill Automates complete OPA Gatekeeper integration with RHACM following [ch-stark/gatekeeper-examples](https://github.com/ch-stark/gatekeeper-examples). Intelligently filters [gatekeeper-library](https://github.com/open-policy-agent/gatekeeper-library) based on OpenShift SCC coverage. ## Core Workflow ### Step 1: Cluster Discovery & Gatekeeper Check 1. **Get cluster version**: ``` Use: mcp__kubernetes__resources_get Parameters: apiVersion=config.openshift.io/v1, kind=ClusterVersion, name=version Extract: status.desired.version ``` 2. **Determine platform**: - ClusterVersion found → `PLATFORM=openshift`, `SCC_FILTERING=true` - Not found → `PLATFORM=kubernetes`, `SCC_FILTERING=false` 3. **Check Gatekeeper Operator installation**: ``` Use: mcp__kubernetes__namespaces_list Check: namespace "gatekeeper-system" or "openshift-gatekeeper-system" exists ``` ``` Use: mcp__kubernetes__resources_list Parameters: apiVersion=apps/v1, kind=Deployment, namespace=gatekeeper-system Check: gatekeeper-controller-manager and gatekeeper-audit deployments exist and Ready ``` 4. **Set Gatekeeper status**: - Deployments found and Ready → `GATEKEEPER_INSTALLED=true` - Not found or not Ready → `GATEKEEPER_INSTALLED=false` 5. **Output status**: ``` ✓ Cluster Discovery Complete Platform: OpenShift 4.18.0 Gatekeeper: Installed ✓ (or: Not Installed - will be deployed via PolicyGenerator) SCC Filtering: Enabled ``` **Note**: If `GATEKEEPER_INSTALLED=false`, the PolicyGenerator will include `policy-install-gatekeeper` with `remediationAction: enforce` to automatically install Gatekeeper on target clusters. This follows the ch-stark/gatekeeper-examples pattern where Gatekeeper installation is the first policy in the dependency chain. ### Step 2: SCC Analysis (OpenShift Only) 1. **Get SCC list**: `mcp__kubernetes__resources_list` (security.openshift.io/v1 SecurityContextConstraints) 2. **Get pod SCC distribution**: `mcp__kubernetes__pods_list`, extract `openshift.io/scc` annotation 3. **Fetch SCC specs via WebSearch**: Query "OpenShift {version} {scc_name} SCC site:docs.openshift.com" 4. **Calculate coverage** using `references/SCC_GATEKEEPER_MAPPING.md`: - ≥95% coverage → `SKIP` (redundant) - <95% coverage → `INCLUDE` (gap-filling) - No SCC equivalent → `INCLUDE` (always) ### Step 3: Generate PolicyGenerator 1. **Create output directory**: ```bash TRACE_ID=$(python3 skills/gatekeeper-rhacm-integration/scripts/get_trace_id.py) mkdir -p skills/gatekeeper-rhacm-integration/assets/${TRACE_ID} ``` 2. **Generate files** following `references/POLICYGENERATOR_TEMPLATE.md`: - `policyGenerator.yaml` - Main PolicyGenerator (exact ch-stark format) - `kustomization.yaml` - Only references policyGenerator.yaml - `gatekeeperlibrary/kustomization.yaml` - SCC-filtered library resources 3. **Gatekeeper Installation Policy**: - Always included in PolicyGenerator (following ch-stark pattern) - `policy-install-gatekeeper` with `remediationAction: enforce` - Uses path: `https://raw.githubusercontent.com/ch-stark/gatekeeper-examples/main/gatekeeperinstall` - All subsequent policies depend on this via `dependencies` chain - If Gatekeeper already installed, policy reports Compliant immediately 4. **Key difference from ch-stark/gatekeeper-examples**: - `gatekeeperlibrary/kustomization.yaml` excludes policies with ≥95% SCC coverage - See `references/SCC_FILTERED_LIBRARY.md` for excluded policies ### Step 4: Deploy to Cluster 1. **Create policies namespace**: ```bash kubectl create namespace policies --dry-run=client -o yaml | kubectl apply -f - ``` 2. **Set up ArgoCD and Placements** (from ch-stark/gatekeeper-examples): ```bash # Apply setupgitops files in order for i in 01 02 03; do curl -sL https://raw.githubusercontent.com/ch-stark/gatekeeper-examples/main/setupgitops/${i}_*.yaml | kubectl apply -f - done # Wait for GitOps operator sleep 30 # Apply remaining setup files (ArgoCD, Applications, Placements) for i in 04 05 06 07 08 09; do curl -sL https://raw.githubusercontent.com/ch-stark/gatekeeper-examples/main/setupgitops/${i}_*.yaml | kubectl apply --validate=false -f - done ``` 3. **Install PolicyGenerator plugin**: ```bash # Download latest PolicyGenerator plugin mkdir -p ~/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator curl -sL https://github.com/open-cluster-management-io/policy-generator-plugin/releases/latest/download/darwin-arm64-PolicyGenerator \ -o ~/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator chmod +x ~/.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator ``` 4. **Download manifest files locally** (PolicyGenerator requires local paths): ```bash cd assets/${TRACE_ID} # Download all ch-stark manifest directories python3 -c " import urllib.request, json, os base = 'https://api.github.com/repos/ch-stark/gatekeeper-examples/contents' dirs = ['gatekeeperinstall', 'gatekeeperconfig', 'gatekeeperchecks', 'gatekeeperconstraint', 'extracontrainttemplates', 'checkadmissionevents', 'mutation', 'hub/templates', 'hub/constraints', 'verify-deprecatedapi'] for d in dirs: os.makedirs(d, exist_ok=True) with urllib.request.urlopen(f'{base}/{d}') as resp: for f in json.load(resp): if f.get('download_url'): with urllib.request.urlopen(f['download_url']) as r: with open(f\"{d}/{f['name']}\", 'wb') as out: out.write(r.read()) " ``` 5. **Build and apply policies**: ```bash kustomize build --enable-alpha-plugins . | kubectl apply -n policies -f - ``` 6. **Label clusters for Gatekeeper deployment**: ```bash # Label managed clusters to receive Gatekeeper policies kubectl label managedcluster local-cluster gatekeeper=true kubectl label managedcluster <cluster-name> gatekeeper=true ``` 7. **Verify deployment**: ```bash # Check policies kubectl get policies -n policies # Check placements kubectl get placement -n policies # Check policy compliance (after MCH fully installed) kubectl get policies -n policies -o custom-columns="NAME:.metadata.name,COMPLIANT:.status.compliant" ``` ## Trigger Phrases - "Integrate Gatekeeper with RHACM" - "Deploy gatekeeper-library to OpenShift with ACM" - "Set up OPA Gatekeeper following ch-stark/gatekeeper-examples" - "Enforce Gatekeeper policies on my cluster" - "Apply the PolicyGenerator to my RHACM hub" ## Key Sources | Source | Purpose | |--------|---------| | [ch-stark/gatekeeper-examples](https://github.com/ch-stark/gatekeeper-examples) | PolicyGenerator structure, deployment patterns | | [gatekeeper-library](https://github.com/open-policy-agent/gatekeeper-library) | ConstraintTemplates and Constraints | | `references/POLICYGENERATOR_TEMPLATE.md` | Exact policyGenerator.yaml template | | `references/SCC_GATEKEEPER_MAPPING.md` | SCC field to gatekeeper policy mapping | | `references/SCC_FILTERED_LIBRARY.md` | Pre-computed OpenShift exclusion list | ## Output Structure ``` assets/${TRACE_ID}/ ├── policyGenerator.yaml # Main PolicyGenerator (local paths) ├── kustomization.yaml # generators: [policyGenerator.yaml] ├── gatekeeperlibrary/ # SCC-filtered gatekeeper-library │ └── kustomization.yaml ├── gatekeeperinstall/ # Downloaded: Gatekeeper Operator subscription ├── gatekeeperconfig/ # Downloaded: Gatekeeper configuration ├── gatekeeperchecks/ # Downloaded: Gatekeeper health checks ├── gatekeeperconstraint/ # Downloaded: Constraint instances ├── extracontrainttemplates/ # Downloaded: Additional templates ├── checkadmissionevents/ # Downloaded: Admission event monitoring ├── mutation/ # Downloaded: Mutation policies ├── hub/ │ ├── templates/ # Downloaded: Hub-specific templates │ └── constraints/ # Downloaded: Hub-specific constraints ├── verify-deprecatedapi/ # Downloaded: Deprecated API validation └── DEPLOYMENT_REPORT.md # Summary report ``` **Note**: Manifest files are downloaded locally because the PolicyGenerator plugin does not support remote URLs. ArgoCD handles remote URL fetching when using GitOps workflow. ## Troubleshooting | Issue | Cause | Fix | |-------|-------|-----| | Gatekeeper not installing | OperatorPolicy has `remediationAction: inform` | Change to `enforce` in `gatekeeperinstall/gatekeepersubscription.yaml` | | ConstraintTemplate error: "unknown field" | Invalid fields in template (listKind, plural, singular, scope) | Remove extra fields, keep only `kind` in `spec.crd.spec.names` | | Policy stuck on NonCompliant | CRDs not cached by config-policy-controller | Delete and recreate the policy to force refresh |