The Kubernetes APIs

If you want to understand the capabilities of a system and what it provides, you must pay a lot of attention to its APIs. These APIs provide a comprehensive view of what you can do with the system as a user. Kubernetes exposes several sets of REST APIs for different purposes and audiences through API groups. Some of the APIs are used primarily by tools and some can be used directly by developers. An important fact regarding the APIs is that they are under constant development. The Kubernetes developers keep it manageable by trying to extend it (by adding new objects and new fields to existing objects) and avoid renaming or dropping existing objects and fields. In addition, all API endpoints are versioned, and often have an alpha or beta notation too. For example:

/api/v1
/api/v2alpha1  

You can access the API through the kubectl cli, through client libraries, or directly through REST API calls. There are elaborate authentication and authorization mechanisms that we will explore in a later chapter. If you have the right permissions, you can list, view, create, update, and delete various Kubernetes objects. At this point, let's glimpse the surface area of the APIs. The best way to explore these APIs is through API groups. Some API groups are enabled by default. Other groups can be enabled/disabled via flags. For example, to disable the batch V1 group and enable the batch V2 alpha group, you can set the --runtime-config flag when running the API server as follows:

--runtime-config=batch/v1=false,batch/v2alpha=true 

The following resources are enabled by default, in addition to the core resources:

• DaemonSets
• Deployments
• HorizontalPodAutoscalers
• Ingress
• Jobs
• ReplicaSets

Resource categories

In addition to API groups, another useful classification of the available APIs is functionality. The Kubernetes API is huge, and breaking it down into categories helps a lot when you're trying to find your way around. Kubernetes defines the following resource categories:

• Workloads: The objects you use to manage and run containers on the cluster.
• Discovery and load balancing: The objects you use to expose your workloads to the world as externally accessible, load-balanced services.
• Config and storage: The objects you use to initialize and configure your applications, and to persist data that is outside the container.
• Cluster: The objects that define how the cluster itself is configured; these are typically used only by cluster operators.
• Metadata: The objects you use to configure the behavior of other resources within the cluster, such as HorizontalPodAutoscaler for scaling workloads.

In the following subsections, I'll list the resources that belong to each group, along with the API group they belong to. I will not specify the version here because APIs move rapidly from alpha to beta to general availability (GA), and then from V1 to V2, and so on.

Workloads API

The workloads API contains the following resources:

• Container: Core
• CronJob: Batch
• DaemonSet: Apps
• Deployment: Apps
• Job: Batch
• Pod: Core
• ReplicaSet: Apps
• ReplicationController: Core
• StatefulSet: Apps

Containers are created by controllers using pods. Pods run containers and provide environmental dependencies, such as shared or persistent storage volumes, and configuration or secret data injected into the container.

Here is a detailed description of one of the most common operations, which gets a list of all the pods as a REST API:

GET /api/v1/pods 

It accepts various query parameters (all optional):

• pretty: If true, the output is pretty printed
• labelSelector: A selector expression to limit the result
• watch: If true, this watches for changes and returns a stream of events
• resourceVersion: Returns only events that occurred after that version
• timeoutSeconds: Timeout for the list or watch operation

Discovery and load balancing

By default, workloads are only accessible within the cluster, and they must be exposed externally using either a LoadBalancer or NodePort service. During development, internally accessible workloads can be accessed via a proxy through the API master using the kubectl proxy command:

• Endpoints: Core
• Ingress: Extensions
• Service: Core

Config and storage

Dynamic configuration without redeployment is a cornerstone of Kubernetes and running complex distributed applications on your Kubernetes cluster:

• ConfigMap: Core
• Secret: Core
• PersistentVolumeClaim: Core
• StorageClass: Storage
• VolumeAttachment: Storage

Metadata

The metadata resources typically are embedded as subresources of the resources they configure. For example, a limit range will be part of a pod configuration. You will not interact with these objects directly most of the time. There are many metadata resources. You can find the complete list at https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/#-strong-metadata-strong-.

Cluster

The resources in the cluster category are designed for use by cluster operators as opposed to developers. There are many resources in this category as well. Here some of the most important resources:

• Namespace: Core
• Node: Core
• PersistentVolume: Core
• ResourceQuota : Core
• ClusterRole: Rbac
• NetworkPolicy : Networking