Tutorial: Como criar e depurar Kubernetes StatefulSet

A cada pod no Kubernetes StatefulSet é atribuído um hostname exclusivo e estável, além de uma identidade DNS completa. Essa identidade é preservada durante reinicializações e ajustes de escala.

O que é Kubernetes StatefulSet?

O Kubernetes StatefulSet é o recurso especializado em gerenciar aplicações com requisitos específicos de dados persistentes e identidades fixas. Ele garante que pods com réplicas sejam iniciados em uma ordem específica, além de atribuir a cada Kubernetes pod, uma ID única e possibilitar acessos ao armazenamento persistente. Essas funções são úteis em bancos de dados que dependem de relações estáveis entre instâncias e que precisam armazenar dados de forma duradoura. O StatefulSet é, portanto, uma solução eficaz para a orquestração e a operação de aplicações complexas no Kubernetes.

Criar Kubernetes StatefulSet

Primeiro, comece com a definição de um arquivo de configuração YAML. Lá, estabeleça as propriedades desejadas do StatefulSet e crie pods Kubernetes. Finalizada a configuração, o StatefulSet monitorará continuamente o status do cluster e verificará o número, a disponibilidade e o funcionamento dos pods predefinidos. Caso um pod falhe ou seja removido de um nó, o StatefulSet reconhecerá automaticamente a situação e iniciará o provisionamento de um novo pod, com a mesma ID exclusiva. Esse novo pod será conectado ao armazenamento persistente já existente e receberá a mesma configuração que o pod original, incluindo solicitações e limites de recursos.

Um gerenciamento preciso de pods e identidades é essencial para que clientes, que antes estavam sendo atendidos pelo pod agora indisponível, possam ser redirecionados para o novo pod, sem interrupções. O acesso ao armazenamento persistente garante que as operações continuem ininterruptamente.

Observe abaixo um arquivo YAML completo que contém o passo a passo para criar um Kubernetes StatefulSet para o Nginx:

apiVersion: apps/v1
kind: StatefulSet
metadata:
    name: nginx-statefulset
spec:
    serviceName: nginx
    replicas: 3
    selector:
        matchLabels:
            app: nginx
    template:
        metadata:
            labels:
                app: nginx
        spec:
            containers:
            - name: nginx
                image: nginx:latest
                volumeMounts:
                - name: nginx-config
                    mountPath: /etc/nginx/conf.d
                - name: nginx-html
                    mountPath: /usr/share/nginx/html
volumeClaimTemplates:
- metadata:
        name: nginx-html
    spec:
        accessModes: [ "ReadWriteOnce" ]
        resources:
            requests:
                storage: 1Gi
- metadata:
        name: nginx-config
    spec:
        accessModes: [ "ReadWriteOnce" ]
        resources:
            requests:
                storage: 1Gi

Esse arquivo YAML define um Kubernetes StatefulSet para o Nginx com três réplicas. Ele usa um objeto de serviço de nome nginx e rótulos para identificar corretamente os pods. Os pods, por sua vez, usam a imagem mais recente do Nginx e têm dois volumes montados: um para a configuração e outro para os arquivos HTML. VolumeClaimTemplates garantem o armazenamento persistente dos volumes, capacidade de 1 GB e acesso configurado como ReadWriteOnce.

Depurar Kubernetes StatefulSet

A depuração de Kubernetes StatefulSets demanda etapas específicas para verificar se os pods foram inicializados corretamente e, se necessário, identificar e corrigir erros.

Passo 1: Listar pods

Antes de iniciar a depuração, você deve verificar o status dos pods.

Abra o terminal e use o seguinte comando para listar todos os pods no StatefulSet desejado:

kubectl get pods -l app=statefulset-label

A saída esperada deverá conter:

NOME                        PRONTO STATUS    REINICIAR   IDADE
nginx-statefulset-0           1/1      Em execução      0       2m
nginx-statefulset-1           1/1      Em execução       0       1m
nginx-statefulset-2           1/1      Em execução      0       1m

