If you are using a released version of Kubernetes, you should refer to the docs that go with that version.
The latest release of this document can be found [here](http://releases.k8s.io/release-1.4/docs/devel/adding-an-APIGroup.md).Documentation for other releases can be found at releases.k8s.io.
This document includes the steps to add an API group. You may also want to take a look at PR #16621 and PR #13146, which add API groups.
Please also read about API conventions and API changes before adding an API group.
We plan on improving the way the types are factored in the future; see #16062 for the directions in which this might evolve.
-
Create a folder in pkg/apis to hold your group. Create types.go in pkg/apis/
<group>
/ and pkg/apis/<group>
/<version>
/ to define API objects in your group; -
Create pkg/apis/
<group>
/{register.go,<version>
/register.go} to register this group's API objects to the encoding/decoding scheme (e.g., pkg/apis/authentication/register.go and pkg/apis/authentication/v1beta1/register.go; -
Add a pkg/apis/
<group>
/install/install.go, which is responsible for adding the group to thelatest
package, so that other packages can access the group's meta throughlatest.Group
. You probably only need to change the name of group and version in the example). You need to import thisinstall
package in {pkg/master, pkg/client/unversioned}/import_known_versions.go, if you want to make your group accessible to other packages in the kube-apiserver binary, binaries that uses the client package.
Step 2 and 3 are mechanical, we plan on autogenerate these using the cmd/libs/go2idl/ tool.
-
Generate conversions and deep-copies:
- Add your "group/" or "group/version" into cmd/libs/go2idl/conversion-gen/main.go;
- Make sure your pkg/apis/
<group>
/<version>
directory has a doc.go file with the comment// +k8s:deepcopy-gen=package,register
, to catch the attention of our generation tools. - Make sure your
pkg/apis/<group>/<version>
directory has a doc.go file with the comment// +k8s:conversion-gen=<internal-pkg>
, to catch the attention of our generation tools. For most APIs the only target you need isk8s.io/kubernetes/pkg/apis/<group>
(your internal API). - Make sure your
pkg/apis/<group>
andpkg/apis/<group>/<version>
directories have a doc.go file with the comment+groupName=<group>.k8s.io
, to correctly generate the DNS-suffixed group name. - Run hack/update-all.sh.
-
Generate files for Ugorji codec:
- Touch types.generated.go in pkg/apis/
<group>
{/,<version>
}; - Run hack/update-codecgen.sh.
- Touch types.generated.go in pkg/apis/
-
Generate protobuf objects:
- Add your group to
cmd/libs/go2idl/go-to-protobuf/protobuf/cmd.go
toNew()
in thePackages
field - Run hack/update-generated-protobuf.sh
- Add your group to
We are overhauling pkg/client, so this section might be outdated; see #15730 for how the client package might evolve. Currently, to add your group to the client package, you need to:
-
Create pkg/client/unversioned/
<group>
.go, define a group client interface and implement the client. You can take pkg/client/unversioned/extensions.go as a reference. -
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. -
If you need to support the group in kubectl, you'll also need to modify pkg/kubectl/cmd/util/factory.go.
-
Add your group in pkg/api/testapi/testapi.go, then you can access the group in tests through testapi.
<group>
; -
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.