How to user code-generator
In this article, we will focus on how to use the K8s code-generator from scratch.
Let's assume we want to create CRD in group "foo.com", and there is a type called "HelloType" with a "message" field in the spec:
# Definition
---
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: hellotypes.foo.com
spec:
group: foo.com
version: v1
scope: Namespaced
names:
kind: HelloType
shortNames: ht
plural: hellotypes
singular: hellotype
# HelloType
---
apiVersion: foo.com/v1
kind: HelloType
metadata:
name: superman-hello
spec:
message: hello world
There are two steps to generate the CRD resource code:
Write the type definition code with code generator tags
Run run the generator to create the client codes which include: clientset, informers, listers for your customer resource
Write type definition code
cd $GOPATH/src
mkdir -p github.com/superman/demo
cd $GOPATH/src/github.com/superman/demo
Create the skeleton files as below under
$GOPATH/src/github.com/superman/demo
pkg/
├── apis
└── foo
└── v1
├── doc.go
├── register.go
└── types.go
doc.go
// +k8s:deepcopy-gen=package
// +k8s:defaulter-gen=TypeMeta
// +groupName=foo.com
package v1
This file provide controls of the global tags that will apply to every type in the same version with default setting.
The tags compose of two parts, the function name and the value to pass in normally. For example in+k8s:deepcopy-gen=package
, deepcopy-gen
is the function to call for generating the deep copies codes for types. package
denotes applying the function to the whole v1 package in this case.
types.go
package v1
import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
// +genclient
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
// HelloType is a top-level type
type HelloType struct {
metav1.TypeMeta `json:",inline"`
// +optional
metav1.ObjectMeta `json:"metadata,omitempty"`
// +optional
Status HelloTypeStatus `json:"status,omitempty"`
// This is where you can define
// your own custom spec
Spec HelloSpec `json:"spec,omitempty"`
}
// custom spec
type HelloSpec struct {
Message string `json:"message,omitempty"`
}
// custom status
type HelloTypeStatus struct {
Name string
}
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
// no client needed for list as it's been created in above
type HelloTypeList struct {
metav1.TypeMeta `json:",inline"`
// +optional
metav1.ListMeta `son:"metadata,omitempty"`
Items []HelloType `json:"items"`
}
+genclient
means generating API client for the type.
+k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
means when generating deepcopy for the type, use runtime.Object interface.
+optional
indicates the field is optional. The data can be empty for the field.
register.go
package v1
import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/apimachinery/pkg/runtime"
"k8s.io/apimachinery/pkg/runtime/schema"
)
// Define your schema name and the version
var SchemeGroupVersion = schema.GroupVersion{
Group: "foo.com",
Version: "v1",
}
var (
SchemeBuilder runtime.SchemeBuilder
localSchemeBuilder = &SchemeBuilder
AddToScheme = localSchemeBuilder.AddToScheme
)
func init() {
// We only register manually written functions here. The registration of the
// generated functions takes place in the generated files. The separation
// makes the code compile even when the generated files are missing.
localSchemeBuilder.Register(addKnownTypes)
}
// Resource takes an unqualified resource and returns a Group qualified GroupResource
func Resource(resource string) schema.GroupResource {
return SchemeGroupVersion.WithResource(resource).GroupResource()
}
// Adds the list of known types to the given scheme.
func addKnownTypes(scheme *runtime.Scheme) error {
scheme.AddKnownTypes(
SchemeGroupVersion,
&HelloType{},
&HelloTypeList{},
)
scheme.AddKnownTypes(
SchemeGroupVersion,
&metav1.Status{},
)
metav1.AddToGroupVersion(
scheme,
SchemeGroupVersion,
)
return nil
}
The register.go
file contains the functions registering the new types we just created to the schema so the API server can recognize them.
Run code-generator to create client codes
go get -u k8s.io/code-generator/...
go get k8s.io/apimachinery
cd $GOPATH/src/k8s.io/code-generator
./generate-groups.sh all "github.com/superman/demo/pkg/client" "github.com/superman/demo/pkg/apis" "foo:v1"
The usage of generate-groups.sh
. More details could be found here.
Usage: $(basename "$0") <generators> <output-package> <apis-package> <groups-versions> ...
<generators> the generators comma separated to run (deepcopy,defaulter,client,lister,informer) or "all".
<output-package> the output package name (e.g. github.com/example/project/pkg/generated).
<apis-package> the external types dir (e.g. github.com/example/api or github.com/example/project/pkg/apis).
<groups-versions> the groups and their versions in the format "groupA:v1,v2 groupB:v1 groupC:v2", relative
to <api-package>.
... arbitrary flags passed to all generator binaries.
After above steps, you will see the following file structure:
kubo@jumper:~/GoProjects/src/github.com/superman/demo/pkg$ tree client/
client/
├── clientset
│ └── versioned
│ ├── clientset.go
│ ├── doc.go
│ ├── fake
│ │ ├── clientset_generated.go
│ │ ├── doc.go
│ │ └── register.go
│ ├── scheme
│ │ ├── doc.go
│ │ └── register.go
│ └── typed
│ └── foo
│ └── v1
│ ├── doc.go
│ ├── fake
│ │ ├── doc.go
│ │ ├── fake_foo_client.go
│ │ └── fake_hellotype.go
│ ├── foo_client.go
│ ├── generated_expansion.go
│ └── hellotype.go
├── informers
│ └── externalversions
│ ├── factory.go
│ ├── foo
│ │ ├── interface.go
│ │ └── v1
│ │ ├── hellotype.go
│ │ └── interface.go
│ ├── generic.go
│ └── internalinterfaces
│ └── factory_interfaces.go
└── listers
└── foo
└── v1
├── expansion_generated.go
└── hellotype.go
16 directories, 22 files
References:
Last updated
Was this helpful?