Todos os produtos
Search
Central de documentação

Container Service for Kubernetes:Use a StatefulSet to create a stateful application

Última atualização: Jun 27, 2026

Diferentemente dos Deployments, os StatefulSets mantêm a identidade de cada pod durante reinicializações, o que os torna a escolha ideal para bancos de dados, filas de mensagens e sistemas de armazenamento distribuído. Este tópico descreve o funcionamento dos StatefulSets e como criar um no Container Service for Kubernetes (ACK).

Após concluir este tópico, você saberá:

  • Explicar as três garantias de identidade fornecidas pelos StatefulSets

  • Criar um StatefulSet pelo console do ACK ou kubectl

  • Verificar se os pods retêm seus nomes e identidades de rede após a exclusão

Como funcionam os StatefulSets

Um StatefulSet gerencia um número fixo de pods, assim como um Deployment. A diferença é que os StatefulSets atribuem a cada pod uma identidade estável e persistente que sobrevive a reinicializações e reagendamentos. Essa identidade possui três componentes:

Nomes de pod ordenados

Os pods recebem nomes no formato <StatefulSet name>-<serial number>, começando em 0. Um StatefulSet chamado db-app com duas réplicas cria os pods db-app-0 e db-app-1. Se um pod for excluído e recriado, ele receberá o mesmo nome.

Identidade de rede estável

Associe um headless Service ao StatefulSet definindo spec.serviceName como o nome do Service. O headless Service atribui a cada pod um nome DNS estável no seguinte formato:

<pod name>.<headless Service name>.<namespace>.svc.<ClusterDomain>

Por exemplo: db-app-01.db-app.default.svc.cluster.local

Ao contrário de um Service padrão, um headless Service não faz balanceamento de carga de tráfego — ele retorna os endereços IP de todos os pods de backend diretamente nas consultas DNS. Quando um pod é recriado, seu nome DNS resolve automaticamente para o novo endereço IP do pod.

Armazenamento persistente estável

Defina um modelo de persistent volume claim (PVC) em spec.volumeClaimTemplates. O StatefulSet cria automaticamente um PVC separado para cada pod, nomeado como <PVC template name>-<pod name>. Quando um pod é excluído, seu PVC é retido. Ao recriar o pod com o mesmo número de série, o PVC é reconectado automaticamente.

Juntas, essas três garantias asseguram que um pod recriado retome exatamente de onde o original parou — mesmo nome, mesmo endereço DNS e mesmos dados persistentes.

Para obter a especificação completa do StatefulSet, consulte StatefulSets.

Limitações

Antes de usar StatefulSets, observe os seguintes pontos:

  • Headless Service obrigatório. Crie o headless Service manualmente — o ACK não o cria automaticamente. Sem ele, os pods não terão nomes DNS estáveis.

  • PVCs não são excluídos com o StatefulSet. Excluir um StatefulSet não remove os PVCs criados por ele. Limpe os PVCs manualmente após excluir um StatefulSet para evitar custos inesperados de armazenamento.

  • Criação e exclusão ordenada de pods. Por padrão, o pod N+1 só inicia quando o pod N estiver Running e Ready. Da mesma forma, o pod N+1 é encerrado antes do pod N. Reduza o StatefulSet para 0 antes da exclusão para garantir um desligamento limpo e ordenado.

Pré-requisitos

Antes de começar, certifique-se de ter:

Para criação via kubectl, você também precisa de:

Criar um StatefulSet

Criar pelo console

  1. Faça login no console do ACK. No painel de navegação à esquerda, clique em Clusters.

  2. Na página Clusters, clique no nome do cluster. No painel à esquerda, escolha Workloads > StatefulSets.

  3. No canto superior esquerdo da página StatefulSets, clique em Create from Image.

  4. Na etapa Basic Information, configure as definições básicas da aplicação. Clique em Next.

  5. Na etapa Container, configure Image Name e Port. Mantenha os demais parâmetros com seus valores padrão. Para Image Name, use:

    Importante

    O cluster deve ter acesso à Internet para baixar esta imagem. Se você manteve o valor padrão para Configure SNAT for VPC ao criar o cluster, o acesso à Internet já está habilitado. Para clusters existentes, consulte Habilitar o acesso à Internet em um cluster ACK existente.

    registry.cn-hangzhou.aliyuncs.com/acs-sample/nginx:latest

    Clique em Next.

    image

  6. Na etapa Advanced, vá até a seção Access Control. Crie um Service do tipo Cluster IP, selecione Headless Service e clique em OK. Em seguida, clique em Create.

    image

