Understanding Kubernetes API Fundamentals

Welcome to the practical part! Before we write a single line of Go code to talk to Kubernetes, it's crucial to understand what we're talking to. At its heart, Kubernetes is driven entirely by its API. Everything you do, whether via kubectl, a dashboard, or custom automation, ultimately interacts with this central API server. Think of the Kubernetes API server as the brain and gatekeeper of your cluster.

In this first chapter, we'll lay the groundwork by understanding the API's structure and then write our very first Go program to connect to it.

Understanding Kubernetes API Fundamentals

The Kubernetes API is designed around RESTful principles. If you've worked with web APIs before, this should feel somewhat familiar. What does "RESTful" mean in this context?

  1. Resource-Oriented: Everything in Kubernetes is treated as an API Resource – Pods, Services, Deployments, Nodes, Secrets, ConfigMaps, NetworkPolicies, etc. You interact with these resources.

  2. Standard HTTP Verbs: You use standard HTTP methods (verbs) to perform actions on these resources:

    • GET: Retrieve a resource or list resources.

    • POST: Create a resource.

    • PUT: Update/replace an existing resource.

    • PATCH: Partially update an existing resource.

    • DELETE: Delete a resource.

    • WATCH: (Via WebSockets/streaming GET) Monitor resources for changes in real-time.

  3. Stateless: Each request from the client (our Go program) to the API server should contain all the information needed to understand and process the request.

Understanding this RESTful nature is key because it dictates how we structure our interactions, whether using curl, kubectl, or our Go client-go library.

API Structure: Groups, Versions, and Kinds/Resources

Kubernetes doesn't just throw all resource types into one giant bucket. To keep things organized, extensible, and versioned, the API is structured using three main concepts:

  1. API Groups: A collection of related API types. Groups help avoid name collisions and allow Kubernetes to be extended easily. Think of them like namespaces for API types. Some common examples include:

    • The core (or legacy) group: Often represented by an empty string ("") in API definitions but accessed via the /api path. Contains fundamental objects like Pod, Service, Node, Namespace, Secret, ConfigMap.

    • apps: Contains workload-related objects like Deployment, StatefulSet, DaemonSet.

    • networking.k8s.io: Contains networking objects like Ingress and NetworkPolicy.

    • rbac.authorization.k8s.io: For role-based access control objects.

    • Many others, including custom ones you can define yourself (CRDs)!

  2. Versions: Each API Group has one or more versions (e.g., v1, v1beta1, v2alpha1). Versions allow the API structure for a resource type to evolve over time without breaking compatibility.

    • v1: Generally indicates a stable API.

    • vXbetaY: Beta versions, potentially with minor changes before stabilization. Use with caution in production, but often necessary.

    • vXalphaY: Alpha versions, experimental, may change or be removed without notice. Avoid in production.

    • Our client-go code will need to specify which Group and Version of a resource we want to work with.

  3. Kinds & Resources:

    • Kind: This is the specific type of object you're dealing with, written in CamelCase (e.g., Pod, Service, Deployment, NetworkPolicy). You'll see the kind: field prominently in Kubernetes YAML manifests.

    • Resource: This is the lowercase, usually plural name used to refer to the collection of objects of a specific Kind within the API URL path (e.g., pods, services, deployments, networkpolicies). The mapping is usually straightforward (Kind Pod -> Resource pods), but not always guaranteed.

Putting It Together: The API Path

These three components combine to form the path for accessing resources via the REST API. The general structure looks like this:

  • For the core group: /api/VERSION/resource

  • For named groups: /apis/GROUP/VERSION/resource

Examples:

# List all Pods in the core group, version v1
GET /api/v1/pods

# Get a specific Pod named 'my-app-pod' in the 'default' namespace
GET /api/v1/namespaces/default/pods/my-app-pod

# List all Deployments in the 'apps' group, version v1
GET /apis/apps/v1/deployments

# Get a specific NetworkPolicy named 'allow-frontend' in the 'production' namespace
GET /apis/networking.k8s.io/v1/namespaces/production/networkpolicies/allow-frontend

# List all Nodes (cluster-scoped resource, no namespace)
GET /api/v1/nodes

Namespacing

Notice the /namespaces/{namespace} part in some paths. Most Kubernetes resources (like Pods, Services, Deployments, NetworkPolicies) are namespaced, meaning they exist within a specific logical boundary called a Namespace. This helps organize resources and control access. Some resources, however, are cluster-scoped (like Nodes, Namespaces themselves, ClusterRoles) and don't belong to a namespace. Their API paths won't include the /namespaces/{namespace} segment.

Why Does This Matter for Go?

While client-go will provide convenient functions that abstract away some of the raw HTTP path construction, understanding this underlying structure (Group, Version, Kind/Resource, Namespace) is absolutely fundamental. It helps you:

  • Know which part of the client-go library to use (e.g., the CoreV1 client, the AppsV1 client, the NetworkingV1 client).

  • Debug issues when interacting with the API.

  • Understand API discovery and how clients find available resources.

  • Read and interpret Kubernetes API documentation effectively.

Okay, that's the theory of the API structure. Next, let's look at how our Go program can actually authenticate and establish a connection to start making these API calls.

PreviousWelcomeNextIn-Cluster vs Out-of-Cluster Auth Configuration

Last updated

Was this helpful?