Diseño de CRD y Scaffolding con kubebuilder

Las Definiciones de Recursos Personalizados (Custom Resource Definitions) exponen el lenguaje de dominio de tu operador a los usuarios del clúster como YAML.

kubebuilder convierte tipos de API Go y comentarios marcadores en manifiestos CRD, reglas RBAC y stubs de webhook a través de controller-gen.

Resumen

Define tipos bajo api/v1/ (y versiones futuras) con campos de estructura etiquetados para JSON y validación.

Los comentarios marcadores como +kubebuilder:validation:Minimum=1 se convierten en restricciones OpenAPI en la CRD.

Ejecuta make manifests para regenerar YAML cada vez que cambien los tipos.

Planifica el versionado temprano: añade v2 como un nuevo paquete, marca una versión como de almacenamiento, implementa la conversión si los campos cambian de nombre.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:scope=Namespaced
// +kubebuilder:printcolumn:name="Replicas",type=integer,JSONPath=".spec.frontendSize"
// +kubebuilder:printcolumn:name="Ready",type=boolean,JSONPath=".status.ready"
type Guestbook struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`
    Spec   GuestbookSpec   `json:"spec,omitempty"`
    Status GuestbookStatus `json:"status,omitempty"`
}
 
type GuestbookSpec struct {
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=10
    FrontendSize int32 `json:"frontendSize"`
}

Cuándo usar esto:

• Al definir un nuevo tipo de CRD con kubebuilder create api
• Al añadir validación antes de que los usuarios apliquen especificaciones rotas
• Al exponer columnas de kubectl get para ingenieros de soporte
• Al introducir una nueva versión de API sin romper manifiestos existentes

Ejemplo de Trabajo

// api/v1/guestbook_types.go
package v1
 
import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
 
// GuestbookSpec define el estado deseado de Guestbook.
type GuestbookSpec struct {
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=10
    FrontendSize int32 `json:"frontendSize"`
 
    // +kubebuilder:validation:Enum=small;medium;large
    Tier string `json:"tier,omitempty"`
}
 
// GuestbookStatus define el estado observado de Guestbook.
type GuestbookStatus struct {
    Ready      bool               `json:"ready,omitempty"`
    Conditions []metav1.Condition `json:"conditions,omitempty"`
}
 
// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:storageversion
// +kubebuilder:resource:shortName=gb
// +kubebuilder:printcolumn:name="Tier",type=string,JSONPath=".spec.tier"
// +kubebuilder:printcolumn:name="Ready",type=boolean,JSONPath=".status.ready"
type Guestbook struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`
    Spec   GuestbookSpec   `json:"spec,omitempty"`
    Status GuestbookStatus `json:"status,omitempty"`
}
 
// +kubebuilder:object:root=true
type GuestbookList struct {
    metav1.TypeMeta `json:",inline"`
    metav1.ListMeta `json:"metadata,omitempty"`
    Items           []Guestbook `json:"items"`
}
 
func init() {
    SchemeBuilder.Register(&Guestbook{}, &GuestbookList{})
}

# Objetivo de Makefile (generado por kubebuilder)
controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases

Lo que esto demuestra:

• Tipos de lista y objeto raíz registrados en SchemeBuilder
• Los marcadores de validación se convierten en restricciones de esquema CRD
• +kubebuilder:storageversion fija el almacenamiento etcd a esta versión
• make manifests alimenta config/crd/bases/webapp.example.com_guestbooks.yaml

Inmersión Profunda

Cómo Funciona

• controller-gen escanea archivos Go en busca de marcadores +kubebuilder: y emite YAML CRD, reglas ClusterRole y configuraciones de webhook.
• Las CRD se ubican en config/crd/bases/; las superposiciones de kustomize parchean nombres, namespaces y bundles de CA de webhook para la instalación.
• El grupo de API proviene del dominio del archivo PROJECT + el flag create api --group (webapp.example.com/v1).
• Las actualizaciones de estado requieren tanto la sección subresources.status de la CRD como los permisos RBAC */status generados a partir de los marcadores +kubebuilder:rbac en los reconciliadores.

Estrategia de Versionado

Marcadores Comunes

Notas de Go

// Marcadores RBAC del Reconciliador (en el archivo del controlador)
// +kubebuilder:rbac:groups=webapp.example.com,resources=guestbooks,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=webapp.example.com,resources=guestbooks/status,verbs=get;update;patch

Trampas

• Editar YAML de CRD manualmente - el próximo make manifests sobrescribirá los cambios. Solución: cambia los tipos y marcadores de Go, luego regenera.
• Renombrar campos JSON sin una nueva versión de API - rompe objetos almacenados y cachés de clientes. Solución: añade v2, implementa la conversión, mantén v1 servido.
• Omitir el tipo de lista - la generación de código falla o el registro del Esquema se rompe. Solución: genera siempre GuestbookList con +kubebuilder:object:root=true.
• Múltiples versiones de almacenamiento - la aplicación de CRD falla. Solución: exactamente una +kubebuilder:storageversion entre versiones.
• Puntero vs valor para campos opcionales - omitempty en escalares no puede distinguir cero de no establecido para validación. Solución: usa punteros para enteros opcionales o enums cuando cero sea válido.
• Olvidar RBAC de estado - Status().Update devuelve 403. Solución: añade verbos guestbooks/status a los marcadores rbac.

Alternativas

Preguntas Frecuentes

Relacionado

• Fundamentos de Operadores de Kubernetes - scaffolding y make install
• Webhooks de Admisión: Validación y Mutación en Go - más allá de la validación OpenAPI
• Escribiendo un Reconciliador: ctrl.Request y Bucle Reconcile - actúa sobre la spec del CR
• OLM Bundles, Actualizaciones y RBAC Multi-inquilino - envía CRDs en bundles
• Por qué Go Domina el Ecosistema de Operadores de Kubernetes - ventaja de la generación de código

Versiones de Stack: Esta página fue escrita para Go 1.26.x (GC por defecto Green Tea, go fix modernizers - verifica el parche en la compilación), chi (última - verifica en la compilación), gin (última - verifica en la compilación), echo (última - verifica en la compilación), google.golang.org/grpc (última - verifica en la compilación), sigs.k8s.io/controller-runtime (última - verifica en la compilación), kubebuilder (última - verifica en la compilación), tinygo (última - verifica objetivos de placa en la compilación), wazero (última - verifica en la compilación), y golangci-lint (última - verifica el conjunto de linters en la compilación).