Docker Swarm: Guia Completo de Configuração e Deploy

Visão Geral do Docker Swarm

O Docker Swarm é a ferramenta nativa de orquestração de containers do ecossistema Docker, projetada para transformar um grupo de máquinas isoladas em um único cluster lógico e unificado. Diferente do Docker Engine padrão, que gerencia containers individualmente em um único host, o Swarm permite que você gerencie múltiplos servidores como se fossem um único recurso computacional. Essa capacidade de orquestração é fundamental para arquiteturas modernas que exigem alta disponibilidade e escalabilidade horizontal, permitindo que aplicações web sobrevivam à falha de instâncias individuais de hardware.

No coração do funcionamento do Swarm está o conceito de Manager Nodes (Nós Gerenciadores) e Worker Nodes (Nós de Trabalho). O Manager Node é o cérebro do cluster; ele é responsável por manter o estado desejado da aplicação, receber comandos de API, gerenciar o agendamento de tarefas e garantir a consistência do cluster através de um algoritmo de consenso chamado Raft. Já os Worker Nodes são os braços executores, dedicados exclusivamente a rodar os containers (chamados de Tasks dentro do contexto de Swarm) conforme as instruções recebidas do gerenciador.

Um dos grandes diferenciais técnicos do Docker Swarm é a implementação do Routing Mesh (Malha de Roteamento). Quando você publica um serviço em uma porta específica do cluster, o Swarm utiliza um mecanismo de rede virtual que permite que qualquer nó do cluster receba o tráfego destinado àquela porta e o encaminhe internamente para o container correto, independentemente de onde ele esteja rodando. Isso elimina a necessidade de configurar balanceadores de carga externos complexos para cada nova instância de container, simplificando drasticamente a infraestrutura de rede.

Ao utilizar o Swarm, você deixa de gerenciar containers isolados e passa a gerenciar Services (Serviços). Um serviço define qual imagem utilizar, quantas réplicas devem estar rodando e quais recursos de rede estão disponíveis. Se um container falhar ou um servidor inteiro cair, o orquestrador detecta a discrepância entre o estado atual e o estado desejado, reiniciando automaticamente as tarefas em nós saudáveis para garantir que sua aplicação web permaneça online sem intervenção manual.

Conceitos de Orquestração e Cluster

A orquestração de containers é o processo de automatizar o ciclo de vida de aplicações implantadas em containers, gerenciando desde o provisionamento de recursos até a manutenção da saúde do serviço. Em um ambiente de produção, rodar um único container via docker run é insuficiente para garantir a continuidade do negócio. É aqui que entra o conceito de cluster, que é um grupo de máquinas (nós) que trabalham de forma coordenada para que pareçam um único recurso computacional gigante. O Docker Swarm transforma instâncias isoladas de Docker em um ecossistema unificado.

Para entender como o Swarm opera, precisamos distinguir os papéis fundamentais dentro do cluster:

• Manager Nodes: São o céreador do cluster. Eles são responsáveis pelo gerenciamento do estado do cluster, recebem as ordens de deploy, agendam os serviços nos nós disponíveis e mantêm o consistência dos dados através de um log de replicated state machine. Se um Manager falha, o cluster pode perder a capacidade de gerenciar novos serviços, mas os containers existentes continuam rodando.
• Worker Nodes: São os executores. A única função destes nós é receber as tarefas (tasks) enviadas pelo Manager e garantir que o container esteja rodando conforme a definição. Eles não tomam decisões de escalonamento, apenas processam a carga de trabalho.
• Services: Diferente de um container comum, um serviço no Swarm define o "estado desejado". Se você define que um serviço web deve ter 5 réplicas, o orquestrador monitora constantemente se essas 5 instâncias estão ativas.
• Tasks: É a menor unidade de trabalho. Quando você implanta um serviço, o Swarm quebra esse serviço em tarefas individuais, que são os containers propriamente ditos sendo executados em um nó específico.

O grande diferencial da orquestração é a auto-recuperação (self-healing). Se um Worker Node sofrer uma queda de energia ou falha de hardware, o Manager detecta a perda de conectividade e reatribui as tasks que estavam naquele nó para outros nós saudáveis do cluster. Além disso, o Swarm utiliza uma rede Overlay, que permite que containers situados em servidores físicos diferentes se comuniquem como se estivessem na mesma rede local, facilitando a criação de arquiteturas de microserviços distribuídas e altamente escaláveis.

Pré-requisitos do Ambiente

