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.