Introduction

Kubernetes, a powerful container orchestration platform, offers a rich set of functionalities through its API (Application Programming Interface). To effectively utilize Kubernetes' capabilities, it's crucial to comprehend its API structure, which includes API groups and versions. In this article, we'll explore the types of API groups in Kubernetes, alongside examples to illustrate their significance, while also delving into API versions for a comprehensive understanding.

Types of API Groups

API groups in Kubernetes categorize related resources under specific endpoints within the API server. Understanding the types of API groups helps in organizing and managing Kubernetes resources effectively.

Core API Group (/api/v1):
- The core API group in Kubernetes encompasses essential resources that are fundamental for cluster operation.
- Resources within the core API group are standardized and maintained by the Kubernetes project, ensuring consistency and reliability.
- Core resources include Pods, Services, Namespaces, ConfigMaps, and others that form the backbone of Kubernetes cluster management.
Named API Group (/apis/{group}/{version}):
- Named API groups are custom groups created by users to extend Kubernetes with additional resources and functionalities beyond the core API group.
- Users can define their API groups under the /apis endpoint, specifying a unique group name and version.
- Resources within named API groups are tailored to specific use cases or organizational requirements, providing flexibility and customization options.

Why there are named groups and core groups

Kubernetes doesn’t put all its eggs in one basket. Instead, it smartly categorizes its API into different groups based on their purpose. Kubernetes organizes its features into different groups, kind of like how a library has sections for different types of books. These groups help keep things organized and make it easier for developers to find what they need.

The core group includes important features that Kubernetes needs to run properly, like Pods, Nodes, Namespaces, and Services. These features are so essential that they're considered the backbone of Kubernetes.

Named groups, also called namespaces, are used to group related features together based on their function. For example, all the features related to networking are grouped under networking.k8s.io. This makes it easier to add new features and customize Kubernetes for specific needs, like networking or storage.

The core group API endpoint is located at /api/v1*. On the other hand, the **named groups API endpoint is /apis/$GROUP_NAME/$VERSION**.*

Example and Scenario

A. Core Group

The core group is where all core functionality exists. Such as namespaces, PODs, replication controllers, events, endpoints, nodes, bindings, Persistent volumes, persistent volume claims, configmaps, secrets, services, etc.

The core group’s API endpoint is located at /api/v1.

/api/v1

apiVersion field in the manifest file:

The core group is not specified as part of the apiVersion field.

apiVersion: v1

Core API Group Example: Suppose you want to deploy a basic web application represented by a Pod in Kubernetes.

Manifest File for Pod Resource:

apiVersion: v1
kind: Pod
metadata:
  name: my-web-app
spec:
  containers:
  - name: my-container
    image: my-web-image:latest

In this scenario:

You interact with the core API group (/api/v1) to create a Pod, a fundamental resource for running containerized workloads in Kubernetes.
The Pod resource is part of the core API group and is represented by the API version v1, indicating its standardization and essential nature in Kubernetes cluster management.

B. Named Group

The named group API in Kubernetes is more organized and groups resource thematically.

It includes groups for apps, extensions, networking, storage, authentication, authorization certificates, and more.

Going forward, all newer features will be made available to these named groups. The named groups allow for the extension of Kubernetes functionality by introducing custom resources and controllers tailored to specific areas, such as networking or storage.

The named groups API is located at /apis/$GROUP_NAME/$VERSION.

$GROUP_NAME : the name of your custom resource
$VERSION: the API version of your custom resource.

/apis/$GROUP_NAME/$VERSION

The named group is identified by the $GROUP_NAME included in the apiVersion field.

apiVersion: $GROUP_NAME/$VERSION

Resources:

The resources in named groups depend on the specific named group that is being used. The following are some examples of named groups in Kubernetes and their associated resources:

apps: Deployments, ReplicaSets, StatefulSets, DaemonSets, and DeploymentsRollback.
extensions: Ingresses, NetworkPolicies, and PodSecurityPolicies.
batch: CronJobs and Jobs.
storage.k8s.io: StorageClasses and VolumeAttachments.
policy: PodDisruptionBudgets.

Named API Group Example: Let's imagine we're creating a Kubernetes custom resource for managing game servers within a game called "SpaceBattle".

First, we'll define a Custom Resource Definition (CRD) for the GameServer resource. We'll give the custom resource a named API group called game.spacebattle.io.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: gameservers.game.spacebattle.io
spec:
  group: game.spacebattle.io
  names:
    kind: GameServer
    listKind: GameServerList
    plural: gameservers
    singular: gameserver
  ...

In this CRD definition:

group: game.spacebattle.io specifies the named API group as game.spacebattle.io.
kind: GameServer specifies the singular name of the custom resource.
listKind: GameServerList specifies the name of the resource list.
plural: gameservers specifies the plural name of the resource.
singular: gameserver specifies the singular name of the resource.

Now that we've defined the GameServer custom resource with the named API group game.spacebattle.io, we can use it to manage game servers within the "SpaceBattle" game.

Here's how you might create an instance of a GameServer resource:

apiVersion: game.spacebattle.io/v1
kind: GameServer
metadata:
  name: spacebattle-server-1
spec:
  gameMode: "Team Deathmatch"
  map: "Space Station"
  maxPlayers: 10
  ...

In this example, we're creating a GameServer resource with the name "spacebattle-server-1" running in "Team Deathmatch" mode on the "Space Station" map with a maximum of 10 players.

By using named API groups, game developers can extend Kubernetes to manage game-related resources such as game servers, matches, leaderboards, etc., in a standardized way within their Kubernetes cluster, providing scalability and flexibility for managing game infrastructure.

Conclusion

Understanding Kubernetes API groups and versions is essential for effective cluster management. The use of core and named groups, along with the ability to enable or disable API groups, provides a flexible and extensible framework for interacting with the Kubernetes API.

By grasping these concepts, developers, and administrators can effectively navigate and leverage the rich functionality offered by the Kubernetes API.

Saurabh Adhau's Blog