MCPInstall

kubernetes-operator

by alirezarezvaniDevOps & Cloud

Use when building a Kubernetes Operator — custom controllers that reconcile CRD state. Triggers on "build an operator", "CRD design", "reconcile loop", "controller-runtime", "kubebuilder", "operator-sdk", "metacontroller", "KOPF", "operator capability levels", or "custom resource". Ships CRD validator, reconcile-loop linter, and OperatorHub capability auditor (all stdlib Python), 4 references on the operator pattern + CRD design + reconcile patterns + tooling landscape, and a /operator-audit slash command. NOT a generic k8s skill — specifically the Operator pattern.

Installs
504
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/alirezarezvani/claude-skills --skill kubernetes-operator
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads kubernetes-operator automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Kubernetes Operator

Build operators that reconcile correctly. Most operator bugs are not Kubernetes bugs — they are reconcile-loop bugs: missing finalizers, blocking calls, no requeue on transient errors, status drift, RBAC over-grants. This skill catches them deterministically before they reach a cluster.

When to use

  • Building a new Kubernetes Operator (controller for a CRD)
  • Reviewing an existing operator for capability-level gaps
  • Auditing a CRD spec for status/conditions/finalizer correctness
  • Choosing a framework (controller-runtime / kubebuilder / operator-sdk / metacontroller / KOPF)
  • Designing the API surface of a Custom Resource
  • Hardening RBAC, leader election, or webhook validation

When NOT to use

  • Plain Helm chart packaging → use helm-chart-builder
  • Standard kubectl operations / blue-green deploys → use senior-devops
  • General k8s security posture → use cloud-security
  • "I want to run a workload" — that's a Deployment / Job, not an operator

Core principle: an operator is a reconcile loop, not a script

observe(actual) → desired = read(spec) → diff(actual, desired) → act → update(status)
                                                                          ↓
                                                                   requeue / done

Operators that fail are the ones that:

  1. Treat reconcile as imperative (do this, then this, then this) instead of declarative (make actual=desired, idempotently)
  2. Don't requeue transient failures
  3. Don't use finalizers, leaving orphan resources
  4. Mutate spec instead of status
  5. Don't use the status subresource (status updates trigger spec reconciles → loop)
  6. Block in reconcile (long HTTP calls, locks)
  7. Forget leader election → split-brain on multi-replica deploys

The 3 tools below catch each of these.

Quick start

SKILL=engineering/kubernetes-operator/skills/kubernetes-operator

# Validate a CRD design
python "$SKILL/scripts/crd_validator.py" --crd config/crd/myapp.yaml

# Lint a Go reconcile function
python "$SKILL/scripts/reconcile_lint.py" --controller controllers/myapp_controller.go

# Score against OperatorHub Capability Levels (1-5)
python "$SKILL/scripts/operator_capability_audit.py" --operator-dir .

The 3 Python tools

All stdlib-only. Run with --help.

crd_validator.py

Validates a CRD YAML against operator-pattern best practices.

python scripts/crd_validator.py --crd config/crd/myapp.yaml
python scripts/crd_validator.py --crd config/crd/ --format json

Checks:

  • spec.versions[*].subresources.status is set (status subresource)
  • spec.scope is Namespaced (not Cluster) unless explicitly justified
  • Singular and listKind defined
  • spec.versions[*].schema.openAPIV3Schema has type definitions (no x-kubernetes-preserve-unknown-fields: true at top level)
  • A version is marked served: true AND storage: true
  • Conditions array is in the schema (allows metav1.Conditions)
  • Printer columns include Age and Status/Phase

reconcile_lint.py

Lints a Go controller reconcile function for anti-patterns.

python scripts/reconcile_lint.py --controller controllers/myapp_controller.go

Checks (regex-based heuristics):

  • Returns are (ctrl.Result, error) shape
  • Errors trigger a non-zero requeue (return ctrl.Result{Requeue: true}, err)
  • client.Update() on the spec object is flagged (controllers should update only status)
  • time.Sleep inside reconcile is flagged (use RequeueAfter)
  • HTTP calls without context cancellation are flagged
  • Missing defer after a finalizer add
  • No IsConditionTrue / SetCondition calls when conditions present in CRD
  • Reconcile function exceeds 80 lines (extract subroutines)

operator_capability_audit.py

Scores an operator against OperatorHub's 5 Capability Levels.

python scripts/operator_capability_audit.py --operator-dir .

Levels:

  • L1 — Basic Install: CRD defined, controller deploys it
  • L2 — Seamless Upgrades: PDBs, conversion webhooks, version skew strategy
  • L3 — Full Lifecycle: backups, restores, failure recovery
  • L4 — Deep Insights: metrics endpoint, Prometheus rules, alerts
  • L5 — Auto Pilot: auto-scaling, auto-tuning, anomaly detection

Reports current level + concrete next steps to advance one level.

Tooling landscape

Pick a framework based on language and complexity. See references/tooling_landscape.md.

