From 712e4b64571fccb5a5b2e90fdf4a52750b2fd521 Mon Sep 17 00:00:00 2001 From: Chao Xu Date: Wed, 19 Jul 2017 16:41:50 -0700 Subject: [PATCH] redirect adding-an-APIGroup.md to api-changes.md --- contributors/devel/adding-an-APIGroup.md | 110 +---------------------- 1 file changed, 1 insertion(+), 109 deletions(-) diff --git a/contributors/devel/adding-an-APIGroup.md b/contributors/devel/adding-an-APIGroup.md index 82da60b3d..fee831edf 100644 --- a/contributors/devel/adding-an-APIGroup.md +++ b/contributors/devel/adding-an-APIGroup.md @@ -1,115 +1,7 @@ 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. - +Please refer to [api_changes.md](api_changes.md#making-a-new-api-group).