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.
Add new client library procedure proposal
- Loading branch information
Showing
2 changed files
with
292 additions
and
0 deletions.
There are no files selected for viewing
192 changes: 192 additions & 0 deletions
192
contributors/design-proposals/csi-client-structure-proposal.md
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,192 @@ | ||
| # Overall Kubernetes Client Structure | ||
|
|
||
| **Status:** Approved by SIG API Machinery on March 29th, 2017 | ||
|
|
||
| **Authors:** @lavalamp, @mbohlool | ||
|
|
||
| **last edit:** 2017-3-22 | ||
|
|
||
| ## Goals | ||
|
|
||
| * Users can build production-grade programmatic use of Kubernetes-style APIs in their language of choice. | ||
|
|
||
| ## New Concept | ||
|
|
||
| Today, Kubernetes has the concept of an API Group. Sometimes it makes sense to package multiple groups together in a client, for example, the core APIs we publish today. I’ll call this a "group collection" as it sounds a bit better than “group group.” Group collections will have names. In particular, this document uses “core” as the name for the current set of APIs. | ||
|
|
||
| ## Repositories | ||
|
|
||
| We’ve decomposed the problem into several components. We’d like to make the following repositories under a new `kubernetes-client` github org. | ||
|
|
||
| * github.com/kubernetes-client/gen | ||
|
|
||
| * Contents: | ||
|
|
||
| * OpenAPI preprocessing (shared among multiple languages) and client generator(s) scripts | ||
|
|
||
| * The Kubernetes go language client generator, which currently takes as input a tree of types.go files. | ||
|
|
||
| * Future work: Convert OpenAPI into a types.go tree, or modify the input half of the go language generator. | ||
|
|
||
| * Make the client generation completely automated so it can be part of a build process. Less reason for people to create custom repos as many clients for single language (and different api extensions) could be confusing. | ||
|
|
||
| * gen is intended to be used as part of build tool chains. | ||
|
|
||
| * github.com/kubernetes-client/go-base | ||
|
|
||
| * Contents: | ||
|
|
||
| * All reusable components of the existing client-go library, including at least: | ||
|
|
||
| * Transport | ||
|
|
||
| * RESTClient | ||
|
|
||
| * Workqueue | ||
|
|
||
| * Informer (not the typed informers) | ||
|
|
||
| * Dynamic and Discovery clients | ||
|
|
||
| * Utility functions (if still necessary) | ||
|
|
||
| * But omitting: | ||
|
|
||
| * API types | ||
|
|
||
| * current generated code. | ||
|
|
||
| * go-base is usable as a client on its own (dynamic client, discovery client) | ||
|
|
||
| * github.com/kubernetes-client/core-go | ||
|
|
||
| * Contents: | ||
|
|
||
| * The existing examples. | ||
|
|
||
| * The output (including API types) resulting from running client-gen on the source api types of the core API Group collection. | ||
|
|
||
| * Any hand-written *_expansion.go files. | ||
|
|
||
| * github.com/kubernetes-client/python-base | ||
|
|
||
| * Hand-tuned pieces (auth, watch support etc) for python language clients. | ||
|
|
||
| * github.com/kubernetes-client/core-python | ||
|
|
||
| * The output of kubernetes-client/gen for the python language. | ||
|
|
||
| * Note: We should provide a packaging script to make sure this is backward compatible with current `pip` package. | ||
|
|
||
| * github.com/kubernetes-client/core-{lang} and github.com/kubernetes-client/{lang}-base | ||
|
|
||
| * The output of kubernetes-client/gen for language {lang}, and hand-tuned pieces for that language. [See here](https://docs.google.com/document/d/1hsJNlowIg-u_rz3JBw9hXh6rj2LgeAdMY7OleOL1srw/edit). | ||
|
|
||
| Note that the word "core" in the above package names represents the API groups that will be included in the repository. “core” would indicate inclusion of the groups published in the client today. (One can imagine replacing it with “service-catalog” etc.) | ||
|
|
||
| ## Why this split? | ||
|
|
||
| The division of each language into two repositories is intended to allow for composition: generated clients for [multiple different API sources](https://docs.google.com/document/d/1UZyb5sQc-G2Ix4YL6dA9f4xJWtz3VKCiFPNHVHDUq9Y/edit#) can be used together without any code duplication. To clarify further: | ||
|
|
||
| * Some who run the generator don't need go-base. | ||
|
|
||
| * I want to publish an API extension client. | ||
|
|
||
| * Some who use the kubernetes-client/core-go package don't need the generator. | ||
|
|
||
| * I don’t use any extensions, just vanilla k8s. | ||
|
|
||
| * Some who use go-base need neither the generator nor the core-go package. | ||
|
|
||
| * I want to use the dynamic client since I only care about metadata. | ||
|
|
||
| * Those who write automation only for their extension need the generator and go-base but possibly not core-go. | ||
|
|
||
| That is, there should only be one kubernetes-client/{lang}-base for any given language, but many different API providers may provide a kubernetes-client/{collection}-{lang} for the language (e.g., core Kubernetes, the API registration API, the cluster federation effort, service catalog, heapster/metrics API, OpenShift). | ||
|
|
||
| It is preferred to use the generation as part of the user’s build process so we can have fewer kubernetes-client/{collection}-{lang} for custom APIs out in the wild. Users should only expect super popular extensions to host their own client, as there’s otherwise a combinatorial explosion of API Group collections x languages. | ||
|
|
||
| Users may want to run the client generator themselves with the particular collection of APIs enabled in their particular cluster, or at a different version of the generator. | ||
|
|
||
| ## Versioning | ||
|
|
||
| `kubernetes-client/gen` must be versioned, so that users can get deterministic, repeatable client interfaces. (Use case: adding a reference to a new API resource to existing slightly out-of-date code.) We will use semver. | ||
|
|
||
| The versions of kubernetes-client/gen must correspond to the versions of all kubernetes-client/{lang}-base repositories. | ||
|
|
||
| kubernetes-client/{collection}-{lang} repos have their own version. Each release of such repos must clearly state both: | ||
|
|
||
| * the version of the OpenAPI source (or go types for the go client) | ||
|
|
||
| * the version of kubernetes-client/gen used to generate the client | ||
|
|
||
| This will allow users to regenerate any given kubernetes-client/{collection}-{lang} repo, adding custom API resources etc. | ||
|
|
||
| ## Clients for API Extensions | ||
|
|
||
| Providers of API extensions (e.g., service catalog or cluster federation) may choose to publish a generated client for their API types, to make users’ lives easier (it’s not strictly necessary, since end users could run the generator themselves). Publishing a client like this should be as easy as importing the generator execution script from e.g. the main kubernetes-client/core-go repo, and providing a different input source. | ||
|
|
||
| ## Language-specific considerations | ||
|
|
||
| ### Go | ||
|
|
||
| * The typed informer generator should be included with the client generator. | ||
|
|
||
| * We need a "clientset" adaptor concept to make it easy to compose clients from disparate client repos. | ||
|
|
||
| * Prior strategy doc [is here](https://docs.google.com/document/d/1h_IBGYPMa8FS0oih4NbVkAMAzM7YTHr76VBcKy1qFbg/edit#heading=h.ve95t2prztno). | ||
|
|
||
| ### {My Favorite Language} | ||
|
|
||
| Read about the process for producing an official client library [here](https://docs.google.com/document/d/1hsJNlowIg-u_rz3JBw9hXh6rj2LgeAdMY7OleOL1srw/edit). | ||
|
|
||
| ## Remaining Design Work | ||
|
|
||
| * Client Release Process | ||
|
|
||
| * Needs definition, i.e., who does what to which repo when. | ||
|
|
||
| * Client release note collection mechanism | ||
|
|
||
| * For go, we’ve talked about amending the Kubernetes merge bot to require a client-relnote: `Blah` in PRs that touch a few pre-identified directories. | ||
|
|
||
| * Once we are working on the generator in the generator repo, it becomes easier to assemble release notes: we can grab all changes to the interface by looking at the kubernetes-client/gen and kubernetes-client/{lang}-base repos, and we can switch the release note rule to start tracking client-visible API changes in the main repository. | ||
|
|
||
| * Client library documentation | ||
|
|
||
| * Ideally, generated | ||
|
|
||
| * Ideally, both: | ||
|
|
||
| * In the native form for the language, and | ||
|
|
||
| * In a way that can easily be aggregated with the official Kubernetes API docs. | ||
|
|
||
| ## Timeline Guesstimate | ||
|
|
||
| Rough order of changes that need to be made. | ||
|
|
||
| 1. Begin working towards collecting client release notes. | ||
|
|
||
| 2. Split client-go into kubernetes-client/core-go and kubernetes-client/go-base | ||
|
|
||
| 3. Move go client generator into kubernetes-client/gen | ||
|
|
||
| 1. kubernetes-client/gen becomes the canonical location for this. It is vendored into the main repository (downloaded at a specific version & invoked directly would be even better). | ||
|
|
||
| 2. The client generator is modified to make a copy of the go types specifically for the client. (Either from the source go types, or generated from an OpenAPI spec.) | ||
|
|
||
| 4. Split client-python into kubernetes-client/core-python and kubernetes-client/python-base | ||
|
|
||
| 5. Move OpenAPI generator into kubernetes-client/gen | ||
|
|
||
| 6. Declare 1.0.0 on kubernetes-client/gen, and all kubernetes-client/{lang}-base repositories. (This doesn’t mean they’re stable, but we need a functioning versioning system since the deliverable here is the entire process, not any one particular client.) | ||
|
|
||
| 7. Instead of publishing kubernetes-client/core-go from its location in the staging directory: | ||
|
|
||
| 3. Add a script to it that downloads kubernetes-client/gen and the main repo and generates the client. | ||
|
|
||
| 4. Switch the import direction, so that we really just vendor kubernetes-client/core-go in the main repo. (Alternative: main repo can just run the generator itself to avoid having to make multiple PRs) | ||
|
|
||
| 8. At this point we should have finished the bootstrapping process and we’ll be ready to automate and execute on whatever release process we’ve defined. | ||
|
|
100 changes: 100 additions & 0 deletions
100
contributors/design-proposals/csi-new-client-library-procedure.md
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 @@ | ||
| # Kubernetes: New Client Library Procedure | ||
|
|
||
| **Status:** Approved by SIG API Machinery on March 29th, 2017 | ||
|
|
||
| **Authors:** @mbohlool, @lavalamp | ||
|
|
||
| **Last Updated:** 2017-03-06 | ||
|
|
||
| # Background | ||
|
|
||
| Kubernetes currently officially supports both Go and [Python client](https://github.com/kubernetes-incubator/client-python) libraries. The go client is developed and extracted from main kubernetes repositories in a complex process. On the other hand, the python client is based on OpenAPI, and is mostly generated code (via [swagger-codegen](https://github.com/swagger-api/swagger-codegen)). By generating the API Operations and Data Models, updating the client and tracking changes from main repositories becomes much more sustainable. | ||
|
|
||
| The python client development process can be repeated for other languages. Supporting a basic set of languages would help the community to build more tools and applications based on kubernetes. We may consider adjusting the go client library generation to match, but that is not the goal of this doc. | ||
|
|
||
| More background information can be found [here](https://github.com/kubernetes/kubernetes/issues/22405). | ||
|
|
||
| # Languages | ||
|
|
||
| The proposal is to support *Java*, *PHP*, *Ruby*, *C#*, and *Javascript* in addition to the already supported libraries, Go and Python. There are good clients for each of these languages, but having a basic supported client would even help those client libraries to focus on their interface and delegate transport and config layer to this basic client. For community members willing to do some work producing a client for their favorite language, this doc establishes a procedure for going about this. | ||
|
|
||
| # Development process | ||
|
|
||
| Development would be based on a generated client using OpenAPI and [swagger-codegen](https://github.com/swagger-api/swagger-codegen). Some basic functionality such as loading config, watch, etc. would be added (i.e., hand-written) on top of this generated client. The idea is to develop transportation and configuration layer, and modify as few generated files (such as API and models) as possible. The clients would be in alpha, beta or stable stages, and may have either bronze, silver, or gold support according to these requirements: | ||
|
|
||
| ### Client Capabilities | ||
|
|
||
| * Bronze Requirements [](https://github.com/kubernetes-client) | ||
|
|
||
| * Support loading config from kube config file | ||
|
|
||
| * Basic Auth (username/password) (Add documentation to discourage this and only use for testing.) | ||
|
|
||
| * X509 Client certificate (inline and referenced by file) | ||
|
|
||
| * Bearer tokens (inline and referenced by file) | ||
|
|
||
| * encryption/TLS (inline, referenced by file, insecure) | ||
|
|
||
| * Basic API calls such as list pods should work | ||
|
|
||
| * Works from within the cluster environment. | ||
|
|
||
| * Silver Requirements [](https://github.com/kubernetes-client) | ||
|
|
||
| * Support watch calls | ||
|
|
||
| * Gold Requirements [](https://github.com/kubernetes-client) | ||
|
|
||
| * Support exec, attach, port-forward calls (these are not normally supported out of the box from [swagger-codegen](https://github.com/swagger-api/swagger-codegen)) | ||
|
|
||
| * Proto encoding | ||
|
|
||
| * Generated examples | ||
|
|
||
| ### Client Support Level | ||
|
|
||
| * Alpha [](https://github.com/kubernetes-client) | ||
|
|
||
| * Clients don’t even have to meet bronze requirements | ||
|
|
||
| * Beta [](https://github.com/kubernetes-client) | ||
|
|
||
| * Client at least meets bronze standards | ||
|
|
||
| * Reasonably stable releases | ||
|
|
||
| * Installation instructions | ||
|
|
||
| * 2+ individual maintainers/owners of the repository | ||
|
|
||
| * Stable [](https://github.com/kubernetes-client) | ||
|
|
||
| * Support level documented per-platform | ||
|
|
||
| * Library documentation | ||
|
|
||
| * Deprecation policy (backwards compatibility guarantees documented) | ||
|
|
||
| * How fast may the interface change? | ||
|
|
||
| * Versioning procedure well documented | ||
|
|
||
| * Release process well documented | ||
|
|
||
| * N documented users of the library | ||
|
|
||
| The API machinery SIG will somewhere (community repo?) host a page listing clients, including their stability and capability level from the above lists. | ||
|
|
||
| # Kubernetes client repo | ||
|
|
||
| New clients will start as repositories in the [kubernetes client](https://github.com/kubernetes-client/) organization. | ||
|
|
||
| We propose to make a `gen` repository to house common functionality such as preprocessing the OpenAPI spec and running the generator, etc. | ||
|
|
||
| For each client language, we’ll make a client-[lang]-base and client-[lang] repository (where lang is one of java, csharp, js, php, ruby). The base repo would have all utility and add-ons for the specified language and the main repo will have generated client and reference to base repo. | ||
|
|
||
| # Support | ||
|
|
||
| These clients will be supported by the Kubernetes [API Machinery special interest group](https://github.com/kubernetes/community/tree/master/sig-api-machinery); however, individual owner(s) will be needed for each client language for them to be considered stable; the SIG won’t be able to handle the support load otherwise. If the generated clients prove as easy to maintain as we hope, then a few individuals may be able to own multiple clients. | ||
|
|