Kubernetes API and Resource Manifest Structure

Understanding Kubernetes Objects

At its core, Kubernetes is a state machine. You tell it what you want your system to look like, and it works tirelessly to make it so. The "things" you tell Kubernetes about are called objects.

As you just read, every Kubernetes object has two main parts:

• spec (Specification): This is the desired state that you define. It's a declaration of what you want to exist in the cluster. For example, "I want three replicas of my web server running the Nginx 1.21 image."
• status: This is the current state of the object, as observed and reported by the Kubernetes system. The control plane constantly works to reconcile the status with the spec. If a web server instance crashes, the status will reflect two running replicas, Kubernetes will see the mismatch with the spec (which asks for three), and it will automatically start a new one.

This declarative model is powerful. You don't tell Kubernetes how to do something (imperative); you tell it what you want the end result to be (declarative).

The Kubernetes API: Groups and Versions

All interactions with Kubernetes objects happen through the Kubernetes API. When you run a kubectl command, you're making a RESTful API call to the kube-apiserver. This API is extensive and is organized into logical API Groups and managed with Versions.

Understanding this structure is crucial, especially as you work towards your CKA certification. It explains why different resources have different apiVersion fields in their manifests.

Key takeaways from the video:

• API Groups: Bundle related resources. The original, fundamental resources (Pods, Services, Namespaces) are in the core group, which has a special apiVersion of just v1. Newer resources are in named groups like apps, batch, or networking.k8s.io.
• API Versions:
  • Alpha (v1alpha1): Experimental, disabled by default, may be buggy and can be removed without notice. For testing only.
  • Beta (v1beta1): Well-tested and enabled by default. The feature is considered stable, but the schema (the structure of the object's spec) might change.
  • Stable/GA (v1, v2, etc.): Production-ready. The feature will be available for many future releases.

You can explore the available API resources in your cluster at any time using the command kubectl api-resources.

Describing an Object: The Manifest File

Now let's connect the theory to practice. You describe a Kubernetes object and its spec in a manifest file, which is typically written in YAML. Think of this as the equivalent of a Terraform .tf file for defining a resource.

A manifest file has four essential, top-level fields:

1. apiVersion: The API group and version for this object (e.g., apps/v1, v1).
2. kind: The type of object you want to create (e.g., Pod, Deployment, Service).
3. metadata: Information that uniquely identifies the object, such as its name and labels.
4. spec: The desired state for the object. The structure of the spec is different for each kind.

Let's watch a short video that walks through these fields in the context of a real YAML file.

Writing Your First Manifest

Let's put it all together by examining a complete manifest for a Pod, the smallest deployable unit of computing in Kubernetes. We will cover Pods in detail in a future lesson, but for now, they serve as a perfect example of a basic Kubernetes object.

Here is a manifest file named my-pod.yaml:

# my-pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: my-nginx-pod
  labels:
    app: web-server
spec:
  containers:
    - name: nginx-container
      image: nginx:1.21.6
      ports:
        - containerPort: 80

Let's break this down:

• apiVersion: v1: We're using the stable core API group. Pods are a fundamental resource, so they live here.
• kind: Pod: We are defining a Pod object.
• metadata: We've given our Pod a unique name (my-nginx-pod) and attached a label to it for organization.
• spec: This is the desired state. Here, we specify that this Pod must contain one container.
  • containers: A list of containers to run in the Pod.
  • name: A name for the container inside the Pod.
  • image: The container image to pull and run, which you're very familiar with from Docker.
  • ports: A list of network ports the container exposes.

To create this Pod in your cluster, you would save the file and run:
kubectl apply -f my-pod.yaml

Kubernetes would then read this manifest, create the Pod object, and the control plane would schedule it to a node. The kubelet on that node would then instruct the container runtime to pull the nginx:1.21.6 image and start the container.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
      - name: api-server
        image: my-company/api:2.5

Conclusion

In this lesson, we transitioned from the physical components of the cluster to the logical, declarative way we manage it. You now have the foundational knowledge to read and understand Kubernetes manifests.

Here are the key takeaways:

• Kubernetes Objects are records of intent that represent your cluster's state.
• The spec field defines your desired state, while the status field reflects the current state.
• The Kubernetes API is organized into Groups and Versions (apiVersion), which determine a feature's stability (alpha, beta, GA).
• A manifest file (YAML) is how you declaratively define an object, using the four required fields: apiVersion, kind, metadata, and spec.

In the next few lessons, we'll get our hands dirty by setting up a real Kubernetes cluster from scratch using kubeadm. We'll begin by preparing our nodes, installing the necessary packages, and getting ready to initialize the control plane. You'll see the components we've discussed (kubelet, kubeadm, etc.) in action.