Concepts and Terminology

Kubernetes is a large and complex system and the API (and related APIs in the ecosystem) expose it in all of its glory. Consequently the Kubernetes API can sometimes seem a bit confusing. Kube’s remit is to try and insulate the developer from most of this complexity and provide a pythonic, intuitive interface to work with, while adhering to the main Kubernetes API concepts. This chapter outlines these concepts, and in addition describes how and where kube fits in. Throughout the documentation we will endeavour to consistently use the terminology defined here.

If you are interested in getting a deeper understanding of the concepts employed by the Kubernetes API (and we strongly recommend that you do) then the Kubernetes API conventions document is a must read.

Kubernetes API concepts from 10,000 feet

Principally, the Kubernetes API defines the following terms:

  • Kind: The name of a particular object schema (e.g. Node or Pod kinds that have different attributes and properties).
  • Resource: A representation of a system entity, sent or retrieved as JSON via HTTP to the server. Resources are represented as:
  • Collections: A list of resources of the same type.
  • Elements: An individual resource.

Resources typically deal in data of a particular kind. For example, the kind Pod (a kind of resource element) is exposed as a pods resource (a resource collection with a kind of PodList) that allows end users to create, update, and delete pods. Kubernetes maintains a convention that resource collection names are all lowercase and plural, whereas kinds (that are the types of resource elements) are CamelCase and singular. Here are some resource kinds:

  • Collections: e.g. PodList, ServiceList, NodeList
  • Elements: e.g. Pod, Service, Node

Additionally, by convention the Kubernetes API makes a distinction between the specification of an object, and the status of an object at the current time.

The specification is a complete description of an object’s desired state, including configuration settings provided by the user, default values expanded by the system, and properties initialized or otherwise changed after creation by other ecosystem components (e.g., schedulers, auto-scalers), and is persisted in stable storage with the API object. If the specification is deleted, the object will be purged from the system.

The status summarises the current state of the object in the system, and is usually persisted with the object by an automated processes but may be generated on the fly.

When a new version of an object is POSTed or PUT, the specification is updated and available immediately. Over time the system will work to bring the status into line with the specification. The system will drive toward the most recent “spec” regardless of previous versions of that stanza.

In other words Kubernetes’ behavior is level-based rather than edge-based which enables robust behavior in the presence of missed intermediate state changes.

How Kube maps these concepts

Views and Items

kube maintains two important concepts that support the principle Kubernetes API concepts described above: views and items. As discussed 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. Note however that a kube View is not exactly the same as a resource collection; resource collections on the K8s API carry metadata and are versioned, this detail is not exposed in kube views.

Items, on the other hand, provide access to the individual resource items (elements) themselves, e.g. a Pod or a Node.

All kube views and items implement the abstract base classes kube.ViewABC and kube.ItemABC respectively, relating to the Collections and Elements concepts prescribed by the Kubernetes API. Consequently, View and Item instances that represent them all have a kind property. Additionally:

  • As a minimum, Views have a:
  • fetch method to get an Item.
  • filter method to get a subset of the items in a resource collection.
  • watch method to get an iterator that will provide access to watch events that represent updates to items belonging to the view.
  • As a minimum, Items have a:
  • fetch method to get the latest version of an Item.
  • spec method that represents the specification of the Item.
  • meta property that provides access to an Item’s metadata.
  • watch method to get an iterator that will provide access to any watch events that represent updates to the item.
  • resource property that provides name of the Kubernetes API resource.

So as one can see, an Item’s specification is available via any Item instance’s spec method. An Item’s status however, is represented by a selection attributes particular to the kind of Item. For example, in the case of a Pod, attributes like; kube.PodItem.phase, kube.PodItem.start_time, kube.PodItem.message.

How Kube handles Kubernetes API versions

kube maintains a list of API base paths for present and past API versions for each resource type. When iterating over items in a kube view, kube uses the most recent API version base path that is found to be available.

Additional Terminology

Cluster

A Kubernetes cluster is a set of physical or virtual machines and other infrastructure which runs containerised applications. You would normally interact with the apiserver running on the Kubernetes master node. This is represented with kube‘s entry-point class kube.Cluster, an instance of which is used to access, among other things, Views representing resource collections.

API object

The Kubernetes system is almost entirely controllable via the HTTP ReSTful API which provides the standard HTTP methods to control the API objects using various HTTP verbs. We use the general term API object to refer to collections (Views) or an element (Item), that is any object which can be retrieved using HTTP GET and has a kind in the returned JSON.

