4. How to Communicate with Kubernetes (API Server)

Overview

In this chapter, we will build a foundational understanding of the Kubernetes API server and the various ways of interacting with it. We will learn how kubectl and other HTTP clients communicate with the Kubernetes API server. We will use some practical demonstrations to trace these communications and see the details of HTTP requests. Then, we will also see how we can look up the API details so that you can write your own API request from scratch. By the end of this chapter, you will be able to create API objects by directly communicating with the API server using any HTTP client, such as curl, to make RESTful API calls to the API server.

Introduction

As you will recall from Chapter 2, An Overview of Kubernetes, the API server acts as the central hub that communicates with all the different components in Kubernetes. In the previous chapter, we took a look at how we can use kubectl to instruct the API server to do various things.

In this chapter, we will take a further look into the components that make up the API server. As the API server is at the center of our entire Kubernetes system, it is important to learn how to effectively communicate with the API server itself and how API requests are processed. We will also look at various API concepts, such as resources, API groups, and API versions, which will help you understand the HTTP requests and responses that are made to the API server. Finally, we will interact with the Kubernetes API using multiple REST clients to achieve many of the same results we did in the previous chapter using the kubectl command-line tool.

The Kubernetes API Server

In Kubernetes, all communications and operations between the control plane components and external clients, such as kubectl, are translated into RESTful API calls that are handled by the API server. Effectively, the API server is a RESTful web application that processes RESTful API calls over HTTP to store and update API objects in the etcd datastore.

The API server is also a frontend component that acts as a gateway to and from the outside world, which is accessed by all clients, such as the kubectl command-line tool. Even the cluster components in the control plane interact with each other only through the API server. Additionally, it is the only component that interacts directly with the etcd datastore. Since the API server is the only way for clients to access the cluster, it must be properly configured to be accessible by clients. You will usually see the API server implemented as kube-apiserver.

Note

We will explain the RESTful API in more detail...

Kubernetes HTTP Request Flow

As we learned in earlier chapters, when we run any kubectl command, the command is translated into an HTTP API request in JSON format and is sent to the API server. Then, the API server returns a response to the client, along with any requested information. The following diagram shows the API request life cycle and what happens inside the API server when it receives a request:

Figure 4.2: API server HTTP request flow

As you can see in the preceding figure, the HTTP request goes through the authentication, authorization, and admission control stages. We will take a look at each of these in the following subtopics.

Authentication

In Kubernetes, every API call needs to authenticate with the API server, regardless of whether it comes from outside the cluster, such as those made by kubectl, or a process inside the cluster, such as those made by kubelet.

When an HTTP request is sent to the API server, the API server needs to...

The Kubernetes API

The Kubernetes API uses JSON over HTTP for its requests and responses. It follows the REST architectural style. You can use the Kubernetes API to read and write Kubernetes resource objects.

Note

For more details about the RESTful API, please refer to https://restfulapi.net/.

Kubernetes API allows clients to create, update, delete, or read a description of an object via standard HTTP methods (or HTTP verbs), such as the examples in the following table:

Figure 4.12: HTTP verbs and their usage

In the context of Kubernetes API calls, it is helpful to understand how these HTTP methods map to API request verbs. So, let's take a look at which verbs are sent through which methods:

• GET: get, list, and watch

  Some example kubectl commands are kubectl get pod, kubectl describe pod <pod-name>, and kubectl get pod -w.

• POST: create

  An example kubectl command is kubectl create -f <filename.yaml>.

• PATCH: patch

  An example...

Scope of API Resources

All resource types can either be cluster-scoped resources or namespace-scoped resources. The scope of a resource affects the access of that resource and how that resource is managed. Let's look at the differences between namespace and cluster scope.

Namespace-Scoped Resources

As we saw in Chapter 2, An Overview of Kubernetes, Kubernetes makes use of Linux namespaces to organize most Kubernetes resources. Resources in the same namespace share the same control access policies and authorization checks. When a namespace is deleted, all resources in that namespace are also deleted.

Let's see what forms the request paths for interacting with namespace-scoped resources take:

