API Groups, Domains, and Versioning

Understanding how Kubernetes organizes and names its APIs through domains, groups, and versioning is crucial for working with custom resources and API extensions.

API vs Group: Key Differences

API (Application Programming Interface)

Definition: The complete interface for interacting with Kubernetes
Scope: Encompasses all endpoints, operations, and resources
Example: The entire Kubernetes API includes all groups, versions, and resources

Group (API Group)

Definition: A logical namespace within the API for organizing related resources
Scope: A subset of the API containing related resource types
Example: The apps group contains Deployments, ReplicaSets, DaemonSets

Visual Hierarchy

Kubernetes API
├── Core Group (v1)
│   ├── Pod
│   ├── Service
│   └── ConfigMap
├── apps Group
│   ├── v1
│   │   ├── Deployment
│   │   ├── ReplicaSet
│   │   └── DaemonSet
│   └── v1beta1 (deprecated)
├── batch Group
│   ├── v1
│   │   └── Job
│   └── v1beta1
│       └── CronJob
└── networking.k8s.io Group
    └── v1
        ├── NetworkPolicy
        └── Ingress

API Group Structure

Kubernetes APIs are organized hierarchically:

Core APIs (Legacy)

Domain: No domain (empty string)
Group: No group (empty string)
Examples: pods, services, configmaps, secrets
Full API Path: /api/v1/pods

Named API Groups

Domain: Usually a reverse domain name
Group: Logical grouping of related resources
Examples: apps/v1, networking.k8s.io/v1, rbac.authorization.k8s.io/v1
Full API Path: /apis/{group}/{version}/{resource}

Domain Name Conventions

Built-in Kubernetes Domains

# Core Kubernetes APIs
k8s.io                    # Main Kubernetes domain
kubernetes.io            # Legacy domain (being phased out)
x-k8s.io                 # Experimental features

# Specific API categories
networking.k8s.io        # Network-related APIs
rbac.authorization.k8s.io # RBAC APIs
storage.k8s.io           # Storage APIs
admissionregistration.k8s.io # Admission controllers
apiextensions.k8s.io     # Custom Resource Definitions

Custom Domains

# Company/organization domains
mycompany.com
acme.corp
example.org

# Project-specific domains
istio.io
knative.dev
prometheus.io

API Versioning Scheme

Kubernetes uses a structured versioning scheme for APIs, including custom resources.

Version Format

{API Level}{Stability Level}{Version Number}

Components Breakdown

API Level

v1 = Version 1 (most common)
v2 = Version 2
v3 = Version 3, etc.

Stability Levels

Level	Description	Use Case	Compatibility
`alpha`	Early development	Experimental features	⚠️ Breaking changes expected
`beta`	More stable	Testing environments	⚠️ Minor changes possible
`stable` (no suffix)	Production ready	Production use	✅ Backward compatibility guaranteed

Version Numbers within Stability

Alpha: alpha1, alpha2, alpha3, etc.
Beta: beta1, beta2, beta3, etc.
Stable: No additional number (just v1, v2, etc.)

Version Progression Examples

v1alpha1 → v1alpha2 → v1beta1 → v1beta2 → v1

Common API Versions

v1alpha1 = First alpha version (highly experimental)
v1alpha2 = Second alpha version (may have breaking changes from alpha1)
v1beta1 = First beta version (more stable, ready for testing)
v1beta2 = Second beta version (minor refinements)
v1 = First stable version (production ready)

Group Name Examples and Comparisons

Core Groups

Resource	API Group	Version	Full Name
Pod	"" (core)	v1	v1/Pod
Service	"" (core)	v1	v1/Service
Deployment	apps	v1	apps/v1/Deployment
StatefulSet	apps	v1	apps/v1/StatefulSet

Extended Groups

Resource	API Group	Version	Full Name
NetworkPolicy	networking.k8s.io	v1	networking.k8s.io/v1/NetworkPolicy
Ingress	networking.k8s.io	v1	networking.k8s.io/v1/Ingress
ClusterRole	rbac.authorization.k8s.io	v1	rbac.authorization.k8s.io/v1/ClusterRole
StorageClass	storage.k8s.io	v1	storage.k8s.io/v1/StorageClass

