forked from kubernetes/community
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
61 changed files
with
9,284 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| # Kubernetes Developer Guide | ||
|
|
||
| The developer guide is for anyone wanting to either write code which directly accesses the | ||
| Kubernetes API, or to contribute directly to the Kubernetes project. | ||
| It assumes some familiarity with concepts in the [User Guide](../user-guide/README.md) and the [Cluster Admin | ||
| Guide](../admin/README.md). | ||
|
|
||
|
|
||
| ## The process of developing and contributing code to the Kubernetes project | ||
|
|
||
| * **On Collaborative Development** ([collab.md](collab.md)): Info on pull requests and code reviews. | ||
|
|
||
| * **GitHub Issues** ([issues.md](issues.md)): How incoming issues are reviewed and prioritized. | ||
|
|
||
| * **Pull Request Process** ([pull-requests.md](pull-requests.md)): When and why pull requests are closed. | ||
|
|
||
| * **Kubernetes On-Call Rotations** ([on-call-rotations.md](on-call-rotations.md)): Descriptions of on-call rotations for build and end-user support. | ||
|
|
||
| * **Faster PR reviews** ([faster_reviews.md](faster_reviews.md)): How to get faster PR reviews. | ||
|
|
||
| * **Getting Recent Builds** ([getting-builds.md](getting-builds.md)): How to get recent builds including the latest builds that pass CI. | ||
|
|
||
| * **Automated Tools** ([automation.md](automation.md)): Descriptions of the automation that is running on our github repository. | ||
|
|
||
|
|
||
| ## Setting up your dev environment, coding, and debugging | ||
|
|
||
| * **Development Guide** ([development.md](development.md)): Setting up your development environment. | ||
|
|
||
| * **Hunting flaky tests** ([flaky-tests.md](flaky-tests.md)): We have a goal of 99.9% flake free tests. | ||
| Here's how to run your tests many times. | ||
|
|
||
| * **Logging Conventions** ([logging.md](logging.md)): Glog levels. | ||
|
|
||
| * **Profiling Kubernetes** ([profiling.md](profiling.md)): How to plug in go pprof profiler to Kubernetes. | ||
|
|
||
| * **Instrumenting Kubernetes with a new metric** | ||
| ([instrumentation.md](instrumentation.md)): How to add a new metrics to the | ||
| Kubernetes code base. | ||
|
|
||
| * **Coding Conventions** ([coding-conventions.md](coding-conventions.md)): | ||
| Coding style advice for contributors. | ||
|
|
||
| * **Document Conventions** ([how-to-doc.md](how-to-doc.md)) | ||
| Document style advice for contributors. | ||
|
|
||
| * **Running a cluster locally** ([running-locally.md](running-locally.md)): | ||
| A fast and lightweight local cluster deployment for development. | ||
|
|
||
| ## Developing against the Kubernetes API | ||
|
|
||
| * The [REST API documentation](../api-reference/README.md) explains the REST | ||
| API exposed by apiserver. | ||
|
|
||
| * **Annotations** ([docs/user-guide/annotations.md](../user-guide/annotations.md)): are for attaching arbitrary non-identifying metadata to objects. | ||
| Programs that automate Kubernetes objects may use annotations to store small amounts of their state. | ||
|
|
||
| * **API Conventions** ([api-conventions.md](api-conventions.md)): | ||
| Defining the verbs and resources used in the Kubernetes API. | ||
|
|
||
| * **API Client Libraries** ([client-libraries.md](client-libraries.md)): | ||
| A list of existing client libraries, both supported and user-contributed. | ||
|
|
||
|
|
||
| ## Writing plugins | ||
|
|
||
| * **Authentication Plugins** ([docs/admin/authentication.md](../admin/authentication.md)): | ||
| The current and planned states of authentication tokens. | ||
|
|
||
| * **Authorization Plugins** ([docs/admin/authorization.md](../admin/authorization.md)): | ||
| Authorization applies to all HTTP requests on the main apiserver port. | ||
| This doc explains the available authorization implementations. | ||
|
|
||
| * **Admission Control Plugins** ([admission_control](../design/admission_control.md)) | ||
|
|
||
|
|
||
| ## Building releases | ||
|
|
||
| See the [kubernetes/release](https://github.com/kubernetes/release) repository for details on creating releases and related tools and helper scripts. | ||
|
|
||
| <!-- BEGIN MUNGE: GENERATED_ANALYTICS --> | ||
| []() | ||
| <!-- END MUNGE: GENERATED_ANALYTICS --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| 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/`<group>`/ and pkg/apis/`<group>`/`<version>`/ to define API objects | ||
| in your group; | ||
|
|
||
| 2. 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](../../pkg/apis/authentication/register.go) and | ||
| [pkg/apis/authentication/v1beta1/register.go](../../pkg/apis/authentication/v1beta1/register.go); | ||
|
|
||
| 3. Add a pkg/apis/`<group>`/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/authentication/install/install.go)). You | ||
| need to import this `install` 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. | ||
|
|
||
| ### 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/`<group>`/`<version>` 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/<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 is `k8s.io/kubernetes/pkg/apis/<group>` (your internal API). | ||
| 3. Make sure your `pkg/apis/<group>` and `pkg/apis/<group>/<version>` directories | ||
| have a doc.go file with the comment `+groupName=<group>.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/`<group>`{/, `<version>`}; | ||
| 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/`<group>`.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.`<group>`; | ||
|
|
||
| 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. | ||
|
|
||
|
|
||
|
|
||
| <!-- BEGIN MUNGE: GENERATED_ANALYTICS --> | ||
| []() | ||
| <!-- END MUNGE: GENERATED_ANALYTICS --> |
Oops, something went wrong.