Kubernetes Platform at a Glance

On one side of the chain, the user declares the high-level resources to build applications to deploy: Deployments, Ingresses, and so on.

In the middle, controllers are activated to transform these resources into low-level resources (Pods), and the scheduler distributes these resources into nodes. On the other side of the chain, the node agents deploy the low-level resources onto nodes.

A flow diagram of Kubernetes Architecture. The control plane includes an A P I server that bidirectionally connects to controllers and scheduler. It has a single connection with e t c d in the control plane and Kubelet and Kube-proxy in the nodes.

OpenAPI Specification

The Kubernetes API is an HTTP REST API. The Kubernetes team provides a specification for this API in the OpenAPI format, either in v2 format at https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec or in Kubernetes v1.24, in v3 format, at https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec/v3.

These specifications also are accessible from the API Server at these paths: /openapi/v2 and /openapi/v3.

An OpenAPI specification is made up of various parts and, among these, are a list of paths and a list of definitions. The paths are the URLs you use to request this API, and for each path, the specification gives the distinct operations such as get, delete, or post. Then for each operation, the specification indicates what are the parameters and body format for the request, and what are the possible response codes and associated body format for the response.

The parameters and bodies for requests and responses can be either simple types or, more generally, structures containing data. The list of definitions includes data structures that help build the parameters and bodies for the operations’ requests and responses.

Figure 1-2 is a simplified view of a specification for a User API. This API can accept two different paths: /user/{userId} and /user. The first path, /user/{userId}, can accept two operations, get and delete, respectively, to receive information about a specific user, given its user ID; and to delete information about a specific user, given its user ID. The second path, /user, can accept a single operation, post, to add a new user, given its information.

In this API, a definition of a structure User is given, describing the information for a user: its ID, first name, and last name. This data structure is used in the response body of the get operation on the first path, and in the request body of the post operation on the second path.

A pseudocode. The sub-heading paths include get, delete, and post operations. The second sub-heading definition indicates the user I D, first name, and last name.

Verbs and Kinds

The Kubernetes API adds two concepts to this specification: the Kubernetes API Verbs and the Kubernetes Kinds.

The Kubernetes Kinds are a subset of the definitions in the OpenAPI specification. When requests are made to the Kubernetes API, data structures are exchanged through the bodies of requests and responses. These structures share common fields, apiVersion and kind, to help the participants of the request recognize these structures.

If you wanted to make your User API manage this Kind concept, the User structure would contain two additional fields, apiVersion and kind—for example, with values v1 and User. To determine whether a definition in the Kubernetes OpenAPI specification is a Kubernetes Kind, you can look at the x-kubernetes-group-version-kind field of the definition. If this field is defined, the definition is a kind, and it gives you the values of the apiVersion and kind fields.

Group-Version-Resource

The Kubernetes API is a REST API, and as a result of that it manages Resources, and the paths to manage these resources follow the REST naming conventions—that is, by using a plural name to identify a resource and by grouping these resources.

Because the Kubernetes API manages hundreds of resources, they are grouped together, and because the API evolves, the resources are versioned. For these reasons, each resource belongs to a given Group and Version, and each resource is uniquely identified by a Group-Version-Resource, commonly known as GVR.

To find the various resources in the Kubernetes API, you can browse the OpenAPI specification to extract the distinct paths. Legacy resources (e.g., pods or nodes) will have been introduced early in the Kubernetes API and all belong to the group core and the version v1.

The paths to manage legacy resources cluster-wide follow the format /api/v1/<plural_resource_name>—for example, /api/v1/nodes to manage nodes. Note that the core group is not represented in the path. To manage resources in a given namespace, the path format is /api/v1/namespaces/<namespace_name>/<plural_resource_name>—for example, /api/v1/namespaces/default/pods to manage pods in the default namespace.

Newer resources are accessible through paths following the format /apis/<group>/<version>/<plural_resource_name> or /apis/<group>/<version>/namespaces/<namespace_name>/<plural_resource_name>.

Sub-resources

Most Kubernetes resources have a status sub-resource. You can see, when writing operators, that the operator needs to update the status sub-resource to be able to indicate the state of this resource observed by the operator. The operations that can be executed in the status sub-resource are get, patch, and update. The Pod has more sub-resources, including attach, binding, eviction, exec, log, portforward, and proxy. These sub-resources are useful for getting information about a specific running pod, or executing some specific operation on a running pod, and so on.

The resources that can Scale (i.e., deployments, replicasets, etc.) have a scale sub-resource. The operations that can be executed in the scale sub-resource are get, patch, and update.

Official API Reference Documentation

The official reference documentation of the API can be found at https://kubernetes.io/docs/reference/kubernetes-api/. The resources managed by the API are first grouped together by category (i.e., workloads, storage, etc.), and for each category, you can obtain a list of resource names with a short description (Figure 1-3).

Note that these categories are not part of the Kubernetes API definition but are used in this website to help inexperienced users find their way into the multitude of available resources.

A screenshot of the Kubernetes web page includes 3 tabs labeled documentation, Kubernetes blog, and training. Documentation is selected. The text reads about Kubernetes A P I.

