Kubernetes API

The Kubernetes API server (kube-apiserver) is the control plane component that exposes the Kubernetes API. It receives requests, validates them, processes authentication and authorization, and coordinates resource changes with other control plane components.

• It provides HTTP-based API endpoints for Kubernetes resources.
• It authenticates requests and checks whether the requester has permission to perform an operation.
• It validates resource definitions before accepting changes.
• It works with etcd, the cluster's backing data store, to persist Kubernetes resource state.

How It Works

When a user runs a kubectl command, the request is sent to the Kubernetes API server. The server processes the request and coordinates the required operation.

• The user runs a command or sends an API request.
• The API server authenticates and authorizes the request.
• The API server validates the requested operation and processes the resource change.
• The resource state is stored, and Kubernetes controllers work to make the actual cluster state match the desired state.

Kubernetes API Resources and Endpoints

The Kubernetes API organizes cluster objects into resources. Each resource has an API endpoint used to perform operations on it.

• Core resources such as Pods and Services use the /api/v1 API group.
• Resources such as Deployments belong to named API groups, such as apps/v1.
• Namespaced resources exist within a namespace, while cluster-scoped resources, such as Nodes, are not tied to a namespace.
• Available API groups, versions, and resources can be inspected using kubectl api-resources and kubectl api-versions.

Common Kubernetes API Operations

The Kubernetes API supports standard HTTP methods to manage resources.

The kubectl command translates user operations into API requests. For example, kubectl get pods retrieves Pod information, while kubectl apply -f pod.yaml sends the required changes to the API server.

Authentication and Authorization in Kubernetes API

The Kubernetes API protects cluster resources by checking who is making a request and what that requester is allowed to do.

• Authentication verifies the identity of a user, service account, or other client.
• Authorization determines whether the authenticated identity can perform the requested operation.
• Role-Based Access Control (RBAC) can grant permissions to users and service accounts for specific resources and actions.
• TLS protects communication with the API server, and access should be restricted to trusted clients.

Create a Pod Using the Kubernetes API

In this hands-on, we will create a Pod by sending a direct HTTP request to the Kubernetes API server through kubectl proxy. We will then retrieve the Pod through the API and delete it using an API request. This demonstrates how Kubernetes resources can be managed through API endpoints rather than only through kubectl resource commands.

Step 1: Start a Kubernetes Cluster

Start Minikube if it is not already running.

minikube start

Verify that the cluster is accessible.

kubectl get nodes

The node should appear with a Ready status.

Step 2: Start the Kubernetes API Proxy

Open a terminal and run:

kubectl proxy --port=8001

Keep this terminal running. The proxy exposes a local HTTP endpoint and forwards requests to the Kubernetes API server using your configured Kubernetes credentials. Open a second terminal for the remaining steps.

Step 3: Create a Pod Definition

Create a JSON file containing the Pod definition. This JSON will be sent directly to the Kubernetes API.

cat > api-pod.json <<'EOF'
{
  "apiVersion": "v1",
  "kind": "Pod",
  "metadata": {
    "name": "api-demo-pod",
    "labels": {
      "app": "api-demo"
    }
  },
  "spec": {
    "containers": [
      {
        "name": "nginx",
        "image": "nginx:1.27",
        "ports": [
          {
            "containerPort": 80
          }
        ]
      }
    ]
  }
}
EOF

The file defines a Pod named api-demo-pod that runs an NGINX container.

Step 4: Create the Pod Through an API Request

Run the following command to send a POST request to the Kubernetes API server.

curl -i -X POST \
  http://127.0.0.1:8001/api/v1/namespaces/default/pods \
  -H "Content-Type: application/json" \
  --data-binary @api-pod.json

The API server should return a successful creation response, normally with HTTP status 201 Created, along with the created Pod's details.

• POST requests the creation of a resource.
• The endpoint specifies the core API version and the default namespace.
• The JSON file provides the desired Pod configuration.

Step 5: Retrieve the Pod Through the Kubernetes API

Send a GET request to retrieve the newly created Pod.

curl -i \
  http://127.0.0.1:8001/api/v1/namespaces/default/pods/api-demo-pod

The response should contain the Pod's JSON representation, including its name, labels, container specification, and current status. You can also verify the same resource using:

kubectl get pod api-demo-pod

This confirms that the resource created through the API is visible through kubectl, which uses the same Kubernetes API server.

Step 6: Delete the Pod Through an API Request

Send a DELETE request to remove the Pod.

curl -i -X DELETE \
  http://127.0.0.1:8001/api/v1/namespaces/default/pods/api-demo-pod \
  -H "Content-Type: application/json" \
  -d '{}'

The API server should accept the deletion request and return a successful response. The Pod may take a short time to disappear while deletion is processed.

Verify the result:

kubectl get pod api-demo-pod

The command should report that the Pod is not found once deletion has completed.

Security Note: Use kubectl proxy only in a trusted local environment. Do not expose the proxy port to untrusted networks.

Best Practices

Following API best practices helps protect cluster resources and makes automation more reliable.

• Use authenticated API access and grant only the permissions required by each client.
• Prefer supported API versions and check resource compatibility before upgrading a cluster.
• Use kubectl or well-maintained Kubernetes client libraries for routine automation instead of manually constructing every request.
• Handle API errors, timeouts, and rate limits in automation code.
• Avoid exposing the API server or local proxy endpoints to untrusted networks.