Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 78 ยท Getting Started

The Kubernetes API, Resources and Versions

Understand API groups, versions, kinds versus resources, REST paths, custom resources and how deprecations remove old apiVersions, with a router in Python.

Kubernetes is, at heart, a REST API with a very good database behind it. Every object you have seen so far, and every one you will meet later, is a resource with a URL. Understanding how the API is organised explains the odd-looking apiVersion: apps/v1 line, why kubectl get po and kubectl get pods are the same, and why upgrading a cluster can suddenly break an old manifest.

This lesson covers groups, versions, the difference between a kind and a resource, the URL scheme, custom resources and the deprecation policy. The runnable stand-in turns a manifest into the REST path the real API server would use.

Anatomy of apiVersion

Group apps, batch, networking.k8s.io.
Version v1, v1beta1, v2.
Kind Deployment, Job, Ingress.

The core group has no name, so its apiVersion is just v1.

1 / 2

Groups, versions and kinds

The API is split into API groups so that parts can evolve independently. The group is part of the apiVersion, in the form group/version:

apiVersion Group Example kinds
v1 core (empty name) Pod, Service, ConfigMap, Secret, Namespace, Node
apps/v1 apps Deployment, ReplicaSet, StatefulSet, DaemonSet
batch/v1 batch Job, CronJob
networking.k8s.io/v1 networking.k8s.io Ingress, NetworkPolicy
rbac.authorization.k8s.io/v1 rbac.authorization.k8s.io Role, ClusterRole, RoleBinding
autoscaling/v2 autoscaling HorizontalPodAutoscaler

The version tells you how mature the group is. v1alpha1 is experimental, usually disabled by default and may be dropped without notice. v1beta1 is more reliable but can still change. A plain v1, v2 is stable: it will be supported for a long time. The same group can serve several versions at once, and the API server converts between them when you read or write.

A kind is the name of the type, written with a capital letter (Deployment) and used in manifests. A resource is the plural, lowercase collection name that appears in URLs and in kubectl (deployments). The kind is the type; the resource is the endpoint that serves it. Usually they differ only by case and a plural, but a few break the pattern: Ingress becomes ingresses, NetworkPolicy becomes networkpolicies, Endpoints stays endpoints.

Some resources have subresources, extra endpoints below the object: pods/log for logs, pods/exec for exec, deployments/scale for scaling, */status for the status. RBAC rules (a later lesson) refer to them by name.

You can list everything your cluster serves:

Terminal
kubectl api-resources
kubectl api-resources --api-group=apps
kubectl api-versions
kubectl explain deployment --api-version=apps/v1

REST paths

Every resource has a predictable URL. The API server splits resources into cluster-scoped (Nodes, Namespaces, PersistentVolumes) and namespaced (almost all others).

TEXT
/api/v1/nodes                                        core, cluster-scoped
/api/v1/namespaces/shop/pods                         core, namespaced collection
/api/v1/namespaces/shop/pods/web-1                   one pod
/api/v1/namespaces/shop/pods/web-1/log               subresource
/apis/apps/v1/namespaces/shop/deployments            named group
/apis/apps/v1/namespaces/shop/deployments/web/scale  subresource

The core group lives under /api/v1; every named group lives under /apis/<group>/<version>. You can watch kubectl use these paths by raising its verbosity, and you can call them yourself through a local proxy:

Terminal
kubectl get pods -n shop -v=6
kubectl proxy --port=8001 &
curl http://127.0.0.1:8001/apis/apps/v1/namespaces/shop/deployments

HTTP verbs map onto the operations you know: GET reads (add ?watch=true to stream changes), POST creates, PUT replaces, PATCH changes parts, DELETE removes.

A router in Python

The following stand-in implements the rule above. It maps an apiVersion, kind and namespace to a REST path using a small table, including the irregular plurals and the cluster-scoped kinds. The table is a simplified model of what the real API server learns from its discovery documents.

