Skip to content
LoveOps Docs

K8s API

1. The Anatomy of an API Endpoint

Every interaction with Kubernetes goes through the kube-apiserver. The endpoint structure is strictly defined to organize chaos.

The Base Structure: [HOST]:[PORT] / [API_PATH] / [API_GROUP] / [VERSION] / namespaces / [NAMESPACE] / [RESOURCE]

The Two Path Splits:

  • The Core Group (/api): The legacy foundation. It lacks a named group in the URL. Example: /api/v1/pods (Contains Pods, Namespaces, Nodes, Secrets, ConfigMaps).
  • The Named Groups (/apis): The modern standard for organization. All new features go here. Example: /apis/apps/v1/deployments. (Groups include apps, networking.k8s.io, rbac.authorization.k8s.io).

2. The Versioning Madness Decoded

Kubernetes uses versions to evolve objects without instantly breaking existing clusters.

  • Alpha (v1alpha1): Experimental. Disabled by default. Buggy, lacks end-to-end tests, and can be deleted without warning. To enable: You must manually edit the kube-apiserver manifest and add the runtime-config flag with the specific API group.
  • Beta (v1beta1): Stable-ish. Enabled by default. It has tests, but minor bugs may exist. The project commits to eventually making it GA.
  • GA / Stable (v1): Rock solid. Enabled by default. Part of conformance tests and highly reliable.

3. Preferred vs. Storage Versions (The “Under the Hood” Logic)

A single cluster can simultaneously support multiple versions of the exact same object (e.g., v1, v1beta1, v1alpha1). You can submit a YAML file using any of those enabled versions.

However, the API server enforces strict rules to prevent database corruption:

  • The Preferred Version: The default version the API responds with when you run kubectl get or query an endpoint.
  • The Storage Version: The single format actually written to the etcd database. If you submit a v1beta1 YAML, the API server transparently converts it into the Storage Version (e.g., v1) before saving it to etcd.

4. The API Deprecation Policy (Pure Constraints)

To prevent chaos during upgrades, K8s enforces a strict lifecycle.

  • Rule 1 (Evolution): An API element can only be removed by incrementing the API version (e.g., you can drop a field in v1alpha2, but it must remain in v1alpha1).
  • Rule 2 (No Data Loss): Objects must perfectly round-trip between versions during conversion. If v2 introduces a new field, v1 must have a dummy equivalent added so data isn’t destroyed when the API server translates between the two.
  • Rule 3 (Hierarchy): An unstable version (Alpha) can never deprecate a stable version (GA).
  • Rule 4 (Survival): After an API is officially announced as deprecated, it cannot be immediately deleted.
    • GA (v1): Must survive for 12 months or 3 releases.
    • Beta (v1beta1): Must survive for 9 months or 3 releases.
    • Alpha: 0 releases. It dies instantly.

(Admin Tip: Use the kubectl-convert plugin to automatically translate your old deprecated YAML files into the new supported versions.)

5. Accessing the API via Windows + Docker Desktop

If you attempt to curl the API server directly, you will be rejected with an unauthorized error. The API strictly requires TLS client certificates.

Here is how to bypass that securely using Docker Desktop on Windows.

The Misconception:

Do not confuse kube-proxy with kubectl proxy.

  • kube-proxy runs on worker nodes to route pod networking.
  • kubectl proxy is an HTTP interceptor you run on your local machine.

The Execution:

Docker Desktop automatically configures your C:\Users\<Name>\.kube\config file with the correct certificates to talk to its internal cluster.

  1. Open PowerShell / Command Prompt.

  2. Start the proxy: kubectl proxy --port=8080

    (Logic: This spins up a local web server. It reads your Docker Desktop certificates from the .kube/config file.)

  3. Open a second terminal window.

  4. Query the API without certificates: curl http://127.0.0.1:8080/api/v1/pods

    (Logic: You send a raw, unauthenticated HTTP request to localhost. The kubectl proxy intercepts it, attaches the complex Docker Desktop TLS certificates, forwards it to the real API server via HTTPS, and hands you back the JSON.)

6. OpenAPI and Discovery (How kubectl works)

kubectl is not magic. It is a dumb client that reads the API to figure out what to do.

  • Discovery API (/api and /apis): When you run a command, kubectl hits these root endpoints to get a map of every Group, Version, and Resource the cluster currently supports.
  • OpenAPI (/openapi/v3): This endpoint provides the raw JSON schema. It tells kubectl exactly what fields are allowed in a deployment, which are integers, and which are strings. (OpenAPI v3 is the modern, lossless standard; v2 drops certain complex validation rules).