FrameworkLanguageBest forMaintenance
controller-runtimeGoProduction-grade, low-level controlActive (sig-api-machinery)
kubebuilderGoStandard scaffolding, opinionatedActive (Kubernetes SIGs)
operator-sdkGo / Helm / AnsibleOpenShift / mixed-paradigm teamsActive (Red Hat)
metacontrollerAny (webhook-based)Polyglot teams, avoiding GoLess active
KOPFPythonPython shops, async-firstActive (community)
java-operator-sdkJavaJVM shopsActive (Red Hat / Java SIG)

Decision rules:

  • New operator + Go shop → kubebuilder
  • New operator + Python shop → KOPF
  • New operator + can't pick a language → metacontroller
  • OpenShift target → operator-sdk

CRD design principles

See references/crd_design.md for full detail. Quick rules:

  1. status is the source of truth for the controller's view of the world. Spec is what the user wants; status is what the controller observed.
  2. Use the status subresource. Without it, status updates re-trigger reconcile (loop).
  3. Use Conditions. Ready, Reconciling, Degraded. Each carries a reason and message.
  4. Add finalizers. Without finalizers, deletion races the controller and orphans external resources.
  5. Version your CRD from day 1. v1alpha1 → v1beta1 → v1. Plan a conversion webhook.
  6. Validate via OpenAPI v3 schema. Don't rely on the controller for validation that should fail at admission.
  7. Use additionalPrinterColumns for kubectl get. Show Age, Phase, Ready at minimum.
  8. Namespace your CRDs unless they manage cluster-scoped resources.

Reconcile loop principles

See references/reconcile_loop.md for full detail. Quick rules:

  1. Idempotent. Reconciling the same state twice → same result, zero side effects.
  2. Read once, decide, act. Don't observe the world repeatedly during reconcile.
  3. Update status, not spec. Spec belongs to the user.
  4. Return errors that requeue. Use ctrl.Result{RequeueAfter: ...} for known transient cases.
  5. Never block. No time.Sleep. No long HTTP calls without context.
  6. Use the cache. Read via the controller's cached client; only escape the cache for a specific reason.
  7. Leader-elect when running >1 replica. Otherwise enable single-replica mode.
  8. Set OwnerReferences. Cascading deletion is the operator pattern's free gift.

Workflows

Workflow 1: Bootstrap a new operator (Go + kubebuilder)

1. Pick a Group/Version/Kind: e.g., apps.example.com/v1alpha1, kind=MyApp
2. kubebuilder init --domain example.com --repo github.com/org/myapp-operator
3. kubebuilder create api --group apps --version v1alpha1 --kind MyApp
4. Run crd_validator.py on config/crd/bases/apps.example.com_myapps.yaml
   → Fix every WARN before writing controller code
5. Implement the reconcile function (Karpathy principle 2: simplest correct version first)
6. Run reconcile_lint.py on controllers/myapp_controller.go
7. Run operator_capability_audit.py --operator-dir . — confirm L1
8. Test in a kind cluster: kubectl apply -f config/samples/
9. Add status conditions; aim for L2 in the same PR

Workflow 2: Audit an existing operator

1. Run operator_capability_audit.py --operator-dir <path>
2. Run crd_validator.py --crd config/crd/
3. Run reconcile_lint.py --controller controllers/
4. Triage findings:
   - FAIL → block release; fix before next deploy
   - WARN → file an issue; fix in next 30 days
5. Document current capability level in README; commit
6. Plan one capability level advancement per quarter

Workflow 3: Choose a framework

1. Identify primary language constraint (team skill)
2. Identify deployment target (vanilla k8s vs OpenShift)
3. Identify operator complexity (single CRD vs multi-CRD vs cluster-wide)
4. Cross-reference with references/tooling_landscape.md
5. Build a 1-week proof-of-concept before committing

References

  • references/operator_pattern.md — what an operator IS, when to use vs alternatives
  • references/crd_design.md — CRD design principles, versioning, conversion webhooks
  • references/reconcile_loop.md — reconcile patterns, error handling, idempotency
  • references/tooling_landscape.md — framework comparison + decision tree

Slash command

/operator-audit — Run all 3 tools on an operator repo and produce a markdown report.

Asset templates

  • assets/crd_template.yaml — CRD with status subresource, conditions, finalizer hint, printer columns
  • assets/reconcile_skeleton.go — Go controller reconcile function with idempotency, conditions, finalizers, requeue patterns

Anti-patterns

  • time.Sleep(30 * time.Second) inside reconcile — block other reconciles. Use RequeueAfter.
  • r.Client.Update(ctx, obj) to set status — use r.Status().Update(ctx, obj) instead.
  • No leader election + 2+ replicas — split-brain.
  • No finalizer — external resources orphan on deletion.
  • CRD without status subresource — status updates trigger spec reconciles (infinite loop).
  • Reconcile function > 200 lines — extract reconcileXxx subroutines per condition.
  • x-kubernetes-preserve-unknown-fields: true on spec root — defeats validation.
  • Imperative reconcile — "if creating, do A; if updating, do B; if deleting, do C". Wrong shape. Reconcile = make actual=desired, regardless of how we got here.

