Conecte um container Docker ao Tailscale

O container oficial executa o cliente Tailscale e registra uma identidade na tailnet. Comece conferindo esse registro e a persistência do estado. A aplicação que você pretende conectar terá uma configuração de rede própria, feita depois desta etapa.

Prepare a autenticação

Use um host com Docker disponível e gere uma auth key para o ambiente. Para este exemplo persistente, mantenha a opção de dispositivo efêmero desativada. Guarde a chave em um arquivo local chamado tailscale.env, fora do Git:

1
TS_AUTHKEY=SUBSTITUA_PELA_SUA_AUTH_KEY

No Linux, limite a leitura do arquivo:

1
chmod 600 tailscale.env

O valor permanece acessível à administração do Docker. Não publique o arquivo, a saída de inspeção do container ou a chave em comentários e capturas.

Crie o container e preserve seu estado

O exemplo usa o modo userspace, sem interface TUN. A imagem latest acompanha atualizações. Em um ambiente mantido por você, registre e fixe a versão ou o digest depois da sua validação.

1
docker volume create tailscale-state
2
docker run -d \
3
  --name tailscale-guia \
4
  --env-file ./tailscale.env \
5
  -e TS_HOSTNAME=docker-guia \
6
  -e TS_STATE_DIR=/var/lib/tailscale \
7
  -e TS_AUTH_ONCE=true \
8
  -e TS_USERSPACE=true \
9
  -v tailscale-state:/var/lib/tailscale \
10
  --restart unless-stopped \
11
  tailscale/tailscale:latest

O volume mantém a identidade do dispositivo. A opção TS_AUTH_ONCE evita autenticar novamente uma identidade já válida a cada inicialização.

Confira o registro e o reinício

Abra Machines no painel administrativo e procure docker-guia. No host, consulte o estado:

1
docker exec tailscale-guia tailscale status
2
docker exec tailscale-guia tailscale ip -4
3
docker restart tailscale-guia
4
docker exec tailscale-guia tailscale status

Aguarde a inicialização antes da última consulta. Confira que o registro original continua presente e que o endereço permaneceu associado a ele. Se aparecer uma nova máquina, revise o volume e o caminho do estado.

Investigue o container antes da aplicação

O host e o container são ambientes distintos. Executar tailscale status diretamente no host não consulta o cliente instalado dentro deste container. Use docker exec como nos exemplos anteriores.

Se a inicialização falhar, leia os registros recentes:

1
docker logs --tail 50 tailscale-guia
2
docker inspect --format '{{json .Mounts}}' tailscale-guia

O segundo comando restringe a inspeção aos volumes montados. Confira o destino /var/lib/tailscale e o volume esperado. Evite publicar uma inspeção completa: as variáveis de ambiente podem conter a auth key. Examine também os logs antes de compartilhá-los.

Um volume vazio, um caminho alterado ou uma autenticação ainda pendente explicam comportamentos diferentes. Corrija a causa identificada antes de recriar o container. O estado persistido contém material de autenticação do dispositivo. Mantenha seu backup com acesso restrito. Excluir esse estado muda as condições para retomar a identidade, mesmo que você reutilize o nome do container.

Conecte a aplicação em uma etapa separada

Este container registra o cliente. Ele não publica automaticamente as portas de outros containers. Para integrar uma aplicação, consulte o exemplo oficial de Docker Compose com compartilhamento do namespace de rede. O modo kernel também exige TUN e permissões adicionais.

Para parar este exercício, use docker stop tailscale-guia. Preserve o volume se pretende retomar a mesma identidade. Depois do primeiro registro, retire a chave da configuração ao recriar o container com o mesmo volume e estado autenticado.