giantswarm / crd-docs-generator

Tooling to create user-friendly reference documentation for Kubernetes Custom Resource Definitions (CRDs)

crd-docs-generator

Generates schema reference documentation for Kubernetes Custom Resource Definitions (CRDs).

This tool is built to generate our Management API CRD schema reference.

The generated output consists of Markdown files packed with HTML. By itself, this does not provide a fully readable and user-friendly set of documentation pages. Instead it relies on the HUGO website context, as the giantswarm/docs repository, to provide an index page and useful styling.

Assumptions/Prerequisites

This tool relies on:

• CRDs being defined in public source repositories in YAML format.
• CRDs providing an OpenAPIv3 validation schema
  • either in the .spec.validation section of a CRD containg only one version
  • or in the .spec.versions[*].schema position of a CRD containing multiple versions
• OpenAPIv3 schemas containing description attributes for every property.
• The topmost description value explaining the CRD itself. (For a CRD containing multiple versions, the first description found is used as such.)
• CR examples to be found in the source repository/repositories as one example per YAML file.

Usage

Docker

The generator can be executed in Docker using a command like this:

docker run \
    -v $PWD/path/to/output-folder:/opt/crd-docs-generator/output \
    -v $PWD:/opt/crd-docs-generator/config \
    gsoci.azurecr.io/giantswarm/crd-docs-generator:0.11.0 \
      --config /opt/crd-docs-generator/config/config.example.yaml

Here, the tag 0.11.0 is the version number of the crd-docs-generator release you're going to use. See our GitHub releases for available tags.

The volume mapping defines where the generated output will land.

Development

With Go installed and this repository cloned, you can exetute the program like this:

go run main.go --config config.example.yaml

See the config.example.yaml file for an idea how to configure your source repositories.

TODO

• Parse template only once instead of for every CRD

crd-docs-generator's Issues

can you declare different locations other than /docs and /config

To use this tool, the git repository needs two top-level directories defined (config which contains config/crd, and docs which contains docs/cr).

Is there anyway to override this? I would like to be able to have a single top level directory with everything in it. e.g.

crd-docs
      |____config
      |        |___crd
      |____docs
             |____cr

So I can still have the config/crd and docs/cr directories, but they are all under a single top level directory crd-docs.

Workaround I am going to use is create softlinks in my git repo so my top level config and docs directories are linked to the corresponding directories under crd-docs. But I would prefer not to have these extra directories at the top of my repo.

How to add example CRs

Hi, first of all, many thanks for this great tool!
I saw that the published docs include example CRs, but despite looking at the source codes in the different repos, I couldn't find out where they are coming from. How can you configure crd-docs-generator to include an example CR file for a CRD, or where does it look for the file by default?

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: Preset is invalid JSON (github>giantswarm/renovate-presets:default.json5)

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

circleci

.circleci/config.yml

• architect 5.5.1

dockerfile

Dockerfile

• gsoci.azurecr.io/giantswarm/alpine 3.20.2

gomod

go.mod

• go 1.22.0
• go 1.23.0
• github.com/Masterminds/sprig/v3 v3.2.3
• github.com/ghodss/yaml v1.0.0
• github.com/giantswarm/microerror v0.4.1
• github.com/google/go-cmp v0.6.0
• github.com/russross/blackfriday/v2 v2.1.0
• github.com/spf13/cobra v1.8.1
• gopkg.in/yaml.v3 v3.0.1
• k8s.io/apiextensions-apiserver v0.31.0
• k8s.io/apimachinery v0.31.0
• github.com/coreos/etcd v3.3.27+incompatible
• github.com/gogo/protobuf v1.3.2
• golang.org/x/net v0.28.0

kubernetes

pkg/crd/testdata/awsclusterconfig.yaml

• CustomResourceDefinition apiextensions.k8s.io/v1

testdata/case1/crd/crd1.yaml

• CustomResourceDefinition apiextensions.k8s.io/v1

testdata/case1/crd/crd2.yaml

• CustomResourceDefinition apiextensions.k8s.io/v1

---

• Check this box to trigger a request for Renovate to run again on this repository

Content of config.example.yaml

Hi ,

I am trying to use your project but it is not clear to me what should be the content of the config file ( config.example.yaml)
Is there an example we can use?

Kind Regards,
Niels

Original image quay.io/giantswarm/crd-docs-generator is not up to date?

I tried to use the tool and found that it simply does not work, even when using the provider config example. Then I decided to try an older release, just in case. And so I have discovered that the container image from DockerHub actually works but the one from quay.io/giantswarm/crd-docs-generator does not.

