Docker Cookbook

5.12 Exploring the Kubernetes API
Problem
Kubernetes exposes a REST API, which you need to learn to be able to manage your
Kubernetes cluster and run applications in it.
Solution
Kubernetes exposes a versioned API. With the release of the v1 API, users should
expect no breaking changes when targeting that version. Several versions of the API
can be served by the API server concurrently, but most users should target the v1
API.
Start a local Kubernetes cluster using Docker, as shown in 
Recipe 5.9
. This is the easi‐
est way to try it out. Once all components are running, you can reach the API served
by the API server. If you are on the machine running the API server, you can reach it
at 
http://localhost:8080
without any authentication. Using 
curl
gives you your
158 | Chapter 5: Kubernetes

---

first Kubernetes raw API experience. Try listing all the API versions available by call‐
ing the 
http://localhost:8080/api
route like so:
$ curl http://localhost:8080/api
{
"versions": [
"v1",
]
}
As you can see here, the server exposes only the v1 API. If you see something like
v1beta3
, you are running an old version of Kubernetes. If you see something like
v2beta1
, you are running a bleeding-edge version. To verify which version of Kuber‐
netes you are running, 
curl
the 
http://localhost:8080/version
. Note that the API
version and binary version don’t necessarily line up:
$ curl http://localhost:8080/version
{
"major": "1",
"minor": "0",
"gitVersion": "v1.0.1",
"gitCommit": "6a5c06e3d1eb27a6310a09270e4a5fb1afa93e74",
"gitTreeState": "clean"
}
This shows you that in this example I am running the official 1.0.1 build of Kuber‐
netes. This is quite basic and does not give a complete view of the API. Thankfully,
Kubernetes uses 
Swagger
for API documentation. This means that we have a 
/swag‐
gerapi/
endpoint that gives all the available API endpoints, like so:
$ curl http://localhost:8080/swaggerapi/
{
"swaggerVersion": "1.2",
"apis": [
{
"path": "/api/v1",
"description": "API at /api/v1 version v1"
},
{
"path": "/api",
"description": "get available API versions"
},
{
"path": "/version",
"description": "git code version from which this is built"
}
],
"apiVersion": "",
"info": {
"title": "",
"description": ""