Kubernetes Is About APIs, Not Containers: Understanding the API Framework and CRDs

Introduction – The article links several previous posts and argues that the core value of Kubernetes is its universal, vendor‑agnostic, declarative API framework, not the container runtime.

1.1 Containers are the foundation – In 2013 a simple docker run postgres command amazed developers and opened the door to agile infrastructure, leading to widespread container adoption.

1.2 The API is the core – Kubernetes provides a standard programming interface (API) for software‑defined infrastructure. It defines a Specification + Implementation model, where resources are typed, watched, and reconciled by controllers. Before Kubernetes, cloud services were a heterogeneous mix of vendor‑specific APIs; Kubernetes unified them under a common API schema.

1.3 Summary – While the API framework is not perfect, its ubiquity, tooling, and vendor support make it the decisive factor for Kubernetes’s success.

2. Kubernetes API Types

2.1 Standard API (built‑in resources) – Namespaced resources (e.g., pods , services , networkpolicies ) use the URL pattern /api/{version}/namespaces/{namespace}/{resource} . Un‑namespaced resources (e.g., nodes , clusterroles ) use /api/{version}/{resource} .

2.2 Extension API (apiextensions) – Namespaced: /apis/{apiGroup}/{apiVersion}/namespaces/{namespace}/{resource} . Un‑namespaced: /apis/{apiGroup}/{apiVersion}/{resource} .

2.3 CRD (Custom Resource Definition) – Allows users to declare arbitrary resources (databases, task runners, message buses, certificates, etc.) and have Kubernetes automatically generate the corresponding API.

3. Intuitive Analogy: Kubernetes as a Database, CRD as a Table, API as SQL

Just like a relational database, a Kubernetes cluster is a database; each Kind is a table; each property is a column; each resource instance is a row. The article provides a concrete CRD example named Fruit with fields name , sweet , and weight .

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: fruits.example.org
spec:
  conversion:
    strategy: None
  group: example.org
  names:
    kind: Fruit
    listKind: FruitList
    plural: fruits
    singular: fruit
  scope: Namespaced
  versions:
  - name: v1
    schema:
      openAPIV3Schema:
        properties:
          spec:
            properties:
              comment:
                type: string
              sweet:
                type: boolean
              weight:
                type: integer
            type: object
        type: object
    served: true
    storage: true
    additionalPrinterColumns:
    - jsonPath: .spec.sweet
      name: sweet
      type: boolean
    - jsonPath: .spec.weight
      name: weight
      type: integer
    - jsonPath: .spec.comment
      name: comment
      type: string

Creating the CRD corresponds to CREATE TABLE fruits … . Sample CR instances:

apiVersion: example.org/v1
kind: Fruit
metadata:
  name: apple
spec:
  sweet: false
  weight: 100
  comment: little bit rotten

apiVersion: example.org/v1
kind: Fruit
metadata:
  name: banana
spec:
  sweet: true
  weight: 80
  comment: just bought

kubectl commands map to SQL operations:

Create CRD: kubectl create -f fruits-crd.yaml → CREATE TABLE fruits …

Create CR: kubectl create -f apple-cr.yaml → INSERT INTO fruits …

Query CR: kubectl get fruits → SELECT * FROM fruits

Delete CR: kubectl delete fruit apple → DELETE FROM fruits WHERE name='apple'

3.3 API is SQL – The underlying API calls can be inspected with high log levels, showing the exact HTTP request bodies sent to the API server.

$ kubectl create -v 10 -f apple-cr.yaml
Request Body: {"apiVersion":"example.org/v1","kind":"Fruit","metadata":{"name":"apple","namespace":"default"},"spec":{"comment":"little bit rotten","sweet":false,"weight":100}}

4. Other Topics

4.1 Labeling CRs – CRs can be labeled and filtered by label, just like built‑in resources.

4.2 RBAC – Both built‑in and extended APIs are protected by Kubernetes RBAC. References are provided for deeper study.

References include the original articles "Kubernetes isn’t about containers" (2021), "Kubernetes is a Database" (2019), "CRD is just a table in Kubernetes" (2020), and a guide on cracking the Kubernetes RBAC model (2022).