MVH

Appearance

Crossplane Docs ​

A CLI tool that automatically generates developer-friendly documentation from Crossplane XRDs and Compositions.

Overview ​

While building XRDs and Compositions for Crossplane, I hit a documentation problem. Developers new to the platform needed clear, readable docs explaining what resources were available and how to use them. Writing and maintaining this documentation manually was tedious and error-prone.

I remembered how well terraform-docs solved this exact problem for Terraform modules. It automatically generates clean markdown documentation straight from your code. I checked if Crossplane had something similar. It didn't.

So I built one.

The Problem ​

Crossplane's power comes from its extensibility through XRDs (Composite Resource Definitions) and Compositions. But that flexibility creates a documentation challenge:

  • XRDs define custom APIs with potentially dozens of fields and options
  • Compositions implement those APIs using cloud provider resources
  • Developers need to understand what's available, what's required, and how to use it
  • Manually documenting all of this is time-consuming and quickly gets out of sync

The alternative is expecting developers to read YAML definitions directly, which isn't realistic at scale.

The Solution ​

Crossplane Docs is a CLI tool that parses your XRDs and Compositions and generates structured markdown documentation. It extracts field names, types, descriptions, validation rules, and examples, then formats everything in a way that's actually useful for developers.

For XRDs, it generates complete field tables showing spec and status fields with types, required/optional indicators, defaults, and validation constraints. For Compositions, it shows what managed resources get created and documents the field mappings and transformations between your XRD and the underlying cloud resources.

Built with Cobra for the CLI framework and leveraging Kubernetes API types, the tool reads your manifests and outputs clean markdown documentation.

Think of it as terraform-docs for Crossplane. Point it at your files, and it generates readable documentation that you can publish to your internal developer portal or include in your repository.

Key Features ​

  • XRD documentation: Complete spec and status field tables with types, validation rules, and defaults
  • Composition analysis: Shows managed resources created and field mapping transformations
  • Type awareness: Documents field types, required vs optional fields, and constraints
  • Nested object support: Handles complex schemas with proper indentation
  • Customizable output: Control verbosity and flatten nested structures if needed
  • CLI-first: Integrates easily into CI/CD pipelines for always up-to-date docs

Getting Started ​

The tool is available on GitHub. Installation and usage instructions are in the repository.

Installation ​

bash
go install github.com/michielvha/crossplane-docs@latest

Usage ​

Generate documentation for XRDs:

bash
# Print to stdout
crossplane-docs xrd xrd.yaml

# Save to file
crossplane-docs xrd xrd.yaml -o README.md

# Flatten nested structures for simpler output
crossplane-docs xrd xrd.yaml --show-nested=false

Generate documentation for Compositions:

bash
# Print to stdout
crossplane-docs composition composition.yaml

# Save to file
crossplane-docs composition composition.yaml -o COMPOSITION.md

# Hide patch details for cleaner output
crossplane-docs composition composition.yaml --show-patches=false

The generated documentation can then be committed to your repository or published to your internal documentation platform.

Why It Matters ​

Platform engineering is about reducing cognitive load for developers. If using your platform requires deep knowledge of YAML schemas and Kubernetes CRDs, you've failed.

Good documentation lowers that barrier. But documentation that's manually maintained becomes stale, and stale documentation is worse than no documentation.

Automated documentation generation solves this. Your docs stay in sync with your code because they're generated from the same source. Developers get reliable, up-to-date information without platform teams spending hours writing and updating documentation.

TIP

This tool works best when your XRDs include good field descriptions and validation rules. The better your source definitions, the better the generated documentation. Treat your XRD schemas as documentation sources, not just API definitions.