Skip to main content

API Architecture and Authorization Mechanisms

The Kubernetes API is the central nervous system of the cluster. Every operation, whether performed by a human via kubectl or an internal controller, is a RESTful request to the kube-apiserver. Understanding the structure of this API is a prerequisite for mastering Kubernetes security and authorization.

1. THE KUBERNETES API ARCHITECTURE​

The API is resource-based, utilizing standard HTTP verbs (GET, POST, PUT, DELETE, PATCH) to manipulate the state stored in etcd.

1.1 The Request Lifecycle (Internal Path)​

When a request hits the API server, it follows a strict serial path:

  1. Authentication: "Who are you?" (Certificates, Tokens, OIDC).
  2. Authorization: "What can you do?" (RBAC, Webhook, Node).
  3. Admission Control: "Is the content valid?" (Mutating and Validating Admission Controllers).
  4. Persistence: Data is written to etcd.

1.2 API Discovery and Groups​

Kubernetes organizes its API into Groups, Versions, and Resources (GVR) to allow for modularity and incremental updates.

A. The Core Group (Legacy)​

  • Path: /api/v1
  • Resources: Pods, Services, Nodes, Namespaces, ConfigMaps, Secrets.
  • YAML: apiVersion: v1 (The group is an empty string "").

B. The Named Groups (Modern)​

  • Path: /apis/<group>/<version>
  • Examples:
    • /apis/apps/v1: Deployments, StatefulSets.
    • /apis/rbac.authorization.k8s.io/v1: Roles, RoleBindings.
    • /apis/networking.k8s.io/v1: Ingress.

C. Discovery API​

You can query the API server to see which resources it supports. This is how kubectl knows what to do when you type kubectl get ....

# Get all available API resources and their verbs
kubectl api-resources -o wide

# Check the raw discovery endpoint
kubectl get --raw /apis/apps/v1

2. AUTHORIZATION MODES​

Kubernetes supports a pluggable authorization model. The API server evaluates modes sequentially via the --authorization-mode flag.

2.1 Node Authorization​

A specialized authorizer that limits the scope of Kubelets.

  • Logic: A Kubelet on Node-A can only read Secrets or ConfigMaps associated with Pods scheduled on Node-A. It cannot access data for Pods on Node-B.
  • Production Standard: This should always be enabled (--authorization-mode=Node,RBAC) and is paired with the NodeRestriction admission controller.

2.2 RBAC (Role-Based Access Control)​

The industry standard. Permissions are granted via "Roles" and "RoleBindings."

  • Benefit: Declarative and stored in etcd. No API server restart required for changes.

2.3 Webhook Authorization​

Outsources the decision to an external HTTP service (e.g., OPA, Styra, or a custom service).

  • Mechanism: The API Server sends a SubjectAccessReview JSON payload to the remote service.
  • Sample Webhook Config (/etc/kubernetes/webhook-config.yaml):
apiVersion: v1
kind: Config
clusters:
- name: external-auth-service
  cluster:
    server: https://policy-engine.internal:8080/authorize
    certificate-authority: /etc/kubernetes/pki/ca.crt
users:
- name: api-server-client
  user:
    client-certificate: /etc/kubernetes/pki/apiserver.crt
    client-key: /etc/kubernetes/pki/apiserver.key
contexts:
- context:
    cluster: external-auth-service
    user: api-server-client
  name: webhook
current-context: webhook

2.4 ABAC (Attribute-Based Access Control)​

  • Mechanism: Permissions are defined in a static JSON file on the master node.
  • Pitfall: Requires a restart of the API Server to apply changes. Extremely hard to scale in production. Not recommended.

3. THE AUTHORIZATION CHAIN (LOGIC FLOW)​

The API Server checks the --authorization-mode list from left to right. Example: --authorization-mode=Node,Webhook,RBAC

  1. Is the request from a Kubelet? The Node authorizer checks. If it can decide (Allow/Deny), it does. If not, it returns "No Opinion."
  2. No Opinion? Pass to the Webhook authorizer.
  3. No Opinion? Pass to RBAC.
  4. Denied by all? If the end of the chain is reached without an "Allow," the request is rejected with a 403 Forbidden.

4. AUDITING PERMISSIONS (KUBECTL NINJA)​

You don't need to guess if a user has access. Use the auth can-i tool, which utilizes the SelfSubjectAccessReview API.

# 1. Check your own permissions
kubectl auth can-i create deployments

# 2. Check as another user (Requires admin rights)
kubectl auth can-i list secrets --as=system:serviceaccount:default:my-sa

# 3. Check for a specific resource instance
kubectl auth can-i delete pod/nginx-pod -n production

Inspecting RBAC via API​

To see the actual logic the API server uses to authorize you:

# View the rules applied to your current identity
kubectl auth can-i --list

5. AUTHORIZATION VS. ADMISSION CONTROL​

One of the most common points of confusion for engineers is where to place security logic.

FeatureAuthorization (AuthZ)Admission Control
Check TypeIdentity-based (Who/What/Where).Content-based (The "How").
Logic"Is Seema allowed to create Pods in 'Dev'?""Is this Pod using a root container or an untrusted image?"
Metadata AccessUser, Verb, Namespace, Resource.Full JSON body of the object being created/updated.
PhaseBefore the object is validated.After schema validation, before persistence.

6. PRODUCTION PITFALLS & REAL-WORLD WARNINGS​

  1. Over-Permissive Node Identity: If Node authorizer is missing, a compromised Kubelet could steal secrets from the entire cluster.
  2. Webhook Latency: If using Webhook Auth, the external service becomes a critical path. If it is slow, kubectl commands will feel sluggish. If it is down, the API server might block all requests (depending on configuration).
  3. Discovery API Access: By default, the system:unauthenticated group often has access to the /version and /healthz endpoints. Ensure you aren't exposing sensitive cluster versions to the public internet.