Gerador K8s StatefulSet

Gerador YAML de Kubernetes StatefulSet e Headless Service

Gere manifestos de Kubernetes StatefulSet prontos para produção com Headless Service complementar, volumeClaimTemplates persistentes, réplicas e podManagementPolicy.

Predefinições
Configuração de StatefulSet e serviço
Pods com ordinal >= partition serão atualizados primeiro (Canary)
Número de pods indisponíveis durante a implementação
:
:
# ============================================================================
# Kubernetes StatefulSet: postgres-ha
# Generated via ToolsAA - 100% Client-Side Stateful Workload Builder
# Headless Network Domain: postgres-ha-headless.database.svc.cluster.local
# Pod Stable FQDN: postgres-ha-[0..2].postgres-ha-headless.database.svc.cluster.local
# ============================================================================
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres-ha
  namespace: database
  labels:
    app: "postgres-ha"
    tier: "database"
    app.kubernetes.io/managed-by: toolsaa
  annotations:
    cluster.toolsaa.com/role: "primary-replica"
spec:
  serviceName: "postgres-ha-headless"
  replicas: 3
  podManagementPolicy: OrderedReady
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 0
      maxUnavailable: 1
  revisionHistoryLimit: 10
  minReadySeconds: 10
  persistentVolumeClaimRetentionPolicy:
    whenDeleted: Retain
    whenScaled: Retain
  selector:
    matchLabels:
      app: "postgres-ha"
  template:
    metadata:
      labels:
        app: "postgres-ha"
        tier: "database"
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "9187"
    spec:
      serviceAccountName: postgres-sa
      terminationGracePeriodSeconds: 120
      securityContext:
        runAsNonRoot: true
        runAsUser: 999
        runAsGroup: 999
        fsGroup: 999
        fsGroupChangePolicy: "OnRootMismatch"
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchExpressions:
                - key: app
                  operator: In
                  values: ["postgres-ha"]
              topologyKey: "kubernetes.io/hostname"
      nodeSelector:
        node-role.kubernetes.io/database: "true"
      containers:
      - name: postgres
        image: postgres:16-alpine
        imagePullPolicy: IfNotPresent
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop:
            - ALL
        ports:
        - name: postgresql
          containerPort: 5432
          protocol: TCP
        env:
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: POD_IP
          valueFrom:
            fieldRef:
              fieldPath: status.podIP
        - name: POSTGRES_DB
          value: "app_production"
        - name: POSTGRES_USER
          value: "postgres"
        - name: PGDATA
          value: "/var/lib/postgresql/data/pgdata"
        resources:
          requests:
            cpu: "500m"
            memory: "1Gi"
          limits:
            cpu: "2000m"
            memory: "4Gi"
        volumeMounts:
        - name: pgdata
          mountPath: "/var/lib/postgresql/data"
        livenessProbe:
          exec:
            command:
            - "pg_isready"
            - "-U"
            - "postgres"
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
          successThreshold: 1
          failureThreshold: 3
        readinessProbe:
          exec:
            command:
            - "pg_isready"
            - "-U"
            - "postgres"
            - "-h"
            - "127.0.0.1"
          initialDelaySeconds: 15
          periodSeconds: 5
          timeoutSeconds: 3
          successThreshold: 1
          failureThreshold: 3
        startupProbe:
          exec:
            command:
            - "pg_isready"
            - "-U"
            - "postgres"
          initialDelaySeconds: 10
          periodSeconds: 5
          timeoutSeconds: 3
          successThreshold: 1
          failureThreshold: 15
  volumeClaimTemplates:
  - metadata:
      name: pgdata
      labels:
        app: "postgres-ha"
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: "gp3"
      resources:
        requests:
          storage: 50Gi
Réplicas com estadoOrderedReady
3 Pods com estado

Partição: 0 | Estratégia: RollingUpdate

Modelos de PVCgp3
50Gi / pod (1 modelos)

Retenção: Retain | fsGroup:: 999

Postura de blindagemGrau de segurança A+
100 / 100 Prontidão

Sondas: 3/3 ativas

Geração de manifestos 100% no navegador

Zero envio para servidores externos ou rastreamento. Todos os manifestos de StatefulSet, serviços headless e modelos de PVC são gerados diretamente na memória do navegador.

Ciclo de vida ordenado e identidade DNS estável

Garante identidades ordinais exclusivas, resolução DNS estável com Headless Service, controle de ciclo de vida OrderedReady e modelos de volume persistente.

Segurança padrão CIS e exportação multiformato

Impõe contextos de segurança não-root, eliminação de privilégios e gera saídas prontas para produção em Helm, Kustomize e comandos da CLI kubectl.

Referência técnica e guia de arquitetura

Guia do Desenvolvedor do Gerador de YAML de Kubernetes StatefulSet & Headless Service — Guia de referência

Gere manifestos de Kubernetes StatefulSet prontos para produção com Headless Service complementar, volumeClaimTemplates persistentes, réplicas e podManagementPolicy.

Parâmetros principais e controles

spec.serviceNamestring

Nome do Headless Service complementar (clusterIP: None) responsável pela identidade de rede e roteamento DNS SRV dos ordinais dos pods.

Padrão: Obrigatório
spec.replicasinteger

Número desejado de pods com estado (0 a N-1) criados sequencialmente em ordem crescente.

