Kubernetes: APIs

Documentation: Kubernetes API Concepts

General notes

• The Kubernetes API is REST-based.
• The API can change between versions.
• Everything in Kubernetes is API-driven.
• kubectl uses the API.
• The API can also be used externally via requests or passing JSON.
• Users or groups can be impersonated using the API, for debugging purposes.
• Kubernetes uses JSON serialization by default.

• YAML can be used but it is converted to JSON.

• Every Kubernetes object has a resourceVersion field representing the version of that resource as stored in the underlying database.

• Clients need to pass back a resourceVersion when objects are updated.

• If there is a mismatch between versions, the API server rejects the update, returning a 409 CONFLICT.

• Passive verbs, such as GET, do not cause resourceVersion changes.

• kubectl has a verbose (--v=INT) that shows the API calls that it is making. INT can currently be between 0 and 10.

• Kubernetes uses the Swagger specification.

Examples of useful actions that can be performed via the API

• Accessing logs.
• Exec into a container.
• Watch changes to a container.

Example of accessing logs:

curl --cert /tmp/client.pem --key /tmp/client-key.pem \
--cacert /tmp/ca.pem -v -XGET \ 
 https://IP_ADDRESS:6443/api/v1/namespaces/default/pods/firstpod/log

Other endpoints:

GET /api/v1/namespaces/{namespace}/pods/{name}/exec
GET /api/v1/namespaces/{namespace}/pods/{name}/log
GET /api/v1/watch/namespaces/{namespace}/pods/{name}

v1 API Group

• When an API becomes stable it joins the v1 groups.
• v1 is not a single API group any more; there are currently eight groups.
• Examples of v1 groups:

  v1
  storage.k8s.io/v1
  rbac.authorization.k8s.io/v1
  

Discovering API Groups

The top-level API Group list can be listed via:

curl https://localhost:6443/apis --header "Authorization: Bearer $token" -k

The API Groups listed can then be curled.