Tutorial: Como criar e depurar Ku­ber­ne­tes Sta­te­ful­Set

A cada pod no Ku­ber­ne­tes Sta­te­ful­Set é atribuído um hostname exclusivo e estável, além de uma iden­ti­dade DNS completa. Essa iden­ti­dade é pre­ser­vada durante rei­ni­ci­a­li­za­ções e ajustes de escala.

O que é Ku­ber­ne­tes Sta­te­ful­Set?

O Ku­ber­ne­tes Sta­te­ful­Set é o recurso es­pe­ci­a­li­zado em gerenciar apli­ca­ções com re­qui­si­tos es­pe­cí­fi­cos de dados per­sis­ten­tes e iden­ti­da­des fixas. Ele garante que pods com réplicas sejam iniciados em uma ordem es­pe­cí­fica, além de atribuir a cada Ku­ber­ne­tes pod, uma ID única e pos­si­bi­li­tar acessos ao ar­ma­ze­na­mento per­sis­tente. Essas funções são úteis em bancos de dados que dependem de relações estáveis entre ins­tân­cias e que precisam armazenar dados de forma duradoura. O Sta­te­ful­Set é, portanto, uma solução eficaz para a or­ques­tra­ção e a operação de apli­ca­ções complexas no Ku­ber­ne­tes.

Criar Ku­ber­ne­tes Sta­te­ful­Set

Primeiro, comece com a definição de um arquivo de con­fi­gu­ra­ção YAML. Lá, es­ta­be­leça as pro­pri­e­da­des desejadas do Sta­te­ful­Set e crie pods Ku­ber­ne­tes. Fi­na­li­zada a con­fi­gu­ra­ção, o Sta­te­ful­Set mo­ni­to­rará con­ti­nu­a­mente o status do cluster e ve­ri­fi­cará o número, a dis­po­ni­bi­li­dade e o fun­ci­o­na­mento dos pods pre­de­fi­ni­dos. Caso um pod falhe ou seja removido de um nó, o Sta­te­ful­Set re­co­nhe­cerá au­to­ma­ti­ca­mente a situação e iniciará o pro­vi­si­o­na­mento de um novo pod, com a mesma ID exclusiva. Esse novo pod será conectado ao ar­ma­ze­na­mento per­sis­tente já existente e receberá a mesma con­fi­gu­ra­ção que o pod original, incluindo so­li­ci­ta­ções e limites de recursos.

Um ge­ren­ci­a­mento preciso de pods e iden­ti­da­des é essencial para que clientes, que antes estavam sendo atendidos pelo pod agora in­dis­po­ní­vel, possam ser re­di­re­ci­o­na­dos para o novo pod, sem in­ter­rup­ções. O acesso ao ar­ma­ze­na­mento per­sis­tente garante que as operações continuem inin­ter­rup­ta­mente.

Observe abaixo um arquivo YAML completo que contém o passo a passo para criar um Ku­ber­ne­tes Sta­te­ful­Set 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 Ku­ber­ne­tes Sta­te­ful­Set para o Nginx com três réplicas. Ele usa um objeto de serviço de nome nginx e rótulos para iden­ti­fi­car cor­re­ta­mente os pods. Os pods, por sua vez, usam a imagem mais recente do Nginx e têm dois volumes montados: um para a con­fi­gu­ra­ção e outro para os arquivos HTML. Vo­lu­me­Claim­Tem­pla­tes garantem o ar­ma­ze­na­mento per­sis­tente dos volumes, ca­pa­ci­dade de 1 GB e acesso con­fi­gu­rado como Re­ad­Wri­te­Once.

Depurar Ku­ber­ne­tes Sta­te­ful­Set

