Bazel code generators

codegen.md

Kubernetes Code Generators

Kubernetes provides a collection of code generators to assist with developing APIs. These code generators generate useful libraries such as clients, openapi definitions, copying go structs, etc.

The kubegen uses directory structure conventions to detect Kubernetes APIs definitions and run the standard set of Kubernetes code generators.

There are 2 methods for running kubegen

• Directly through the kubegen command line by downloading the binary and running at a the project root
• Through Bazel by adding rules to WORKSPACE and BUILD.gazel

Kubernetes API conventions

kubegen will run the full set of Kubernetes code generators for all APIs it finds in the project. kubegen looks for API groups defined under pkg/apis/<group>/<version> where group and version match the following patterns.

• group pattern: ^[a-z]+$
• version pattern: ^v\d+(alpha\d+|beta\d+)*$

By default, kubegen will run code generators for both external types defined under pkg/apis/<group>/<version> and internal types defined under pkg/apis/<group>.

kubegen will prepend all generated files with a copright and license.

Running via Command line

The kubegen binary statically compiles all of the Kubernetes code generators and by default runs all of them against all API group/versions defined in the project.

Installing the command line

• Download the latest kubegen release from the code-generators release page.
• Extract the tar and add the kubegen binary to the PATH
• Run kubegen version to list the version
  • Will correspond to a Kubernetes release

Running the command line

kubegen

• run all code generators against discovered APIs
  • run for both internal and external types
• prepend license to generated files
  • wrap the contents of the LICENSE in comments
  • exit non-zero if the LICENSE file is missing

kubegen --copyright "The Kubernetes Authors."

• run all code generators against discovered APIs
  • run for both internal and external types
• prepend license to generated files
  • wrap the contents of the LICENSE in comments
  • start license with "Copyright " e.g. Copyright 2018 The Kubernetes Authors.
  • exit non-zero if the LICENSE file is missing

kubegen --license "Apache 2.0"

• run all code generators against discovered APIs
  • run for both internal and external types
• prepend license to generated files
  • use an Apache 2.0 license

kubegen --license-file "boilerplate.go.txt"

• run all code generators against discovered APIs
  • run for both internal and external types
• prepend license to generated files
  • use the contents from boilerplate.go.txt
  • if boilerplate.go.txt is already in comments then use it verbatim, otherwise wrap it in comments
  • exit non-zero if boilerplate.go.txt is missing

kubegen --generate-internal=false

• run all code generators against discovered APIs
  • run for external types only
• prepend license to generated files
  • wrap the contents of the LICENSE in comments
  • exit non-zero if the LICENSE file is missing

kubegen apps/v1

• run all code generators against the apps/v1 apigroup
  • run for both internal and external types
• prepend license to generated files
  • wrap the contents of the LICENSE in comments
  • exit non-zero if the LICENSE file is missing

kubegen --generator client-gen

• run only the client-gen code generator
  • run for both internal and external types
• prepend license to generated files
  • wrap the contents of the LICENSE in comments
  • exit non-zero if the LICENSE file is missing

Running via Bazel

Installing via bazel

Add the following to the project WORKSPACE file

http_archive(
    name = "io_k8s_rules_go",
    url = "https://github.com/kubernetes/bazelbuild/releases/download/v1.8.0/rules_go-1.8.0.tar.gz",
    sha256 = "<number>",
)

Add the following to the project root BUILD.bazel file

load("@io_k8s_rules_go//go:def.bzl", "code-generator")

kubegen(
    name = "kubegen",
    license = "Apache 2.0",
    copyright = "The Kubernetes Authors.",
)

Running the Bazel target

bazel run //:kubegen

Bazel options

• license: same behavior as license flag for cli
• license-file: same behavior as license-file flag for cli
• copyright: same behavior as copyright flag for cli

FAQ

How does kubegen invoke the other code generators without me having to download them?

kubegen statically compiles the logic for all code generators

How can Kubernetes APIs be provided as inputs to the code generators for things like generating openapi

kubegen will include any vendored API groups found under vendor/k8s.io/api/