API Reference¶

The full API documentation.

Exceptions¶

There are a number of common exceptions used.

exception kube.KubeError¶: The base class for all custom exceptions used by the the kube library.

exception kube.APIError¶

This is an exception which gets raised whenever there is a problem communicating with the Kubernetes API server or if the server returns the wrong HTTP status code.

message¶: An optional custom message for the exception.

response¶: The requests.Response object of the failed API server communication.

status_code¶: The HTTP status code of the failed response from the API server. This is a shortcut to the status_code attribute of the response object itself.

exception kube.StatusError¶: All resource items, represented by concrete instances of ItemABC, have a number of attributes which represent the status of the resource item. Not all status items are always available depending on the state of the resource item. If a status attribute is not available then this exception is used.

exception kube.NamespaceError¶: This represents the use of an invalid namespace. Some resources do not support namespaces, while others require a namespace. If the namespace use was wrong this exception will be raised.

Cluster¶

The cluster class is the global entry point to a Kubernetes API server. It holds some resources for the cluster it connects to.

Mostly this provides access to the API objects via the ref:views present as attributes.

class kube.Cluster(url='http://localhost:8001/')¶

A Kubernetes cluster.

The entry point to control a Kubernetes cluster. There is only one connection mechanism, which is via a local API server proxy. This is normally achieved by running kubectl proxy.

Parameters:	url (str) – The URL of the API server.

The default of the url parameter coincides with the defaults used by kubectl proxy so will usually be the correct value.

The cluster instance can also be used as a context manager. When used like this close() will be called automatically when the context manager exits.

proxy¶: A APIServerProxy instance for this cluster. This provides low-level access to the API server if you need it.

nodes¶: A global NodeView instance providing convenient access to cluster nodes.

namespaces¶: A global NamespaceView instance providing convenient access to the namespaces present in the cluster.

replicasets¶: A global ReplicaSetView instance providing convenient access to all ReplicaSet objects present in the cluster. This view is not bound to a particular namespace.

replicationcontrollers¶: A global ReplicationControllerView instance providing convenient access to all ReplicationController objects present in the cluster. This view is not bound to a particular namespace.

daemonsets¶: A global DaemonSetView instance providing convenient access to all DaemonSet objects present in the cluster. This view is not bound to a particular namespace.

deployments¶: A global DeploymentView instance providing convenient access to all Deployment objects present in the cluster. This view is not bound to a particular namespace.

pods¶: A global PodView instance providing convenient access to all Pod objects present in the cluster. This view is not bound to a particular namespace.

services¶: A global ServiceView instance providing convenient access to all Service objects present in the cluster. This view is not bound to a particular namespace.

secrets¶: A global SecretView instance providing convenient access to all Secret objects present in the cluster. This view is not bound to a particular namespace.

close()¶: Close and clean up underlying resources.

create(data, namespace=None)¶

Create a new resource item.

Parameters:	data (dict) – The specification to create the resource from, this must include the `apiVersion`, `kind`, `metadata` and `spec` fields. It is usually simply the de-serialised YAML but allows you to insert template processing if you require so. namespace (str) – Create the resource item in the given namespace. If the `spec` includes a namespace this namespace must match or an exception will be raised.
Returns:	The newly created item.
Return type:	A `kube.ViewABC` instance of the right type according to the kind of resource item created based on the data in the spec.
Raises:	kube.APIError – For errors from the k8s API server. kube.KubeError – If the spec is incomplete or the kind is unknown.

classmethod kindimpl(kind)¶

Return the class which implements the resource kind.

Parameters:	kind (kube.Kind) – The `kube.Kind` instance.
Returns:	A class implementing either `kube.ViewABC` or `kube.ItemABC` depending on the kind.
Raises:	ValueError – If the kind is not known.

APIServerProxy¶

This provides low-level access to the Kubernetes cluster. It can be useful to interact with API objects not yet wrapped by the library.

class kube.APIServerProxy(base_url='http://localhost:8001/')¶

Helper class to directly communicate with the API server.

Since most classes need to communicate with the Kubernetes cluster’s API server in a common way, this class helps take care of the common logic. It also keeps the requests session alive to enable connection pooling to the API server.

Parameters:	base_url (str) – The URL of the API, not including the API version.