Para implementar um cluster Docker Swarm robusto e funcional, a infraestrutura de base deve atender a requisitos rigorosos de rede, software e hardware. A falha em qualquer um desses pontos pode impedir a comunicação entre os nós ou causar instabilidade no plano de controle (control plane).

• Servidores com Docker Engine instalado: Todos os nós (Manager e Workers) devem possuir o Docker instalado. Recomenda-se a versão 20.10.x ou superior para garantir compatibilidade com as funcionalidades mais recentes de redes overlay e segredos (secrets).
• Acesso SSH com privilégios de Sudo: É indispensável ter acesso root ou um usuário com permissões de sudo em todas as máquinas para gerenciar processos do sistema e configurar regras de firewall.
• Endereçamento IP Estático: Cada servidor no cluster deve possuir um endereço IP fixo. O uso de IPs dinâmicos (DHCP) pode quebrar a comunicação do cluster caso o endereço de um nó mude após um reboot.
• Conectividade de Rede e Portas Abertas: O firewall (iptables, ufw ou firewalld) deve permitir o tráfego nas portas críticas para o funcionamento do Swarm. As portas essenciais são:
  • TCP 2377: Utilizada para a comunicação de gerenciamento do cluster entre os nós.
  • TCP/UDP 7946: Utilizada para o controle de descoberta de nós (node discovery) via protocolo gossip.
  • UDP 4789: Necessária para o tráfego de dados da rede overlay (encapsulamento VXLAN).
• Sincronização de Horário (NTP): É fundamental que todos os servidores estejam sincronizados via NTP (Network Time Protocol). Diferenças significativas no relógio do sistema podem invalidar certificados TLS usados na comunicação interna do Swarm.
• Recursos de Hardware Homogêneos: Embora o Swarm suporte heterogeneidade, para aplicações de alta disponibilidade, recomenda-se que os nós tenham capacidades de CPU e RAM minimamente equivalentes para evitar gargalos de escalonamento.

Preparação dos Nós do Cluster

Antes de iniciar a inicialização do cluster, é fundamental garantir que todos os servidores (nós) estejam em um estado de conformidade técnica. A homogeneidade do ambiente reduz drasticamente a ocorrência de erros de runtime durante a escalabilidade dos containers.

Para que o Docker Swarm opere corretamente, siga este procedimento de configuração em cada máquina que fará parte do cluster:

1. Atualize os repositórios e o sistema operacional para garantir que todas as bibliotecas de rede e segurança estejam em suas versões mais recentes.
   O comando update atualiza a lista de pacotes, enquanto o upgrade instala as novas versões, prevenindo conflitos de dependências de kernel.

    

2. Configure o Hostname de forma única para cada servidor. O Docker utiliza o hostname para identificar os membros do cluster nos logs e no gerenciamento de tarefas.
   O comando hostnamectl altera o nome da máquina de forma persistente, sendo essencial que cada nó tenha um nome distinto (ex: manager-01, worker-01).

    

3. Ajuste as regras do Firewall (UFW) para permitir o tráfego de comunicação entre os nós. O Swarm exige portas específicas para o plano de controle e para o tráfego de rede overlay.
   A porta 2377/tcp gerencia o cluster; a 7946 cuida do controle de descoberta de nós (TCP/UDP); e a 4789/udp é vital para o tráfego de rede VXLAN (overlay).

    

4. Garanta que o Docker Engine esteja instalado e rodando com a mesma versão em todos os nós para evitar incompatibilidades de API.
   Este comando exprime a versão do cliente e do servidor, permitindo validar se o daemon está ativo e pronto para receber comandos de orquestração.

    

5. Sincronize o relógio do sistema utilizando o NTP. Diferenças de tempo entre o Manager e os Workers podem causar falhas na validação de certificados TLS e na expiração de tokens de segurança do cluster.
   A flag set-ntp true ativa a sincronização automática via rede, garantindo que todos os nós compartilhem o mesmo timestamp.

    

   Configurando o Manager Node

   O Manager Node é o cérebro do seu cluster. Ele é responsável por manter o estado desejado do serviço, gerenciar o agendamento de tarefas e garantir a consistência do cluster através do protocolo de consenso Raft. Sem um nó manager ativo, o cluster perde sua capacidade de orquestração e decisões de escalonamento.

   1. Inicie o modo Swarm no servidor destinado a ser o líder do cluster. Este comando transforma o daemon do Docker de um modo de container isolado para um modo de orquestrador.

      --advertise-addr é fundamental, pois define o endereço IP público ou privado que os outros nós (workers) utilizarão para se comunicar com o manager. Substitua pelo IP real da sua interface de rede.

       

   2. Capture o token de autenticação gerado. Após a inicialização, o Docker exibirá um comando contendo um token longo. Este token é a única chave que permite a entrada de novos nós no cluster de forma segura.
      Procure pela linha Swarm: active no output. Se o status estiver como inactive, o processo de inicialização falhou ou não foi executado com privilégios de root.