Python From manifest to REST path

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the Deployment without a namespace lands in default, and that Node and ClusterRole have no namespaces segment at all.

Custom resources

Kubernetes is extensible: you can teach the API server new kinds with a CustomResourceDefinition (CRD). After you create one, a new group and resource appear, with the same URL scheme, kubectl support and RBAC as built-in objects. Tools like Argo CD, cert-manager and database operators work this way. A custom resource may look like this:

YAML
apiVersion: shop.example.com/v1alpha1
kind: Backup
metadata:
  name: nightly
spec:
  schedule: "0 2 * * *"
  target: orders-db

The server would then serve /apis/shop.example.com/v1alpha1/namespaces/default/backups. Custom Resources and Operators shows how to build them. The router above would handle it after one more entry in the registry, which is exactly what applying a CRD does.

Versions, deprecation and removal

Kubernetes ships a new minor version roughly three times a year, and APIs have a formal lifecycle. A beta version is deprecated when a newer version of the same API is available, and a removed version stops being served by the API server in a later release. Stable (v1) APIs are deprecated only with at least twelve months or three releases of notice, whichever is longer, and removed rarely.

Well-known removals have broken real clusters. For example, extensions/v1beta1 and apps/v1beta1 Deployments disappeared in Kubernetes 1.16, and networking.k8s.io/v1beta1 Ingress went away in 1.22; manifests using them still exist in old blog posts and Helm charts. The fix is always to move to the stable version, which usually needs small schema changes too (Ingress in v1 requires a pathType).

Check what a manifest or cluster uses before upgrading:

Terminal
kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis
kubectl convert -f old-ingress.yaml --output-version networking.k8s.io/v1
kubectl apply --dry-run=server -f manifests/
Python Which manifests break on upgrade?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

This is the principle behind tools such as kubent and pluto, which scan your manifests and live objects before an upgrade. The removal table in this stand-in is a small sample, not a complete list.

Do not copy manifests from old articles without checking their apiVersion. If kubectl apply says no matches for kind "Ingress" in version "extensions/v1beta1", the cluster no longer serves that version.

Talking to the API server from outside: kubectl proxy and REST

Everything kubectl does is an HTTPS call, so you can make the same calls with curl or a library. The easiest bridge is kubectl proxy, which listens on your machine, adds your credentials from the kubeconfig and forwards requests to the API server:

Terminal
kubectl proxy --port=8001 &
curl -s http://127.0.0.1:8001/api/v1/namespaces/default/pods | head
curl -s http://127.0.0.1:8001/version

No token is needed on the curl side, because the proxy supplies it. For that reason the proxy listens on 127.0.0.1 only by default. Never start it with --address 0.0.0.0 on a shared network, because anyone who can reach the port acts with your permissions.

Create, read and delete a Pod over REST

Create the Pod by POSTing JSON to the collection URL:

Terminal
curl -s -X POST \
  -H 'Content-Type: application/json' \
  --data '{"apiVersion":"v1","kind":"Pod","metadata":{"name":"demo"},
           "spec":{"containers":[{"name":"c","image":"nginx:1.27"}]}}' \
  http://127.0.0.1:8001/api/v1/namespaces/default/pods

curl -s http://127.0.0.1:8001/api/v1/namespaces/default/pods/demo
curl -s -X DELETE http://127.0.0.1:8001/api/v1/namespaces/default/pods/demo

The verbs and status codes follow ordinary REST:

Action Request Success Common failures
Create POST /api/v1/namespaces/N/pods 201 Created 409 already exists, 422 invalid object
List GET /api/v1/namespaces/N/pods 200 403 forbidden
Read one GET .../pods/NAME 200 404 not found
Replace PUT .../pods/NAME 200 409 conflict (stale resourceVersion)
Patch PATCH .../pods/NAME with Content-Type: application/merge-patch+json (or strategic-merge-patch+json, json-patch+json) 200 422
Delete DELETE .../pods/NAME 200 404