Breaking Down a Full API Name

Let’s analyze the full name: networking.k8s.io/v1/NetworkPolicy

Component Breakdown

networking.k8s.io/v1/NetworkPolicy
│              │ │  │
│              │ │  └── Resource Name (Kind)
│              │ └───── API Version
│              └──────── API Group
└─────────────────────── Domain

Detailed Parts

Domain: k8s.io - The top-level domain indicating this is a Kubernetes API
Group Prefix: networking - The functional area this API serves
API Group: networking.k8s.io - Complete group identifier
Version: v1 - API version (stable release)
Kind/Resource: NetworkPolicy - The specific resource type

Built-in API Groups

Group	Purpose	Example Resources
`apps`	Application workloads	Deployment, ReplicaSet, DaemonSet
`batch`	Batch processing	Job, CronJob
`networking.k8s.io`	Network policies	NetworkPolicy, Ingress
`rbac.authorization.k8s.io`	Security & permissions	Role, ClusterRole, RoleBinding
`autoscaling`	Auto-scaling	HorizontalPodAutoscaler
`storage.k8s.io`	Storage management	StorageClass, VolumeAttachment
`apiextensions.k8s.io`	API extensions	CustomResourceDefinition
`admissionregistration.k8s.io`	Admission control	ValidatingAdmissionWebhook
`certificates.k8s.io`	Certificate management	CertificateSigningRequest
`coordination.k8s.io`	Coordination primitives	Lease
`discovery.k8s.io`	Service discovery	EndpointSlice
`events.k8s.io`	Event handling	Event
`node.k8s.io`	Node management	RuntimeClass
`policy`	Pod policies	PodDisruptionBudget, PodSecurityPolicy
`scheduling.k8s.io`	Scheduling	PriorityClass

Custom Resource Example

CRD Definition

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.mycompany.com
spec:
  group: mycompany.com        # Custom domain
  versions:
  - name: v1
    served: true
    storage: true
  scope: Namespaced
  names:
    plural: databases
    singular: database
    kind: Database

Using the Custom Resource

apiVersion: mycompany.com/v1  # Custom group/version
kind: Database                # Custom kind
metadata:
  name: my-database
spec:
  engine: postgresql
  version: "13"

Operator API Examples

Operators are a common pattern in Kubernetes that extend the API with custom resources. Here are real-world operator API examples:

Database Operators

# PostgreSQL Operator (CloudNativePG)
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: postgres-cluster
spec:
  instances: 3
  postgresql:
    parameters:
      max_connections: "200"
  
# MySQL Operator (Oracle)
apiVersion: mysql.oracle.com/v2
kind: InnoDBCluster
metadata:
  name: mysql-cluster
spec:
  secretName: mysql-secret
  tlsUseSelfSigned: true
  instances: 3

Service Mesh Operators

# Istio Operator
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
  name: control-plane
spec:
  values:
    global:
      meshID: mesh1
      network: network1

# Linkerd Operator
apiVersion: linkerd.io/v1alpha2
kind: ServiceProfile
metadata:
  name: webapp
spec:
  routes:
  - name: api
    condition:
      method: GET
      pathRegex: "/api/.*"

Monitoring Operators

# Prometheus Operator
apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  name: prometheus-main
spec:
  serviceAccountName: prometheus
  serviceMonitorSelector:
    matchLabels:
      team: frontend

# Grafana Operator
apiVersion: integreatly.org/v1alpha1
kind: Grafana
metadata:
  name: grafana
spec:
  ingress:
    enabled: true
  config:
    auth:
      disable_login_form: false

GitOps Operators

# ArgoCD Operator
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook

# Flux Operator
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: GitRepository
metadata:
  name: podinfo
spec:
  interval: 30s
  ref:
    branch: master
  url: https://github.com/stefanprodan/podinfo

Certificate Management

# Cert-Manager Operator
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-tls
spec:
  secretName: example-com-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
  - example.com
  - www.example.com

# External Secrets Operator  
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: "https://vault.example.com"
      path: "secret"
      auth:
        kubernetes:
          mountPath: "kubernetes"
          role: "example"

Operator API Naming Analysis

