Writing documentation for Kubernetes Operators can feel like a repetitive task. You define Custom Resource Definitions (CRDs) with extensive schemas, then need to document each field, its type, defaults, and valid values. This article shows how AI assistants streamline the process of generating operator documentation directly from your CRD specifications.

Why Documenting Operators Is Challenging

Kubernetes Operators extend the Kubernetes API with Custom Resources. Each Custom Resource Definition specifies the structure your operator understands. When building production-grade operators, these schemas often include:

• Dozens of fields across nested objects
• Complex validation rules using CEL expressions or OpenAPI v3 schemas
• Default values and enum constraints
• Descriptions that need to match implementation behavior

Manually maintaining documentation that reflects these specs requires significant effort. A small change in your CRD can invalidate several paragraphs of documentation. AI assistants solve this problem by reading your schema and generating accurate documentation automatically.

How AI Assistants Process CRD Specifications

Modern AI coding assistants understand Kubernetes resources and can interpret CRD syntax. When you provide a CRD specification, these tools can extract field information and produce structured documentation.

Input Format: Your CRD YAML

Here’s a typical CRD specification you might feed to an AI assistant:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: caches.example.com
spec:
  group: example.com
  names:
    kind: Cache
    plural: caches
  scope: Namespaced
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              size:
                type: string
                enum: ["small", "medium", "large"]
                default: "medium"
                description: "Cache size determines memory allocation"
              ttlSeconds:
                type: integer
                minimum: 60
                maximum: 86400
                default: 3600
                description: "Time-to-live for cached entries in seconds"
              backend:
                type: object
                properties:
                  type:
                    type: string
                    enum: ["redis", "memcached"]
                  connectionString:
                    type: string
                    minLength: 1
                required: ["type", "connectionString"]
            required: ["backend"]
          status:
            type: object
            properties:
              phase:
                type: string
                enum: ["Pending", "Ready", "Failed"]
              conditions:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    status:
                      type: string
                    lastTransitionTime:
                      type: string
                      format: date-time

Prompting the AI Assistant

To generate documentation, provide your CRD to the AI with a clear request:

Generate API reference documentation for this Kubernetes CRD. Include:
1. A table describing each field in spec and status
2. The type, default value, and description for each field
3. Valid enum values where applicable
4. Required fields marked clearly
5. Example Custom Resource manifests

Example Output

The AI generates documentation similar to this:

Cache CRD API Reference

Example Cache Resource

apiVersion: example.com/v1
kind: Cache
metadata:
  name: my-cache
spec:
  size: large
  ttlSeconds: 7200
  backend:
    type: redis
    connectionString: redis-master:6379

Advanced Documentation Features

Beyond basic API references, AI assistants can generate several other documentation types from your CRD specifications.

Status Conditions Documentation

Kubernetes operators commonly expose status conditions. An AI assistant can explain what each condition type means in the context of your operator:

Generate documentation explaining each status condition type for this operator.
Include troubleshooting guidance for each condition.

The output might explain that a Pending phase indicates the operator is still initializing the cache, while Failed would detail specific error conditions like connection failures or memory exhaustion.

Validation Rule Documentation

If your CRD includes CEL validation rules, AI assistants can explain what they enforce:

x-kubernetes-validations:
- rule: "self.replicas <= self.maxReplicas"
  message: "replicas cannot exceed maxReplicas"

The AI documents these rules in plain language, helping users understand why certain values are rejected.

Migration Guides

When updating operator versions, AI assistants can compare old and new CRD versions:

Compare this v1beta1 CRD with the v1 CRD I just provided.
List all breaking changes, new required fields, and deprecated parameters.

This helps users understand what changes they need to make to their existing Custom Resources.

Automating Documentation with a Script

For teams with multiple operators, you can wrap the AI call in a script that processes every CRD file in a directory and writes the resulting documentation to Markdown files automatically:

# generate_docs.py
import os
import glob
import anthropic

client = anthropic.Anthropic()

PROMPT_TEMPLATE = """
Generate API reference documentation for this Kubernetes CRD.
Include:
1. A Markdown table for all spec fields (type, default, required, description)
2. A Markdown table for all status fields
3. Valid enum values inline in the description column
4. CEL validation rules explained in plain English
5. A complete example Custom Resource

Output only Markdown, no extra commentary.

CRD:
{crd_yaml}
"""

def generate_docs_for_crd(crd_path: str, output_dir: str) -> None:
    with open(crd_path) as f:
        crd_yaml = f.read()

    message = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=4096,
        messages=[{
            "role": "user",
            "content": PROMPT_TEMPLATE.format(crd_yaml=crd_yaml),
        }],
    )

    doc_content = message.content[0].text
    base_name = os.path.splitext(os.path.basename(crd_path))[0]
    out_path = os.path.join(output_dir, f"{base_name}-reference.md")

    with open(out_path, "w") as f:
        f.write(doc_content)

    print(f"Generated: {out_path}")


if __name__ == "__main__":
    import sys
    crd_dir = sys.argv[1] if len(sys.argv) > 1 else "./config/crd/bases"
    out_dir = sys.argv[2] if len(sys.argv) > 2 else "./docs/api"
    os.makedirs(out_dir, exist_ok=True)

    for crd_file in glob.glob(f"{crd_dir}/**/*.yaml", recursive=True):
        generate_docs_for_crd(crd_file, out_dir)

Run it as part of your CI pipeline after any CRD change:

# .github/workflows/docs.yml
- name: Generate CRD docs
  run: python generate_docs.py config/crd/bases docs/api
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Comparing AI Assistants for This Task

