Adding an API Group =============== This document includes the steps to add an API group. You may also want to take a look at PR [#16621](https://github.com/kubernetes/kubernetes/pull/16621) and PR [#13146](https://github.com/kubernetes/kubernetes/pull/13146), which add API groups. Please also read about [API conventions](api-conventions.md) and [API changes](api_changes.md) before adding an API group. ### Your core group package: We plan on improving the way the types are factored in the future; see [#16062](https://github.com/kubernetes/kubernetes/pull/16062) for the directions in which this might evolve. 1. Create a folder in pkg/apis to hold your group. Create types.go in pkg/apis/``/ and pkg/apis/``/``/ to define API objects in your group; 2. Create pkg/apis/``/{register.go, ``/register.go} to register this group's API objects to the encoding/decoding scheme (e.g., [pkg/apis/authentication/register.go](https://github.com/kubernetes/kubernetes/blob/master/pkg/apis/authentication/register.go) and [pkg/apis/authentication/v1beta1/register.go](https://github.com/kubernetes/kubernetes/blob/master/pkg/apis/authentication/v1beta1/register.go); The register files must have a var called SchemeBuilder for the generated code to reference. There must be an AddToScheme method for the installer to reference. You can look at a group under `pkg/apis/...` for example register.go files to use as a template, but do not copy the register.go files under `pkg/api/...`--they are not general. 3. Add a pkg/apis/``/install/install.go, You probably only need to change the name of group and version in the [example](https://github.com/kubernetes/kubernetes/blob/master/pkg/apis/authentication/install/install.go)). This package must be imported by the server along with `k8s.io/kubernetes/pkg/api/install`. Import these packages with the blank identifier as they do not have user callable code and exist solely for their initialization side-effects. Step 2 and 3 are mechanical, we plan on autogenerate these using the cmd/libs/go2idl/ tool. ### Type definitions in `types.go` Each type should be an exported struct (have a capitalized name). The struct should have the `TypeMeta` and `ObjectMeta` embeds. There should be a `Spec` and a `Status` field. If the object is solely a data storage object, and will not be modified by a controller, the status field can be left off and the fields inside the `Spec` can be inlined directly into the struct. For each top-level type there should also be a `List` struct. The `List` struct should have the `TypeMeta` and `ListMeta` embeds. There should be an `Items` field that is a slice of the defined type. ### Scripts changes and auto-generated code: 1. Generate conversions and deep-copies: 1. Add your "group/" or "group/version" into cmd/libs/go2idl/conversion-gen/main.go; 2. Make sure your pkg/apis/``/`` directory has a doc.go file with the comment `// +k8s:deepcopy-gen=package,register`, to catch the attention of our generation tools. 3. Make sure your `pkg/apis//` directory has a doc.go file with the comment `// +k8s:conversion-gen=`, to catch the attention of our generation tools. For most APIs the only target you need is `k8s.io/kubernetes/pkg/apis/` (your internal API). 3. Make sure your `pkg/apis/` and `pkg/apis//` directories have a doc.go file with the comment `+groupName=.k8s.io`, to correctly generate the DNS-suffixed group name. 5. Run hack/update-all.sh. 2. Generate files for Ugorji codec: 1. Touch types.generated.go in pkg/apis/``{/, ``}; 2. Run hack/update-codecgen.sh. 3. Generate protobuf objects: 1. Add your group to `cmd/libs/go2idl/go-to-protobuf/protobuf/cmd.go` to `New()` in the `Packages` field 2. Run hack/update-generated-protobuf.sh ### Client (optional): We are overhauling pkg/client, so this section might be outdated; see [#15730](https://github.com/kubernetes/kubernetes/pull/15730) for how the client package might evolve. Currently, to add your group to the client package, you need to: 1. Create pkg/client/unversioned/``.go, define a group client interface and implement the client. You can take pkg/client/unversioned/extensions.go as a reference. 2. Add the group client interface to the `Interface` in pkg/client/unversioned/client.go and add method to fetch the interface. Again, you can take how we add the Extensions group there as an example. 3. If you need to support the group in kubectl, you'll also need to modify pkg/kubectl/cmd/util/factory.go. ### Make the group/version selectable in unit tests (optional): 1. Add your group in pkg/api/testapi/testapi.go, then you can access the group in tests through testapi.``; 2. Add your "group/version" to `KUBE_TEST_API_VERSIONS` in hack/make-rules/test.sh and hack/make-rules/test-integration.sh TODO: Add a troubleshooting section. [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/adding-an-APIGroup.md?pixel)]()