6. Configure a rede de overlay para comunicação entre containers. Embora o Swarm crie redes automaticamente para serviços, é uma boa prática definir uma rede global para que seus microserviços web se comuniquem de forma isolada.

   --driver overlay habilita a comunicação entre hosts diferentes, e a flag --attachable permite que containers individuais (fora de um service) também se conectem a esta rede.

    

Adicionando Workers ao Swarm

Após a inicialização do Manager Node, o próximo passo fundamental é integrar os nós de processamento, conhecidos como Workers, ao cluster. Enquanto o Manager detém o controle do plano de controle (control plane) e gerencia o estado do cluster, os Workers são responsáveis exclusivamente pela execução dos containers (data plane), garantindo que a carga de trabalho seja distribuída de forma eficiente entre os servidores disponíveis.

1. Obtenha o token de ingresso no nó gerenciador. Para que um novo servidor possa se juntar ao cluster, você precisa de uma chave de autenticação única gerada pelo Docker. Execute o comando abaixo no Manager Node:

   docker swarm join-token worker

   O comando exibirá uma string longa de caracteres que contém o endereço IP do Manager e o token de segurança necessário para a autenticação.
2. Acesse o servidor de destino via SSH. Utilize um cliente SSH para se conectar ao servidor que será destinado à função de Worker. Certifique-se de que este servidor possui o Docker Engine instalado e que as regras de firewall permitem a comunicação com o Manager.
3. Execute o comando de ingresso no nó Worker. Copie a string gerada no passo anterior e cole no terminal do novo servidor. O comando deve seguir este formato: <pre>docker swarm join --token :2377 A flag --token instrui o Docker a utilizar a credencial específica para o cluster, enquanto o parâmetro :2377 define o endereço do nó mestre e a porta padrão do swarm mode para comunicação de gerenciamento.
4. Valide a integração no nó Manager. Retorne ao terminal do Manager Node para confirmar que o novo nó foi reconhecido e está pronto para receber tarefas de orquestração.

   docker node ls

   Este comando lista todos os membros do cluster. Verifique se o novo servidor aparece na lista com o status Ready e com a availability definida como Active.

Deploy de Serviços Web

Com o cluster estabelecido, o próximo passo é realizar o deploy de um serviço que utilize a capacidade de orquestração do Swarm. Diferente do Docker comum, no Swarm trabalhamos com services, que definem o estado desejado da aplicação, permitindo que o orquestrador gerencie réplicas e reinicie containers em caso de falhas.

1. Crie um arquivo de composição chamado docker-compose.yml. Embora o Swarm utilize o comando docker service create, o uso de arquivos Compose é a prática padrão para gerenciar configurações complexas de rede e volumes de forma declarativa.
2. Defina a estrutura do serviço web no arquivo. Utilizaremos uma imagem do Nginx para este exemplo, configurando o modo de replicação:

   version: '3.8'
   services:
     web-app:
       image: nginx:latest
       ports:
         - "80:80"
       deploy:
         replicas: 3
         update_config:
           parallelism: 1
           delay: 10s
         restart_policy:
           condition: on-failure

   Neste arquivo, a diretiva replicas: 3 instrui o Swarm a manter sempre três instâncias do Nginx rodando no cluster. A seção update_config define que, ao atualizar a imagem, o Swarm deve atualizar um container por vez (parallelism: 1) com um intervalo de 10 segundos entre eles, garantido o zero downtime.

    

3. Execute o deploy do stack no cluster. No nó Manager, utilize o comando docker stack deploy para ler o arquivo e distribuir as tarefas entre os nós disponíveis:

   docker stack deploy -c docker-compose.yml meu-site

   A flag -c especifica o caminho do arquivo de configuração, enquanto meu-site é o nome do stack que agrupa todos os serviços relacionados.

    

4. Escalabilidade manual do serviço. Caso perceba um aumento de tráfego, você pode escalar o serviço de forma imediata sem alterar o arquivo original:

   docker service scale meu-site_web-app=5

   O parâmetro scale altera o número de réplicas do serviço web-app (dentro do stack meu-site) para 5 instâncias distribuídas pelo cluster.

    

