Gatekeeper Rhacm Integration

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

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