• Return the information about a specific pod in a namespace:

  GET /api/v1/namespaces/{my-namespace}/pods/{pod-name}

• Return the information about a collection of all Deployments in a namespace:

  GET /apis/apps/v1/namespaces/{my-namespace}/deployments

• Return the information...

API Groups

An API group is a collection of resources that are logically related to each other. For example, Deployments, ReplicaSets, and DaemonSets all belong to the apps API group: apps/v1.

Note

You will learn about Deployments, ReplicaSets, and DaemonSets in detail in Chapter 7, Kubernetes Controllers. In fact, this chapter will talk about many API resources that you will encounter in later chapters.

The --api-group flag can be used to scope the output to a specific API group, as we will see in the following sections. Let's take a closer look at the various API groups in the following sections.

Core Group

This is also called the legacy group. It contains objects such as pods, services, nodes, and namespaces. The URL path for these is /api/v1, and nothing other than the version is specified in the apiVersion field. For example, consider the following screenshot where we are getting information about a pod:

Figure 4.25: API group of a pod...

API Versions

In the Kubernetes API, there is the concept of API versioning; that is, the Kubernetes API supports multiple versions of a type of resource. These different versions may act differently. Each one has a different API path, such as /api/v1 or /apis/extensions/v1beta1.

The different API versions differ in terms of stability and support:

• Alpha: This version is indicated by alpha in the apiVersion field—for example, /apis/batch/v1alpha1. The alpha version of resources is disabled by default as it is not intended for production clusters but can be used by early adopters and developers who are willing to provide feedback and suggestions and report bugs. Also, support for alpha resources may be dropped without notice by the time the final stable version of Kubernetes is finalized.
• Beta: This version is indicated by beta in the apiVersion field—for example, /apis/certificates.k8s.io/v1beta1. The beta version of resources is enabled by default, and the...

Interacting with Clusters Using the Kubernetes API

Up until now, we've been using the Kubernetes kubectl command-line tool, which made interacting with our cluster quite convenient. It does that by extracting the API server address and authentication information from the client kubeconfig file, which is located in ~/.kube/config by default, as we saw in the previous chapter. In this section, we will look at the different ways to directly access the API server with HTTP clients such as curl.

There are two possible ways to directly access the API server via the REST API—by using kubectl in proxy mode or by providing the location and authentication credentials directly to the HTTP client. We will explore both methods to understand the pros and cons of each one.

Accessing the Kubernetes API Server Using kubectl as a Proxy

kubectl has a great feature called kubectl proxy, which is the recommended approach for interacting with the API server. This is recommended because...

Direct Access to the Kubernetes API Using Authentication Credentials

Instead of using kubectl in proxy mode, we can provide the location and credentials directly to the HTTP client. This approach can be used if you are using a client that may get confused by proxies, but it is less secure than using the kubectl proxy due to the risk of MITM attacks. To mitigate this risk, it is recommended that you import the root certificate and verify the identity of the API server when using this method.

When thinking about accessing the cluster using credentials, we need to understand how authentication is configured and what authentication plugins are enabled in our cluster. Several authentication plugins can be used, which allow different ways of authenticating with the server:

• Client certificates
• ServiceAccount bearer tokens
• Authenticating proxy
• HTTP basic auth

  Note

  Note that the preceding list includes only some of the authentication plugins. You can learn more about authentication...

Summary

In this chapter, we took a closer look at the Kubernetes API server, the way that Kubernetes uses the RESTful API, and how API resources are defined. We learned that all commands from the kubectl command-line utility are translated into RESTful HTTP API calls and are sent to the API server. We learned that API calls go through multiple stages, including authentication, authorization, and admission control. We also had a closer look at each stage and some of the modules involved.

Then, we learned about some API resources, how they are categorized as namespace-scoped or cluster-scoped resources, and their API group and API version. We then learned how we can use this information to build an API path for interacting with the Kubernetes API.

We also applied what we learned by making an API call directly to the API server, using the curl HTTP client to interact with objects by using different authentication methods, such as ServiceAccounts and an X.509 certificate.

In...