Merge pull request #1464 from garethr/client-libraries-contrib-summit

Automatic merge from submit-queue.

Notes from the client libraries discussion

@brendandburns notes from the session you lead at the contributor summit

1 files changed, 68 insertions, 0 deletions

diff --git a/community/2017-events/12-contributor-summit/kubernetes-client-libraries-open-space.md b/community/2017-events/12-contributor-summit/kubernetes-client-libraries-open-space.md
new file mode 100644
index 00000000..a48fb15d
--- /dev/null
+++ b/community/2017-events/12-contributor-summit/kubernetes-client-libraries-open-space.md
@@ -0,0 +1,68 @@
+_Notes from the open space discussion at the Kubernetes Contributor Summit 2017 lead by @brendandburns_
+
+Three high-level topics:
+
+* Client libraries and autogeneration
+* OpenAPI description status
+* Fluent libraries (ie. those with native sensibilities) - is this scalable given need for lots of hand-written code?
+
+Early shout-out for the [Common LISP client](https://github.com/brendandburns/cl-k8s) :)
+
+Currently Java, Python, .Net, Javascript clients are all silver. Reference to the [badge and capabilities descriptions](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/csi-new-client-library-procedure.md#client-capabilities)
+Python still outside the [clients org](https://github.com/kubernetes-client/) - should this move from incubator?
+
+Lots of code in client libraries to handle limitations in OpenAPI 2, some of which is fixed in 3. What is required/should we move to OpenAPI 3?
+
+The Go client is a special case, predates the swagger work and bypasses the autogeneration. This leads to it being an odd first-class citizen.
+
+Noted that currently client libraries generated against specific version of API
+> “I can’t currently write a library which supports multiple versions of the API from the same client”
+
+Discussion of packaging. Should clients be packaged as one thing (with support for multiple versions in  subpackages) or with each package representing support for a specific version?
+
+Autogeneration is desirable, given the wide number of languages. But what should be the canonical description. Noted that  
+go-restful, which is currently in use, (starts from Go) vs go-swagger (which starts from an OpenAPI description), worthwhile discussing which mode would work best now.
+
+Would it be possible to annotate the Go types to avoid some problems in the generator code?
+
+The API documentation is currently poor, mainly non-language specific API documentation.
+
+What kind of examples do we expect for each client? It would be great to create a set of canonical usecases for clients and for each of them to have (maybe autogenerated) examples for each.
+
+There are some Client Guidelines, @mbohlool would have a link?
+
+Note that the websockets protocol is under-documented. Kubernetes Java client has a description of the protocol and is the best place to look for details.
+
+SPDY still in use. Should this be deprecated?
+
+Question about what additional clients, or improvements, people would like to see:
+* A smaller Go client
+* Rust
+* C++
+
+Informers, should this be part of the API and available so as to be easier to use from other languages? This is not currently part of the client capabilities set mentioned above. We’re probably better off building a generic multiwatch controller than supporting the informers in all other client libraries.
+
+Service Catalogue and other extension points. Advice is to use the generator tools to generate your own clients. See [kubernetes-client/gen](https://github.com/kubernetes-client/gen)
+
+There is a plan to split the go client in to two - one hand rolled, one autogenerated.
+
+API supports proto as a wire format, but client generation here is hard. The protocol doesn’t know the path to which it needs to be sent. Protos are also generated from the Go structs.
+
+At least have a common language for description APIs. Proto vs Go.
+
+Worth noting that kubernetes-client is actually relatively low barrier to entry for getting started contributing to Kubernetes. We should talk about that more publicly.
+
+Discussion of issues with kubeconfig.
+
+* There is no spec for kubeconfig?
+* One proposal, move folks to kubeconfig.d (ie. one config file per cluster)
+* No clients support (apart from Go) support merging kubeconfigs.
+* Problem with changes here is the large number of kubeconfigs in existence.
+* Can we have a new config file format (v2) which exists alongside the existing one.
+
+Noting that kubeconfig contains several things, which arguably shouldn't be as closely coupled.
+
+* Identities
+* List of clusters
+* Namespace
+* Current context