Design e Scaffolding de CRD com kubebuilder

Q: O que gera o YAML CRD?

O controller-gen invocado por make manifests lê tipos Go e marcadores kubebuilder. A saída fica em config/crd/bases/.

Q: Como adiciono uma segunda versão de API?

Execute kubebuilder create api --group webapp --version v2 --kind Guestbook, implemente a conversão, marque a versão de armazenamento na versão canônica.

Q: Como as colunas de impressão ajudam?

Elas adicionam colunas kubectl get sem plugins personalizados. O JSONPath deve corresponder aos campos de esquema CRD publicados.

Q: Quando preciso de validação CEL?

Quando as regras envolvem múltiplos campos (spec.end > spec.start) que os marcadores OpenAPI por campo não conseguem expressar. Adicione regras +kubebuilder:validation:XValidation em versões mais recentes do kubebuilder ou corrija o YAML CRD.

Q: Posso escopar CRDs em todo o cluster?

Use +kubebuilder:resource:scope=Cluster em tipos com escopo de cluster. O RBAC e o manuseio de namespace nos reconciliadores mudam de acordo.

Q: Como funcionam os nomes curtos?

+kubebuilder:resource:shortName=gb permite kubectl get gb. Ainda exige que os usuários conheçam o grupo de API para nomes curtos ambíguos.

Custom Resource Definitions expõem a linguagem de domínio do seu operador aos usuários do cluster como YAML.

O kubebuilder transforma tipos de API Go e comentários de marcadores em manifestos CRD, regras RBAC e stubs de webhook através do controller-gen.

Resumo

Defina tipos em api/v1/ (e versões futuras) com campos de struct marcados para JSON e validação.

Marcadores de comentário como +kubebuilder:validation:Minimum=1 tornam-se restrições OpenAPI no CRD.

Execute make manifests para regenerar o YAML sempre que os tipos mudarem.

Planeje o versionamento com antecedência: adicione v2 como um novo pacote, marque uma versão como de armazenamento, implemente a conversão se os campos mudarem de nome.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// +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"`
}

Quando usar isso:

Definindo um novo tipo de CRD com kubebuilder create api
Adicionando validação antes que os usuários apliquem especificações quebradas
Expondo colunas do kubectl get para engenheiros de suporte
Introduzindo uma nova versão de API sem quebrar manifestos existentes

Exemplo de Trabalho

// api/v1/guestbook_types.go
package v1
 
import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
 
// GuestbookSpec define o estado desejado do 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 o estado observado do 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{})
}

# Alvo do Makefile (gerado pelo kubebuilder)
controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases

O que isso demonstra:

Tipos de lista e objeto raiz registrados em SchemeBuilder
Marcadores de validação se tornam restrições de esquema CRD
+kubebuilder:storageversion fixa o armazenamento etcd nesta versão
make manifests alimenta config/crd/bases/webapp.example.com_guestbooks.yaml

Mergulho Profundo

Como Funciona

controller-gen escaneia arquivos Go em busca de marcadores +kubebuilder: e emite YAML CRD, regras ClusterRole e configurações de webhook.
CRDs ficam em config/crd/bases/; sobreposições kustomize corrigem nomes, namespaces e bundles de CA de webhook para instalação.
O grupo de API vem do domínio do arquivo PROJECT + flag create api --group (webapp.example.com/v1).
Atualizações de status exigem tanto a estrofe subresources.status do CRD quanto permissões RBAC */status geradas a partir de marcadores +kubebuilder:rbac nos reconciliadores.

Estratégia de Versionamento

Padrão	Propósito
`v1alpha1`	Experimental, alterações que quebram são permitidas
`v1beta1`	Conjunto de campos estabilizando, a conversão pode aparecer
`v1`	Compatível com GA; prefira adições retrocompatíveis
Conversão hub-spoke	Mapeia campos `v1` e `v2` através de um tipo hub

