Kube-API Server

The Kubernetes API Server (kube-apiserver) is effectively the “brain” and the “heart” of the Kubernetes control plane. It is the central management entity that intercepts all REST requests, validates them, and executes the logic bound to them. It is the only component in the Kubernetes architecture that communicates directly with the Etcd database.

Key Characteristics to Remember

Here are the golden rules to remember the API Server forever:

• The Hub: It is the central meeting point where all traffic enters the cluster.
• The Guard: It validates every single request before processing it. No exceptions!
• The Messenger: It is the only component allowed to write data to the Etcd database.
• The Scaler: Unlike other control plane tools, the API Server acts like a web server—you can run many of them at once (Stateless).
• The Listener: It uses a “Watch” mechanism to notify other components instantly when things change, rather than them asking repeatedly.
• Stateless: It stores no data itself; it pushes everything to Etcd.
• RESTful: It speaks standard HTTP (GET, POST, PUT, DELETE).
• Secure: It enforces TLS encryption for all communications.

The Central Hub: How It Works

Think of the API Server as the Grand Central Station of Kubernetes. No matter who you are or what you are a DevOps engineer running kubectl commands, a CI/CD pipeline deploying code, or a Kubelet on a worker node reporting a pod crash you must go through the API Server.

• The Only Writer: No other component (Scheduler, Controller Manager, or Kubelet) can write to Etcd directly. They must send a request to the API Server, which then writes to Etcd. This ensures that the state of the cluster is managed consistently and securely.
• Statelessness: The API Server itself is stateless. It processes requests but stores all data in Etcd. This is a critical architectural decision that allows the API Server to scale horizontally easily.

The Three Gates of Security

Before any request is processed, it must pass through three distinct security gates in a specific order:

1. Authentication (AuthN) – “Who are you?”

Kubernetes does not have a “User” object in its database for humans. It relies on external identity providers for humans and internal mechanisms for system components.

Identity Types

• Normal Users (Humans): Managed externally (e.g., Google Accounts, LDAP, Active Directory). Kubernetes identifies them via valid certificates or tokens.
• Service Accounts (Robots): Managed by Kubernetes itself. These are namespaced resources used by Pods to talk to the API Server.
  • Credential: Stored as a generic Secret (legacy) or an ephemeral TokenRequest (modern).
  • Naming: system:serviceaccount:<namespace>:<service_account_name>

Common Auth Methods

• X.509 Client Certificates: Used often by admin tools and system components (like the Kubelet). The Common Name (CN) is used as the User, and Organization (O) as the Group.
• Static Token File: A CSV file on the control plane (not recommended for production).
• OpenID Connect (OIDC): The standard for integrating with external providers (Okta, Azure AD, Keycloak). The API server verifies the JWT token signed by the provider.
• Webhook Token: The API server asks an external service (like AWS IAM Authenticator) to verify the bearer token.

Kubernetes needs to know who is making a request. It looks for credentials in specific places in the HTTP request.

1. X509 Client Certificates:
   • This is the most common way for Admins (using kubeadm).
   • Inside the certificate, the CN (Common Name) is treated as the User Name (e.g., CN=rajkumar).
   • The O (Organization) is treated as the Group (e.g., O=devs).
   • Tools: OpenSSL, CFSSL.
2. Service Accounts (JWT):
   • Created automatically by Kubernetes for Pods.
   • When a Pod starts, K8s mounts a secret token at /var/run/secrets/kubernetes.io/serviceaccount/token.
   • The Pod uses this token to talk to the API Server.

For a secure production cluster, simple certs are not enough. You need enterprise integration.

1. OpenID Connect (OIDC):
   • Kubernetes cannot store user passwords. Instead, it trusts an external “Identity Provider” (IdP) like Okta, Google, Keycloak, or AWS IAM.
   • The Flow:
     1. User logs into Okta -> gets an ID Token (JSON Web Token).
     2. User sends this Token to K8s API Server in the HTTP Header (Authorization: Bearer <token>).
     3. K8s verifies the signature with the IdP’s certificate.
     4. If valid, K8s reads the email or sub field to identify the user.
   • Official Link: Configuring OIDC
2. Authentication Proxy:
   • Used when you have complex auth requirements (like LDAP or strict mTLS).
   • You put a proxy server in front of the API Server. The proxy checks the user, and if successful, adds a header X-Remote-User: jane and forwards it to the API Server.
   • Tools: Pinniped, Teleport.

Common Issues, Problems, and Solutions

2. Authorization (AuthZ) – “What can you do?”

• Once identified, the server checks if the user has permission to perform the specific action (e.g., create pods, delete services). This is typically handled by RBAC (Role-Based Access Control).
• Analogy: Checking if your visa or ticket allows you into a specific country or VIP lounge.

1. Admission Control – “Is this request safe and valid?”
   • Even if you are authenticated and authorized, the request can still be rejected. Admission controllers intercept the request to validate content (e.g., “Image pull policy must be Always”) or mutate it (e.g., “Inject a sidecar container”).
   • Analogy: The airport security scan. You have a ticket, but you can’t bring a forbidden item on board.

Key Characteristics

Scalability and High Availability

Since the API Server is the only component that handles external traffic and internal coordination, it is the primary bottleneck.

• Horizontal Scaling: Because it is stateless, you can run multiple replicas of the kube-apiserver (usually 3 for High Availability) behind a Load Balancer.
• Load Balancing: The Load Balancer (e.g., HAProxy, NGINX, or a Cloud LB) distributes traffic across the available API Server instances.

The Watch Mechanism

One of the most powerful features of the API Server is the Watch API. Instead of clients constantly polling the server (“Is there a change? Is there a change?”), they can establish a long-lived connection. The API Server pushes updates to connected clients immediately when a change occurs.

• Why it matters: This is how the kube-scheduler knows instantly that a new Pod needs to be scheduled, or how kube-proxy knows a Service IP has changed.

API Priority and Fairness (APF)

In high-traffic clusters, the API Server can get overwhelmed. APF is a feature that allows you to categorize and prioritize incoming requests.

• Function: It prevents a flood of low-priority requests (e.g., log scraping) from starving critical requests (e.g., Kubelet heartbeats or system component updates).

RESTful and Declarative

• RESTful: It supports standard HTTP verbs: GET (retrieve), POST (create), PUT (update/replace), PATCH (partial update), and DELETE (remove).
• Declarative Management: You do not tell the API Server how to do something; you tell it what the final result should look like (Desired State). The controllers then work to make that reality.
  • You send the “Desired State” (YAML), and the API Server accepts it.

Custom Resource Definitions (CRDs)

The API Server is designed to be extended. Users can define their own resources (e.g., PrometheusRule, Backup, Database) via CRDs. To the API Server, these look and act just like native Pods.

The Aggregation Layer

This is a special layer inside the API Server. It allows you to run extension API servers (like the metrics-server) that sit behind the main API IP. When you run kubectl top pods, the main API server acts as a proxy, forwarding that request to the extension server.

Audit Logs

The API Server can record every single request (who did what and when) to a file or external backend. This is mandatory for security compliance (SOC2, PCI-DSS).

The Kubernetes API server primarily uses TCP port 6443 for secure, HTTPS connections by default. 

• Versioned: APIs are versioned (e.g., v1, v1beta1). This ensures stability; old scripts don’t break when K8s is upgraded.

Benefits

• Centralized Security: You only need to secure one entry point (the API Server) to secure the control plane actions.
• Consistency: Since all data goes through one validation pipeline, invalid data rarely enters the system.

Common Challenges and Troubleshooting

• Kubernetes API Server
• Kubernetes API Reference Docs
• Accessing the API