Complete documentation for the breakglass privilege escalation system.
- Quick Start - Get up and running in 5 minutes
- End-to-End Example - Complete production deployment walkthrough
- Installation - Complete step-by-step installation
- Use Cases - Real-world use cases with configuration examples
- Building - Build breakglass from source
- CLI Tool (bgctl) - Command-line interface for terminal access and automation
- Troubleshooting - Common issues and solutions
- Deployment Targets - Kustomize targets (base, debug, dev) and manifest generation
- Production Deployment Checklist - Pre-production readiness verification
- Upgrade Guide - Version upgrades, migration, and rollback procedures
- Configuration Reference - config.yaml settings and examples
- CLI Flags Reference - All controller flags and environment variables
- Ingress Configuration - CORS, security headers, and reverse proxy setup
- Scaling and Leader Election - Multi-replica deployments with leader election
- Webhook Setup - Configure authorization webhooks
- Auth-Operator Integration - Integration with auth-operator for complete RBAC management
- Metrics - Prometheus metrics and monitoring
- Rate Limiting - Multi-tier rate limiting architecture, tiers, and troubleshooting
- Logging and Debugging - Frontend and backend logging infrastructure, debugging tips
- CI Logs and Artifacts - Retrieve CI logs and artifacts with gh CLI
- Identity Provider - OIDC configuration and multi-IDP setup
- Keycloak Configuration - Comprehensive Keycloak configuration for all five OIDC operating modes, including realm setup, client configuration, protocol mappers, GoCloak API interactions, and troubleshooting
- Advanced Features - Multi-IDP Guide - Multiple identity provider configuration and best practices
- Mail Provider - SMTP configuration for email notifications
- Email Templates - Customize and override email notification templates
- Webhook Setup - Configure authorization webhooks
- ClusterConfig - Connect tenant clusters
- BreakglassEscalation - Define escalation policies
- Advanced Features - Request reasons, self-approval prevention, domain restrictions
- ClusterConfig - Manage tenant cluster connections
- BreakglassEscalation - Define privilege escalation policies
- BreakglassSession - Active escalation sessions
- Debug Session - Debug pod deployments and kubectl debug access
- Debug Session Cluster Bindings - Delegate template access to teams and clusters
- Extra Deploy Variables - User-provided variables for customizable templates
- DenyPolicy - Explicit access restrictions
- AuditConfig - Configure audit sinks (Kafka, webhooks, logs)
- IdentityProvider - OIDC identity provider configuration
- MailProvider - SMTP mail provider configuration
- Webhook Setup - Authorization webhook configuration
- API Reference - REST API endpoints and usage
- Metrics - Prometheus metrics and monitoring
- Advanced Features - Request/approval reasons, self-approval prevention, domain restrictions
- Security Best Practices - Rate limiting, input sanitization, network security
- Frontend input sanitization - Request reason sanitization and duration parsing are centralized in shared UI utilities for consistent validation.
- DenyPolicy - Explicit access restrictions and pod security rules
- Pod Security Evaluation - Risk-based exec/attach/portforward controls
- BreakglassEscalation - Security Overrides - Per-escalation pod security exemptions
- Technical Debt - Known TODOs, future enhancements, and maintenance tracking
- Package Structure - Sub-package layout of
pkg/breakglass/ - Release Process - Release signing, provenance, and checklist
- Contributing Guide - Contribution requirements, test policy, and review process
┌──────────────────────────────────────────────────────────────┐
│ Hub Cluster │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Breakglass Controller (webhook + API + policy) │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ ClusterConfig BreakglassEscalation DenyPolicy │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│
│ (webhook endpoint)
▼
┌──────────────────────────────────────────────────────────────┐
│ Tenant Cluster (any of many) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Kubernetes API Server + Authorization Webhook │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
- Policy - Admins create
BreakglassEscalationpolicies - Request - Users request elevated access
- Approval - Approvers review and approve/deny
- Active - Approved sessions grant temporary privileges
- Webhook - Kubernetes validates requests against active sessions
- Expiry - Sessions auto-expire after set duration
- Production Incidents - Emergency cluster-admin access with approval
- Development - Self-service namespace-admin for debugging
- Contractors - Limited-time access with manager approval
- Compliance - All escalations logged and auditable
- Time-bounded access (expires automatically)
- Mandatory approvals for sensitive escalations
- Explicit deny policies override all permissions
- Real-time webhook-based authorization
- Complete audit trail for compliance
- Multi-cluster support
- Scheduled sessions with deferred activation
- Debug sessions and debug pod templates
- Multi-IDP support with optional group sync
- CLI automation via
bgctl - Request modals reset to a clean state when closed for consistent UX
Breakglass supports multiple deployment patterns via component enable flags. See the Installation and CLI Flags Reference for full examples.
- Monolithic (default): frontend + API + SAR webhook + cleanup + validating webhooks
- Webhook-only: validating webhooks only (CRD validation)
- API-only: frontend + API + SAR webhook (no validating webhooks)
- Frontend-only: web UI only
- Cleanup-only: background cleanup routine only