From ecf490b75612d6ae4d19ef2eb19b9a666c88962a Mon Sep 17 00:00:00 2001 From: Ahmet Alp Balkan Date: Sat, 8 Jul 2017 19:25:05 -0700 Subject: [PATCH] Document API client libraries Add concept page about the Kubernetes API client libraries explaining what they do and list officially-supported & community-maintained client libraries. The list is obtained from https://github.com/kubernetes/community/blob/master/contributors/devel/client-libraries.md and I am planning to add a notice there urging people to update the /docs/reference/client-libraries.md when they add something there. Alternatively we could remove that page altogether. Signed-off-by: Ahmet Alp Balkan --- _data/reference.yml | 1 + docs/reference/api-overview.md | 3 ++ docs/reference/client-libraries.md | 56 ++++++++++++++++++++++++++++++ docs/reference/index.md | 9 +++++ 4 files changed, 69 insertions(+) create mode 100644 docs/reference/client-libraries.md diff --git a/_data/reference.yml b/_data/reference.yml index 81125b8b54..ce18add118 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -6,6 +6,7 @@ toc: - title: Using the API section: - docs/reference/api-overview.md + - docs/reference/client-libraries.md - title: Accessing the API section: - docs/admin/accessing-the-api.md diff --git a/docs/reference/api-overview.md b/docs/reference/api-overview.md index cc2dd58547..8cf06e4aa6 100644 --- a/docs/reference/api-overview.md +++ b/docs/reference/api-overview.md @@ -21,6 +21,9 @@ Most operations can be performed through the command-line tools, such as [kubeadm](/docs/admin/kubeadm/), which in turn use the API. However, the API can also be accessed directly using REST calls. +Consider using one of the [client libraries](/docs/reference/client-libraries/) +if you are writing an application using the Kubernetes API. + ## API versioning To make it easier to eliminate fields or restructure resource representations, Kubernetes supports diff --git a/docs/reference/client-libraries.md b/docs/reference/client-libraries.md new file mode 100644 index 0000000000..4acc272602 --- /dev/null +++ b/docs/reference/client-libraries.md @@ -0,0 +1,56 @@ +--- +title: Client Libraries +assignees: +- ahmetb +--- + +{% capture overview %} +This page contains an overview of the client libraries for using the Kubernetes +API from various programming languages. +{% endcapture %} + +{% capture body %} +To write applications using the [Kubernetes REST API](/docs/reference/api-overview/), +you do not need to implement the API calls and request/response types yourself. +You can use a client library for the programming language you are using. + +Client libraries often handle common tasks such as authentication for you. +Most client libraries can discover and use the Kubernetes Service Account to +authenticate if the API client is running inside the Kubernetes cluster, or can +understand the [kubeconfig file](/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig/) +format to read the credentials and the API Server address. + +## Officially-supported Kubernetes client libraries + +The following client libraries are officially maintained by [Kubernetes SIG API +Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery). + + +| Language | Client Library | Sample Programs | +|----------|----------------|-----------------| +| Go | [github.com/kubernetes/client-go/](https://github.com/kubernetes/client-go/) | [browse](https://github.com/kubernetes/client-go/tree/master/examples) +| Python | [github.com/kubernetes-incubator/client-python/](https://github.com/kubernetes-incubator/client-python/) | [browse](https://github.com/kubernetes-incubator/client-python/tree/master/examples) + +## Community-maintained client libraries + +The following Kubernetes API client libraries are provided and maintained by +their authors, not the Kubernetes team. + +| Language | Client Library | +|----------|----------------| +| Clojure | [github.com/yanatan16/clj-kubernetes-api](https://github.com/yanatan16/clj-kubernetes-api) | +| Go | [github.com/ericchiang/k8s](https://github.com/ericchiang/k8s) | +| Java (OSGi) | [bitbucket.org/amdatulabs/amdatu-kubernetes](https://bitbucket.org/amdatulabs/amdatu-kubernetes) | +| Java (Fabric8, OSGi) | [github.com/fabric8io/kubernetes-client](https://github.com/fabric8io/kubernetes-client) | +| Node.js | [github.com/tenxcloud/node-kubernetes-client](https://github.com/tenxcloud/node-kubernetes-client) | +| Node.js | [github.com/godaddy/kubernetes-client](https://github.com/godaddy/kubernetes-client) | +| Perl | [metacpan.org/pod/Net::Kubernetes](https://metacpan.org/pod/Net::Kubernetes) | +| PHP | [github.com/devstub/kubernetes-api-php-client](https://github.com/devstub/kubernetes-api-php-client) | +| PHP | [github.com/maclof/kubernetes-client](https://github.com/maclof/kubernetes-client) | +| Python | [github.com/eldarion-gondor/pykube](https://github.com/eldarion-gondor/pykube) | +| Ruby | [github.com/Ch00k/kuber](https://github.com/Ch00k/kuber) | +| Ruby | [github.com/abonas/kubeclient](https://github.com/abonas/kubeclient) | +| Scala | [github.com/doriordan/skuber](https://github.com/doriordan/skuber) | +{% endcapture %} + +{% include templates/concept.md %} diff --git a/docs/reference/index.md b/docs/reference/index.md index 995d831eb7..82794236f7 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -12,6 +12,15 @@ assignees: * [1.6](/docs/api-reference/v1.6/) * [1.5](/docs/api-reference/v1.5/) +## API Client Libraries + +To call the Kubernetes API from a programming language, you can use +[client libraries](/docs/reference/client-libraries/). Officially supported +client libraries: + +- [Kubernetes Go client library](https://github.com/kubernetes/client-go/) +- [Kubernetes Python client libary](https://github.com/kubernetes-incubator/client-python) + ## CLI Reference * [kubectl](/docs/user-guide/kubectl-overview) - Main CLI tool for running commands and managing Kubernetes clusters.