conversion-gen

README

code-generator

Golang code-generators used to implement Kubernetes-style API types.

Purpose

These code-generators can be used

• in the context of CustomResourceDefinition to build native, versioned clients, informers and other helpers
• in the context of User-provider API Servers to build conversions between internal and versioned types, defaulters, protobuf codecs, internal and versioned clients and informers.

Resources

• The example sample controller shows a code example of a controller that uses the clients, listers and informers generated by this library.
• The article Kubernetes Deep Dive: Code Generation for CustomResources gives a step by step instruction on how to use this library.

Compatibility

HEAD of this repo will match HEAD of k8s.io/apiserver, k8s.io/apimachinery, and k8s.io/client-go.

Where does it come from?

code-generator is synced from https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/code-generator. Code changes are made in that location, merged into k8s.io/kubernetes and later synced here.

Documentation

Overview

conversion-gen is a tool for auto-generating functions that convert between internal and external types. A general conversion code generation task involves three sets of packages: (1) a set of packages containing internal types, (2) a single package containing the external types, and (3) a single destination package (i.e., where the generated conversion functions go, and where the developer-authored conversion functions are). The packages containing the internal types play the role known as "peer packages" in the general code-generation framework of Kubernetes.

For each conversion task, `conversion-gen` will generate functions that efficiently convert between same-name types in the two (internal, external) packages. The generated functions include ones named

autoConvert_<pkg1>_<type>_To_<pkg2>_<type>

for each such pair of types --- both with (pkg1,pkg2) = (internal,external) and (pkg1,pkg2) = (external,internal). The generated conversion functions recurse on the structure of the data types. For structs, source and destination fields are matched up according to name; if a source field has no corresponding destination or there is a fundamental mismatch in the type of the field then the generated autoConvert_... function has just a warning comment about that field. The generated conversion functions use standard value assignment wherever possible. For compound types, the generated conversion functions call the `Convert...` functions for the subsidiary types.

For each pair of types `conversion-gen` will also generate a function named

Convert_<pkg1>_<type>_To_<pkg2>_<type>

if both of two conditions are met: (1) the destination package does not contain a function of that name in a non-generated file and (2) the generation of the corresponding autoConvert_... function did not run into trouble with a missing or fundamentally differently typed field. A generated Convert_... function simply calls the corresponding `autoConvert...` function. `conversion_gen` also generates a function that updates a given `runtime.Scheme` by registering all the Convert_... functions found and generated. Thus developers can override the generated behavior for selected type pairs by putting the desired Convert_... functions in non-generated files. Further, developers are practically required to override the generated behavior when there are missing or fundamentally differently typed fields.

`conversion-gen` will scan its `--input-dirs`, looking at the package defined in each of those directories for comment tags that define a conversion code generation task. A package requests conversion code generation by including one or more comment in the package's `doc.go` file (currently anywhere in that file is acceptable, but the recommended location is above the `package` statement), of the form:

// +k8s:conversion-gen=<import-path-of-internal-package>

This introduces a conversion task, for which the destination package is the one containing the file with the tag and the tag identifies a package containing internal types. If there is also a tag of the form

// +k8s:conversion-gen-external-types=<import-path-of-external-package>

then it identifies the package containing the external types; otherwise they are in the destination package.

For each conversion code generation task, the full set of internal packages (AKA peer packages) consists of the ones specified in the `k8s:conversion-gen` tags PLUS any specified in the `--base-peer-dirs` and `--extra-peer-dirs` flags on the command line.

When generating for a package, individual types or fields of structs may opt out of Conversion generation by specifying a comment on the of the form:

// +k8s:conversion-gen=false