Noções Básicas de Kubernetes Operators

10 exemplos para você começar com K8s Operators - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale Go 1.26.x ou posterior em go.dev/dl.
• Instale kubebuilder (última versão - verifique na compilação): siga kubebuilder.io.
• Instale kubectl e um cluster local (kind, minikube ou Docker Desktop Kubernetes).
• Instale kustomize (incluído com versões recentes do kubectl) para make deploy.
• Verifique as ferramentas: go version, kubebuilder version, kubectl cluster-info.

Exemplos Básicos

1. Estruturar um Projeto Kubebuilder

Crie um módulo com o grupo de API webapp.example.com e um tipo Guestbook.

mkdir guestbook-operator && cd guestbook-operator
kubebuilder init --domain example.com --repo example.com/guestbook-operator
kubebuilder create api --group webapp --version v1 --kind Guestbook --resource --controller

• init gera o esqueleto de main.go, Makefile e Dockerfile.
• create api adiciona api/v1/guestbook_types.go e internal/controller/guestbook_controller.go.
• Execute go mod tidy após a estruturação para resolver os módulos do controller-runtime.

Relacionado: Design de CRD e Estruturação do Kubebuilder - Marcadores de API e geração de código

2. Gerar Manifestos CRD e RBAC

Use controller-gen através do Makefile do projeto para emitir o YAML de instalação.

make manifests
ls config/crd/bases/

• make manifests executa controller-gen com marcadores +kubebuilder dos tipos Go.
• A saída é direcionada para config/crd/bases/ e config/rbac/.
• Regenerere após cada alteração na struct da API antes de kubectl apply.

Relacionado: Design de CRD e Estruturação do Kubebuilder - marcadores de validação

3. Instalar CRDs em um Cluster Local

Aplique CRDs e RBAC gerados ao kind ou minikube.

make install
kubectl get crd | grep webapp

• make install aplica as bases de CRD de config/crd.
• Confirme se guestbooks.webapp.example.com aparece antes de iniciar o gerenciador.
• Erros de esquema de CRD surgem aqui; corrija os marcadores Go e regenere.

Relacionado: Gerenciador, Cliente e Esquema do controller-runtime - Registro do Esquema

4. Esqueleto Mínimo de Reconciliador

O controlador gerado implementa Reconcile com um cliente tipado.

func (r *GuestbookReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    var gb webappv1.Guestbook
    if err := r.Get(ctx, req.NamespacedName, &gb); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }
    // TODO: garantir que os recursos filhos desejados existam
    return ctrl.Result{}, nil
}

• req.NamespacedName identifica o objeto que acionou o trabalho.
• Retorne client.IgnoreNotFound(err) quando o CR foi excluído.
• ctrl.Result{} vazio significa sucesso sem reenfileiramento forçado.

Relacionado: Escrevendo um Reconciliador: Loop ctrl.Request & Reconcile - reenfileiramento e erros

5. Registrar o Controlador com o Gerenciador

Conecte o reconciliador em main.go com o cliente e o esquema do Gerenciador.

if err = (&controller.GuestbookReconciler{
    Client: mgr.GetClient(),
    Scheme: mgr.GetScheme(),
}).SetupWithManager(mgr); err != nil {
    setupLog.Error(err, "unable to create controller", "controller", "Guestbook")
    os.Exit(1)
}

• mgr.GetClient() é um cliente em cache seguro para leituras dentro da reconciliação.
• SetupWithManager registra watches e conecta a workqueue.
• A eleição de líder e as métricas se vinculam à mesma instância do Gerenciador.

Relacionado: Gerenciador, Cliente e Esquema do controller-runtime - Ciclo de vida do Gerenciador

6. Executar o Gerenciador Localmente

Inicie o operador contra seu kubeconfig com a eleição de líder desabilitada para desenvolvimento.

make run

• make run executa go run ./cmd/main.go com acesso ao cluster sem envtest.
• Aplique um CR de exemplo em outro terminal: kubectl apply -f config/samples/.
• Observe os logs do gerenciador em busca de linhas de reconciliação quando o exemplo for alterado.

Relacionado: Eleição de Líder, Métricas e Observabilidade do Operador - endpoints de saúde e métricas

7. Aplicar um Recurso Personalizado de Exemplo

Use o manifesto de exemplo gerado para acionar a reconciliação.

apiVersion: webapp.example.com/v1
kind: Guestbook
metadata:
  name: guestbook-sample
  namespace: default
spec:
  frontendSize: 2

kubectl apply -f config/samples/webapp_v1_guestbook.yaml
kubectl get guestbook guestbook-sample -o yaml

• Exemplos ficam em config/samples/ após create api.
• Atualizações de subrecurso de status aparecem em .status assim que você as implementar.
• Edite spec e confirme se o reconciliador é executado novamente (orientado por nível).

Relacionado: Watches, Predicates, Owner References & Finalizers - filtragem de eventos

Exemplos Intermediários

8. Definir Referências de Proprietário em Deployments Filhos

Vincule o ciclo de vida de um Deployment filho ao CR Guestbook pai.

dep := &appsv1.Deployment{ObjectMeta: metav1.ObjectMeta{
    Name: gb.Name + "-frontend", Namespace: gb.Namespace,
}}
if err := controllerutil.SetControllerReference(&gb, dep, r.Scheme); err != nil {
    return ctrl.Result{}, err
}

• Referências de proprietário permitem a coleta de lixo do Kubernetes quando o CR é excluído.
• SetControllerReference requer que o proprietário tenha o sinalizador de controlador definido.
• Um controlador por tipo de objeto de propriedade por namespace é o padrão comum.

Relacionado: Watches, Predicates, Owner References & Finalizers - GC e watches

9. Adicionar um Finalizador de Exclusão

Bloqueie a remoção do CR até que a limpeza externa seja concluída.

if !controllerutil.ContainsFinalizer(&gb, finalizerName) {
    controllerutil.AddFinalizer(&gb, finalizerName)
    return ctrl.Result{}, r.Update(ctx, &gb)
}
if !gb.DeletionTimestamp.IsZero() {
    // desfaça os recursos externos, então:
    controllerutil.RemoveFinalizer(&gb, finalizerName)
    return ctrl.Result{}, r.Update(ctx, &gb)
}

• Finalizadores impedem a remoção do objeto até que seu código os limpe.
• Sempre reenfileire após adicionar ou remover finalizadores via Update.
• Emparelhe finalizadores com lógica de descarte idempotente.

Relacionado: Watches, Predicates, Owner References & Finalizers - segurança de descarte

10. Executar Testes de Integração com envtest

Teste a lógica de reconciliação sem um cluster ativo usando envtest.

make test

testEnv := &envtest.Environment{
    CRDDirectoryPaths: []string{filepath.Join("..", "..", "config", "crd", "bases")},
}
cfg, err := testEnv.Start()

• Projetos Kubebuilder incluem configuração do envtest em suite_test.go.
• make test executa go test com CRDs carregados em um plano de controle local.
• Adicione asserções de reconciliação com o cliente envtest antes de enviar.

Relacionado: Testando Operadores com envtest e cliente fake - padrões de cliente fake

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, 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).