2.3 Kubernetes API, Declarative Management & kubectl

2.3 Kubernetes API, Declarative Management & kubectl

All interactions with a Kubernetes cluster—whether issued by human operators via kubectl, automated CI/CD pipelines, or internal controllers—are processed as HTTP REST API calls targeting kube-apiserver. Understanding the API hierarchy, resource management paradigms, object manifests, and CLI toolsets is essential for cloud-native operations.

---

1. RESTful API Structure & GVK Paradigm

The Kubernetes API is structured logically around the Group / Version / Kind (GVK) model. This schema hierarchy categorizes resources and manages API lifecycle evolution.

                      KUBERNETES REST API SCHEME 
                                   | 
         +-------------------------+-------------------------+ 
         |                                                   | 
  Core API Group (/api/v1)                       Named API Groups (/apis/GROUP/VERSION) 
  e.g., Pods, Services, ConfigMaps               e.g., apps/v1, networking.k8s.io/v1 

Group, Version, Kind Breakdown

• API Group: A collection of related resource types. The Core Group (legacy group) is served under /api/v1 (e.g., Pod, Service, Namespace, ConfigMap, Node). Named Groups are served under /apis/GROUP/VERSION (e.g., apps, batch, networking.k8s.io, rbac.authorization.k8s.io).
• API Version: Indicates maturity and stability:
  • v1alpha1: Experimental features; subject to breaking schema changes without notice.
  • v1beta1: Feature-complete; enabled by default but may be deprecated in future releases.
  • v1: Stable; guaranteed backward compatibility across major release cycles.
• Kind: The specific object schema name defined in code (e.g., Deployment, StatefulSet, Service, CustomResourceDefinition).

GVK vs. GVR: While GVK (Group/Version/Kind) refers to the schema definition used in manifest code, GVR (Group/Version/Resource) refers to the corresponding HTTP REST endpoint path exposed by the API server (e.g., /apis/apps/v1/namespaces/default/deployments).

---

2. Imperative vs. Declarative Management

Kubernetes supports three distinct approaches for managing cluster objects:

A. Imperative Commands (kubectl run, kubectl create)

Directly command Kubernetes on how to perform an operational step:

# Create a deployment imperatively
kubectl create deployment web-server --image=nginx:1.25 --replicas=3

# Expose the deployment as a ClusterIP service
kubectl expose deployment web-server --port=80 --target-port=80

• Pros: Fast, convenient for ad-hoc testing and emergency troubleshooting.
• Cons: Lacks auditability, cannot be reviewed in version control, hard to reproduce.

B. Imperative Object Configuration (kubectl create -f)

Operate on specific manifest files with explicit verbs (create, replace, delete). While files are used, the user explicitly dictates the action to perform.

C. Declarative Object Configuration (kubectl apply -f)

Specify the desired state in YAML/JSON manifests and instruct Kubernetes to reconcile current state toward desired state using kubectl apply:

# Declaratively apply all manifests in a directory
kubectl apply -f ./manifests/

The Three-Way Strategic Merge

When kubectl apply is executed, Kubernetes compares three states:

1. The local manifest file provided by the user.
2. The live object configuration currently running in the cluster.
3. The last-applied-configuration annotation stored on the live object (kubectl.kubernetes.io/last-applied-configuration).

This three-way merge ensures that changes made out-of-band by controllers (such as horizontal pod autoscalers updating replica counts) are preserved while applying user updates.

---

3. Anatomy of a YAML Object Manifest

Every Kubernetes YAML resource definition requires four top-level root keys:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app-deployment
  namespace: production
  labels:
    app: web-app
    environment: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web-app
  template:
    metadata:
      labels:
        app: web-app
    spec:
      containers:
      - name: nginx-container
        image: nginx:1.25.3
        ports:
        - containerPort: 80
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "500m"
            memory: "512Mi"

Root Field Definitions

• apiVersion: The API Group and Version schema matching the resource (e.g., apps/v1).
• kind: The object type to create (e.g., Deployment).
• metadata: Unique identification data including name, namespace, labels (key-value metadata for filtering), and annotations (non-identifying operational data).
• spec: The desired state specification defining container images, replicas, ports, and volumes.
• status: System-managed field populated by control plane controllers representing actual live state.

---

4. Kubeconfig File Structure

kubectl uses a configuration file known as kubeconfig (default location: ~/.kube/config) to locate and authenticate against cluster API endpoints.

Kubeconfig Architecture

A kubeconfig file contains three main array sections:

1. clusters: Server URLs and Certificate Authority (certificate-authority-data) details.
2. users: Authentication credentials (client certificates, bearer tokens, or IAM plugins).
3. contexts: Binds a specific cluster, user, and default namespace into an environment target.

apiVersion: v1
kind: Config
current-context: dev-context
clusters:
- name: dev-cluster
  cluster:
    server: https://192.168.1.100:6443
    certificate-authority-data: LS0tLS1CRUdJTi...
users:
- name: dev-user
  user:
    client-certificate-data: LS0tLS1CRUdJTi...
    client-key-data: LS0tLS1CRUdJTi...
contexts:
- name: dev-context
  context:
    cluster: dev-cluster
    user: dev-user
    namespace: development

Practical Kubeconfig Commands

# Display formatted kubeconfig settings
kubectl config view

# List all available contexts
kubectl config get-contexts

# Switch active context to target cluster
kubectl config use-context dev-context

# Change default namespace for current context
kubectl config set-context --current --namespace=production

---

5. Essential kubectl Commands