Verifiable success

A team using this skill should achieve:

  • 100% of new CRDs pass crd_validator.py before merge
  • All reconcile functions pass reconcile_lint.py strict mode
  • Operators reach OperatorHub Capability Level 3 (Full Lifecycle) before public release
  • Mean time to fix a reconcile bug: <1 day (no infinite loops in production)

FAQ

What does the kubernetes-operator skill do?

Use when building a Kubernetes Operator — custom controllers that reconcile CRD state. Triggers on "build an operator", "CRD design", "reconcile loop", "controller-runtime", "kubebuilder", "operator-sdk", "metacontroller", "KOPF", "operator capability levels", or "custom resource". Ships CRD validator, reconcile-loop linter, and OperatorHub capability auditor (all stdlib Python), 4 references on the operator pattern + CRD design + reconcile patterns + tooling landscape, and a /operator-audit slash command. NOT a generic k8s skill — specifically the Operator pattern.

How do I install kubernetes-operator?

Run npx skills add https://github.com/alirezarezvani/claude-skills --skill kubernetes-operator in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/kubernetes-operator/ (personal) or .claude/skills/kubernetes-operator/ (project).

Which AI agents can use kubernetes-operator?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is kubernetes-operator safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains kubernetes-operator?

It is published by alirezarezvani in alirezarezvani/claude-skills. It has 504 recorded installs.

More from alirezarezvani/claude-skills

View all →

engineering-skills

alirezarezvani/claude-skills

Index of the engineering-team skills bundle for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365 (stdlib-only Python tools). Use when browsing or choosing among engineering-team role skills — load only the one specialist SKILL.md you need, never bulk-load the bundle.

Backend & APIs2.4K installs

finance-skills

alirezarezvani/claude-skills

Router/index for the finance skills bundled in this plugin: financial-analyst (ratio analysis, DCF valuation, budget variance, rolling forecasts), saas-metrics-coach (ARR/MRR, churn, CAC/LTV, NRR, quick ratio) and month-end-close (close calendar, reconciliations, flux review). Use when a finance request doesn't obviously match one skill and you need to pick the right one (e.g., 'analyze these financials', 'how healthy are my SaaS metrics').

Business & Finance2.3K installs

marketing-skills

alirezarezvani/claude-skills

Directory and router for the marketing skills library. Use when you need to find the right marketing skill for a task, see what marketing capabilities exist, or get oriented in this plugin. 44 specialist skills across 8 pods (content, SEO + AEO, CRO, channels, growth, intelligence, sales enablement, ops), 59 stdlib Python tools. Routes to one skill — it does not execute marketing work itself.

Marketing & SEO2.3K installs

business-growth-skills

alirezarezvani/claude-skills

Router/index for the 4 business & growth skills bundled in this plugin: customer-success-manager (health scoring, churn risk, expansion), sales-engineer (RFP analysis, competitive matrices, PoC planning), revenue-operations (pipeline, forecast accuracy, GTM efficiency), and contract-and-proposal-writer. Use when a growth/revenue request doesn't obviously match one skill and you need to pick the right one (e.g., 'which accounts are at risk', 'should we bid on this RFP').

Business & Finance2.2K installs

engineering-advanced-skills

alirezarezvani/claude-skills

Index of 37 advanced engineering agent skills for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Use when browsing or choosing among the POWERFUL-tier engineering skills: agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, changelog/release automation, reliability (SLO/chaos/flags/operators), platform ops.

AI & Agents2K installs

product-skills

alirezarezvani/claude-skills

Use when coordinating product work across the 12 bundled product sub-skills (RICE, OKRs, UX research, design tokens, competitive teardown, analytics, experiments, discovery, roadmaps, spec-to-repo, landing pages, SaaS scaffolding) or the 4 standalone product-team plugins (user stories, Apple HIG, code-to-PRD, research summarizer). Triggers on 'help me prioritize', 'plan a product experiment', 'we ship features nobody uses', 'run the discovery loop', 'is our OST sound'. Forks context to route to one sub-skill via a deterministic signal router and returns a digest; can also drive a continuous-discovery loop (Torres cadence tracker + OST linter as machine gates) or a full goal→plan→execute→verify→close run through the repo-wide agent-harness. Distinct from project-management (how to deliver vs what to build), marketing/landing (from-scratch pages), and engineering/agent-harness (the generic loop engine this orchestrator plugs into).

Code Quality & Workflow2K installs

Popular devops & cloud skills

View category →

microsoft-foundry

microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure

OfficialDevOps & Cloud579.1K installs

azure-diagnostics

microsoft/azure-skills

Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.

OfficialDevOps & Cloud569.8K installs

azure-prepare

microsoft/azure-skills

Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.

OfficialDevOps & Cloud569K installs

azure-ai

microsoft/azure-skills

Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.

OfficialDevOps & Cloud568.8K installs

azure-deploy

microsoft/azure-skills

Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.

OfficialDevOps & Cloud568.6K installs

azure-validate

microsoft/azure-skills

Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.

OfficialDevOps & Cloud568K installs