To be precise, the name displayed is not the resource name in the REST sense, but the associated principal kind, as shown in Figure 1-4. For example, when managing Pods, the resource name used in the REST paths is pods (i.e., lowercase and plural), and the definition used to exchange information about Pods during HTTP requests is named Pod (i.e., uppercase and singular). Note that other kinds can be associated with the same resource. In the example in this chapter, the PodList kind (used to exchange information about Lists of Pods) also exists.

A screenshot of the Kubernetes web page includes 3 tabs labeled documentation, Kubernetes blog, and training. Documentation is selected. It presents 8 workload resources, including pod, pod template, replication controller, and deployment.

The Deployment Documentation

Let’s explore the reference page for the Deployment available at this address: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/. The title of the page, Deployment, is the principal kind associated with the deployments resource shown in Figure 1-5.

A screenshot of the Kubernetes web page includes 2 tabs labeled documentation and Kubernetes blog. Documentation is selected. It presents the deployment information and deployment specifications.

The apiVersion indicated in the header can help you write a YAML manifest for a Deployment resource because you need to specify, for each resource in a Kubernetes manifest, the apiVersion and kind.

In this case, you know the manifest for a deployment will start with the following:

apiVersion: apps/v1

kind: Deployment

The next header line indicates the import to use when writing Go code. In Chapter 3, you will see how to use this import when describing resources in Go.

A dashed rectangle contains the text, O B J.

After the header, a list of structure definitions is described, also accessible from the table of contents for the Deployment documentation page in Figure 1-6. The first one is the principal kind of the resource, optionally followed by structure definitions that are used in fields of the first kind.

A screenshot of the table of contents for deployment includes a list of operations. It highlights patch partially update the specified deployment.

For example, the Deployment kind contains a spec field, of type DeploymentSpec, which is described later. Note that DeploymentSpec is not a structure directly exchanged during HTTP requests, and for that, it is not a kind and does not contain kind or apiVersion fields.

Following the principal kind, and its associated definitions, other kinds associated with the resource are displayed. In this case, the DeploymentList kind.

Operations Documentation

The next subject in the API Documentation for a resource is the list of possible operations on this resource or its sub-resources, also accessible from the table of contents page (see Figure 1-6). By examining the details for the create operation to Create a Deployment, as shown in Figure 1-7, you can see the HTTP Request verb and path to use, the parameters to pass during the request, and the possible responses. The HTTP verb to use for the request is POST and the path is /apis/apps/v1/namespaces/{namespace}/deployments.

A screenshot of the Kubernetes web page. The right pane includes the details to create a deployment, H T T P request, parameters, and response. The left pane contains a list of options, including the workload resources.

The {namespace} part of the path indicates a path parameter, which is to be replaced by the name of the namespace on which you want to create the deployment. You can specify the query parameters: dryRun, fieldManager, fieldValidation, and pretty. These parameters will follow the path with the format path?dryRun=All.

The body of the request must be a Deployment kind. When using kubectl, you are writing Kubernetes Manifests that contain this body. In Chapter 3, you will see how to build the body in Go. The possible HTTP codes for the responses are: 200, 201, 202, and 401; and for the 2xx codes, the response body will contain a Deployment kind.

The Pod Documentation

Some structures contain many fields. For them, the Kubernetes API documentation categorizes the fields. An example is the documentation of the Pod resource.

The documentation page for the Pod resource first contains the description for the principal kind, Pod, followed by the description of the PodSpec structure. The PodSpec structure contains about 40 fields. To help you understand the relationships between these fields and to simplify their exploration, they are arranged into categories. The PodSpec fields’ categories are the following: Containers, Volumes, Scheduling, Lifecycle, and so on.

Additionally, for fields containing nested fields, descriptions of them are generally displayed inline to avoid a back and forth between structure descriptions. For complex structures, however, the description is reported subsequently on the page, and a link is present next to the field name to be able to access it easily.

This is always the case for the Spec and Status structures because they are very commonly found in almost all the resources. In addition, this is the case for some structures used in the Pod kind—for example, Container, EphemeralContainer, LifecycleHandler, NodeAffinity, and so on.

Some structures used in several resources are placed in the Common Definitions section, and a link is present next to the field name to access it easily. In Figure 1-8, you can see the Containers category inside the description of the PodSpec structure.

A screenshot of the pod specifications depicts the containers with 3 sub-headings. 1. Containers. 2. Initialization containers. 3. Image pull secrets.

You also can see that the fields, containers and initContainers, are of the same type as Container, which is described later on the page and is accessible with a link. The imagePullSecrets field is of type LocalObjectReference, which is described in the Common Definitions section and also is accessible through a link.

Conclusion

In this chapter, you have been able to discover the architecture of the Kubernetes platform, and that the API Server plays a central role. The Kubernetes API is an HTTP REST API, and the resources are categorized into various versioned groups.

Kinds are specific structures used to exchange data between the API server and the clients. You can browse, using the official Kubernetes website, the API specifications in a human-readable form to discover the structure of the various resources and kinds, the different operations available for each resource and sub-resource, and their associated verbs.