• NOME: Cada pod recebe um nome exclusivo, baseado no esquema de nomes do StatefulSet, e um número sequencial.
• PRONTO: Indica quantos, dos contêineres desejados no pod, estão prontos. No exemplo, cada pod possui um contêiner, e 1/1 significa que o contêiner está pronto para uso.
• STATUS: Indica o status atual do pod.
• REINICIAR: Indica quantas vezes o contêiner foi reiniciado no pod. O valor 0 significa que nenhuma reinicialização foi realizada ainda.
• IDADE: Indica há quanto tempo o pod está em execução.

Alguns resultados, contudo, podem indicar falhas:

• Failed (Falhou): Um ou mais contêineres no pod falharam devido a problemas como dependências ausentes ou configurações incorretas.
• Unknown (Desconhecido): O estado do pod não pôde ser determinado. Pode indicar problemas de comunicação entre o cluster Kubernetes e o pod, como falhas de rede ou permissões inadequadas.

Em ambos os casos, recomendamos o uso de ferramentas de diagnóstico, como a de verificação de logs do pod ou o comando kubectl describe pod, para que você possa obter mais detalhes sobre o erro e identificar suas causas.

Passo 2: Depurar pods individuais

Adicionar anotações a um pod pode ser uma ferramenta de depuração útil, que influenciará o processo de inicialização ou acionará ações específicas.

Primeiro, você deve identificar o nome do pod que deseja depurar.

kubectl get pods

Use o seguinte comando no terminal para adicionar uma anotação ao pod selecionado:

kubectl annotate pods [pod-name] pod.alpha.kubernetes.io/initialized="false" --overwrite

Substitua [pod-name] pelo nome real do pod. Isso marcará o pod como não inicializado. Monitore o pod para observar como essa alteração impactará o comportamento do pod.

Mais especificamente, você pode verificar eventos e logs do pod:

kubectl describe pod [pod-name]
kubectl logs [pod-name]

Procure por eventos ou saídas de logs que possam indicar a ocorrência de problemas durante o processo de inicialização. Quando a depuração estiver concluída e você quiser restaurar o processo normal de inicialização, basta definir a anotação de volta para true.

Passo 3: Inicialização em etapas

Se a depuração do pod com as técnicas descritas anteriormente não for bem-sucedida, pode ser que algo esteja errado com as condições de corrida do bootstrap do Kubernentes StatefulSet. Para resolver esse problema, você deve especificar initialized="false" no manifesto do StatefulSet e, em seguida, criá-lo com essa anotação no cluster:

apiVersion: apps/v1
kind: StatefulSet
metadata:
    name: [statefulset-name]
spec:
    template:
        metadata:
            annotations:
                pod.alpha.kubernetes.io/initialized: "false"
        ...

Aplique o manifesto atualizado no seu cluster Kubernetes:

kubectl apply -f statefulset.yaml

Inspecione os pods e identifique possíveis fontes de erro. Execute as medidas de depuração necessárias, com base nos eventos e logs observados. Se necessário, exclua o StatefulSet com o comando kubectl delete statefulsets. Para remover serviços associados, utilize o comando kubectl delete service.

Depois de concluir a depuração, você poderá restaurar a anotação de inicialização e atualizar o Kubernetes StatefulSet no cluster:

kubectl annotate pods [pod-name] pod.alpha.kubernetes.io/initialized="true" --overwrite

O comando acima define a anotação de inicialização de um pod como true, garantindo que os valores existentes sejam sobrescritos. Depois de verificar o primeiro pod, o Kubernetes StatefulSet irá automaticamente inicializar o próximo pod. Você pode repetir os passos de depuração para cada pod adicional.

No nosso tutorial Kubernetes, você encontrará instruções detalhadas e práticas para configurar clusters Kubernetes.