Not every AI assistant handles CRD documentation equally well. Here is how the major options compare across the criteria that matter for this use case:

Claude tends to produce the most structurally complete output on first attempt, particularly for complex nested schemas with CEL validation. Copilot and Cursor are more convenient for in-editor workflows where you want to paste the CRD and get documentation in a side panel.

For automated pipelines using the API, Claude is generally the strongest choice. For interactive one-off documentation sessions directly in your editor, Cursor offers the lowest-friction experience since it can read your CRD files directly from the filesystem without copy-pasting.

Practical Workflow

Integrating AI-assisted documentation into your operator development workflow follows a straightforward pattern:

1. Define your CRD first: Write complete CRD specifications with proper descriptions, defaults, and validation rules.
2. Generate initial documentation: Feed the CRD to your AI assistant and request API reference documentation.
3. Review and enhance: Add context that only a human author can provide, such as usage scenarios and troubleshooting tips.
4. Automate on changes: Set up CI/CD to regenerate documentation when CRD files change.

This workflow ensures documentation stays synchronized with your implementation.

Keeping Documentation in Sync

The biggest maintenance problem with operator documentation is drift — the CRD evolves but the documentation does not. Two strategies prevent this:

Hash-based staleness detection: Store a hash of the CRD file alongside the generated docs. In CI, recompute the hash and skip regeneration if nothing changed. Fail the pipeline if docs are missing for any CRD that has changed.

#!/bin/bash
# check_docs_fresh.sh
for crd in config/crd/bases/*.yaml; do
  name=$(basename "$crd" .yaml)
  doc="docs/api/${name}-reference.md"
  hash_file="docs/api/${name}.sha256"

  current_hash=$(sha256sum "$crd" | cut -d' ' -f1)
  stored_hash=$(cat "$hash_file" 2>/dev/null || echo "")

  if [ "$current_hash" != "$stored_hash" ]; then
    echo "STALE: $doc needs regeneration"
    exit 1
  fi
done
echo "All docs are fresh"

Version-pinned generation: Include the CRD metadata.resourceVersion or a manual docs-version annotation in the generated file header. Reviewers can spot at a glance whether documentation reflects the current CRD version.

Integration with Documentation Pipelines

Modern documentation for operators should live in version control and regenerate on every CRD change. Set up a GitHub Actions workflow that feeds updated CRDs to an AI assistant and commits generated docs:

name: Generate Operator Docs
on:
  push:
    paths:
      - 'config/crd/**'
jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Fetch updated CRDs
        run: |
          find config/crd -name "*.yaml" -exec cat {} \; > /tmp/crd-bundle.yaml

      - name: Generate docs with Claude
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          python scripts/generate_operator_docs.py /tmp/crd-bundle.yaml

      - name: Commit generated docs
        run: |
          git config user.name "Operator Docs Bot"
          git config user.email "bot@example.com"
          git add docs/api-reference.md
          git commit -m "docs: regenerate from CRD $(git rev-parse --short HEAD)" || true
          git push

The Python script uses Claude to interpret CRD files and generate markdown:

import anthropic
import yaml

def generate_operator_docs(crd_yaml: str) -> str:
    """Generate operator documentation from CRD specifications."""
    client = anthropic.Anthropic()

    # Parse CRD to extract key information
    crd = yaml.safe_load(crd_yaml)
    kind = crd['spec']['names']['kind']
    group = crd['spec']['group']

    prompt = f"""Generate comprehensive API reference documentation for this Kubernetes operator CRD.

CRD Name: {kind}
API Group: {group}

CRD Specification:
{crd_yaml}

Create documentation with:
1. Overview of what this custom resource represents
2. A detailed table of all fields in spec and status
3. Valid enum values and constraints for each field
4. Three practical example manifests showing common use cases
5. Troubleshooting guide for common issues
6. Migration guide if there are multiple API versions

Format as Markdown suitable for publishing in operator docs.
"""

    message = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=4096,
        messages=[{"role": "user", "content": prompt}]
    )

    return message.content[0].text

# Generate and save
with open('crd-bundle.yaml') as f:
    crd_content = f.read()

docs = generate_operator_docs(crd_content)
with open('docs/api-reference.md', 'w') as f:
    f.write(docs)

Comparison: AI Tools for Operator Docs

Claude excels here because it can hold large YAML documents in context and understand Kubernetes API conventions deeply. For enterprise operators with 50+ fields, Claude generates more complete references without hallucinating field descriptions.

Advanced Patterns

Generating TypedMeta Helpers from CRDs

Your operator code often needs strongly-typed accessors. Claude can generate these:

prompt = """Generate a TypeScript type definition file from this CRD that provides
strong typing for this resource in client code. Use the @kubernetes/client-node types."""

Claude will generate interfaces, constants for status phases, and helper functions for common patterns like checking conditions.

Webhook Documentation

If your CRD has validation or mutation webhooks defined in annotations, ask Claude to document the webhook contracts:

Extract webhook configurations from this CRD. For each webhook, generate:
1. Trigger conditions (create/update/delete)
2. Mutation examples
3. Validation rules applied
4. Failure modes and what happens when validation fails

Related Articles

• AI Tools for Writing Kubernetes Operators 2026
• Best AI Tools for Writing Kubernetes Custom Resource
• Best AI Tools for Writing Kubernetes Operator Code
• Best AI Tools for Go Kubernetes Operator Development
• Best AI Tools for Writing Kubernetes Manifests and Helm

Built by theluckystrike — More at zovo.one