A namespace admission controller for Rancher project automation

Managing Rancher project assignments across multiple clusters is tedious:

• Manual assignment - Clicking through Rancher UI for each namespace
• Drift - GitOps tools recreate namespaces without project assignments
• Inconsistency - Different clusters have different project configurations
• No automation - Rancher doesn't natively support declarative project assignment

Fencemaster solves this by letting you declare project membership as a simple label. Your GitOps pipeline (Flux, ArgoCD, etc.) creates namespaces with a project: platform label, and Fencemaster automatically assigns them to the correct Rancher project.

Fencemaster is a namespace admission controller that enables Rancher project automation. This mutating admission webhook runs in your Rancher management cluster and automatically adds project annotations to namespaces based on a simple label.

# Add this label to your namespace
labels:
  project: platform

# Fencemaster automatically adds
annotations:
  field.cattle.io/projectId: c-m-xxxxx:p-xxxxx

• Automatic project assignment - Namespaces with project label get Rancher project annotation
• Multi-cluster support - Single deployment serves all downstream clusters
• GitOps friendly - Declarative namespace-to-project mapping
• Namespace exclusions - Skip system namespaces (kube-system, cattle-*, etc.)
• Configurable - Customize label and annotation names
• Caching - In-memory cache for cluster/project lookups
• Prometheus metrics - Monitor webhook performance and cache efficiency

┌─────────────────────────────┐      ┌─────────────────────────────┐
│   Downstream Cluster A      │      │   Downstream Cluster B      │
│                             │      │                             │
│  MutatingWebhookConfig      │      │  MutatingWebhookConfig      │
│  url: .../mutate/cluster-a  │      │  url: .../mutate/cluster-b  │
└──────────────┬──────────────┘      └──────────────┬──────────────┘
               │                                    │
               └──────────────┬─────────────────────┘
                              ▼
               ┌──────────────────────────────┐
               │   Rancher Management Cluster │
               │                              │
               │   fencemaster                │
               │   /mutate/{cluster-name}     │
               │                              │
               │   Queries:                   │
               │   - clusters.provisioning... │
               │   - projects.management...   │
               └──────────────────────────────┘

1. A namespace is created/updated in a downstream cluster with a project label
2. The MutatingWebhookConfiguration sends the admission request to Fencemaster
3. Fencemaster extracts the cluster name from the URL path (/mutate/{cluster-name})
4. Looks up the cluster ID from clusters.provisioning.cattle.io in the management cluster
5. Looks up the project ID from projects.management.cattle.io using the label value
6. Returns a JSON Patch adding the field.cattle.io/projectId annotation
7. Rancher sees the annotation and assigns the namespace to the project

• Rancher v2.6+ (management cluster)
• Kubernetes v1.25+
• Network connectivity from downstream clusters to the webhook endpoint
• TLS termination (via Istio, Gateway API, or ingress controller)

# Install in management cluster
helm install fencemaster oci://ghcr.io/rvbsalgado/charts/fencemaster \
  -n fencemaster --create-namespace

See charts/fencemaster for full installation instructions.

By default, the following namespaces are excluded from mutation:

• kube-system, kube-public, kube-node-lease, default
• cattle-* (all Rancher system namespaces)
• fleet-* (all Fleet namespaces)

You can customize this with the --exclude-namespaces flag or EXCLUDE_NAMESPACES environment variable. Patterns ending with * match prefixes:

# Custom exclusions
--exclude-namespaces="kube-system,kube-public,my-system-*"

Allows namespace creation even if cluster or project lookup fails. The namespace is created without the project annotation.

Rejects the admission request if the cluster or project cannot be found. Use this to enforce that all namespaces with the project label must be assigned to a valid project.

Logs what mutations would be applied without actually patching namespaces. Useful for testing configuration changes.

Fencemaster exposes Prometheus metrics on port 9090 (configurable):

# Build
make build

# Run tests
make test

# Run linter
make lint

# Run all checks
make check

# Build Docker image
make docker-build

• Chart README - Installation and configuration

Apache 2.0 - See LICENSE for details