casbin-admission-webhook

Casbin Admission Webhook

A Kubernetes Admission Webhook that uses Casbin for Policy-as-Code enforcement. This webhook validates Kubernetes API requests based on Casbin policies, enabling fine-grained access control over cluster resources.

Features

• 🔐 Policy-based Access Control: Use Casbin's powerful policy engine for Kubernetes admission control
• 🚀 Easy Deployment: Simple Kubernetes manifests and automated certificate generation
• 🧪 Well-tested: Comprehensive unit tests and integration tests
• 📦 Container-ready: Pre-built Docker images available
• 🔄 CI/CD: Automated releases with semantic versioning
• 🛡️ Secure: Runs with minimal privileges and read-only root filesystem

How It Works

The Casbin Admission Webhook acts as a Kubernetes ValidatingWebhookConfiguration that intercepts API requests before they are persisted to etcd. Each request is evaluated against Casbin policies to determine if it should be allowed or denied.

Flow:

1. User makes a Kubernetes API request (e.g., create a pod)
2. Kubernetes API server sends an AdmissionReview to the webhook
3. Webhook evaluates the request against Casbin policies
4. Webhook responds with Allow/Deny decision
5. If allowed, Kubernetes proceeds with the request

Quick Start

Prerequisites

• Kubernetes cluster (v1.16+)
• kubectl configured to access your cluster
• Docker (for building custom images)

Installation

1. Generate TLS certificates and deploy:

# Clone the repository
git clone https://github.com/casbin/casbin-admission-webhook.git
cd casbin-admission-webhook

# Generate certificates and deploy to Kubernetes
make deploy

This will:

• Create the casbin-system namespace
• Generate TLS certificates
• Deploy the webhook server
• Configure the ValidatingWebhookConfiguration

1. Verify the deployment:

kubectl get pods -n casbin-system
kubectl logs -n casbin-system -l app=casbin-admission-webhook

Configuration

Casbin Model

The Casbin model defines the request format and matching rules. Default model (deploy/kubernetes/model.conf):

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = r.sub == p.sub && (r.obj == p.obj || p.obj == "*") && (r.act == p.act || p.act == "*")

Casbin Policy

The policy file defines access rules (deploy/kubernetes/policy.csv):

# Format: p, subject, object, action
# Allow admin to do everything
p, admin, *, *

# Allow developer to create/update/delete pods in development namespace
p, developer, pods/development, CREATE
p, developer, pods/development, UPDATE
p, developer, pods/development, DELETE

# Allow viewer to get resources
p, viewer, */*, GET

Request Format:

• subject: Kubernetes username (from UserInfo)
• object: {resource}/{namespace} (e.g., pods/default)
• action: Kubernetes operation (CREATE, UPDATE, DELETE, etc.)

Customize Policies

Edit the ConfigMap to update policies:

kubectl edit configmap casbin-config -n casbin-system
# Restart pods to reload configuration
kubectl rollout restart deployment casbin-admission-webhook -n casbin-system

Development

Build from Source

# Install dependencies
go mod download

# Run tests
make test

# Build binary
make build

# Run locally (requires valid certs and config)
make run

Run Tests

# Run all tests
go test ./... -v

# Run with coverage
make coverage

Build Docker Image

# Build image
make docker-build

# Build and push (requires Docker Hub credentials)
make docker-push VERSION=v1.0.0

Deployment Options

Using kubectl

# Deploy everything
kubectl apply -f deploy/kubernetes/deployment.yaml
kubectl apply -f deploy/kubernetes/webhook-config.yaml

Manual Certificate Generation

If you prefer to manage certificates yourself:

./deploy/kubernetes/generate-certs.sh casbin-system casbin-admission-webhook

Environment Variables

The webhook supports the following environment variables:

Examples

Example 1: Role-based Access Control

# Admins can do everything
p, system:serviceaccount:kube-system:admin, *, *

# Developers can manage pods in dev namespace
p, developer@example.com, pods/dev, CREATE
p, developer@example.com, pods/dev, UPDATE
p, developer@example.com, pods/dev, DELETE

# Viewers can only read
p, viewer@example.com, */*, GET

Example 2: Namespace Isolation

# Team A can only access team-a namespace
p, team-a, */team-a, *

# Team B can only access team-b namespace
p, team-b, */team-b, *

Example 3: Resource Type Restrictions

# Allow creating configmaps but not secrets
p, developer, configmaps/*, CREATE
p, developer, secrets/*, ""

# Allow reading everything
p, developer, */*, GET

Troubleshooting

Webhook not receiving requests

1. Check webhook configuration:

   kubectl get validatingwebhookconfigurations casbin-admission-webhook -o yaml
   

2. Verify service endpoints:

   kubectl get endpoints -n casbin-system
   

3. Check webhook logs:

   kubectl logs -n casbin-system -l app=casbin-admission-webhook -f
   

Certificate issues

Regenerate certificates:

./deploy/kubernetes/generate-certs.sh casbin-system casbin-admission-webhook
kubectl rollout restart deployment casbin-admission-webhook -n casbin-system

Policy not working as expected

1. Enable verbose logging by checking pod logs
2. Verify policy syntax in the ConfigMap
3. Test policy locally using Casbin's online editor: https://casbin.org/editor

Uninstallation

make undeploy

Or manually:

kubectl delete -f deploy/kubernetes/webhook-config.yaml
kubectl delete -f deploy/kubernetes/deployment.yaml
kubectl delete namespace casbin-system

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.