alirezarezvani/claude-skills / engineering/skills/kubernetes-operator
kubernetes-operator
VerifiedUse when building a Kubernetes operator or CRD (controller-runtime, kubebuilder, operator-sdk, KOPF), before writing the controller. Validates CRDs with crd_validator.py, lints reconcile loops with reconcile_lint.py and scores OperatorHub capability level.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.7 KB |
| assets/crd_template.yaml | config | 2.6 KB |
| assets/reconcile_skeleton.go | script | 4.0 KB |
| references/crd_design.md | markdown | 6.8 KB |
| references/operator_pattern.md | markdown | 7.0 KB |
| references/reconcile_loop.md | markdown | 7.1 KB |
| references/tooling_landscape.md | markdown | 7.5 KB |
| scripts/crd_validator.pyexecutable | script | 5.8 KB |
| scripts/operator_capability_audit.pyexecutable | script | 5.8 KB |
| scripts/reconcile_lint.pyexecutable | script | 6.3 KB |
references/tooling_landscape.md
View on GitHub# Tooling landscape
Five mainstream operator frameworks. Pick by language, complexity, and target environment.
## At-a-glance
| Framework | Language | Scaffolding | Webhook support | Best for | Project status |
|---|---|---|---|---|---|
| **controller-runtime** | Go | None (library) | Yes | Production-grade, low-level | Active (sig-api-machinery) |
| **kubebuilder** | Go | Yes (CLI) | Yes | Standard Go operator path | Active (Kubernetes SIGs) |
| **operator-sdk** | Go / Helm / Ansible | Yes (CLI) | Yes | OpenShift, mixed paradigms | Active (Red Hat) |
| **metacontroller** | Any (webhook) | None | N/A (uses webhooks) | Polyglot, avoid Go | Less active |
| **KOPF** | Python | None (library) | Yes | Python shops, async-first | Active (community) |
| **java-operator-sdk** | Java | Yes | Yes | JVM shops | Active (Red Hat / Java SIG) |
## Decision tree
```
Primary language?
├── Go ──┬── Need scaffolding + opinionated path → kubebuilder
│ ├── Targeting OpenShift / OLM → operator-sdk (Go)
│ └── Library-only, full control → controller-runtime
├── Python ─────────────────────────────────────────→ KOPF
├── Java ─────────────────────────────────────────→ java-operator-sdk
└── Other (Node, Ruby, Rust)
└── webhook-based, polyglot → metacontroller
```
## controller-runtime (Go library)
**What it is:** The Go library that everyone else builds on. Provides `Manager`, `Reconciler`, cache, client, predicates, leader election.
**Use when:**
- You need fine-grained control over the manager and event sources
- You're building reusable operator components
- Your team has Go experience and prefers libraries to scaffolders
**Skip when:**
- You want bootstrap-by-CLI (use kubebuilder)
- You don't speak Go
**Example:**
```go
mgr, _ := ctrl.NewManager(cfg, ctrl.Options{Scheme: scheme})
ctrl.NewControllerManagedBy(mgr).
For(&apps.MyApp{}).
Complete(&MyAppReconciler{Client: mgr.GetClient()})
mgr.Start(ctx)
```
## kubebuilder (Go scaffolder)
**What it is:** The standard scaffolding tool. Wraps controller-runtime with project layout, code generation, and the `kubebuilder` CLI.
**Use when:**
- New Go operator
- You want predictable project structure
- You'll publish the operator publicly
**Workflow:**
```bash
kubebuilder init --domain example.com --repo github.com/org/myapp-operator
kubebuilder create api --group apps --version v1alpha1 --kind MyApp
make manifests
make generate
make run
```
**Strengths:** Excellent docs, mature, used by everyone from cert-manager to Crossplane.
**Weaknesses:** Some teams find the layout opinionated; sometimes hard to escape from.
## operator-sdk (Red Hat / OpenShift)
**What it is:** Wraps kubebuilder for Go and adds Helm-based and Ansible-based operators (no Go required).
**Use when:**
- Targeting OpenShift / OLM (Operator Lifecycle Manager)
- Building a Helm-based operator from an existing chart
- Building an Ansible-based operator from existing playbooks
**Helm-based operator:**
```bash
operator-sdk init --plugins=helm --domain example.com --group apps --version v1 --kind MyApp
operator-sdk create api --group apps --version v1 --kind MyApp --helm-chart=./mychart
```
The operator's reconcile becomes `helm upgrade --install`. Fast on-ramp; less power.
**Ansible-based operator:**
Similar, but reconcile invokes a playbook. Useful for ops teams already deep in Ansible.
**Skip when:**
- Vanilla k8s target (kubebuilder is more direct)
- You want a Go operator without OpenShift coupling
## metacontroller (webhook-based, language-agnostic)
**What it is:** Runs in-cluster, watches your CRDs, and POSTs webhook calls to your endpoints with desired-state computations. You implement the logic in any language behind an HTTP endpoint.
**Use when:**
- Polyglot team (Python, Node, Ruby, etc.)
- Want to avoid Go and Java
- Operator logic is genuinely simple (compute children from parent)
**Example sync hook:**
```python
# Python webhook returns desired children given parent + observed
def sync(request):
parent = request['parent']
return {
'status': {'phase': 'Ready'},
'children': [{'apiVersion': 'apps/v1', 'kind': 'Deployment', ...}],
}
```
**Strengths:** No Go required; fast iteration in any language.
**Weaknesses:** Lower ecosystem activity; not great for complex multi-CRD operators; webhook-based latency.
## KOPF (Python)
**What it is:** A Python framework for building operators. Async-first, decorator-based, no scaffolding step.
**Use when:**
- Python shop
- Operator logic is moderate complexity
- Want fast iteration without recompilation
**Example:**
```python
import kopf
@kopf.on.create('apps.example.com', 'v1alpha1', 'myapps')
async def create_fn(spec, name, namespace, logger, **_):
logger.info(f"creating MyApp {name}")
# ... create children
return {'phase': 'Ready'}
@kopf.on.delete('apps.example.com', 'v1alpha1', 'myapps')
async def delete_fn(spec, name, namespace, **_):
# cleanup external resources
pass
```
**Strengths:**
- Async/await native (good for many concurrent reconciles)
- No code generation
- Good for ML/data teams already in Python
**Weaknesses:**
- Smaller ecosystem than Go
- Some features lag controller-runtime (e.g., complex caching)
- Python startup cost in the controller pod
## java-operator-sdk
**What it is:** Java framework, Quarkus integration, modeled after controller-runtime.
**Use when:** JVM shop with strong Spring/Quarkus skills.
**Skip when:** You don't already have a JVM ops setup.
## Comparison: complexity vs control
```
control ↑
│ controller-runtime (full control, library)
│ │
│ kubebuilder (scaffolded controller-runtime)
│ │
│ operator-sdk Go (kubebuilder + OLM)
│ │
│ KOPF (Python decorators)
│ │
│ java-operator-sdk (JVM)
│ │
│ operator-sdk Ansible (playbooks)
│ │
│ operator-sdk Helm (chart-based)
│ │
│ metacontroller (webhook hooks)
↓
complexity ↓
```
Higher control = more code, more flexibility. Lower complexity = faster start, less power.
## Cross-cutting concerns
Regardless of framework:
- **Webhooks for validation** — reject bad CRs at admission
- **cert-manager** — rotate webhook certs automatically
- **Prometheus** — `/metrics` endpoint via controller-runtime's built-in metrics
- **OLM** (Operator Lifecycle Manager) — for OperatorHub publishing
- **OperatorHub Capability Levels** — see `operator_capability_audit.py`
## Migration paths
| From | To | Effort |
|---|---|---|
| controller-runtime | kubebuilder | Low (kubebuilder uses controller-runtime) |
| Helm chart | Helm-based operator-sdk | Low |
| Helm chart | Go operator (kubebuilder) | High (rewrite logic in Go) |
| KOPF | Go operator | High (language change) |
| Any | metacontroller | Medium (move logic behind HTTP) |
## Selection checklist
Before committing:
- [ ] Identify primary language constraint
- [ ] Target environment (vanilla k8s vs OpenShift/OLM)
- [ ] Operator complexity: 1 CRD vs many
- [ ] Need webhooks?
- [ ] Need OLM publishing?
- [ ] Build a 1-week proof-of-concept; verify reconcile latency, status update flow, and dev-loop ergonomics
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |