apiextensions

README

apiextensions

This library provides generated Kubernetes clients for the Giant Swarm infrastructure.

Usage

• pkg/apis: Contains data structures for custom resources in *.giantswarm.io API groups. See full documentation here.
• pkg/clientset/versioned: Contains a clientset, a client for each custom resource, and a fake client for unit testing. See full documentation here.
• pkg/crd: Contains an interface for accessing individual CRDs or listing all CRDs. See full documentation here.

Contributing

Changing Existing Custom Resources

• Make the desired changes in pkg/apis/<group>/<version>
• Update generated files by calling make.
  • make generate && goimports -local github.com/giantswarm/apiextensions -w ./pkg
• Review and commit all changes including generated code.

Naming Convention

Custom resource structs are placed in packages corresponding to the endpoints in Kubernetes API. For example, structs in package github.com/giantswarm/apiextensions/pkg/apis/infrastructure/v1alpha2 are created from objects under /apis/infrastructure.giantswarm.io/v1alpha2/ endpoint.

As this is common to have name collisions between field type names in different custom objects sharing the same group and version (e.g. Spec or Status) we prefix all type names referenced inside custom object with the name of the parent object.

Example:

package v1alpha1

import (
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

type NewObj struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata"`
	Spec              NewObjSpec `json:"spec"`
}

type NewObjSpec struct {
	Field string `json:"field"`
}

Adding a New Custom Resource

This is example skeleton for adding new object.

• Make sure group and version of the object to add exists (described in previous paragraph).
• Replace NewObj with your object name.
• Put struct definitions inside a proper package denoted by group and version in a file named new_obj_types.go. Replace new_obj with snake_case-formatted object name.
• Add NewObj and NewObjList to knownTypes slice in register.go
• Generate code for the resource by calling make.
• Commit changes and create a release.

package v1alpha1

import (
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// +genclient
// +genclient:noStatus
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// NewObj godoc.
type NewObj struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata"`
	Spec              NewObjSpec `json:"spec"`
}

// NewObjSpec godoc.
type NewObjSpec struct {
	FieldName string `json:"fieldName"`
}

// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// NewObjList godoc.
type NewObjList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata"`
	Items           []NewObj `json:"items"`
}

Adding a New Group and/or Version

This is example skeleton for adding new group and/or version.

• Replace GROUP with new group name and VERSION with new version name.
• Create a new package /pkg/apis/GROUP/VERSION/.
• Inside the package create a file doc.go (content below).
• Inside the package create a file register.go (content below).
• Add a new object (described in next paragraph).

Example doc.go content.

// +k8s:deepcopy-gen=package,register

// +groupName=GROUP.giantswarm.io
package VERSION

Example register.go content.

package VERSION

import (
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
	"k8s.io/apimachinery/pkg/runtime/schema"
)

const (
	group   = "GROUP.giantswarm.io"
	version = "VERSION"
)

// knownTypes is the full list of objects to register with the scheme. It
// should contain pointers of zero values of all custom objects and custom
// object lists in the group version.
var knownTypes = []runtime.Object{
		//&Object{},
		//&ObjectList{},
}

// SchemeGroupVersion is group version used to register these objects
var SchemeGroupVersion = schema.GroupVersion{
	Group:   group,
	Version: version,
}

var (
	schemeBuilder = runtime.NewSchemeBuilder(addKnownTypes)

	// AddToScheme is used by the generated client.
	AddToScheme = schemeBuilder.AddToScheme
)

// Adds the list of known types to api.Scheme.
func addKnownTypes(scheme *runtime.Scheme) error {
	scheme.AddKnownTypes(SchemeGroupVersion, knownTypes...)
	metav1.AddToGroupVersion(scheme, SchemeGroupVersion)
	return nil
}

Updating dependencies

Cluster API

Cluster API CRDs are also exported by this library using controller-gen. The version used is determined by the value of sigs.k8s.io/cluster-api in hack/go.mod.

Code Generation Tools

To change the version of a tool, edit the version manually in hack/tools/<tool>/go.mod and run go mod tidy in that directory so that go.sum is updated.

Versioning

This library uses standard semantic versioning. Versioning of CRDs is a separate issue covered in the Kubernetes deprecation policy. In short, if an API field needs to be removed, a new version must be created, and any versions served concurrently must be convertible in both directions without data loss.

Code generation

This library uses code generation to generate several components so that they do not need to be maintained manually and to reduce the chance of mistakes such as when, for example, defining an OpenAPIV3 schema for a CRD.

Makefile

The Makefile at the root of the repository ensures that required tools (defined below) are installed in hack/tools/bin and then runs each step of the code generation pipeline sequentially.

The main code generation steps are as follows:

• generate-clientset: Generates the clientset for accessing custom resources in a Kubernetes cluster.
• generate-deepcopy: Generates zz_generated.deepcopy.go in each package in pkg/apis with deep copy functions.
• generate-manifests: Generates CRDs in config/crd/v1 and config/crd/v1beta1 from CRs found in pkg/apis.
• generate-fs: Generates pkg/crd/internal package containing a filesystem holding all files in config/crd.
• imports: Sorts imports in all source files under ./pkg.
• patch: Applies the git patch hack/generated.patch to work around limitations in code generators.

These can all be run with make generate or simply make as generate is the default rule.

Extra commands are provided including:

• clean-tools: Deletes all tools from the tools binary directory.
• clean-generated: Deletes all generated files.
• verify: Regenerates files and exits with a non-zero exit code if generated files don't match HEAD in source control.

Tools

Tools are third-party executables which perform a particular action as part of the code generation pipeline. They are defined in hack/tools in separate directories. Versions for the tools are defined in the go.mod file in their respective directories. A common go.mod isn't used so that their dependencies don't interfere.

deepcopy-gen

Generates DeepCopy and DeepCopyInto functions for all custom resources to satisfy the runtime.Object interface.

client-gen

Generates a "client set" which provides CRUD interfaces for each custom resource.

esc

Encodes local filesystem trees into a Go source file containing an http.FileSystem which provides access to the files at runtime. This allows these files to be accessed from a binary outside of the source tree containing those files.

controller-gen

Generates a custom resource definition (CRD) for each custom resource using special comments such as // +kubebuilder:validation:Optional.

kustomize

Provides an extra patch step for generated CRD YAML files because certain CRD fields can't be modified with controller-gen directly.

goimports

Updates Go import lines by adding missing ones and removing unreferenced ones. This is required because CI checks for imports ordered in three sections (standard library, third-party, local) but certain code generators only generate source files with two sections.