Marcadores Comuns

Marcador	Efeito
`+kubebuilder:validation:Required`	Campo obrigatório no OpenAPI
`+kubebuilder:default=value`	Padrão injetado pelo CRD
`+kubebuilder:validation:Pattern`	Regex em strings
`+kubebuilder:rbac:groups=...,resources=...,verbs=...`	Regra RBAC em `config/rbac`
`+kubebuilder:webhook:...`	Configuração de webhook de validação ou mutação

Notas Go

// Marcadores RBAC do Reconciler (no arquivo do controller)
// +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

Armadilhas

Editar YAML CRD manualmente - o próximo make manifests sobrescreverá as alterações. Correção: altere os tipos Go e os marcadores, e regenere.
Renomear campos JSON sem uma nova versão de API - quebra objetos armazenados e caches de clientes. Correção: adicione v2, implemente a conversão, mantenha v1 servido.
Omitir tipo de lista - a geração de código falha ou o registro do Scheme quebra. Correção: sempre gere GuestbookList com +kubebuilder:object:root=true.
Múltiplas versões de armazenamento - a aplicação do CRD falha. Correção: exatamente uma +kubebuilder:storageversion entre as versões.
Ponteiro vs valor para campos opcionais - omitempty em escalares não pode distinguir zero de não definido para validação. Correção: use ponteiros para inteiros opcionais ou enums quando zero for válido.
Esquecer RBAC de status - Status().Update retorna 403. Correção: adicione verbos guestbooks/status aos marcadores rbac.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
kubebuilder + controller-gen	Operadores Go com APIs tipadas	O CRD é mantido por uma equipe separada em YAML bruto
YAML CRD escrito à mão	Fonte de verdade de esquema agnóstica de linguagem	Você quer geração de código RBAC e webhook a partir de Go
Validação declarativa apenas com Kubebuilder	Restrições de campo simples	Regras complexas entre campos precisam de CEL ou webhooks
Webhooks de Admissão para Validação	Políticas além do OpenAPI	Todas as regras simples de min/max (prefira marcadores primeiro)

FAQs

O que gera o YAML CRD?

O controller-gen invocado por make manifests lê tipos Go e marcadores kubebuilder.

A saída fica em config/crd/bases/.

Como adiciono uma segunda versão de API?

Execute kubebuilder create api --group webapp --version v2 --kind Guestbook, implemente a conversão, marque a versão de armazenamento na versão canônica.

O que é a versão de armazenamento?

A versão do CRD que o etcd persiste os objetos.

Outras versões servidas são convertidas para e a partir do armazenamento na leitura/escrita.

Os marcadores validam em tempo de compilação?

Marcadores são comentários interpretados pelo controller-gen no tempo de geração de código.

Sintaxe de marcador inválida falha make manifests, não go build.

Como as colunas de impressão ajudam?

Elas adicionam colunas kubectl get sem plugins personalizados.

O JSONPath deve corresponder aos campos de esquema CRD publicados.

Quando preciso de validação CEL?

Quando as regras envolvem múltiplos campos (spec.end > spec.start) que os marcadores OpenAPI por campo não conseguem expressar.

Adicione regras +kubebuilder:validation:XValidation em versões mais recentes do kubebuilder ou corrija o YAML CRD.

O que o arquivo PROJECT armazena?

Domínio, caminho do repositório e versão do layout que o kubebuilder usa para comandos de scaffolding.

Mantenha-o no controle de versão.

Posso escopar CRDs em todo o cluster?

Use +kubebuilder:resource:scope=Cluster em tipos com escopo de cluster.

O RBAC e o manuseio de namespace nos reconciliadores mudam de acordo.

Como funcionam os nomes curtos?

+kubebuilder:resource:shortName=gb permite kubectl get gb.

Ainda exige que os usuários conheçam o grupo de API para nomes curtos ambíguos.

As structs spec e status devem ser separadas?

