Skip to main content

Kubebuilder

Kubebuilder

Kubernetes API development framework

Kubebuilder is the framework used to build the Control Plane's operators and custom resources.

Development framework

Kubebuilder provides the scaffolding and tooling used to develop the Control Plane's operators and custom resources.

Overview​

Kubebuilder is a framework for building Kubernetes APIs using CRDs, controllers, and webhooks. It's designed to simplify the development of Kubernetes operators and custom resources by providing code generation, scaffolding, and testing capabilities.

Kubebuilder Logo

Why Kubebuilder?​

🏗️ Standardized Structure

Provides a consistent project structure that follows Kubernetes community best practices.

⚡ Rapid Development

Accelerates development with automatic generation of boilerplate code and manifests.

🧩 Controller Runtime

Built on the battle-tested controller-runtime library used by Kubernetes core components.

🔒 Security by Default

Automatically generates RBAC rules based on controller access patterns.

🧪 Testing Framework

Includes a testing framework that simulates the Kubernetes API server for unit and integration tests.

🚀 Production-Ready

Used by major Kubernetes projects and enterprises for building production operators.

🏗️ Scaffolding

Generate code and manifests for new API types and controllers.

🧪 Testing

Framework for controller and webhook testing with envtest.

🔒 RBAC

Automatic generation of role-based access control manifests.

🔍 Webhooks

Infrastructure for validation and defaulting webhooks.

📖 Documentation

Marker-based API documentation generation.

🔧 CLI Tools

Command-line tools for project management and scaffolding.

Project Structure​

The Control Plane follows the standard Kubebuilder project structure:

├── api/
│   └── v1/
│       ├── rover_types.go
│       ├── apispecification_types.go
│       ├── groupversion_info.go
│       └── zz_generated.deepcopy.go
├── controllers/
│   ├── rover_controller.go
│   ├── apispecification_controller.go
│   └── suite_test.go
├── config/
│   ├── crd/
│   │   └── bases/
│   │       └── rover.cp.ei.telekom.de_rovers.yaml
│   ├── rbac/
│   │   ├── role.yaml
│   │   └── role_binding.yaml
│   ├── manager/
│   │   └── manager.yaml
│   └── samples/
│       └── rover_v1_rover.yaml
└── main.go
Standardized organization

The Kubebuilder project structure ensures consistency across all Control Plane operators, making it easier to navigate, understand, and maintain the codebase.

Working with Kubebuilder​

Creating a New API​

The Control Plane uses Kubebuilder to scaffold new APIs and controllers:

# Create a new API with group 'gateway', version 'v1', kind 'Route'
kubebuilder create api --group gateway --version v1 --kind Route

# Create a new webhook for an existing API
kubebuilder create webhook --group gateway --version v1 --kind Route --defaulting --programmatic-validation

Generating CRDs​

Kubebuilder automatically generates CRDs from Go types with markers:

# Generate CRDs from API definitions
make manifests

# Install CRDs into a cluster
make install

Running Controllers Locally​

The Control Plane developers can run controllers locally for testing:

# Run controller against a remote cluster
make run

# Run controller with specific configuration
KUBECONFIG=/path/to/kubeconfig ENABLE_WEBHOOKS=false make run

Testing with Kubebuilder​

Kubebuilder Testing

Kubebuilder provides the envtest package, which sets up a temporary API server for testing controllers without requiring a real Kubernetes cluster.

View Kubebuilder Testing

Best Practices​

Control Plane patterns

The Control Plane follows these best practices for Kubebuilder-based development.

API Design

  • Follow Kubernetes API conventions
  • Use CRD validation for all fields
  • Separate spec (desired state) from status (observed state)
  • Define clear ownership and dependency relationships

Controller Implementation

  • Make reconciliation idempotent
  • Use finalizers for cleanup operations
  • Log relevant information at appropriate levels
  • Handle errors with appropriate retry strategies

Resource Management

  • Implement owner references for garbage collection
  • Set resource requests and limits appropriately
  • Use metrics for performance monitoring
  • Implement proper error handling and reporting

Testing

  • Write comprehensive unit tests
  • Use envtest for controller integration testing
  • Test failure scenarios and edge cases
  • Verify webhooks with admission review requests

Kubernetes

Learn about the core platform extended by Kubebuilder.

View Kubernetes

Controller Runtime

Explore the library that powers Kubebuilder-based controllers.

View Controller Runtime