Verificação do Cluster Ativo

Após realizar o deploy dos serviços, é fundamental validar se a orquestração está funcionando conforme o esperado. Não basta apenas verificar se o container está rodando; é preciso garantir que o Manager Node reconhece os Worker Nodes e que as réplicas do serviço estão distribuídas corretamente entre a infraestrutura disponível.

O primeiro passo é validar o estado de saúde do cluster e a lista de nós participantes. Execute o comando abaixo no nó gerenciador:

docker node ls

Este comando lista todos os nós do cluster. O output esperado deve apresentar uma tabela semelhante a esta:

ID                            HOSTNAME            STATUS              AVAILABILITY        MANAGER STATUS
abc123def456ghi789jkl...       manager-01          Ready               Active              Leader
xyz987abc654def321ghi...       worker-01           Ready               

Certifique-se de que a coluna STATUS indica Ready para todos os membros e que o seu nó principal possui a flag Leader. Se algum nó aparecer como Down, há uma falha de comunicação na rede.

O segundo passo é verificar o status específico do serviço web que você acabou de implantar. Utilize o comando docker service ls para visualizar o resumo das réplicas:

docker service ls

No resultado, observe a coluna REPLICAS. Se você configurou o serviço com 3 réplicas, o output deve mostrar 3/3. Caso apareça algo como 1/3, o Docker Swarm está tentando subir os containers, mas encontrou erros de execução ou falta de recursos nos workers.

Para um diagnóstico profundo sobre onde cada tarefa (task) está sendo executada, utilize o comando docker service ps seguido do nome ou ID do seu serviço:

docker service ps web_app

Este comando detalha o histórico de execução de cada réplica. Verifique a coluna NODE para confirmar que o Swarm está distribuindo as instâncias entre diferentes servidores e a coluna ERROR para garantir que não houve falhas de ImagePull ou erros de runtime do container. Uma verificação completa garante que sua arquitetura de alta disponibilidade está operando com a resiliência planejada.

Troubleshooting de Conectividade

A configuração de um cluster Docker Swarm exige que a comunicação entre os nós seja impecável. Falhas na comunicação impedem que o Manager gerencie o estado dos serviços e que os Workers recebam novas tarefas de orquestração. Abaixo, listamos os problemas mais frequentes encontrados durante a implementação de infraestruturas de alta disponibilidade.

• Sintoma: O comando docker swarm join falha com erro de timeout ou conexão recusada. Causa: Bloqueio de portas essenciais no firewall (iptables, ufw ou firewalld) ou Security Groups da nuvem. Solução: Certifique-se de que a porta 2377/tcp está aberta para o gerenciamento do cluster, a porta 7946/tcp e 7946/udp para descoberta de nós e a porta 4789/udp para o tráfego da rede Overlay.
• Sintoma: O nó aparece como Down ou Unreachable no comando docker node ls. Causa: Inconsistência no protocolo de comunicação Gossip ou perda de pacotes UDP. Solução: Verifique se o tráfego UDP na porta 7946 está fluindo entre os IPs dos servidores. Utilize a ferramenta nc (Netcat) para testar a conectividade entre os nós:

  nc -zv [IP_DO_MANAGER] 2377

  O comando acima tenta validar se a porta de gerenciamento está acessível.
• Sintoma: Os containers web sob o serviço orquestrado não conseguem se comunicar entre si, apesar de estarem rodando. Causa: Falha no encapsulamento do tráfego VXLAN. Solução: Verifique se a porta 4789/udp está liberada em toda a malha de rede do cluster. Sem essa porta, o tráfego da rede Overlay não consegue atravessar os túneis entre os hosts.
• Sintoma: Erros de "split-brain" ou perda de quórum no Manager. Causa: Latência excessiva na rede ou instabilidade no link entre os nós Managers. Solução: Em clusters com múltiplos Managers, garanta que a latência de rede seja mínima e que o número de Managers seja ímpar para evitar problemas de consenso (Raft).

Boas Práticas de Alta Disponibilidade

Configurar um cluster Docker Swarm é apenas o primeiro passo para garantir a resiliência de uma aplicação. Para que o ambiente seja verdadeiramente altamente disponível e capaz de suportar falhas de hardware ou de rede, é necessário implementar estratégias de redundância, monitoramento e isolamento de recursos.