Sim.

A convenção do Kubernetes e a separação de RBAC exigem que o spec seja gravável pelo usuário e o status gravável pelo controlador.

Relacionados

Noções Básicas de Operadores Kubernetes - scaffold e make install
Webhooks de Admissão: Validação e Mutação em Go - além da validação OpenAPI
Escrevendo um Reconciliador: ctrl.Request & Loop Reconcile - agir sobre a especificação CR
OLM Bundles, Upgrades & RBAC Multi-Tenant - enviar CRDs em bundles
Por que Go Domina o Ecossistema de Operadores Kubernetes - vantagem de geração de código

Versões da Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).

O kubebuilder transforma tipos de API Go e comentários de marcadores em manifestos CRD, regras RBAC e stubs de webhook através do controller-gen.

Resumo

Defina tipos em api/v1/ (e versões futuras) com campos de struct marcados para JSON e validação.

Marcadores de comentário como +kubebuilder:validation:Minimum=1 tornam-se restrições OpenAPI no CRD.

Execute make manifests para regenerar o YAML sempre que os tipos mudarem.

Planeje o versionamento com antecedência: adicione v2 como um novo pacote, marque uma versão como de armazenamento, implemente a conversão se os campos mudarem de nome.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// +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"`
}

Quando usar isso:

Definindo um novo tipo de CRD com kubebuilder create api
Adicionando validação antes que os usuários apliquem especificações quebradas
Expondo colunas do kubectl get para engenheiros de suporte
Introduzindo uma nova versão de API sem quebrar manifestos existentes

Exemplo de Trabalho

// api/v1/guestbook_types.go
package v1
 
import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
 
// GuestbookSpec define o estado desejado do 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 o estado observado do 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{})
}

# Alvo do Makefile (gerado pelo kubebuilder)
controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases

O que isso demonstra:

Tipos de lista e objeto raiz registrados em SchemeBuilder
Marcadores de validação se tornam restrições de esquema CRD
+kubebuilder:storageversion fixa o armazenamento etcd nesta versão
make manifests alimenta config/crd/bases/webapp.example.com_guestbooks.yaml

Mergulho Profundo

Como Funciona

controller-gen escaneia arquivos Go em busca de marcadores +kubebuilder: e emite YAML CRD, regras ClusterRole e configurações de webhook.
CRDs ficam em config/crd/bases/; sobreposições kustomize corrigem nomes, namespaces e bundles de CA de webhook para instalação.
O grupo de API vem do domínio do arquivo PROJECT + flag create api --group (webapp.example.com/v1).
Atualizações de status exigem tanto a estrofe subresources.status do CRD quanto permissões RBAC */status geradas a partir de marcadores +kubebuilder:rbac nos reconciliadores.

Estratégia de Versionamento

Padrão	Propósito
`v1alpha1`	Experimental, alterações que quebram são permitidas
`v1beta1`	Conjunto de campos estabilizando, a conversão pode aparecer
`v1`	Compatível com GA; prefira adições retrocompatíveis
Conversão hub-spoke	Mapeia campos `v1` e `v2` através de um tipo hub

Marcadores Comuns

Marcador	Efeito
`+kubebuilder:validation:Required`	Campo obrigatório no OpenAPI
`+kubebuilder:default=value`	Padrão injetado pelo CRD
`+kubebuilder:validation:Pattern`	Regex em strings
`+kubebuilder:rbac:groups=...,resources=...,verbs=...`	Regra RBAC em `config/rbac`
`+kubebuilder:webhook:...`	Configuração de webhook de validação ou mutação

Notas Go

// Marcadores RBAC do Reconciler (no arquivo do controller)
// +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

Armadilhas

