gatekeeper-rhacm-integration

name	gatekeeper-rhacm-integration
description	Automates OPA Gatekeeper integration with RHACM following ch-stark/gatekeeper-examples. Reads cluster version via MCP, compares gatekeeper-library policies against OpenShift SCCs, and generates optimized PolicyGenerator with SCC-filtered library inclusion.
allowed-tools	["mcp__kubernetes__configuration_view","mcp__kubernetes__namespaces_list","mcp__kubernetes__pods_list","mcp__kubernetes__resources_list","mcp__kubernetes__resources_get","WebSearch","WebFetch","Read","Write","Bash"]

Gatekeeper RHACM Integration Skill

Automates complete OPA Gatekeeper integration with RHACM following ch-stark/gatekeeper-examples. Intelligently filters 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:

   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:

   kubectl create namespace policies --dry-run=client -o yaml | kubectl apply -f -
   

2. Set up ArgoCD and Placements (from ch-stark/gatekeeper-examples):

   # 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:

   # 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):

   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:

   kustomize build --enable-alpha-plugins . | kubectl apply -n policies -f -
   

6. Label clusters for Gatekeeper deployment:

   # Label managed clusters to receive Gatekeeper policies
   kubectl label managedcluster local-cluster gatekeeper=true
   kubectl label managedcluster <cluster-name> gatekeeper=true
   

7. Verify deployment:

   # 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	PolicyGenerator structure, deployment patterns
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