Taking the PostgreSQL operator as an example: postgresql.cnpg.io/v1/Cluster

postgresql.cnpg.io/v1/Cluster
│         │    │  │  │
│         │    │  │  └── Resource Name (Kind)
│         │    │  └───── API Version (stable)
│         │    └──────── Top-level domain (.io)
│         └───────────── Organization (cnpg - CloudNativePG)
└─────────────────────── Technology focus (postgresql)

Common Operator Domains

.io - Most common for open source projects
.com - Commercial/enterprise operators
.dev - Development-focused tools
.k8s.io - Kubernetes SIG-maintained operators

Operator Versioning Patterns

# Alpha phase - rapid development
postgresql.cnpg.io/v1alpha1
postgresql.cnpg.io/v1alpha2

# Beta phase - stabilizing API
postgresql.cnpg.io/v1beta1  
postgresql.cnpg.io/v1beta2

# Stable phase - production ready
postgresql.cnpg.io/v1
postgresql.cnpg.io/v2       # Major version bump for breaking changes

API Discovery Commands

List API Groups

kubectl api-resources --api-group=""           # Core APIs
kubectl api-resources --api-group="apps"       # Apps group
kubectl api-resources --api-group="networking.k8s.io"  # Networking group

Get API Versions

kubectl api-versions | grep networking
kubectl api-versions | sort

Describe API Resource

kubectl explain deployment.apps
kubectl explain networkpolicy.networking.k8s.io

Available API groups

kubectl api-versions

Resources in a group

kubectl api-resources --api-group=apps
kubectl api-resources --api-group=networking.k8s.io

Preferred version for a group

kubectl api-versions | grep autoscaling
# Output: autoscaling/v1, autoscaling/v2, autoscaling/v2beta2
# v2 is typically the preferred stable version

Best Practices

Naming Conventions

Use reverse domain notation: mycompany.com not com.mycompany
Be descriptive: database.mycompany.com not db.mycompany.com
Avoid conflicts: Don’t use k8s.io or kubernetes.io domains
Use consistent versioning: Follow semantic versioning principles

Group Organization

# Good: Logical grouping
networking.mycompany.com     # Network-related resources
storage.mycompany.com        # Storage-related resources
security.mycompany.com       # Security-related resources

# Avoid: Generic grouping
mycompany.com               # Too broad
api.mycompany.com           # Redundant

Versioning Best Practices

Start with alpha for new APIs
Promote gradually through stability levels
Maintain backward compatibility in stable versions
Use semantic versioning principles
Document breaking changes clearly between alpha versions

Migration Path Example

# v1alpha1
apiVersion: example.com/v1alpha1
kind: MyResource
spec:
  oldField: value

# v1beta1 (with breaking change)
apiVersion: example.com/v1beta1
kind: MyResource
spec:
  newField: value  # oldField renamed

# v1 (stable)
apiVersion: example.com/v1
kind: MyResource
spec:
  newField: value  # API locked for backward compatibility

Common Patterns

Multi-Tenant Resources

# Tenant-specific groups
tenant1.mycompany.com/v1/Application
tenant2.mycompany.com/v1/Application

Feature-Specific Groups

# Feature-based organization
monitoring.mycompany.com/v1/Alert
logging.mycompany.com/v1/LogConfig
backup.mycompany.com/v1/BackupPolicy

Custom Resource Groups with Domain-based Naming

Use reverse domain notation for custom groups:

apiVersion: company.com/v1alpha1
kind: MyCustomResource

Examples of Custom Groups

# Database operator
apiVersion: postgresql.cnpg.io/v1
kind: Cluster

# Service mesh
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator

# Certificate management
apiVersion: cert-manager.io/v1
kind: Certificate

# Monitoring
apiVersion: monitoring.coreos.com/v1
kind: Prometheus

Group Versioning with Multiple Versions

Groups can have multiple versions simultaneously:

# Same group, different versions
apiVersion: autoscaling/v1      # Basic HPA
apiVersion: autoscaling/v2      # Advanced HPA with multiple metrics
apiVersion: autoscaling/v2beta2 # Beta version with experimental features

Understanding these naming conventions helps in organizing custom resources, debugging API issues, and maintaining clean API structures in Kubernetes environments.