# 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](https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/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.

Dica [Managed Kubernetes](https://cloud.ionos.com/managed/kubernetes "Managed Kubernetes — IONOS") na IONOS Cloud, é uma poderosa plataforma para aplicações baseadas em contêineres. Sua distribuição georredundante garante máxima disponibilidade e alta resiliência. Com funções de controle integradas e atualizações automatizadas, o Managed Kubernetes da IONOS possibilita configurações seguras e eficientes no ambiente de produção.

## 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](https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/criar-kubernetes-pod/). 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:

```yaml
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:

```shell
kubectl get pods -l app=statefulset-label
```

A saída esperada deverá conter:

```shell
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.

```shell
kubectl get pods
```

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

```shell
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:

```shell
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:

```yaml
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:

```shell
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:

```shell
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](https://www.ionos.com/digitalguide/server/configuration/kubernetes-tutorial/ "Tutorial Kubernetes"), você encontrará instruções detalhadas e práticas para configurar clusters Kubernetes.


This is a markdown version of: [https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/kubernetes-statefulset/](https://www.ionos.com/pt-br/digitalguide/servidor/configuracao/kubernetes-statefulset/) for AI/LLM consumption.