❯ docker run -v $PWD/out:/opt/crd-docs-generator/output  -v $PWD:/opt/crd-docs-generator/config quay.io/giantswarm/crd-docs-generator --config /opt/crd-docs-generator/config/config.example.yaml

--- Stack Trace ---
Error: could not parse config file error: yaml: unmarshal errors:
  line 10: field output_path not found in type config.FromFile
  line 21: field crd_paths not found in type config.SourceRepository
  line 23: field cr_paths not found in type config.SourceRepository
  line 59: field crd_paths not found in type config.SourceRepository
  line 61: field cr_paths not found in type config.SourceRepository
  line 74: field crd_paths not found in type config.SourceRepository
  line 76: field cr_paths not found in type config.SourceRepository
  line 88: field crd_paths not found in type config.SourceRepository
  line 90: field cr_paths not found in type config.SourceRepository
  line 103: field annotations_paths not found in type config.SourceRepository
  line 105: field crd_paths not found in type config.SourceRepository
  line 108: field cr_paths not found in type config.SourceRepository
2023/05/04 13:14:04 /root/project/main.go:87
2023/05/04 13:14:04 /root/project/pkg/config/config.go:55

But (also works with 0.11.0 tag):

 docker run -v $PWD/out:/opt/crd-docs-generator/output  -v $PWD:/opt/crd-docs-generator/config giantswarm/crd-docs-generator:0.10.0 --config /opt/crd-docs-generator/config/config.example.yaml
2023/05/04 13:16:43 INFO - repo apiextensions-application (https://github.com/giantswarm/apiextensions-application)
2023/05/04 13:16:43 INFO - repo apiextensions-application - cloning repository
2023/05/04 13:16:44 INFO - repo apiextensions-application - reading CRDs from file /tmp/gitclone/giantswarm/apiextensions-application/config/crd/application.giantswarm.io_appcatalogentries.yaml
2023/05/04 13:16:44 INFO - repo apiextensions-application - processing CRD appcatalogentries.application.giantswarm.io with versions [v1alpha1]
...

Annotations YAML comments not working with Go 1.19

go fmt in Go 1.19 modifies whitespace in comments.

Our system of providing docs metadata to annotations is based on YAML in comments. However go fmt as of Go 1.19 modifies our unit test (pkg/annotations/testdata/aws.go) and the entire build process breaks in CI.

There is impact beyond CI however. If crd-docs-generator is used with a Go repository that defines annotations and uses YAML in comments, this repo will also not work with Go 1.19.

Example

Before:

// support:
//   - crd: awsclusters.infrastructure.giantswarm.io
//     apiversion: v1alpha2
//     release: Since 14.0.0
// documentation:
//   This annotation allows configuration of the MINIMUM_IP_TARGET parameter for AWS CNI.
const AWSCNIMinimumIPTarget = "alpha.cni.aws.giantswarm.io/minimum-ip-target"

After go fmt pkg/annotations/testdata/aws.go:

// support:
//   - crd: awsclusters.infrastructure.giantswarm.io
//     apiversion: v1alpha2
//     release: Since 14.0.0
//
// documentation:
//
//	This annotation allows configuration of the MINIMUM_IP_TARGET parameter for AWS CNI.
const AWSCNIMinimumIPTarget = "alpha.cni.aws.giantswarm.io/minimum-ip-target"

Diff:

--- a/pkg/annotations/testdata/aws.go
+++ b/pkg/annotations/testdata/aws.go
@@ -7,6 +7,8 @@ package aws
 //   - crd: awsclusters.infrastructure.giantswarm.io
 //     apiversion: v1alpha2
 //     release: Since 14.0.0
+//
 // documentation:
-//   This annotation allows configuration of the MINIMUM_IP_TARGET parameter for AWS CNI.
+//
+//     This annotation allows configuration of the MINIMUM_IP_TARGET parameter for AWS CNI.
 const AWSCNIMinimumIPTarget = "alpha.cni.aws.giantswarm.io/minimum-ip-target"

Potential solutions

So far this means we keep our CI using Go 1.18.

To get this problem sorted out and help us move to Go 1.19:

• Create an upstream issue to find out if this behaviour of go fmt is expected.
• Potentially rename the testdata Go files to a different extension than .go. (Would only solve the problem for our CI)
• Can YAML be formatted in a way that is not altered by go fmt?
• Should we change the metadata format from YAML to something else?

Ideas for other solutions are welcome.