Conexões privadas entre aplicações, Jobs, bancos e cache

Uma conexão privada cria um caminho privado e direcional entre recursos da mesma organização. A origem (uma aplicação HTTP ou um Job agendado) passa a chamar o destino (uma aplicação HTTP, um banco de dados ou o Valkey) por um endereço interno, sem passar pela internet. Isso funciona inclusive quando o destino é privado e não tem URL pública, e permite usar um banco sem expô-lo na internet.

Origens e destinos

Jobs agendados só podem ser origem, nunca destino. Bancos de dados e Valkey nunca são origem. Cada destino é acessado na porta padrão do mecanismo:

Como funciona

Cada conexão tem uma origem (quem chama) e um destino (quem recebe). Para uma aplicação HTTP, a origem chama o destino em:

http://<projeto>.<id-da-organização>.zenifra.local

Para um banco de dados ou o Valkey, use o mesmo endereço com a porta do mecanismo, por exemplo <projeto>.<id-da-organização>.zenifra.local:5432.

• <projeto> é um identificador curto, em letras minúsculas, números e hífens, definido na primeira vez que o projeto participa de uma conexão. <id-da-organização> é o identificador de 24 caracteres hexadecimais da organização, exibido no Console e na API. Por exemplo: http://checkout-api.6a11bedda78ad3108eb20e2c.zenifra.local.
• O endereço usa o identificador da organização para ser único e não muda se o projeto ou a organização forem renomeados.
• O tráfego público da aplicação continua protegido por HTTPS. Apenas a chamada a uma aplicação pelo endereço interno usa HTTP na porta padrão, porque ela trafega só dentro da rede privada da sua organização; não é preciso configurar certificado para ela.
• O nome interno é liberado quando o projeto é excluído. Se você recriar um projeto com o mesmo nome, ele reaproveita o mesmo endereço, se o nome estiver livre.
• O endereço interno do destino aparece no mapa depois que o projeto é destino de uma conexão pela primeira vez, e permanece o mesmo depois.

Conexão TLS com bancos de dados e Valkey

Os bancos de dados e o Valkey exigem conexão cifrada. Pelo endereço interno, a conexão é cifrada, mas o certificado pertence ao nome público do serviço e, por isso, o nome do endereço interno não é verificado. Use TLS sem verificação de nome (por exemplo, sslmode=require). O nome do parâmetro de TLS varia por cliente: sslmode=require é o do PostgreSQL. As credenciais continuam as mesmas do banco.

Endereço de leitura

Quando um banco PostgreSQL ou MariaDB tem réplicas (planos com mais de uma instância), o endereço acima aponta para a escrita e há um segundo endereço para leitura:

ro.<projeto>.<id-da-organização>.zenifra.local

O endereço de leitura aparece no mapa junto com o de escrita. Se o número de instâncias mudar, ele é atualizado na próxima sincronização da origem (ligar ou desligar a conexão, novo deploy da origem ou recriação do destino).

Regras

• A conexão vale somente na direção criada. Conectar A a B não permite que B chame A.
• Não há caminho transitivo. Se A chama B e B chama C, A não alcança C.
• Sem conexão, nada muda: não existe caminho privado entre os recursos. Aplicações públicas continuam se falando pela URL pública.
• Renomear o projeto ou a organização não altera o endereço interno. Chamadas existentes continuam funcionando.
• Origem e destino precisam ser da mesma organização (não previews) e do tipo permitido: a origem é uma aplicação HTTP ou um Job agendado; o destino é uma aplicação HTTP, PostgreSQL, MariaDB, ClickHouse ou Valkey. O destino precisa estar pronto para receber a conexão; caso contrário, a criação é recusada até que ele esteja.
• Não há conexão entre organizações.
• Ambientes de preview não participam de conexões.

Criar uma conexão

1. Abra o mapa de conexões da organização no Console.
2. Arraste do conector do recurso de origem até o recurso de destino.
3. Confirme a criação.
4. Aguarde o status da conexão mudar de Preparando para Ativa. Em uma aplicação de origem, depois que o reinício terminar, o endereço fica disponível em todas as instâncias dela; um Job agendado não reinicia e usa o endereço nas próximas execuções.
5. Na origem, use o endereço exibido no mapa: para uma aplicação, chame http://<projeto>.<id-da-organização>.zenifra.local; para um banco ou o Valkey, conecte em <projeto>.<id-da-organização>.zenifra.local:<porta> com TLS.

Em vez de arrastar, clique em Conectar recursos, escolha a origem e o destino, clique em Revisar conexão e confirme.

Uma aplicação de origem pode ser reiniciada para aplicar a mudança. Um Job agendado não reinicia: a mudança vale para as próximas execuções.

Você precisa de permissão para alterar conexões de saída na origem e conexões de entrada no destino. O proprietário da organização tem as duas.

Remover uma conexão

Ao desligar, novas conexões do par são bloqueadas imediatamente. Conexões já abertas não são interrompidas pelo desligamento em si, mas podem ser encerradas se uma aplicação de origem for reiniciada para aplicar a mudança.

Se uma operação falhar, a conexão fica com o status Falhou e você pode tentar a mesma ação novamente.

Organizar o mapa

Arraste o corpo de um cartão para mudar somente sua posição. Mover, aproximar ou sobrepor cartões não cria nem remove conexões. A posição é salva separadamente por usuário e organização.

Próximos passos

• Consulte a referência da API de conexões.
• Revise as opções de configuração do projeto.
• Veja como configurar domínios personalizados.