# Gatekeeper Rhacm Integration

> 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.

- Skill: `redhat-et/gatekeeper-rhacm-integration` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add redhat-et/gatekeeper-rhacm-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redhat-et/gatekeeper-rhacm-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: redhat-et (https://skillmd.com/u/redhat-et)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/redhat-et/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 |