• Redundância de Managers: Nunca utilize apenas um único nó como Manager. Em clusters de produção, utilize pelo menos três nós Manager para manter o quorum. Isso garante que, se um nó falhar, o algoritmo de consenso (Raft) consiga eleger um novo líder e manter o estado do cluster sem interrupções no plano de controle.
• Distribuição de Carga com Constraints: Utilize placement constraints para evitar que todas as réplicas de um serviço crítico fiquem no mesmo servidor físico. Ao configurar um serviço, use a flag --constraint para espalhar containers entre diferentes zonas de disponibilidade ou nós distintos, mitigando o impacto de uma queda de host.
• Implementação de Healthchecks: Não confie apenas no status do container. Configure o healthcheck dentro do seu Dockerfile ou no seu arquivo Docker Compose. Isso permite que o Swarm detecte se a aplicação web travou internamente (mesmo com o processo rodando) e reinicie o container automaticamente para restaurar o serviço.
• Gerenciamento de Recursos (Limits e Reservations): Sempre defina limites de memória e CPU para cada serviço. Sem o uso de limits, um container com vazamento de memória (memory leak) pode consumir toda a RAM do nó, causando o OOM Killer do Linux e derrubando outros serviços vitais do cluster.
• Separação de Tráfego e Dados: Mantenha o tráfego de gerenciamento (SSH, APIs de monitoramento) em uma rede isolada do tráfego de dados da aplicação. Além disso, utilize volumes externos ou soluções de storage distribuído (como NFS ou GlusterFS) para que os dados persistentes não fiquem presos a um único nó Worker.
• Monitoramento Ativo e Logging: Implemente uma stack de observabilidade (como Prometheus e Grafana) para monitorar métricas de performance e logs centralizados (como ELK Stack ou Loki). A alta disponibilidade depende da sua capacidade de identificar anomalias antes que elas se tornem downtime para o usuário final.

Conclusão e Próximos Passos

Configurar o Docker Swarm é um divisor de águas para administradores de sistemas e desenvolvedores que buscam sair de uma infraestrutura monolítica e estática para um modelo de orquestração moderna. Ao concluir este tutorial, você não apenas aprendeu a agrupar servidores, mas estabeleceu uma base sólida para o gerenciamento de cargas de trabalho que podem escalar horizontalmente de forma automática. A transição de um único container rodando em um VPS isolado para um cluster distribuído permite que sua aplicação web suporte picos de tráfego sem a necessidade de intervenção manual constante em cada nó.

No entanto, o Swarm é apenas o ponto de partida para uma infraestrutura de alta disponibilidade completa. O gerenciamento de containers é apenas uma camada da pilha tecnológica. Para que seu cluster seja verdadeiramente resiliente e pronto para produção, você deve considerar a evolução da sua arquitetura para níveis de automação e monitoramento mais profundos.

Para avançar em sua jornada de infraestrutura como código e DevOps, recomendamos os seguintes caminhos de aprendizado:

• Implementação de Load Balancers Externos: Embora o Swarm possua o Routing Mesh, integrar um Nginx ou HAProxy externo (ou até mesmo um Cloud Load Balancer da Toda Solução) permite um controle mais refinado sobre o SSL/TLS e regras de filtragem de tráfego antes mesmo que a requisição chegue ao cluster.
• Persistência de Dados com Volumes Compartilhados: Containers são efêmeros por natureza. O próximo passo crítico é configurar sistemas de arquivos distribuídos, como o NFS ou GlusterFS, para garantir que os volumes de dados dos seus serviços web estejam acessíveis por qualquer nó do cluster, independentemente de onde o container seja escalonado.
• Integração de CI/CD: Automatize o deploy de suas stacks utilizando ferramentas como GitHub Actions ou GitLab CI. O objetivo é que cada git push em seu repositório dispare um comando docker stack deploy, atualizando seus serviços de forma transparente (Rolling Updates).
• Monitoramento e Observabilidade: Um cluster sem métricas é uma caixa preta. Implementar a stack Prometheus e Grafana é essencial para visualizar o consumo de CPU, memória e o estado de saúde dos seus serviços, permitindo identificar gargalos antes que eles causem downtime.
• Segurança de Rede Avançada: Explore o uso de Docker Overlay Networks com segmentação rigorosa, garantindo que apenas os serviços que precisam se comunicar entre si tenham visibilidade na rede, reduzindo a superfície de ataque em caso de comprometimento de um container.

A jornada para dominar a orquestração de containers é contínua. Utilize este cluster como seu laboratório para testar novas tecnologias e, à medida que sua demanda crescer, conte com a infraestrutura de cloud escalável da Toda Solução para fornecer o poder computacional necessário para seus novos nós.