Object Metadata

The Kubernetes API exposes metadata for API Objects. This includes information like the namespace the object resides in, its name, any labels set and their values, version, uid and when the object was created. kube carries much of this information for Items but as discussed, however Views are not exactly the same as collections and only expose properties for particular metadata items, e.g. namespace.

Global Views

Views come in two flavours: global views and views bound to a namespace. Instances of global views are directly accessible from an attribute on a kube.Cluster instance. A global view will only contain all resource items of a certain kind that 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.

Node

A Node is a worker machine in a Kubernetes Cluster. A Node may be a virtual or physical machine, depending on the cluster. kube exposes a cluster’s NodeList resource via the kube.Cluster.nodes view. Each item in the view is a kube.NodeItem instance.

Namespace

Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. kube exposes a cluster’s NamespaceList resource via the kube.Cluster.namespaces view. Each item in the view is a kube.NamespaceItem instance. Furthermore kube exposes an API object’s namespace (if defined) on an instance property. For Views this is on the namespace property, for Items this in on the meta.namespace property.

Replication Controller

A ReplicationController ensures that a specified number of pod “replicas” are running at any one time. In other words, a ReplicationController makes sure that a pod or homogeneous set of pods are always up and available. If there are too many pods, it will kill some. If there are too few, the ReplicationController will start more. Unlike manually created pods, the pods maintained by a ReplicationController are automatically replaced if they fail, get deleted, or are terminated. kube exposes a cluster’s ReplicationControllerList resource via the Cluster.replicationcontrollers view. Each item in the view is a kube.ReplicationControllerItem instance.

ReplicaSet

A ReplicaSet is the next-generation Replication Controller. The only difference between a ReplicaSet and a Replication Controller is the selector support. kube only has views and items representing ReplicaSetLists and ReplicaSet respectively. kube exposes a cluster’s ReplicaSetList resource via the Cluster.replicasets view. Each item in the view is a kube.ReplicaSetItem instance.

Daemonset

A DaemonSet ensures that all (or some) nodes run a copy of a pod. As nodes are added to the cluster, pods are added to them. As nodes are removed from the cluster, those pods are garbage collected. Deleting a DaemonSet will clean up the pods it created. kube exposes a cluster’s DaemonSetList resource via the Cluster.daemonsets view. Each item in the view is a kube.DaemonSetItem instance.

Deployment

A Deployment provides declarative updates for Pods and Replica Sets (the next-generation Replication Controller). You only need to describe the desired state in a Deployment object, and the Deployment controller will change the actual state to the desired state at a controlled rate for you. You can define Deployments to create new resources, or replace existing ones by new ones. kube exposes a cluster’s DeploymentList resource via the Cluster.deployments view. Each item in the view is a kube.DeploymentItem instance.

Pod

A Pod is the smallest deployable unit of computing that can be created and managed in Kubernetes. It is a group of one or more containers (such as Docker containers), the shared storage for those containers, and options about how to run them. Pods model an application-specific “logical host”. kube exposes a cluster’s PodList resource via the Cluster.pods view. Each item in the view is a kube.PodItem instance.

Container

Containers (for example Docker Containers) are run-times that execute on a Node under the shared context of a Pod. The Kubernetes API doesn’t represent containers directly as API Objects but indirectly through a Pod’s specification and status. kube wraps a Pod’s container information up in the kube.PodItem.containers property which provides a list of kube.Container instances that themselves have properties that are kube.ContainerState instances for the current and last known container state.

Service

A Kubernetes Service is an abstraction which defines a logical set of fungible Pods and a policy by which to access them. The set of Pods targeted by a Service is usually determined by a Label Selector. kube exposes a cluster’s ServiceList resource via the kube.Cluster.services view. Each item in the view is a kube.ServiceItem instance.

Secret

A Secret is an API object that contains a small amount of sensitive data such as a password, a token, or a key. kube exposes a cluster’s SecretList resource via the kube.Cluster.secrets view. Each item in the view is a kube.SecretItem instance.

Watching for changes

kube supports the Kubernetes API Watch capability. All Views and Items provided by kube have a watch method that returns an iterator of kube.WatchEvent instances. Whenever one of the resources in a view changes, or a watched Item changes, a kube.WatchEvent instance is yielded.