Padrão: 3
spec.podManagementPolicyenum (OrderedReady | Parallel)

Política de ciclo de vida de pods. 'OrderedReady' inicia pods individualmente aguardando o status Ready; 'Parallel' cria ou encerra todos os pods simultaneamente.

Padrão: OrderedReady
spec.volumeClaimTemplatesarray of objects

Modelos de PersistentVolumeClaim para provisionamento dinâmico de volumes persistentes exclusivos para cada índice de pod ordinal.

Padrão: Obrigatório
spec.updateStrategyobject

Estratégia de atualização contínua automatizada com parâmetro 'partition' opcional para canary ou 'OnDelete' manual.

Padrão: RollingUpdate

Dicas profissionais e melhores práticas

Um StatefulSet requer um Headless

Um StatefulSet requer um Headless Service com 'clusterIP: None'. O CoreDNS registra automaticamente entradas A/AAAA e SRV estáveis no padrão '<nome-do-pod>.<nome-do-servico>.<namespace>.svc.cluster.local', essencial para topologias líder-seguidor e consenso Raft.

Configure

Configure 'spec.updateStrategy.rollingUpdate.partition' com o valor réplicas - 1 para testar uma nova imagem exclusivamente no pod de maior índice ordinal (ex.: statefulset-2) como canary antes de atualizar todo o cluster.

O Kubernetes não remove

O Kubernetes não remove automaticamente os PVCs criados por volumeClaimTemplates ao reduzir réplicas ou excluir o StatefulSet. Novos pods reutilizam os volumes correspondentes ao seu índice ordinal. A partir do K8s 1.27, a política 'persistentVolumeClaimRetentionPolicy' permite controle declarativo.

Aplicações de estado distribuído como

Aplicações de estado distribuído como ZooKeeper, Kafka ou Cassandra exigem quórum estável. Sempre vincule um PodDisruptionBudget com 'minAvailable: 2' ou 'maxUnavailable: 1' para impedir que drenagens de nós causem partições de rede ou indisponibilidade crítica.

Problemas comuns e solução de problemas

Pod permanece travado em Pending com erro 'persistentvolumeclaim unbound'

Execute 'kubectl describe pvc <nome-do-pvc>'. Verifique se a storageClassName indicada existe no cluster, se o driver CSI de provisionamento dinâmico está operante e se os accessModes (como ReadWriteOnce) são suportados pela infraestrutura de armazenamento.

A atualização ou escalabilidade do StatefulSet congela em um pod ordinal específico

Com a política 'OrderedReady', o Kubernetes interrompe o progresso se o pod ordinal anterior falhar na readinessProbe. Verifique os eventos do pod com 'kubectl describe pod <nome>' e corrija problemas nos testes de saúde da aplicação.

Descoberta de peers entre pods falha com erro 'NXDOMAIN' no hostname do Headless Service

Certifique-se de que 'spec.serviceName' no StatefulSet seja idêntico ao 'metadata.name' do Headless Service, que o serviço defina 'clusterIP: None' e que os seletores de rótulos coincidam exatamente em ambos os recursos.

Perguntas frequentes (FAQ)

Qual é a principal diferença entre um Deployment e um StatefulSet no Kubernetes?▼

Um Deployment gerencia pods sem estado intercambiáveis, com sufixos aleatórios e armazenamento efêmero ou compartilhado. Já o StatefulSet oferece nomes ordinais fixos e previsíveis (app-0, app-1), ordem determinística de inicialização e desligamento, volumes persistentes exclusivos por réplica e identidades de rede DNS estáveis através de um Headless Service.

Por que um StatefulSet exige obrigatoriamente um Headless Service ('clusterIP: None')?▼

Services comuns associam um IP virtual único (VIP) que distribui o tráfego aleatoriamente entre pods aptos. No entanto, sistemas de banco de dados distribuídos necessitam comunicar-se ponto a ponto com nós específicos (como nós primários ou réplicas de leitura). O Headless Service dispensa o VIP e gera registros DNS A diretos para o IP de cada pod.

O que acontece com os PersistentVolumeClaims (PVCs) quando um StatefulSet é reduzido ou excluído?▼

Por padrão, o Kubernetes nunca remove automaticamente os PVCs criados por volumeClaimTemplates para resguardar a integridade dos dados. Ao escalar o StatefulSet novamente, os novos pods reconectam-se aos volumes preexistentes correspondentes. A remoção de volumes não mais necessários deve ser feita manualmente via 'kubectl delete pvc'.

Quando se deve utilizar 'podManagementPolicy: Parallel' em vez de 'OrderedReady'?▼

Utilize 'Parallel' em aplicações distribuídas que implementam sua própria descoberta de topologia e consenso de forma desacoplada, sem depender da inicialização sequencial ordenada, ou quando se deseja escalabilidade e atualizações rápidas simultâneas.

Como funciona o parâmetro 'updateStrategy.rollingUpdate.partition'?▼

O parâmetro partition define um limiar ordinal. Apenas pods com índice ordinal maior ou igual a esse valor são atualizados. Se você definir partition como réplicas - 1, somente o último pod receberá a nova imagem para testes canary. Diminuir a partição progressivamente até 0 atualiza todo o cluster.

Ferramentas e utilitários relacionados

Todas as ferramentas →