A depuração de Ku­ber­ne­tes Sta­te­ful­Sets demanda etapas es­pe­cí­fi­cas para verificar se os pods foram ini­ci­a­li­za­dos cor­re­ta­mente e, se ne­ces­sá­rio, iden­ti­fi­car 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 Sta­te­ful­Set 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 Sta­te­ful­Set, e um número se­quen­cial.
• PRONTO: Indica quantos, dos con­têi­ne­res 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 rei­ni­ci­ado no pod. O valor 0 significa que nenhuma rei­ni­ci­a­li­za­ção foi realizada ainda.
• IDADE: Indica há quanto tempo o pod está em execução.

Alguns re­sul­ta­dos, contudo, podem indicar falhas:

• Failed (Falhou): Um ou mais con­têi­ne­res no pod falharam devido a problemas como de­pen­dên­cias ausentes ou con­fi­gu­ra­ções in­cor­re­tas.
• Unknown (Des­co­nhe­cido): O estado do pod não pôde ser de­ter­mi­nado. Pode indicar problemas de co­mu­ni­ca­ção entre o cluster Ku­ber­ne­tes e o pod, como falhas de rede ou per­mis­sões ina­de­qua­das.

Em ambos os casos, re­co­men­da­mos o uso de fer­ra­men­tas de di­ag­nós­tico, como a de ve­ri­fi­ca­ção de logs do pod ou o comando kubectl describe pod, para que você possa obter mais detalhes sobre o erro e iden­ti­fi­car suas causas.

Passo 2: Depurar pods in­di­vi­du­ais

Adicionar anotações a um pod pode ser uma fer­ra­menta de depuração útil, que in­flu­en­ci­ará o processo de ini­ci­a­li­za­ção ou acionará ações es­pe­cí­fi­cas.

Primeiro, você deve iden­ti­fi­car o nome do pod que deseja depurar.

kubectl get pods

Use o seguinte comando no terminal para adicionar uma anotação ao pod se­le­ci­o­nado:

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 ini­ci­a­li­zado. Monitore o pod para observar como essa alteração impactará o com­por­ta­mento do pod.

Mais es­pe­ci­fi­ca­mente, 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 ocor­rên­cia de problemas durante o processo de ini­ci­a­li­za­ção. Quando a depuração estiver concluída e você quiser restaurar o processo normal de ini­ci­a­li­za­ção, basta definir a anotação de volta para true.

Passo 3: Ini­ci­a­li­za­ção em etapas

Se a depuração do pod com as técnicas descritas an­te­ri­or­mente não for bem-sucedida, pode ser que algo esteja errado com as condições de corrida do bootstrap do Ku­ber­nen­tes Sta­te­ful­Set. Para resolver esse problema, você deve es­pe­ci­fi­car initialized="false" no manifesto do Sta­te­ful­Set 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 atu­a­li­zado no seu cluster Ku­ber­ne­tes:

kubectl apply -f statefulset.yaml

Ins­pe­ci­one os pods e iden­ti­fi­que possíveis fontes de erro. Execute as medidas de depuração ne­ces­sá­rias, com base nos eventos e logs ob­ser­va­dos. Se ne­ces­sá­rio, exclua o Sta­te­ful­Set com o comando kubectl delete statefulsets. Para remover serviços as­so­ci­a­dos, utilize o comando kubectl delete service.

Depois de concluir a depuração, você poderá restaurar a anotação de ini­ci­a­li­za­ção e atualizar o Ku­ber­ne­tes Sta­te­ful­Set no cluster:

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

O comando acima define a anotação de ini­ci­a­li­za­ção de um pod como true, ga­ran­tindo que os valores exis­ten­tes sejam so­bres­cri­tos. Depois de verificar o primeiro pod, o Ku­ber­ne­tes Sta­te­ful­Set irá au­to­ma­ti­ca­mente ini­ci­a­li­zar o próximo pod. Você pode repetir os passos de depuração para cada pod adicional.

No nosso tutorial Ku­ber­ne­tes, você en­con­trará ins­tru­ções de­ta­lha­das e práticas para con­fi­gu­rar clusters Ku­ber­ne­tes.