Quickstart¶

Before you start you need to make the Kubernetes API available via a proxy, this is the officially recommended method to connect and the only one supported by kube. To do this, simply run kubectl proxy on the localhost and kube will use that connection, for example:

$ kubectl proxy
Starting to serve on localhost:8001

When running your kube code in an actual Kubernetes cluster you can simply run the kubectl proxy in a container in the same pod that your kube code is running in. Finally, if you haven’t already done so, refer to the Installation chapter and install kube.

Cluster¶

The main entry point provided by kube is the kube.Cluster class. Creating an instance of this class is central to gaining access to the objects inside your Kubernetes cluster. The kube.Cluster class assumes the default endpoint used by kubectl proxy (i.e. http://localhost:8001/api/) so you can simply create an instance as follows:

import kube

cluster = kube.Cluster()

However if you’re running your proxy at a non-default endpoint then you should instance your kube.Cluster class using the url parameter as follows:

cluster = kube.Cluster(url='http://localhost:8080/api')

Pretty much all the ways in which you would want to interact with the Kubernetes API are supported by kube, however a cluster provides a kube.APIServerProxy instance via the kube.Cluster.proxy attribute. This provides low-level access to the Kubernetes cluster and can be useful to manage API objects, or access objects not yet wrapped by kube.

Views and Items¶

kube has two important concepts: views and items. All API objects in Kubernetes have a kind, and views provide access to Kubernetes resources whose kind ends in List e.g. PodList or NodeList. Items, on the other hand, provide access to the individual resource items themselves, e.g. a Pod or a Node.

The kube.Cluster instance has appropriately named attributes representing the views that provide access to the Kubernetes resources for that cluster. So for example, to fetch the ReplicaSet named auth-v3 in the default namespace you can simply use code like this:

>>> rs = cluster.replicasets.fetch('auth-v3', namespace='default')
>>> assert rs.meta.name == 'auth-v3'
>>> assert rs.meta.namespace = 'default'
>>> assert rs.kind is kube.Kind.ReplicaSet

A view is also an iterator of all the resource items it provides access to. So for example, retrieving the names of all the namespaces in your cluster can be done using a simple list comprehension:

>>> ns_names = [ns.meta.name for ns in cluster.namespaces]
>>> assert 'default' in ns_names

Note

Kubernetes versions all of its API objects. Whenever anything changes, the version for the resource is updated. Resource items returned by kube views are snapshots of a resource item’s state at a certain version.

On that note, consider this:

>>> cluster = kube.Cluster()
>>> print([node.meta.version for node in cluster.nodes])
['6434482', '6434483', '6434481']
>>> # A bit later
...
>>> print([node.meta.version for node in cluster.nodes])
['6434485', '6434486', '6434484']

Note

This is just to show you that the metadata attribute carries the resource version and that it is updated when the resource changes. However comparing versions is not very useful as they are opaque blobs. It is advised that you compare resource items directly.

As you have probably noticed, all resource items have a meta attribute and the version of a resource item is kept in meta.version. The meta attribute is an instance of the kube.ObjectMeta class and provides convenient access to a Kubernetes resource item’s metadata. For example, it provides access to the labels defined for a resource item:

>>> rs = cluster.replicasets.fetch('auth-v3', namespace='default')
>>> if 'mylabel' not in rs.meta.labels:
...     curr_rs = rs.meta.labels.set('mylabel', 'value')
...     assert curr_rs.meta.labels['mylabel'] == 'value'
...     print(rs.meta.version)
...     print(curr_rs.meta.version)
...     assert rs != curr_rs
...
6530399
6530416

There are a few points to note from the above:

The labels attribute, an instance of kube.ResourceLabels, behaves as a mapping. Both the keys and values are strings. Note however that the mapping is immutable.
To modify a resource item, kube will always require that you call a method.
Any method which modifies a resource item will always return an instance of the newest revision of that resource item (i.e. curr_rs).

Almost all resource items have a specification and status associated with them. The specification is a copy of the raw data representing the resource, which for example, could be used to re-create it. The specification is accessible in raw dict form using an item’s kube.ItemABC.spec() method.

The resource item’s status is exposed directly on appropriately named attributes. So for example:

>>> assert rs.spec()['replicas'] == rs.observed_replicas

That should be enough to get you going, but do read on. The remainder of this documentation describes kube concepts and terminology in more detail, provides detailed information on using kube in its entirety and gives a full API reference.