Skip to content

Resource generation

Aiven Kubernetes Operator generates service configs code (also known as user configs) and documentation from public service types schema.

Flow overview

When a new schema is issued on the API, a cron job fetches it, parses, patches, and saves in a shared library — go-api-schemas.

When the library is updated, the GitHub dependabot creates PRs to the dependent repositories, like Aiven Kubernetes Operator and Aiven Terraform Provider.

Then the make generate command is called by GitHub action. And the PR is ready for review.

flowchart TB
    API(Aiven API) <-.->|polls schema updates| Schema([go-api-schemas])
    Bot(dependabot) <-.->|polls updates| Schema
    Bot-->|pull request|UpdateOP[/"✨ $ make generate ✨"/]
    UpdateOP-->|review| OP([operator repository])

make generate

The command runs several generators in a certain sequence. First, the user config generator is called. Then controller-gen cli. Then API reference docs generator and charts generator.

Here how it goes in the details:

  1. User config generator creates Go structs (k8s api compatible objects) with docstrings, validation rules and constraints (immutable, maxLength, etc)
  2. controller-gen generates k8s methods, generates CRDs for those objects, creates charts for cluster roles and webhooks.
  3. Docs generator creates API reference out of CRDs:
  4. it looks for an example file for the given CRD kind in ./<api-reference-docs>/example/, if it finds one, it validates that with the CRD. Each CRD has an OpenAPI v3 schema as a part of it. This is also used by Kubernetes itself to validate user input.
  5. generates full spec reference out of the schema
  6. creates a markdown file with spec and example (if exists)
  7. Charts generator updates CRDs, webhooks and cluster roles charts, adds all changes to the changelog
flowchart TB
    Make[/$ make generate/]-->Generator(userconfig generator<br> creates/updates structs using updated spec)
    Generator-->|go: KafkaUserConfig struct| K8S(controller-gen<br> adds k8s methods to structs)
    K8S-->|go files| CRD(controller-gen<br> creates CRDs out of structs)
    CRD-->|CRD: aiven.io_kafkas.yaml| Docs(docs generator)
    subgraph API reference generation
        Docs-->|aiven.io_kafkas.yaml|Reference(creates reference<br> out of CRD)
        Docs-->|examples/kafka.yaml,<br> aiven.io_kafkas.yaml|Examples(validates example<br> using CRD)
        Examples--> Markdown(creates docs out of CRDs, adds examples)
        Reference-->Markdown(kafka.md)
    end
    CRD-->|yaml files|Charts(charts generator<br> updates helm charts<br> and the changelog)
    Charts-->ToRelease("Ready to release 🎉")
    Markdown-->ToRelease

Charts version bump

By default, charts generator keeps the current helm chart's version, because it doesn't know semver. You need it to do manually.

To do so run the following command with the version of your choice:

make version=v1.0.0 charts