Os parâmetros nas etapas Basic Information, Container e Advanced são os mesmos de um Deployment. Para detalhes sobre todos os parâmetros, consulte Parâmetros.

Criar com kubectl

  1. Crie um arquivo chamado statefulset.yaml e cole o conteúdo abaixo. O manifesto define três recursos:

    • Um headless Service chamado nginx, que fornece nomes DNS estáveis para os pods

    • Um StatefulSet chamado nginx-test com um volume hostPath montado

    • Um LoadBalancer Service chamado nginx-test-svc, usado para verificar o acesso ao StatefulSet

    apiVersion: v1
    kind: Service
    metadata:
      name: nginx
      labels:
        app: nginx
    spec:
      clusterIP: None  # Headless Service
      selector:
        app: nginx
      ports:
      - port: 80
        name: http
    ---
    apiVersion: apps/v1
    kind: StatefulSet   # The workload type.
    metadata:
      name: nginx-test
      namespace: default  # Change the namespace as needed.
      labels:
        app: nginx
    spec:
      serviceName: "nginx" # Specify the name of the headless Service you created.
      replicas: 2  # Specify the number of pods.
      selector:
        matchLabels:
          app: nginx
      template: # The pod configurations.
        metadata:
          labels: # The pod labels.
            app: nginx
        spec:
          containers:
          - name: nginx  # The name of the container.
            image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6  # The version of the NGINX image.
            ports:
            - containerPort: 80  # The port exposed by the container.
              protocol: TCP  # Set the protocol to TCP or UDP.
            volumeMounts:
            - name: node-dir-volume  # The volume name. The value must be the same as the volume name specified in the following volumes section.
              mountPath: /tmp  # The mount path of the volume in the container.
          volumes:
          - name: node-dir-volume
            hostPath:
              path: /local_storage  # The directory on the host that you want to mount as a volume.
              type: DirectoryOrCreate     # If the specified directory does not exist, the system automatically creates the directory.
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: nginx-test-svc
      namespace: default  # Change the namespace as needed.
      labels:
        app: nginx
    spec:
      selector:
        app: nginx  # The label used to match backend pods.
      ports:
        - port: 80           # The port provided by the Service in the cluster.
          targetPort: 80     # The port on which the application in the container listens (containerPort).
          protocol: TCP      # The protocol. Default value: TCP.
      type: LoadBalancer      # The Service type. Default value: ClusterIP. ClusterIP Services are accessible from within the cluster.
  2. Aplique o manifesto:

    kubectl apply -f statefulset.yaml

    Saída esperada:

    service/nginx created
    statefulset.apps/nginx-test created
    service/nginx-test-svc created
  3. Obtenha o endereço IP público do LoadBalancer Service:

    kubectl get svc

    Saída esperada:

    NAME            TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)        AGE
    kubernetes      ClusterIP      172.16.**.***    <none>          443/TCP        4h47m
    nginx           ClusterIP      None             <none>          80/TCP         1h10m
    nginx-test-svc  LoadBalancer   172.16.**.***    106.14.**.***   80:31130/TCP   1h10m
  4. Abra um navegador e acesse o endereço IP externo (106.14..*) para confirmar que o contêiner NGINX está acessível.

    image

Verificar as garantias do StatefulSet

Esta seção demonstra que, quando um pod é excluído, o StatefulSet o recria com o mesmo nome — comprovando a garantia de identidade estável.

  1. Verifique o status do pod nginx-test-0:

    kubectl get pod nginx-test-0

    Saída esperada:

    NAME           READY   STATUS    RESTARTS   AGE
    nginx-test-0   1/1     Running   0          7m41s
  2. Exclua o pod:

    kubectl delete pod nginx-test-0

    Saída esperada:

    pod "nginx-test-0" deleted
  3. Consulte o pod novamente:

    kubectl get pod nginx-test-0

    Saída esperada:

    NAME           READY   STATUS    RESTARTS   AGE
    nginx-test-0   1/1     Running   0          20s

    O pod está em execução novamente com o nome original nginx-test-0. O valor de AGE é reiniciado porque se trata de um novo pod, mas seu nome e número de série são preservados.

Próximos passos