Viewing legacy documentation for Kubebuilder, check out the latest documentation instead.

Generating API Documentation

Kubebuilder will generate API reference documentation for your APIs with kubebuilder docs. The reference documentation will be built under docs/reference/build/index.html and can be opened directly in a web browser.

  • Use --docs-copyright to set the copyright footer
  • Use --title to set the title

Non-Kubebuilder Projects

Kubebuilder can also be used to generate API reference documentation for non-kubebuilder projects, as long as the resources are annotated with // +kubebuilder:resource:path=<resource-name> the same as they are in kubebuilder projects.

Important: The // +kubebuilder:resource annotation must appear directly above the go struct defining the resource. No blank lines may appear between the annotation and the go struct.

Creating Examples

Users can provide resource examples by running kubebuilder create example --kind <kind> --group <group> --version <version>. This will create an example file under docs/reference/examples/<kind>/<kind>.yaml for the user to edit. The contents of this file will appear next to the API reference documentation after rerunning kubebuilder docs.

  • note: description that will appear directly above the example
  • sample: example yaml that will be displayed

$ kubebuilder create example --kind Frigate --version v1beta1 --group ships

# docs/reference/examples/frigate/frigate.yaml
note: frigate example
sample: |
  apiVersion: v1beta1
  kind: frigate
  metadata:
    name: frigate
  spec:
    todo: "write me"

Editing Overview and API Group Documentation

Users can modify documentation of the overview and API groups by editing the files under docs/reference/static_includes.

  • Edit _overview.md to provide documentation for the full set of APIs.
  • Edit _<group>.md to provide documentation for a specific API group.

Adding Notes and Warnings for APIs

It is possible to add notes and warnings to APIs in the reference documentation by annotating the go struct with // +kubebuilder:doc:note= or // +kubebuilder:doc:warning=. These will show up in blue and orange boxes.

// Frigate API documentation goes here.
// +kubebuilder:doc:note=this is a note
// +kubebuilder:doc:warning=this is a warning
// +k8s:openapi-gen=true
// +kubebuilder:resource:path=frigates
type Frigate struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    // Spec field documentation goes here.
    Spec   FrigateSpec   `json:"spec,omitempty"`

    // Status field documentation goes here.
    Status FrigateStatus `json:"status,omitempty"`
}

Customizing the API documentation

The generated documentation is controller by the docs/reference/config.yaml file generated by kubebuilder. This file may be manually changed by users to customize the appearance of the documentation, however this is discouraged as the user will need to manually managed the config going forward.

Modifying config.yaml

When manually modifying config.yaml, users must run kubebuilder docs with --generate-config=false to prevent the file from being rewritten.

Table of Contents

docs/reference/config.yaml is automatically generated to create a section for each API group including the APIs in the group, and to show the most mature versions of each API. Both the API sections and displayed API versions may be manually controlled if needed.

generated config.yaml for kubebuilder create resource --kind Bee --group insect --version v1beta1

example_location: "examples"
api_groups: 
  - "Ship"
resource_categories: 
- name: "Ship"
  include: "ship"
  resources: 
  - name: "Frigate"
    version: "v1beta1"
    group: "ship"
    description_warning: "test warnings message annotations"
    description_note: "test notes message annotations"