API Groups & Versions

Understanding API groups and versions is essential for working with Kubernetes because they determine how you specify resources in YAML files, how the API is organized, and how Kubernetes handles API evolution. Every resource you create references an API group and version, so understanding this system helps you write correct configurations and understand API deprecation.

Think of API groups like departments in a company, and versions like different editions of a document. The “core” department handles fundamental things (pods, services), while specialized departments handle specific areas (apps for deployments, networking for ingresses). Versions allow the API to evolve while maintaining backward compatibility.

What are API Groups?

API groups are a way to organize related Kubernetes APIs. They provide logical grouping of resources and allow the API to be extended without cluttering the core API.

Core API Group

The core API group (/api/v1) contains fundamental resources that have been part of Kubernetes since early versions:

• Pods
• Services
• Nodes
• Namespaces
• ConfigMaps
• Secrets
• PersistentVolumes
• And more…

These resources don’t have an explicit group name in their API path—they use /api/v1 instead of /apis/core/v1.

Named API Groups

Named API groups (/apis/<group>/<version>) contain extended resources:

• apps (/apis/apps/v1) - Deployments, ReplicaSets, StatefulSets, DaemonSets
• networking.k8s.io (/apis/networking.k8s.io/v1) - Ingresses, NetworkPolicies
• storage.k8s.io (/apis/storage.k8s.io/v1) - StorageClasses, CSIDrivers
• rbac.authorization.k8s.io (/apis/rbac.authorization.k8s.io/v1) - Roles, RoleBindings
• batch (/apis/batch/v1) - Jobs, CronJobs
• autoscaling (/apis/autoscaling/v2) - HorizontalPodAutoscaler
• And many more…

API Group Structure

API Versions

Each API group can have multiple versions. Versions allow the API to evolve while maintaining compatibility.

Version Types

v1 - Stable version:

• Production-ready
• Guaranteed backward compatibility
• Won’t be removed without deprecation period
• Example: apps/v1, networking.k8s.io/v1

v1beta1, v1beta2 - Beta versions:

• Feature-complete but may have minor changes
• May be promoted to v1 or removed
• Should be used with caution in production
• Example: networking.k8s.io/v1beta1

v1alpha1, v1alpha2 - Alpha versions:

• Experimental features
• May change or be removed at any time
• Not recommended for production
• Example: flowcontrol.apiserver.k8s.io/v1alpha1

Versioning Strategy

Kubernetes uses a three-version system:

• Oldest - Deprecated, will be removed
• Stable - Current stable version (v1)
• Newest - Latest version (may be beta/alpha)

When a new version is introduced, the old version is marked for deprecation and eventually removed after a deprecation period (typically one year).

How to Specify API Groups and Versions

In YAML files, you specify the API group and version in the apiVersion field:

Core API Group

apiVersion: v1  # Core API group, no explicit group name
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
  - name: nginx
    image: nginx:1.21

Named API Group

apiVersion: apps/v1  # apps group, v1 version
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: nginx
        image: nginx:1.21

Full API Path

The apiVersion field maps to the API path:

• v1 → /api/v1
• apps/v1 → /apis/apps/v1
• networking.k8s.io/v1 → /apis/networking.k8s.io/v1

API Version Conversion

Kubernetes can convert between API versions automatically:

• Storage version - One version is used for storage in etcd
• Client versions - Clients can use any supported version
• Automatic conversion - API server converts between versions

This means you can use apps/v1 even if the cluster stores it as apps/v1 internally, and the API server handles conversion.

Common API Groups

apps/v1

Resources for managing applications:

• Deployment - Manages ReplicaSets for stateless apps
• ReplicaSet - Maintains a set of pods
• StatefulSet - Manages stateful applications
• DaemonSet - Ensures pods run on all/some nodes

apiVersion: apps/v1
kind: Deployment

networking.k8s.io/v1

Networking resources:

• Ingress - HTTP/HTTPS routing
• NetworkPolicy - Network isolation rules

apiVersion: networking.k8s.io/v1
kind: Ingress

storage.k8s.io/v1

Storage resources:

• StorageClass - Defines storage classes
• CSIDriver - Container Storage Interface drivers
• VolumeAttachment - Volume attachments

apiVersion: storage.k8s.io/v1
kind: StorageClass

batch/v1

Batch workloads:

• Job - One-time tasks
• CronJob - Scheduled jobs

apiVersion: batch/v1
kind: Job

rbac.authorization.k8s.io/v1

Access control:

• Role - Namespace-scoped permissions
• RoleBinding - Binds roles to subjects
• ClusterRole - Cluster-scoped permissions
• ClusterRoleBinding - Cluster-scoped bindings

apiVersion: rbac.authorization.k8s.io/v1
kind: Role

API Deprecation

Kubernetes has a deprecation policy for API versions:

Deprecation Timeline

1. Announcement - Version marked as deprecated in release notes
2. Deprecation period - Typically one year
3. Removal - Version removed in a future release

Example: apps/v1beta1

• Deprecated in - Kubernetes 1.9
• Removed in - Kubernetes 1.16
• Replacement - apps/v1

Checking Deprecations

# Check API versions
kubectl api-versions

# Check for deprecated APIs
kubectl get --raw /metrics | grep deprecated

Best Practices

Use Stable Versions

Always use v1 versions in production:

• ✅ apps/v1
• ✅ networking.k8s.io/v1
• ❌ apps/v1beta1 (deprecated)
• ❌ networking.k8s.io/v1beta1 (may be deprecated)

Check API Versions

Before using a resource, check available versions:

kubectl api-resources -o wide

Update Regularly

Keep your YAML files updated to use current API versions:

• Review deprecation notices
• Test with new versions
• Update before old versions are removed

Version Compatibility

Different Kubernetes versions support different API versions:

• Older clusters - May not support newer API versions
• Newer clusters - Support multiple versions for compatibility

Check your cluster’s Kubernetes version and supported API versions.

API Version Discovery

You can discover available API versions:

# List all API versions
kubectl api-versions

# List API resources with versions
kubectl api-resources -o wide

# Get specific resource information
kubectl explain deployment.apiVersion

Custom Resource Definitions (CRDs)

CRDs can define their own API groups:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myresources.example.com
spec:
  group: example.com
  versions:
  - name: v1
    served: true
    storage: true
  scope: Namespaced
  names:
    plural: myresources
    singular: myresource
    kind: MyResource

This creates a new API group example.com with version v1.

Key Takeaways

• API groups organize related Kubernetes APIs (core vs named groups)
• Versions allow API evolution (v1 = stable, v1beta1 = beta, v1alpha1 = alpha)
• Core API group uses /api/v1, named groups use /apis/<group>/<version>
• Always use stable (v1) versions in production
• Kubernetes converts between API versions automatically
• API versions can be deprecated and removed after a deprecation period
• Check available API versions before using resources

See Also

• APIs & Access - Overview of Kubernetes API
• Discovery & OpenAPI - Discovering available APIs
• CRDs - Creating custom API groups
• API Objects - Understanding API objects