Editar YAML CRD manualmente - o próximo make manifests sobrescreverá as alterações. Correção: altere os tipos Go e os marcadores, e regenere.
Renomear campos JSON sem uma nova versão de API - quebra objetos armazenados e caches de clientes. Correção: adicione v2, implemente a conversão, mantenha v1 servido.
Omitir tipo de lista - a geração de código falha ou o registro do Scheme quebra. Correção: sempre gere GuestbookList com +kubebuilder:object:root=true.
Múltiplas versões de armazenamento - a aplicação do CRD falha. Correção: exatamente uma +kubebuilder:storageversion entre as versões.
Ponteiro vs valor para campos opcionais - omitempty em escalares não pode distinguir zero de não definido para validação. Correção: use ponteiros para inteiros opcionais ou enums quando zero for válido.
Esquecer RBAC de status - Status().Update retorna 403. Correção: adicione verbos guestbooks/status aos marcadores rbac.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
kubebuilder + controller-gen	Operadores Go com APIs tipadas	O CRD é mantido por uma equipe separada em YAML bruto
YAML CRD escrito à mão	Fonte de verdade de esquema agnóstica de linguagem	Você quer geração de código RBAC e webhook a partir de Go
Validação declarativa apenas com Kubebuilder	Restrições de campo simples	Regras complexas entre campos precisam de CEL ou webhooks
Webhooks de Admissão para Validação	Políticas além do OpenAPI	Todas as regras simples de min/max (prefira marcadores primeiro)

FAQs

O que gera o YAML CRD?

O controller-gen invocado por make manifests lê tipos Go e marcadores kubebuilder.

A saída fica em config/crd/bases/.

Como adiciono uma segunda versão de API?

Execute kubebuilder create api --group webapp --version v2 --kind Guestbook, implemente a conversão, marque a versão de armazenamento na versão canônica.

O que é a versão de armazenamento?

A versão do CRD que o etcd persiste os objetos.

Outras versões servidas são convertidas para e a partir do armazenamento na leitura/escrita.

Os marcadores validam em tempo de compilação?

Marcadores são comentários interpretados pelo controller-gen no tempo de geração de código.

Sintaxe de marcador inválida falha make manifests, não go build.

Como as colunas de impressão ajudam?

Elas adicionam colunas kubectl get sem plugins personalizados.

O JSONPath deve corresponder aos campos de esquema CRD publicados.

Quando preciso de validação CEL?

Quando as regras envolvem múltiplos campos (spec.end > spec.start) que os marcadores OpenAPI por campo não conseguem expressar.

Adicione regras +kubebuilder:validation:XValidation em versões mais recentes do kubebuilder ou corrija o YAML CRD.

O que o arquivo PROJECT armazena?

Domínio, caminho do repositório e versão do layout que o kubebuilder usa para comandos de scaffolding.

Mantenha-o no controle de versão.

Posso escopar CRDs em todo o cluster?

Use +kubebuilder:resource:scope=Cluster em tipos com escopo de cluster.

O RBAC e o manuseio de namespace nos reconciliadores mudam de acordo.

Como funcionam os nomes curtos?

+kubebuilder:resource:shortName=gb permite kubectl get gb.

Ainda exige que os usuários conheçam o grupo de API para nomes curtos ambíguos.

As structs spec e status devem ser separadas?

Sim.

A convenção do Kubernetes e a separação de RBAC exigem que o spec seja gravável pelo usuário e o status gravável pelo controlador.

Relacionados

Noções Básicas de Operadores Kubernetes - scaffold e make install
Webhooks de Admissão: Validação e Mutação em Go - além da validação OpenAPI
Escrevendo um Reconciliador: ctrl.Request & Loop Reconcile - agir sobre a especificação CR
OLM Bundles, Upgrades & RBAC Multi-Tenant - enviar CRDs em bundles
Por que Go Domina o Ecossistema de Operadores Kubernetes - vantagem de geração de código

Versões da Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).

Design e Scaffolding de CRD com kubebuilder

Buscar na documentação

Design e Scaffolding de CRD com kubebuilder