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. Quando o número de instâncias de um PostgreSQL ou MariaDB muda, os endereços de escrita e de leitura são atualizados automaticamente nas origens assim que as novas instâncias ficam prontas, normalmente em até 2 minutos; a origem pode ser reiniciada para aplicar a mudança. Se a atualização não acontecer nesse intervalo, ela ocorre na próxima sincronização da origem (ligar ou desligar a conexão, novo deploy da origem ou recriação do destino).

Banco ou Valkey sem acesso público

PostgreSQL, MariaDB, ClickHouse e Valkey têm o acesso público ligado por padrão: o host e a porta públicos aceitam conexões com TLS. Combinado com as conexões privadas, você pode desligar esse acesso e deixar o banco alcançável somente pelas aplicações e Jobs da organização que você conectou a ele.

1. Crie uma conexão de cada aplicação ou Job que usa o banco até ele e aguarde o status Ativa.
2. Na origem, troque a variável de conexão (por exemplo, DATABASE_URL ou VALKEY_URL) pelo endereço interno exibido no mapa, com TLS, e valide a conexão.
3. Na edição do banco ou do Valkey, desligue o card Acesso público e confirme.

Depois disso:

• as conexões privadas continuam funcionando, no mesmo endereço interno;
• o endereço público deixa de aceitar conexões, inclusive de ferramentas de administração e scripts fora da Zenifra;
• a renovação de senha ou de credencial continua disponível; atualize a nova credencial nas origens;
• se você remover a conexão de uma origem, ela perde o único caminho até o banco.

Ao religar o acesso público, o banco volta a responder no mesmo host e na mesma porta públicos, e a URI de conexão externa continua igual. As conexões privadas não são afetadas.

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.