APIs & Access

The Kubernetes API is the foundation of everything in Kubernetes. Understanding how to access and interact with the API is essential because every operation—creating pods, listing services, updating deployments—goes through the API. Whether you use kubectl, write code with client libraries, or integrate with CI/CD systems, you’re using the Kubernetes API.

Think of the Kubernetes API like a restaurant’s ordering system. You (the client) place orders (API requests), the system (API server) processes them, and you get your food (resources). Just as you can order in different ways (phone, app, in-person), you can access Kubernetes in different ways (kubectl, client libraries, REST API directly).

What is the Kubernetes API?

The Kubernetes API is a RESTful API that exposes the functionality of the Kubernetes control plane. It’s the interface through which all interactions with Kubernetes happen:

• Creating resources - Pods, services, deployments, etc.
• Reading resources - Getting information about cluster state
• Updating resources - Modifying existing resources
• Deleting resources - Removing resources from the cluster
• Watching resources - Getting notified of changes

Everything in Kubernetes is represented as an API object, and the API is the only way to interact with these objects.

RESTful API Principles

Kubernetes follows REST (Representational State Transfer) principles:

Resources as URLs

Each resource type has a URL path:

• /api/v1/pods - Pods in core API group
• /apis/apps/v1/deployments - Deployments in apps API group
• /api/v1/namespaces - Namespaces

HTTP Methods

Standard HTTP methods map to operations:

• GET - Retrieve resources
• POST - Create resources
• PUT - Update resources (replace)
• PATCH - Update resources (partial)
• DELETE - Delete resources

Stateless

Each request is independent—the API server doesn’t maintain session state between requests.

API Structure

API Groups

The Kubernetes API is organized into groups:

• Core API (/api/v1) - Fundamental resources (pods, services, nodes)
• Named API Groups (/apis/<group>/<version>) - Extended resources (deployments, ingresses, CRDs)

API Versions

Each API group has versions:

• v1 - Stable version (production-ready)
• v1beta1, v1alpha1 - Beta/alpha versions (may change)

Resource Paths

Resources are accessed via paths:

/api/v1/namespaces/{namespace}/pods/{name}
/apis/apps/v1/namespaces/{namespace}/deployments/{name}

How Everything is an API Object

In Kubernetes, everything is an API object:

• Pods - API objects representing running containers
• Services - API objects representing network services
• Deployments - API objects representing application deployments
• Nodes - API objects representing worker machines
• Everything else - All resources are API objects

This uniform model makes Kubernetes predictable and programmable.

API Access Methods

There are several ways to access the Kubernetes API:

kubectl (Command Line)

The most common way to interact with Kubernetes:

# Create a pod
kubectl create -f pod.yaml

# Get pods
kubectl get pods

# Update a deployment
kubectl apply -f deployment.yaml

# Delete a resource
kubectl delete pod my-pod

kubectl translates commands into API requests and handles authentication, formatting, and error handling.

Client Libraries

Programmatic access using client libraries:

• client-go (Go) - Official Kubernetes client library
• kubernetes-client (Python) - Python client
• kubernetes-client (Java) - Java client
• kubectl (JavaScript) - Node.js client

These libraries provide type-safe, language-specific interfaces to the API.

REST API Directly

Direct HTTP requests to the API server:

# Using curl
curl -X GET https://api-server/api/v1/pods \
  --header "Authorization: Bearer $TOKEN" \
  --cacert ca.crt

Less common but useful for integration with systems that don’t have Kubernetes clients.

Web UI (Dashboard)

Web-based interfaces that use the API:

• Kubernetes Dashboard
• Lens
• Octant

These provide visual interfaces but ultimately use the API.

Authentication and Authorization

Authentication

The API server authenticates requests to verify identity:

• Client certificates - X.509 certificates
• Bearer tokens - JWT tokens (ServiceAccounts)
• Basic auth - Username/password (deprecated)

Authorization

After authentication, the API server authorizes requests using RBAC:

• Roles - Define what actions are allowed
• RoleBindings - Bind roles to users/groups
• ClusterRoles - Cluster-wide permissions
• ClusterRoleBindings - Cluster-wide bindings

API Request Flow

1. Client sends request - kubectl, client library, or direct HTTP
2. Authentication - API server verifies identity
3. Authorization - API server checks permissions
4. Admission control - Mutating/validating webhooks apply policies
5. API processing - API server processes request
6. etcd interaction - Reads from or writes to etcd
7. Response - API server returns response to client

API Discovery

Clients can discover available APIs:

• API groups - List of available API groups
• API resources - List of resources in each group
• API versions - Available versions for each group
• OpenAPI schema - Complete API specification

This allows clients to dynamically discover what’s available without hardcoding.

Topics

• API Groups & Versions - Understanding API organization and versioning
• Discovery & OpenAPI - How clients discover available APIs
• Clients: kubectl & client-go - Tools and libraries for API access

Key Takeaways

• The Kubernetes API is RESTful and is the only way to interact with Kubernetes
• Everything in Kubernetes is an API object
• The API is organized into groups and versions
• Access methods include kubectl, client libraries, and direct REST calls
• All requests go through authentication, authorization, and admission control
• Clients can discover available APIs dynamically

See Also

• API Objects - Understanding API objects
• Control Plane Components - How the API server works
• RBAC - Controlling API access
• Getting Started Guide - Practical API usage