Most methods take a variable-length path argument which is used to make up the URL queried. These parts are joined together and attached to the base URL configured on the class (e.g. http://localhost:8001/) using the urljoin() method. Thus, to query a namespace at http://localhost:8001/api/v1/namespaces/default, you would use ['api/v1', 'namespace', 'default'] as path. Likewise, ['api/v1', 'namespace', 'default', 'pods', 'foo'] as path would result in a query to http://localhost:8001/api/v1/namespaces/default/pods/foo.

It is also possible to use the full URL path instead as a single argument. This is useful when using the selfLink metadata from an API object. So using ['/api/v1/namespaces/default'] as path would also result in a URL of http://localhost:8001/api/v1/namespaces/default.

close()¶

Close underlying connections.

Once the proxy has been closed then the it can no longer be used to issue further requests.

delete(*path, json=None, **params)¶

HTTP DELETE to the relative path on the API server.

Parameters:	path (str) – Individual relative path components, they will be joined using `urljoin()`. json (collections.abc.Mapping) – The body, which will be JSON-encoded before posting. params (str) – Extra query parameters for the URL of the DELETE request.
Returns:	The decoded JSON data.
Return type:	pyrsistent.PMap
Raises:	kube.APIError – If the response status is not 200 OK.

get(*path, **params)¶

HTTP GET the path from the API server.

Parameters:	path (str) – Individual API path components, they will be joined using “/”. None of the path components should include a “/” separator themselves, other than the first component, the API path, which may. params (dict) – Extra query parameters for the URL of the GET request as a dictionary of strings.
Returns:	The decoded JSON data.
Return type:	pyrsistent.PMap
Raises:	kube.APIError – If the response status is not 200 OK.

patch(*path, patch=None)¶

HTTP PATCH as application/strategic-merge-patch+json.

This allows using the Strategic Merge Patch to patch a resource on the Kubernetes API server.

Parameters:	path (str) – Individual relative path components, they will be joined using “/”. None of the path components should include a “/” separator themselves, other than the first component, the API path, which may - unless you only provide one component, which will be joined to the base URL using `urllib.parse.urljoin()`. This case can be useful to use the links provided by the API itself directly, e.g. from a resource’s `metadata.selfLink` field. patch (dict) – The decoded JSON object with the patch data.
Returns:	The decoded JSON object of the resource after applying the patch.
Raises:	APIError – If the response status is not 200 OK.

post(*path, json=None, **params)¶

HTTP POST to the relative path on the API server.

Parameters:	path (str) – Individual relative path components, they will be joined using `urljoin()`. json (collections.abc.Mapping) – The body to post, which will be JSON-encoded before posting. params (str) – Extra query parameters for the URL of the POST request.
Returns:	The decoded JSON data.
Return type:	pyrsistent.PMap
Raises:	kube.APIError – If the response status is not 201 Created.

urljoin(*path)¶

Wrapper around urllib.parse.urljoin for the configured base URL.

Parameters:	path – Individual relative path components, they will be joined using “/”. None of the path components should include a “/” separator themselves, other than the first component, the API path, which may.

watch(*path, version=None, fields=None)¶

Watch a list resource for events.

This issues a request to the API with the watch query string parameter set to true which returns a chunked response. An iterator is returned which continuously reads from the response, yielding received lines as bytes.

Parameters:	path – The URL path to the resource to watch. See `urljoin()`. version (str) – The resource version to start watching from. fields (dict) – A dict of fields which must match their values. This is a limited form of the full fieldSelector format, it is limited because filtering is done at client side for consistency.
Returns:	An special iterator which allows non-blocking iterating using a `.next(timeout)` method. Using it as a normal iterator will result in blocking behaviour.
Return type:	`kube._watch.JSONWatcher`.
Raises:	APIError – If there is a problem with the API server.

Resources Interface¶

ViewABC¶

Views are central to how the kube API works and are how you get hold of resource items. They give you a view into the resource items part which are part of the resource. Views are implemented in concrete classes for each resource type which is wrapped by kube. The view API presented in this abstract base class which all the concrete views have to implement and provides a consistent API.

Currently views come in two flavours: global views and views bound to a namespace. Instances of global views are directly accessible from attributes on the Cluster instance. When using a global view it will contain all resource items of a certain kind which exist in the cluster, regardless of the namespace they reside in. When using a view bound to a namespace only the resource items residing in the given namespace are accessible.

class kube.ViewABC(cluster, namespace=None)¶

Represents a view to a collection of resources.

All top-level resources in Kubernetes have a collection, resources of a *List kind, with some common functionality. This ABC defines views to provide access to resources in collections in a uniform way. Note that a view is not the same as the collection resource, e.g. collections resources have some metadata associated with them and exist at a particular point in time, they have a metadata.resourceVersion, which views do not have.

It is always possible to create an instance of this without needing to do any requests to the real Kubernetes cluster.

Parameters:	cluster (kube.Cluster) – The cluster this resource list is part of. namespace (str) – The optional namespace this resource list is part of. If the resource list is not part of a namespace this will be `None` which means it will be a view to all resources of a certain type, regardless of their namespace.
Raises:	kube.NamespaceError – When a namespace is provided but the resource does not support one.

api_paths¶

The list of possible Kubernetes API version base paths for resource.

This is a list of the API base path string for each of the existing API versions that could be used in the construction of the API endpoint for a resource, if available. For example, ['api/v1', '/apis/extensions/v1beta1']. They are listed in reverse chronological order, the most recent API version appearing first. kube uses the list to establish and use the most recent API version available.

cluster¶: The kube.Cluster instance this resource is bound to.

fetch(name, namespace=None)¶

Retrieve the current version of a single resource item by name.

If the view itself is associated with a namespace, self.namespace is not None, then this will default to fetching the resource item from this namespace. If the view is not associated with a namespace, self.namespace is None, and the resource requires a namespace then a kube.NamespaceError is raised. Note that the default namespace is not automatically used in this case.

Parameters:	name (str) – The name of the resource. namespace (str) – The namespace to fetch the resource from.
Returns:	A single instance representing the resource.
Raises:	LookupError – If the resource does not exist. kube.NamespaceError – For an invalid namespace, either because the namespace is required for this resource but not provided or the resource does not support namespaces and one was provided. kube.APIError – For errors from the k8s API server.

filter(*, labels=None, fields=None)¶

Return an iterable of a subset of the resources.

Parameters:	labels (dict or str) – A label selector expression. This can either be a dictionary with labels which must match exactly, or a string label expression as understood by k8s itself. fields (dict or str) – A field selector expression. This can either be a dictionary with fields which must match exactly, or a string field selector as understood by k8s itself.
Returns:	An iterator of `kube.ItemABC` instances of the correct type for the resrouce which match the given selector.
Raises:	ValueError – If an empty selector is used. An empty selector is almost certainly not what you want. Kubernetes treats an empty selector as all items and treats a null selector as no items. kube.APIError – For errors from the k8s API server.

kind¶

The kind of the underlying Kubernetes resource.

This is a kube.Kind enum.

This should be implemented as a static attribute since it needs to be available on the class as well as on the instance.

namespace¶

The optional namespace this view is bound to.

If the view is not bound to a namespace this will be None, including for resources which do not support namespaces.

resource¶

The name of the Kubernetes API resource.

The resource name is used in the construction of the API endpoint, e.g. for the API endpoint /namespaces/default/pods/ the resource name is pods. The resource name is identical for both the resource as well as the resource item, e.g. both objects with PodList and Pod as kind will have a resource name of pods.

This should be implemented as a static attribute since it needs to be available on the class as well as on the instance.

watch()¶

Watch for changes to any of the resources in the view.

Whenever one of the resources in the view changes a new kube.WatchEvent instance is yielded. You can currently not control from “when” resources are being watched, other then from “now”. So be aware of any race conditions with watching.

Returns:	An iterator of `kube.WatchEvent` instances.
Raises:	kube.NamespaceError – Whe the namespace no longer exists. kube.APIError – For errors from the k8s API server.

ResourceWatcher¶

A ResourceWatcher is used to watch resources and resource items. It should never be created directly but is instead returned by the ViewABC.watch() and ItemABC.watch() methods.

This class is also a context manager as it holds open active socket connections to the API server. On exiting the context manager the connections are closed. Typical usage would be:

cluster = kube.Cluster()
with cluster.pods.watch() as watcher:
   for event in watcher:
       print(event)

class kube.ResourceWatcher(cluster, jsonwatcher, itemcls)¶

Watcher for a resource.

This is an iterator yielding watch events in either a blocking or non-blocking way, for non-blocking use .next(timeout=0). It uses a JSONWatcher instance for retrieving the actual events, which must be configured correctly to return events for the same resource as this watcher is for.

Parameters:	cluster (kube.Cluster) – The cluster instance. jsonwatcher (JSONWatcher) – A correctly configured watcher instance which yields the decoded JSON objects. itemcls (A callable, usually a class.) – A constructor for the resource item being watched.

close()¶

Close the iterator and release it’s resources.

This releases the underlying socket.

next(*, timeout=None)¶

Return the next watch event.

Parameters:	timeout (int or float) – The maximum time to wait for a new event. Not specifying this will block forever until a new event arrives, otherwise a `TimeoutError` is raised if no new event was received in time.
Raises:	TimeoutError – When no new event is available after the specified timeout.

WatchEvent¶

The namedtuple yielded by a ResourceWatcher.

class kube.WatchEvent¶

Events returned by the ResourceWatcher iterator, this is a namedtuple with the following fields:

evtype [field 0]: The first field of the tuple, representing the type of event, a kube.WatchEventType enum instance.

item [field 1]: The second field of the tuple, representing the API object itself. This will be a concrete instance of ItemABC.

MODIFIED¶: Shortcut to kube.WatchEventType.MODIFIED.

ADDED¶: Shortcut to kube.WatchEventType.ADDED.

DELETED¶: Shortcut to kube.WatchEventType.DELETED.

ERROR¶: Shortcut to kube.WatchEventType.ERROR.

WatchEventType¶

The types of watch events as an enum.

class kube.WatchEventType¶

MODIFIED¶

ADDED¶

DELETED¶

ERROR¶

Resource Items Interface¶

ItemABC¶

Individual resource items are always represented by a class implementing the ItemABC interface. Like with views each resource item is implemented in it’s own concrete class but the abstract base class gives a consistent API.

Instances of an item represent the state of that resource item as a snaphot in time. All API objects in a Kubernetes cluster have a resource version associated with them and this particular version is what is represented by an item instance and thus an item instance is immutable. Items can and do implement methods which change the state of the resource item, in these cases a new instance of the item is returned by the method, representing the resource item in the state after the mutations have happened.

class kube.ItemABC(cluster, raw)¶

Representation for a kubernetes resource.

This is the interface all resource items must implement.

Parameters:	cluster (kube.Cluster) – The cluster this resource is bound to. raw (dict) – The decoded JSON representing the resource.

api_paths¶

The list of possible Kubernetes API version base paths for resource.

This is a list of the API base path string for each of the existing API versions that could be used in the construction of the API endpoint for a resource, if available. For example, ['api/v1', '/apis/extensions/v1beta1']. They are listed in reverse chronological order, the most recent API version appearing first. kube uses the list to establish and use the most recent API version available.

cluster¶: The kube.Cluster instance this resource is bound to.

delete()¶

Delete the resource item.

Return type:	None
Raises:	APIError – For errors from the k8s API server.

fetch()¶

Fetch the current version of the resource item.

This will return a new instance of the current resource item at it’s latest version. This is useful to see any changes made to the object since it was last retrieved.

Returns:	An instance of the relevant `ItemABC` subclass.
Raises:	kube.APIError – For errors from the k8s API server.

kind¶

The Kubernetes resource kind of the resource.

This is a kube.Kind enum.

This should be implemented as a static attribute since it needs to be available on the class as well as on the instance.

meta¶: The resource’s metadata as a kube.ObjectMeta instance.

raw¶

The raw decoded JSON representing the resource.

This behaves like a dict but is actually an immutable view of the dict.

resource¶

The name of the Kubernetes API resource.

The resource name is used in the construction of the API endpoint, e.g. for the API endpoint /namespaces/default/pods/ the resource name is pods. The resource name is identical for both the resource as well as the resource item, e.g. both objects with PodList and Pod as kind will have a resource name of pods.

This should be implemented as a static attribute since it needs to be available on the class as well as on the instance.

spec()¶

The spec of this node’s resource.

This returns a copy of the raw, decoded JSON data representing the spec of this resource which can be used to re-create the resource.

watch()¶

Watch the resource item for changes.

Only changes after the current version will be part of the iterator. However it can not be guaranteed that every change is returned, if the current version is rather old some changes might no longer be available.

Returns:	An iterator of `kube.WatchEvents` instances for the resource item.
Raises:	kube.APIError – For errors from the k8s API server.

Kind¶

All API Objects in Kubernetes have a kind. The kind is represented as an enum instance where both the associated name and value matches the string used to describe the kind on the Kubernetes JSON API.

class kube.Kind¶

DaemonSet¶

DaemonSetList¶

Deployment¶

DeploymentList¶

Node¶

NodeList¶

Namespace¶

NamespaceList¶

Pod¶

PodList¶

ReplicaSet¶

ReplicaSetList¶

ReplicationController¶

ReplicationControllerList¶

Service¶

ServiceList¶

Secret¶

SecretList¶

ObjectMeta¶

Each instance of a concrete ItemABC class represents the metadata of the resource item in a kube.ItemABC.meta attribute. This attribute is always an instance of this ObjectMeta class to provide convenient access to the metadata. You would not normally create an instance manually.

class kube.ObjectMeta(resource)¶

Common metadata for API objects.

Parameters:	resource (kube._base.ItemABC) – The object representing the Kubernetes resource which this metadata describes.

created¶: The created timestamp as a datetime.datetime instance.

labels¶: The labels as a ResourceLabels instance.

link¶

A link to the resource itself.

This is currently an absolute URL without the hostname, but you don’t have to care about that. The kube.APIServerProxy will be just fine with it as it’s path argument.

name¶: The name of the object.

namespace¶: Namespace the object resides in, or None.

uid¶

The Universal ID of the item.

This is unique for this resource kind.

version¶: The opaque resource version.

ResourceLabels¶

This class is a collections.abc.Mapping of the labels applied to a resource item. It is not created manually but instead accessed via the ObjectMeta class.

Manipulation of the labels is supported using explicit method calls.

class kube.ResourceLabels(resource)¶

The labels applied to an API resource item.

This allows introspecting the labels as a normal mapping and provides a few methods to directly manipulate the labels on the resource item.

delete(key)¶

Delete a label.

This will remove the label for a given key from the resource.

Returns:	A new instance of the resource.
Raises:	kube.APIError – If there is a problem with the API server.

set(key, value)¶

Set a (new) label.

This will set or update the label’s value on the resource.

Returns:	A new instance of the resource.
Raises:	kube.APIError – If there is a problem with the API server.

Nodes¶

NodeView¶

class kube.NodeView(cluster, namespace=None)¶

View of all the Node resource items in the cluster.

Parameters:	cluster (kube.Cluster) – The cluster instance. namespace (NoneType) – Limit the view to resource items in this namespace. This is here for the `kube.ViewABC` compatibility but can not be used for the NodeList resource. A `kube.NamespaceError` is raised when this is not `None`.
Raises:	kube.NamespaceError – If instantiated using a namespace.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource. cluster – The `kube.Cluster` instance.

fetch(name, namespace=None)¶

Retrieve an individual node by name.

This returns the current verison of the resource item.

Parameters:	name (str) – The name of the node to retrieve. namespace (str) – Must be None or a `kube.NamespaceError` is raised. Here only for compatibility with the ABC.
Returns:	A single `kube.NodeItem` instance.
Raises:	LookupError – If the node does not exist. kube.APIError – For errors from the k8s API server. kube.NamespaceError – If a namespace is used.

NodeItem¶

class kube.NodeItem(cluster, raw)¶

A node in the Kubernetes cluster.

See http://kubernetes.io/docs/admin/node/ for details.

Parameters:	cluster (kube.Cluster) – The cluster this node belongs to. raw (pyrsistent.PMap) – The raw data of the resource item.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

addresses¶

An iterator of the addresses for this node.

Each address is a namedtuple with (type, addr) as fields. Known types are in the kube.AddressType enumeration.

An empty list is returned if there are not yet any addresses associated with the node.

According to the K8s API spec (and K8s code) the node address array may contain addresses of the types defined by kube.AddressType. The Hostname address type, while unlikely, may present itself for certain cloud providers and will contain a hostname string, not an IP address.

capacity¶

The capacity of the node.

CPU is expressed in cores and can use fractions of cores, while memory is expressed in bytes.

conditions¶: List of conditions.

Namespaces¶

NamespaceView¶

class kube.NamespaceView(cluster, namespace=None)¶

View of all the Namespace resource items in the cluster.

Parameters:	cluster (kube.Cluster) – The cluster instance. namespace (NoneType) – Limit the view to resource items in this namespace. This is here for the `kube.ViewABC` compatibility, namespaces can not be used for the NamespaceList resource. A `kube.NamespaceError` is raised when this is not `None`.
Raises:	kube.NamespaceError – If instantiated using a namespace.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

fetch(name, namespace=None)¶

Retrieve an individual Namespace resource item by name.

This returns the current version of the resource item.

Parameters:	name (str) – The name of the namespace resource item to retrieve. namespace (str) – Must be None or a `kube.NamespaceError` is raised. Here only for compatibility with the ABC.
Returns:	A `kube.NamespaceItem` instance.
Raises:	LookupError – If the namespace does not exist. kube.APIError – For errors from the k8s API server. kube.NamespaceError – If a namespace is used.

NamespaceItem¶

class kube.NamespaceItem(cluster, raw)¶

A namespace in the Kubernetes cluster.

See http://kubernetes.io/docs/admin/namespaces/ for details.

Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource. NamespacePhase – Convenience alias of `NamespacePhase`.

class NamespacePhase¶

Enumeration of all possible namespace phases.

This is aliased to NamespaceResource.NamespacePhase for convenience.

NamespaceItem.delete()¶

Delete the namespace resource item.

For Namespace deletion K8s may have some work to do and could return a 409 (Conflict) instead of a 404 (Not Found) when a subsequent delete call occurs while status is trying to catch up with spec. We hide this idiosyncrasy from the kube user.

Return type:	None
Raises:	APIError – For errors from the k8s API server.

NamespaceItem.phase¶: Phase of the namespace as a kube.NamespacePhase.

ReplicaSets¶

ReplicaSetView¶

class kube.ReplicaSetView(cluster, namespace=None)¶

View of the ReplicaSet resource items in the cluster.

Parameters:	cluster (kube.Cluster) – The cluster instance. namespace (str) – Limit the view to resource items in this namespace.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

ReplicaSetItem¶

class kube.ReplicaSetItem(cluster, raw)¶

A ReplicaSet in the Kubernetes cluster.

A ReplicaSet, formerly known as a ReplicationController, is responsible for keeping a desired number of pods running.

Parameters:	cluster (kube.Cluster) – The cluster this ReplicaSet exists in. raw (pyrsistent.PMap) – The raw data of the resource item.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

available_replicas¶: The number of available replicas (ready for at least minReadySeconds) for the ReplicaSet.

fully_labeled_replicas¶

Number of pods which have an exact matching set of labels.

This counts the pods which have the exact same set of labels as the labelselector of this replicaset.

observed_generation¶: The (integer) generation of the ReplicaSet.

observed_replicas¶: The current number of replicas observed.

ready_replicas¶: The number of ready replicas for the ReplicaSet.

ReplicationControllers¶

ReplicationControllerView¶

class kube.ReplicationControllerView(cluster, namespace=None)¶

View of the Replication Controller resource items in the cluster.

Parameters:	cluster (kube.Cluster) – The cluster instance. namespace (str) – Limit the view to resource items in this namespace.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

ReplicationControllerItem¶

class kube.ReplicationControllerItem(cluster, raw)¶

A Replication Controller in the Kubernetes cluster.

A ReplicationController, is responsible for keeping a desired number of pods running.

Parameters:	cluster (kube.Cluster) – The cluster this Replication Controller exists in. raw (pyrsistent.PMap) – The raw data of the resource item.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

available_replicas¶: The number of available replicas (ready for at least minReadySeconds) for the ReplicaSet.

fully_labeled_replicas¶

Number of pods which have an exact matching set of labels.

This counts the pods which have the exact same set of labels as the labelselector of this replication controller.

observed_generation¶: The (integer) generation of the ReplicaSet.

observed_replicas¶: The current number of replicas observed.

ready_replicas¶: The number of ready replicas for the ReplicaSet.

Daemonsets¶

DaemonsetView¶

class kube.DaemonSetView(cluster, namespace=None)¶

View of the DaemonSet resource items in the cluster.

Parameters:	cluster (kube.Cluster) – The cluster instance. namespace (str) – Limit the view to resource items in this namespace.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

DaemonsetItem¶

class kube.DaemonSetItem(cluster, raw)¶

A DaemonSet in the Kubernetes cluster.

A Daemon Set ensures that all (or some) nodes run a copy of a pod.

Parameters:	cluster (kube.Cluster) – The cluster this DaemonSet exists in. raw (pyrsistent.PMap) – The raw data of the resource item.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

current_number_scheduled¶

The number of nodes that are running at least 1 daemon pod.

The count is of those nodes that are running at least one daemon pod and that are supposed to run the daemon pod.

desired_number_scheduled¶

The total number of nodes that should be running the daemon pod.

This includes nodes correctly running the daemon pod.

number_misscheduled¶: Number of nodes running the daemon pod, but not supposed to be.

number_ready¶

The number of nodes that have one or more of the daemon pod ready.

Nodes counted are those that should be running the daemon pod and have one or more of the daemon pod running and ready.

Deployments¶

DeploymentView¶

class kube.DeploymentView(cluster, namespace=None)¶

View of the Deployment resource items in the cluster.

Parameters:	cluster (kube.Cluster) – The cluster instance. namespace (str) – Limit the view to resource items in this namespace.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

DeploymentItem¶

class kube.DeploymentItem(cluster, raw)¶

A Deployment in the Kubernetes cluster.

A Deployment provides declarative updates for Pods and Replica Sets.

Parameters:	cluster (kube.Cluster) – The cluster this Deployment exists in. raw (pyrsistent.PMap) – The raw data of the resource item.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

available_replicas¶: Number of available pods ready for at least minReadySeconds.

observed_generation¶: The (integer) generation of the Deployment.

observed_replicas¶: Total number of non-terminated pods targeted by this deployment.

unavailable_replicas¶: Total number of unavailable pods targeted by this deployment.

updated_replicas¶: Nr. of non-terminated pods targeted with desired template spec.

Pods¶

PodView¶

class kube.PodView(cluster, namespace=None)¶

View of the Pod resource items in the cluster.

Parameters:	cluster (kube.Cluster) – The cluster instance. namespace (str) – Limit the view to resource items in this namespace.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

PodItem¶

class kube.PodItem(cluster, raw)¶

A pod in the Kubernetes cluster.

Each pod contains a number of containers and volumes which are executed on a node within the cluster. A pod may exist in a namespace. Pods are typically managed by a controller such as a replication controller or job.

Parameters:	cluster (kube.Cluster) – The cluster this pod exists in. raw (pyrsistent.PMap) – The raw data of the resource item.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource. PodPhase – Convenience alias of `PodPhase`.

class PodPhase¶

Enumeration of all possible pod phases.

This is aliased to Pod.PodPhase for convenience.

PodItem.containers¶: Iterate over all Container instances in the pod.

PodItem.host_ip¶

IP address of the pod’s host within the cluster.

This may be as a ipaddress.IPv4Address or a ipaddress.IPv6Address.

Raises:	kube.StatusError – If this status item is not present.

PodItem.ip¶

IP address of the pod within the cluster.

This may be as a ipaddress.IPv4Address or a ipaddress.IPV6Address.

Raises:	kube.StatusError – If this status item is not present.

PodItem.message¶

Human readable message explaining the pod’s state.

Raises:	kube.StatusError – If this status item is not present.

PodItem.phase¶

Phase of the pod as a kube.PodPhase.

Raises:	kube.StatusError – If this status item is not present.

PodItem.reason¶

PascalCase string explaining the pod’s state.

Raises:	kube.StatusError – If this status item is not present.

PodItem.start_time¶

Start the pod was started as a datetime.datetime.

Raises:	kube.StatusError – If this status item is not present.

Container¶

class kube.Container(pod, raw)¶

A container inside a pod.

Containers live inside a pod and may be restarted inside this pod as controlled by the restart policy set on the pod.

Parameters:	pod (PodItem) – The pod the container is part off. raw (pyrsistent.PMap) – The JSON-decoded object describing the status of the container.
Variables:	pod – The `PodItem` instance the container is bound to. raw – The raw JSON-decoded object representing the container.

id¶

The ID of the running container.

For Docker this is in the docker://<hex_id> format.

image¶

The image the container is running.

For Docker this is normally the repository name with tag appended.

image_id¶

The ImageID of the container’s image.

For Docker this is in the docker://<hex_id> format.

last_state¶

Previous state of the container, if known.

This is represented by a ContainerState instance.

Raises:	kube.StatusError – If this status item is not present.

name¶: The name of the container as a string.

ready¶

Boolean indicating if the container passed it’s readyness probe.

Raises:	kube.StatusError – If this status item is not present.

restart_count¶

The number of times the container was restarted as an integer.

Note that this is currently not always accurate, it counts the number of dead containers which have not yet been removed. This means the gargage collection of containers caps this number at 5.

state¶

Current state of the container.

This is represented by a ContainerState instance.

Raises:	kube.StatusError – If this status item is not present.

ContainerState¶

class kube.ContainerState(raw)¶

The state of a container within a pod.

A container can be in one of three states: running, waiting or terminated. This class provides a uniform interface to all states and their associated details. Not all fields are always valid for each state so they can all raise an kube.StatusError when they are not available or not applicable.

The overall state of the container is available both as a string in the state attribute as well as booleans in the waiting, running and terminated attributes.

Parameters:	raw (pyrsistent.PMap) – The raw JSON-decoded `v1.ContainerState` API object as exposed by `v1.ContainerStatus` objects.
Variables:	raw – The raw JSON-decoded object representing the container state.

container_id¶

The container ID of the terminated container. Available for the terminated state.

Raises:	kube.StatusError – When this is not provided.

exit_code¶

Exit code of the container (int).

Available for the terminated state.

Raises:	kube.StatusError – When this is not provided.

finished_at¶

The time the container was terminated (datetime.datetime).

Available for the terminated state.

Raises:	kube.StatusError – When this is not provided.

message¶

Message regarding the container’s state (str).

Available for waiting and terminated states.

Raises:	kube.StatusError – When this is not provided.

reason¶

Brief reason explaining the container’s state (str).

This is normally a CamelCased message ID.

Available for waiting and terminated states.

Raises:	kube.StatusError – When this is not provided.

running¶: Boolean indicating if the container is running.

signal¶

Last signal sent to the container, if known (int).

Not all terminated containers can be expected to have this.

Warning

The signal is identified numerically, however these signal numbers are not portable therefore it’s ill-advised to attempt to compare this value with the constants provided by the built-in singal module.

Available for the terminated state.

Raises:	kube.StatusError – When this is not provided.

started_at¶

The time the container was started or restarted (datetime.datetime).

Available for the running state.

Raises:	kube.StatusError – When this is not provided.

terminated¶: Boolean indicating if the container has been terminated.

waiting¶: Boolean indicating if the container is waiting.

Services¶

ServiceView¶

class kube.ServiceView(cluster, namespace=None)¶

View of the Service resource items in the cluster.

Parameters:	cluster (kube.Cluster) – The cluster instance. namespace (str) – Limit the view to resource items in this namespace.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

ServiceItem¶

class kube.ServiceItem(cluster, raw)¶

A Service in the Kubernetes cluster.

Parameters:	cluster (kube.Cluster) – The cluster this Service exists in. raw (pyrsistent.PMap) – The raw data of the resource item.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

loadbalancer_ingress¶

The load balancer ingress endpoints.

This is a set of ingress endpoints in use by the load balancer. Depending on the infrastructure the cluster runs on the endpoint can be either an ipaddress.IPv4Address, ipaddress.IPv6Address or a hostname as a string.

Secrets¶

SecretView¶

class kube.SecretView(cluster, namespace=None)¶

View of the Secret resource items in the cluster.

Parameters:	cluster (kube.Cluster) – The cluster instance. namespace (str) – Limit the view to resource items in this namespace.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource.

SecretItem¶

class kube.SecretItem(cluster, raw)¶

A Secret in the Kubernetes cluster.

Parameters:	cluster (kube.Cluster) – The cluster this Service exists in. raw (pyrsistent.PMap) – The raw data of the resource item.
Variables:	kind – The kind of the underlying Kubernetes resource item. resource – The name of the Kubernetes API resource. SecretType – Shortcut to `kube.SecretType`.

class SecretType¶: Enumeration of secret types.

SecretItem.data¶

A mapping of the secret data.

A copy of the secret data as a dict. The keys are the names of the secrets as a (unicode) string, while the values are the secrets as bytestrings.

Secret values are stored in a base64 encoding on the k8s master, but this is an implementation detail that this property takes care off for you.

SecretItem.spec()¶

An empty dictionary.

This is supposed to be the secret resource item’s spec. But secrets do not have a spec, so to still follow the kube.ItemABC we return an empty dict.

SecretItem.type¶

The type of secret.

There currently is only the “Opaque” type.