Uma referência de serviço que nunca quebra, mesmo antes de você ativar a rede privada
O conselho usual pra chamadas entre serviços é “use o hostname interno, não o público” — razoável, até os dois serviços acabarem em hosts diferentes, provedores diferentes, ou regiões diferentes, e o hostname interno parar de resolver. A maioria das plataformas resolve isso te fazendo pensar na topologia desde o início. A abordagem da Railyard é fazer a referência resolver corretamente independente da topologia, e trocar o que está por baixo dela conforme a topologia muda.
Três casos, uma referência
Toda aplicação recebe <name>.railyard.internal, e pra onde esse nome realmente resolve depende inteiramente de onde a outra aplicação roda em relação a ela, não de nada que a aplicação que chama precise saber:
- Mesmo servidor: é um alias de rede Docker — resolve direto pro container na própria porta. Sem configuração, sem rede pra montar.
- Servidor diferente, rede privada desligada: a referência ainda funciona — só não é privada. Ela resolve pro endereço público normal
https://da aplicação em vez de simplesmente falhar. Uma referência entre duas aplicações em servidores diferentes degrada pra “funciona, mas pela internet pública”, em vez de quebrar. - Servidor diferente, rede privada ligada: todo servidor da equipe entra numa mesh WireGuard criptografada (
10.210.0.0/16), e o mesmo nome agora resolve pra onde a aplicação de fato roda, entre provedores e regiões, roteado pela mesh em vez da internet pública.
A parte que vale parar pra pensar: uma aplicação referenciando ${{api.RAILYARD_PRIVATE_URL}} não muda quando qualquer uma dessas coisas muda. Mover a api pra outro servidor, conectar um servidor de um provedor de nuvem totalmente diferente, ativar a rede privada pela primeira vez — a referência continua resolvendo, só que por um mecanismo diferente cada vez.
Por que a degradação suave vence uma exigência rígida
O desenho alternativo — a rede privada é obrigatória, ou as referências simplesmente falham até ela ser configurada — seria mais “correto” em algum sentido abstrato e pior na prática: uma equipe pequena num único servidor nunca precisa de rede entre servidores, e não deveria ter que configurar uma mesh WireGuard pra fazer deploy de duas aplicações que, por acaso, moram no mesmo lugar. Fazer o fallback ser “ainda funciona, por HTTPS público” em vez de “não funciona até você configurar isso” significa que a mesma configuração de aplicação é válida no primeiro dia com um servidor e continua válida depois de escalar pra cinco servidores em dois provedores — nada pra reescrever conforme a topologia cresce.
O que ativar isso realmente muda
Servers → Private network → Turn on (só admin) é a única ação: todo servidor que já está na equipe entra na mesh, e os containers que já estão rodando pegam o novo resolver no próximo deploy ou restart — não instantaneamente, o que importa se uma referência é sensível a latência e está resolvendo pela internet pública nesse momento. A partir daí, todo servidor que a equipe adicionar depois — em qualquer provedor, em qualquer região — entra na mesma mesh automaticamente, já que a mesh é uma propriedade da equipe, não algo reconfigurado por servidor.
Referência completa: Networking docs, Variables and secrets.