Failures come back as a Status object with a reason (AlreadyExists, NotFound, Forbidden, Conflict) and a message. Useful query parameters: labelSelector=app%3Dweb, fieldSelector=status.phase%3DRunning, limit and continue for paging, and watch=true to stream changes as they happen (this is what controllers use). The stand-in below implements a tiny part of that API for Pods, so you can see the codes:

Python A tiny Pod REST API

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

You can also let kubectl do the authentication and send a raw request, which is handy for health endpoints and for exploring the API tree:

Terminal
kubectl get --raw /api/v1/namespaces/default/pods | head
kubectl get --raw '/readyz?verbose'
kubectl get --raw /openapi/v3          # list of OpenAPI documents, one per group version
kubectl auth can-i create pods -n default

Without the proxy: tokens and the real address

A program that is not on your laptop has to authenticate itself. The usual recipe is a ServiceAccount token and the API server's address and CA certificate:

Terminal
APISERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
TOKEN=$(kubectl create token default -n default)     # a short-lived token (Kubernetes 1.24+)
curl -s --cacert ca.crt -H "Authorization: Bearer $TOKEN" "$APISERVER/api/v1/namespaces/default/pods"

Inside a Pod, the same pieces are mounted for you: the API server is https://kubernetes.default.svc, the token is in /var/run/secrets/kubernetes.io/serviceaccount/token, and the CA is ca.crt in the same directory. What the token may do is decided by RBAC: a request that RBAC does not allow returns 403 Forbidden with the message that names the user, verb and resource (RBAC, Service Accounts). Give programs the smallest Role that works.

Client libraries

You rarely write raw HTTP in applications. Official and community client libraries handle authentication (kubeconfig or in-cluster), JSON, retries and watches:

Language Library
Go client-go (what kubectl and controllers use)
Python kubernetes
Java kubernetes-client/java, Fabric8
JavaScript / TypeScript @kubernetes/client-node
.NET KubernetesClient

A Python client reads like the REST calls above (read-only example, it needs a cluster):

Python
from kubernetes import client, config

config.load_kube_config()            # or config.load_incluster_config() inside a Pod
v1 = client.CoreV1Api()
for pod in v1.list_namespaced_pod("default").items:
    print(pod.metadata.name, pod.status.phase)

Use a library with informers (a cached watch) instead of polling the list endpoint, and respect the API server's rate limits. The patterns for controllers built this way are in Custom Resources and Operators and Controllers and Reconciliation.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What group does the apiVersion v1 belong to?

    Core objects such as Pod, Service and ConfigMap live in the unnamed core group, so their apiVersion has no slash. Their URLs start with /api/v1.
  2. 2. What is the relationship between a kind and a resource?

    Kinds appear in manifests; resources are the REST endpoints and what kubectl uses, usually the lowercase plural, with a few irregular cases.
  3. 3. Which URL lists the Deployments in the namespace shop?

    Deployments belong to the named group apps, so the path starts with /apis/apps/v1. Core resources use /api/v1.
  4. 4. A manifest uses networking.k8s.io/v1beta1 for an Ingress and fails on a new cluster. What is the correct fix?

    Removed beta versions are not served at all. Migrate to the stable version, noting schema changes such as the required pathType.

Summary

  • apiVersion is group/version, and the core group is written as just v1.
  • A kind is the type name in manifests; a resource is its plural REST endpoint; subresources such as pods/log hang below it.
  • Core resources are served under /api/v1, named groups under /apis/<group>/<version>, and namespaced ones include /namespaces/<ns>.
  • CRDs add new groups and kinds with the same machinery.
  • Beta APIs are removed after deprecation, so check manifests before upgrades. The router and checker above are simplified stand-ins.

Next, start building workloads with the smallest unit in Kubernetes: Pods.