Kubernetes API Versions and API Groups

API Groups

Un API Group es un mecanismo de namespace en Kubernetes que organiza recursos relacionados y sus APIs. Permite que la API de Kubernetes sea modular y extensible.

Estructura de API Groups

  • Core Group (vacío): Recursos fundamentales como Pod, Service, ConfigMap
  • Se representa como apiVersion: v1

  • No tiene nombre de grupo explícito

  • Named Groups: Grupos con nombres específicos

  • Formato: apiVersion: <group>/<version>
  • Ejemplo: apiVersion: apps/v1

Grupos Comunes

Grupo Descripción Recursos Principales
apps Cargas de trabajo de aplicaciones Deployment, StatefulSet, DaemonSet, ReplicaSet
networking.k8s.io Recursos de red Ingress, NetworkPolicy
rbac.authorization.k8s.io Control de acceso Role, ClusterRole, RoleBinding
storage.k8s.io Almacenamiento StorageClass, VolumeAttachment
autoscaling Escalado automático HorizontalPodAutoscaler
batch Trabajos y tareas Job, CronJob

API Versions

Una API Version define la versión específica del esquema para los recursos en un API Group.

Formato de Versiones

  • Alpha: v1alpha1, v2alpha1
  • Experimental, puede cambiar sin aviso
  • Puede contener bugs

  • Deshabilitada por defecto

  • Beta: v1beta1, v2beta1

  • Bien probada, pero puede cambiar
  • Habilitada por defecto

  • Se considera estable para uso no crítico

  • Stable: v1, v2

  • Versión estable y soportada
  • Compatibilidad hacia atrás garantizada
  • Recomendada para producción

Propósito de API Groups

Versionado Independiente

Diferentes grupos pueden evolucionar a diferentes velocidades. El grupo apps puede lanzar v2 mientras networking.k8s.io permanece en v1.

Evitar Conflictos de Nombres

Múltiples grupos pueden tener recursos con el mismo nombre. Por ejemplo, tanto extensions como networking.k8s.io tuvieron recursos Ingress durante transiciones.

Organización Lógica

Funcionalidad relacionada se agrupa junta. Recursos RBAC están en rbac.authorization.k8s.io, recursos de almacenamiento en storage.k8s.io.

Extensibilidad

Operadores de terceros y recursos personalizados pueden crear sus propios API groups sin conflictos con recursos core de Kubernetes.

Comandos de Verificación

Ver Grupos de API Disponibles

kubectl api-versions

Ver Recursos por Grupo

# Todos los recursos
kubectl api-resources

# Recursos de un grupo específico
kubectl api-resources --api-group=apps

# Buscar grupos que contengan texto
kubectl api-resources | grep apps

Documentación de Recursos

# Ver documentación de un recurso
kubectl explain deployment

# Ver campos específicos
kubectl explain deployment.spec
kubectl explain deployment.metadata

Ejemplos de Manifiestos

Recurso Core Group

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
  - name: nginx
    image: nginx

Recurso Named Group

apiVersion: apps/v1
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

Consideraciones de Migración

Deprecación de API Versions

  • Kubernetes depreca versiones beta después de introducir versiones estables
  • Las versiones deprecadas eventualmente se eliminan
  • Usar kubectl convert para migrar manifiestos

Verificación de Compatibilidad

# Verificar si una API version está soportada
kubectl api-versions | grep apps/v1

# Verificar recursos disponibles
kubectl api-resources --api-group=apps --verbs=create

Referencias