Instalar Apache ZooKeeper no Ubuntu 18.04

Diagrama conceitual do Apache ZooKeeper

O Apache ZooKeeper é um serviço centralizado de código aberto para gerenciar informações de configuração, nomeação, sincronização distribuída e provisão de serviços de grupo. Escrito em Java, ZooKeeper permite que você foque na lógica da aplicação sem se preocupar com detalhes de distribuição. A arquitetura do ZooKeeper oferece alta disponibilidade por meio de serviços redundantes. Ele expõe um namespace hierárquico comum para coordenar processos distribuídos e fornece alto débito, baixa latência e controle de acesso aos znodes. ZooKeeper é ideal para armazenar estado, configurações, informações de localização e outros metadados necessários para aplicações distribuídas.

Neste tutorial vamos configurar um cluster ZooKeeper de nó único no Ubuntu 18.04. Este é um ambiente de teste/validação; para produção consulte a seção sobre clusters multi-nó e práticas de segurança abaixo.

O que você vai precisar

Um servidor com Ubuntu 18.04 em execução
Acesso root ou um usuário com privilégios sudo
Conexão à internet para baixar pacotes

Breve explicação técnica

ZooKeeper mantém um conjunto de dados leve e consistente em memória e persiste mudanças em disco. Os clientes se conectam via porta 2181 (por padrão) e interagem com nós chamados znodes. Em produção, ZooKeeper é executado em quorum (múltiplos nós) para tolerância a falhas; aqui veremos um nó único para fins de teste.

Termos chave

znode: nó de dados no namespace hierárquico do ZooKeeper
tickTime: unidade de tempo usada pelo ZooKeeper para heartbeats
quorum: conjunto de nós que formam o serviço em modo distribuído

Recomendação inicial

Important: usar um nó único é aceitável apenas para testes, desenvolvimento ou validação. Em produção use ao menos 3 nós em quorum para tolerância a falhas.

Atualizar o sistema

Primeiro atualize o sistema para as últimas versões dos pacotes:

apt-get update -y  
apt-get upgrade -y

Depois de concluir a atualização, é recomendável reiniciar o servidor para aplicar alterações de kernel e serviços, se necessário.

Instalar Java

ZooKeeper é escrito em Java, portanto o servidor precisa ter o JRE/JDK instalado. No Ubuntu 18.04 a versão Oracle pode não estar nos repositórios oficiais, então o exemplo original adiciona um PPA e instala o pacote oracle-java11-set-default.

Adicionar PPA:

add-apt-repository ppa:linuxuprising/java

Atualizar e instalar Java 11:

apt-get update -y  
apt-get install oracle-java11-set-default

Verificar a versão do Java:

java --version

Exemplo de saída esperada:

java 11.0.2 2018-10-16 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.2+7-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.2+7-LTS, mixed mode)

Nota: se preferir OpenJDK, troque o pacote por openjdk-11-jre-headless e adapte conforme política da sua organização.

Criar usuário dedicado para ZooKeeper

É boa prática executar serviços com um usuário pouco privilegiado.

Criar usuário e definir shell:

useradd zookeeper -m  
usermod --shell /bin/bash zookeeper

Definir senha:

passwd zookeeper

Adicionar ao grupo sudo se você precisar de acesso administrativo para o usuário:

usermod -aG sudo zookeeper

Com o usuário criado, prossiga para instalar o ZooKeeper.

Instalar ZooKeeper

ZooKeeper precisa persistir dados de estado em disco, portanto criaremos um diretório apropriado e ajustaremos permissões.

Criar diretório de dados:

mkdir -p /data/zookeeper

Conceder propriedade ao usuário zookeeper:

chown -R zookeeper:zookeeper /data/zookeeper

Baixar e instalar o ZooKeeper no diretório /opt. O tutorial original utiliza a versão 3.4.9 do arquivo de arquivamento oficial.

cd /opt  
wget https://archive.apache.org/dist/zookeeper/zookeeper-3.4.9/zookeeper-3.4.9.tar.gz

Extrair e renomear:

tar -xvzf zookeeper-3.4.9.tar.gz
mv zookeeper-3.4.9 zookeeper

Ajustar propriedade:

chown -R zookeeper:zookeeper /opt/zookeeper

Observação: versões mais recentes do ZooKeeper existem; verifique compatibilidade com sua aplicação antes de atualizar.

Configurar ZooKeeper

Crie o arquivo de configuração principal:

nano /opt/zookeeper/conf/zoo.cfg

Adicione as linhas básicas necessárias para um nó único:

tickTime=2500
dataDir=/data/zookeeper
clientPort=2181
maxClientCnxns=80

Salve e feche o arquivo.

Iniciando o servidor ZooKeeper manualmente

Inicie o serviço diretamente a partir do diretório de instalação:

cd /opt/zookeeper  
bin/zkServer.sh start

Saída esperada:

ZooKeeper JMX enabled by default
Using config: /opt/zookeeper/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED

Conectar-se ao servidor local com o cliente de linha de comando:

bin/zkCli.sh -server 127.0.0.1:2181

Ao conectar, você verá o prompt do cliente:

[zk: 127.0.0.1:2181(CONNECTED) 1]

Digite help no prompt para listar os comandos disponíveis, por exemplo create, get, set, ls.

Comandos úteis no cliente:

help
ZooKeeper -server host:port cmd args
    stat path [watch]
    set path data [version]
    ls path [watch]
    get path [watch]
    create [-s] [-e] path data acl
    quit

Para sair, digite quit.

Parar o ZooKeeper manualmente:

bin/zkServer.sh stop

Saída esperada:

ZooKeeper JMX enabled by default
Using config: /opt/zookeeper/bin/../conf/zoo.cfg
Stopping zookeeper ... STOPPED

Criar unidade systemd para ZooKeeper

Gerenciar o serviço via systemd facilita inicialização automática e monitoramento.

Criar arquivo de unidade:

nano /etc/systemd/system/zookeeper.service

Adicionar o conteúdo abaixo:

[Unit]
Description=Zookeeper Daemon
Documentation=http://zookeeper.apache.org
Requires=network.target
After=network.target

[Service]    
Type=forking
WorkingDirectory=/opt/zookeeper
User=zookeeper
Group=zookeeper
ExecStart=/opt/zookeeper/bin/zkServer.sh start /opt/zookeeper/conf/zoo.cfg
ExecStop=/opt/zookeeper/bin/zkServer.sh stop /opt/zookeeper/conf/zoo.cfg
ExecReload=/opt/zookeeper/bin/zkServer.sh restart /opt/zookeeper/conf/zoo.cfg
TimeoutSec=30
Restart=on-failure

[Install]
WantedBy=default.target

Salvar e fechar o arquivo. Em seguida recarregue o daemon systemd e habilite o serviço:

systemctl daemon-reload
systemctl start zookeeper  
systemctl enable zookeeper

Verificar status:

systemctl status zookeeper

Exemplo de saída esperada indicando que o serviço está ativo e em execução.

Checagens rápidas

Verifique se a porta 2181 está escutando: sudo ss -ltnp | grep 2181
Verifique logs em /opt/zookeeper/logs ou conforme configurado
Verifique permissões do diretório /data/zookeeper

Guia de troubleshooting comum

Problema: ZooKeeper não inicia
- Verifique logs para erros de Java ou permissão
- Confirme que java –version funciona para o usuário zookeeper
- Confirme que dataDir existe e pertence ao usuário zookeeper
Problema: cliente não conecta
- Confirme que firewall permite porta 2181
- Verifique se o serviço está escutando na interface esperada
Problema: arquivo zoo.cfg mal formado
- Erros de sintaxe no arquivo podem impedir a inicialização; valide que não existam linhas em branco com espaços estranhos

Segurança e práticas recomendadas

Não exponha a porta 2181 na Internet. Use redes privadas ou VPNs.
Configure regras de firewall (ufw/iptables) para limitar acesso a hosts confiáveis.
Habilite autenticação e ACLs em ambientes multi-cliente.
Monitore SLI/SLO básicos: disponibilidade do serviço e latência de operações críticas.

Escalando para multi-nó (breve)

Para produção, crie um cluster com número ímpar de nós (3, 5, …). Em cada nó, além de zoo.cfg, você precisa adicionar linhas server.N=host:peerPort:leaderPort e um arquivo myid no dataDir contendo o id do nó.

Exemplo de entradas no zoo.cfg para um cluster de 3 nós:

server.1=zk1.example.com:2888:3888
server.2=zk2.example.com:2888:3888
server.3=zk3.example.com:2888:3888

Em /data/zookeeper/myid coloque apenas o número do servidor (por exemplo 1). Reinicie os nós para formar o quorum.

Checklist para migrar de nó único para produção

Planejar topologia com mínimo 3 nós
Fazer backups do dataDir antes de qualquer mudança
Sincronizar versões do ZooKeeper e Java entre nós
Configurar monitoring e alerting (logs, métricas, disponibilidade)
Testar falhas simuladas para validar failover

Cheatsheet de comandos úteis

Iniciar: systemctl start zookeeper
Parar: systemctl stop zookeeper
Reiniciar: systemctl restart zookeeper
Status: systemctl status zookeeper
Cliente: /opt/zookeeper/bin/zkCli.sh -server HOST:2181
Logs: verificar /opt/zookeeper/logs ou pasta de logs configurada

Modelos e decisões rápidas

Se o objetivo é desenvolvimento local ou CI, um nó único pode ser suficiente. Para produção com requisitos de alta disponibilidade, sempre usar quorum e separar dados/partições de disco com IOPS adequados.

Pequeno glossário

znode: item de dados no namespace do ZooKeeper
quorum: conjunto mínimo de nós que concordam sobre o estado
tickTime: tempo base do heartbeat

Perguntas frequentes rápidas

Posso usar OpenJDK? Sim. Use uma versão compatível suportada por sua aplicação.
Posso atualizar para ZooKeeper 3.5+ sem mudanças? Verifique notas de versão; 3.5 introduziu mudanças em configuração e SSL.

Conclusão

Você instalou e configurou com sucesso um servidor Apache ZooKeeper de nó único no Ubuntu 18.04. Para produção, converta este ambiente em um cluster multi-nó com quorum, reforce segurança e implemente monitoramento. Se precisar de ajuda para configurar um cluster de 3 nós, ajustar ACLs ou integrar com sua aplicação, pergunte quais são seus requisitos e posso orientar os próximos passos.

Критерии приёмки

ZooKeeper em execução e respondendo na porta 2181
Sistemad gerencia o serviço e inicia automaticamente
Diretório de dados acessível pelo usuário zookeeper

Resumo

ZooKeeper foi instalado em /opt/zookeeper e configurado para usar /data/zookeeper
Serviço gerenciado via systemd com unidade customizada
Notas incluídas sobre segurança, scaling e troubleshooting

Important: este guia usa ZooKeeper 3.4.9 como exemplo. Antes de usar em produção, avalie versões mais recentes e aplique políticas de segurança e alta disponibilidade.