Status: Approved by SIG API Machinery on March 29th, 2017
Authors: @mbohlool, @lavalamp
Last Updated: 2017-03-06
Kubernetes currently officially supports both Go and Python client 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). 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.
Development would be based on a generated client using OpenAPI and 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:
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.
Support exec, attach, port-forward calls (these are not normally supported out of the box from swagger-codegen)
Client at least meets bronze standards
Reasonably stable releases
2+ individual maintainers/owners of the repository
Support level documented per-platform
Deprecation policy (backwards compatibility guarantees documented)
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.
New clients will start as repositories in the 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.
These clients will be supported by the Kubernetes API Machinery special interest group; 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.