From 3e1a0148ed943dc426f4a0202f215a5050392668 Mon Sep 17 00:00:00 2001 From: Chao Xu Date: Wed, 4 Nov 2015 14:07:23 -0800 Subject: [PATCH 1/3] add a guide on how to create an API group --- docs/devel/adding-an-APIGroup.md | 81 ++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/devel/adding-an-APIGroup.md diff --git a/docs/devel/adding-an-APIGroup.md b/docs/devel/adding-an-APIGroup.md new file mode 100644 index 00000000000..6db2319886b --- /dev/null +++ b/docs/devel/adding-an-APIGroup.md @@ -0,0 +1,81 @@ + + + + +WARNING +WARNING +WARNING +WARNING +WARNING + +

PLEASE NOTE: This document applies to the HEAD of the source tree

+ +If you are using a released version of Kubernetes, you should +refer to the docs that go with that version. + + +The latest 1.0.x release of this document can be found +[here](http://releases.k8s.io/release-1.0/docs/devel/adding-an-APIGroup.md). + +Documentation for other releases can be found at +[releases.k8s.io](http://releases.k8s.io). + +-- + + + + + +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: + +1. creaet a folder in pkg/apis to hold you 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 scheme; + +3. add a pkg/apis/\/install/install.go, which is responsible for adding the group to the `latest` package, so that other packages can access the group's meta through `latest.Group`. You need to import this `install` package in {pkg/master, pkg/client/unversioned, cmd/kube-version-change}/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, or the kube-version-change tool. + +### Scripts changes and auto-generated code: + +1. Generate conversions and deep-copies: + + 1. add your "group/" or "group/version" into hack/after-build/{update-generated-conversions.sh, update-generated-deep-copies.sh, verify-generated-conversions.sh, verify-generated-deep-copies.sh}; + 2. run hack/update-generated-conversions.sh, hack/update-generated-deep-copies.sh. + +2. Generate files for Ugorji codec: + + 1. touch types.generated.go in pkg/apis/\{/, \}, and run hack/update-codecgen.sh. + +### Client (optional): + +We are overhauling pkg/client, so this section might be outdated. 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_API_VERSIONS` and `KUBE_TEST_API_VERSIONS` in hack/test-go.sh. + + + + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/adding-an-APIGroup.md?pixel)]() + From 1b6810322da570a430acd764a6cd88d7473e6817 Mon Sep 17 00:00:00 2001 From: Chao Xu Date: Wed, 4 Nov 2015 15:52:18 -0800 Subject: [PATCH 2/3] address lavalamp's comment --- docs/devel/adding-an-APIGroup.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/devel/adding-an-APIGroup.md b/docs/devel/adding-an-APIGroup.md index 6db2319886b..f6bf99a2f34 100644 --- a/docs/devel/adding-an-APIGroup.md +++ b/docs/devel/adding-an-APIGroup.md @@ -40,38 +40,42 @@ Please also read about [API conventions](api-conventions.md) and [API changes](a ### Your core group package: -1. creaet a folder in pkg/apis to hold you group. Create types.go in pkg/apis/\/ and pkg/apis/\/\/ to define API objects in your group. +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. -2. create pkg/apis/\/{register.go, \/register.go} to register this group's API objects to the scheme; +1. Create a folder in pkg/apis to hold you group. Create types.go in pkg/apis/``/ and pkg/apis/``/``/ to define API objects in your group; -3. add a pkg/apis/\/install/install.go, which is responsible for adding the group to the `latest` package, so that other packages can access the group's meta through `latest.Group`. You need to import this `install` package in {pkg/master, pkg/client/unversioned, cmd/kube-version-change}/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, or the kube-version-change tool. +2. Create pkg/apis/``/{register.go, ``/register.go} to register this group's API objects to the encoding/decoding scheme; + +3. Add a pkg/apis/``/install/install.go, which is responsible for adding the group to the `latest` package, so that other packages can access the group's meta through `latest.Group`. You need to import this `install` package in {pkg/master, pkg/client/unversioned, cmd/kube-version-change}/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, or the kube-version-change tool. + +Step 2 and 3 are mechanical, we plan on autogenerate these using the cmd/libs/go2idl/ tool. ### Scripts changes and auto-generated code: 1. Generate conversions and deep-copies: - 1. add your "group/" or "group/version" into hack/after-build/{update-generated-conversions.sh, update-generated-deep-copies.sh, verify-generated-conversions.sh, verify-generated-deep-copies.sh}; - 2. run hack/update-generated-conversions.sh, hack/update-generated-deep-copies.sh. + 1. Add your "group/" or "group/version" into hack/after-build/{update-generated-conversions.sh, update-generated-deep-copies.sh, verify-generated-conversions.sh, verify-generated-deep-copies.sh}; + 2. Run hack/update-generated-conversions.sh, hack/update-generated-deep-copies.sh. 2. Generate files for Ugorji codec: - 1. touch types.generated.go in pkg/apis/\{/, \}, and run hack/update-codecgen.sh. + 1. Touch types.generated.go in pkg/apis/``{/, ``}, and run hack/update-codecgen.sh. ### Client (optional): -We are overhauling pkg/client, so this section might be outdated. Currently, to add your group to the client package, you need to +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. +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. +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. +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.\; +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_API_VERSIONS` and `KUBE_TEST_API_VERSIONS` in hack/test-go.sh. +2. Add your "group/version" to `KUBE_API_VERSIONS` and `KUBE_TEST_API_VERSIONS` in hack/test-go.sh. From f16e8cbc0f74993de64bd73b3663a6f1bb128c8c Mon Sep 17 00:00:00 2001 From: Chao Xu Date: Thu, 5 Nov 2015 15:44:20 -0800 Subject: [PATCH 3/3] address timstclair's comments --- docs/devel/adding-an-APIGroup.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/devel/adding-an-APIGroup.md b/docs/devel/adding-an-APIGroup.md index f6bf99a2f34..e5f08552bcc 100644 --- a/docs/devel/adding-an-APIGroup.md +++ b/docs/devel/adding-an-APIGroup.md @@ -44,9 +44,9 @@ We plan on improving the way the types are factored in the future; see [#16062]( 1. Create a folder in pkg/apis to hold you 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; +2. Create pkg/apis/``/{register.go, ``/register.go} to register this group's API objects to the encoding/decoding scheme (e.g., [pkg/apis/extensions/register.go](../../pkg/apis/extensions/register.go) and [pkg/apis/extensions/v1beta1/register.go](../../pkg/apis/extensions/v1beta1/register.go); -3. Add a pkg/apis/``/install/install.go, which is responsible for adding the group to the `latest` package, so that other packages can access the group's meta through `latest.Group`. You need to import this `install` package in {pkg/master, pkg/client/unversioned, cmd/kube-version-change}/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, or the kube-version-change tool. +3. Add a pkg/apis/``/install/install.go, which is responsible for adding the group to the `latest` package, so that other packages can access the group's meta through `latest.Group`. You probably only need to change the name of group and version in the [example](../../pkg/apis/extensions/install/install.go)). You need to import this `install` package in {pkg/master, pkg/client/unversioned, cmd/kube-version-change}/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, or the kube-version-change tool. Step 2 and 3 are mechanical, we plan on autogenerate these using the cmd/libs/go2idl/ tool. @@ -59,7 +59,8 @@ Step 2 and 3 are mechanical, we plan on autogenerate these using the cmd/libs/go 2. Generate files for Ugorji codec: - 1. Touch types.generated.go in pkg/apis/``{/, ``}, and run hack/update-codecgen.sh. + 1. Touch types.generated.go in pkg/apis/``{/, ``}; + 2. Run hack/update-codecgen.sh. ### Client (optional):