Esta página contém informações e exemplos para conectar-se a uma instância do Cloud SQL a partir de um serviço em execução no Cloud Run.
Para obter instruções passo a passo sobre como executar um aplicativo Web de exemplo do Cloud Run conectado ao Cloud SQL, consulte o início rápido para conexão do Cloud Run .
O Cloud SQL é um serviço de banco de dados totalmente gerenciado que ajuda você a configurar, manter, gerenciar e administrar seus bancos de dados relacionais na nuvem.
O Cloud Run é uma plataforma de computação gerenciada que permite executar contêineres diretamente sobre Google Cloud infraestrutura.
Configurar uma instância do Cloud SQL
- Habilite a API de administração do Cloud SQL no Google Cloud projeto do qual você está se conectando, caso ainda não tenha feito isso:
- Crie uma instância do Cloud SQL para PostgreSQL . Recomendamos que você escolha um local de instância do Cloud SQL na mesma região do seu serviço Cloud Run para obter melhor latência, evitar custos de rede e reduzir os riscos de falhas entre regiões.
Por padrão, o Cloud SQL atribui um endereço IP público a uma nova instância. Você também tem a opção de atribuir um endereço IP privado. Para obter mais informações sobre as opções de conectividade para ambos, consulte a página "Visão geral da conexão" .
Configurar o Cloud Run
As etapas para configurar o Cloud Run dependem do tipo de endereço IP atribuído à sua instância do Cloud SQL. Se você rotear todo o tráfego de saída por meio da saída direta da VPC ou de um conector de acesso VPC sem servidor, use um endereço IP privado. Compare os dois métodos de saída de rede .IP público (padrão)
- Certifique-se de que a instância tenha um endereço IP público. Você pode verificar isso na página Visão geral da sua instância no Google Cloud console . Se precisar adicionar um, consulte a página Configurando IP público para obter instruções.
- Obtenha o INSTANCE_CONNECTION_NAME para sua instância. Você pode encontrar esse valor na página Visão Geral da sua instância no Google Cloud console ou executando o seguinte comando
gcloud sql instances describe
: Substitua INSTANCE_NAME pelo nome da sua instância do Cloud SQL.gcloud sql instances describe INSTANCE_NAME
- Obtenha o CLOUD_RUN_SERVICE_ACCOUNT_NAME para o seu serviço Cloud Run. Você pode encontrar esse valor na página do IAM do projeto que hospeda o serviço Cloud Run no Google Cloud console ou executando o seguinte comando
gcloud run services describe
no projeto que hospeda o serviço Cloud Run: Substitua as seguintes variáveis:gcloud run services describe CLOUD_RUN_SERVICE_NAME --region CLOUD_RUN_SERVICE_REGION --format="value(spec.template.spec.serviceAccountName)"
- CLOUD_RUN_SERVICE_NAME : o nome do seu serviço Cloud Run
- CLOUD_RUN_SERVICE_REGION : a região do seu serviço Cloud Run
- Configure a conta de serviço para o seu serviço Cloud Run. Para se conectar ao Cloud SQL, certifique-se de que a conta de serviço tenha a função IAM
Cloud SQL Client
. - Se você estiver adicionando uma conexão do Cloud SQL a um novo serviço, precisará conteinerizá-lo e enviá-lo ao Container Registry ou ao Artifact Registry. Se ainda não tiver uma conexão, consulte estas instruções sobre como criar e implantar uma imagem de contêiner.
Como qualquer alteração de configuração, definir uma nova configuração para a conexão do Cloud SQL leva à criação de uma nova revisão do Cloud Run. Revisões subsequentes também receberão automaticamente essa conexão do Cloud SQL, a menos que você faça atualizações explícitas para alterá-la.
Console
Comece a configurar o serviço. Para adicionar conexões do Cloud SQL a um serviço existente, faça o seguinte:
- Na lista Serviços , clique no nome do serviço desejado.
- Clique em Editar e implantar nova revisão .
- Habilite a conexão a uma instância do Cloud SQL:
- Clique em Contêiner(es) e depois em Configurações .
- Role até Conexões do Cloud SQL .
- Clique em Adicionar conexão .
- Clique em Habilitar o botão Cloud SQL Admin se você ainda não habilitou a API Cloud SQL Admin.
- Se você estiver adicionando uma conexão a uma instância do Cloud SQL no seu projeto, selecione a instância do Cloud SQL desejada no menu.
- Se você estiver usando uma instância do Cloud SQL de outro projeto, selecione a string de conexão personalizada no menu e insira o nome completo da conexão da instância no formato PROJECT-ID:REGION:INSTANCE-ID .
- Para excluir uma conexão , mantenha o cursor à direita da conexão para exibir o ícone Excluir clique nele.
Clique em Criar ou Implantar .
Linha de comando
Antes de usar qualquer um dos seguintes comandos, faça as seguintes substituições:
- IMAGE com a imagem que você está implantando
- SERVICE_NAME com o nome do seu serviço Cloud Run
INSTANCE_CONNECTION_NAME pelo nome da conexão da sua instância do Cloud SQL ou uma lista de nomes de conexão delimitada por vírgulas.
Se você estiver implantando um novo contêiner, use o seguinte comando:
Se você estiver atualizando um serviço existente, use o seguinte comando:gcloud run deploy \ --image=IMAGE \ --add-cloudsql-instances=INSTANCE_CONNECTION_NAME
gcloud run services update SERVICE_NAME \ --add-cloudsql-instances=INSTANCE_CONNECTION_NAME
Terraform
O código a seguir cria um contêiner base do Cloud Run, com uma instância do Cloud SQL conectada.
- Aplique as alterações digitando
terraform apply
. - Verifique as alterações verificando o serviço Cloud Run , clicando na guia Revisões e, em seguida, na guia Conexões .
IP privado
Se a conta de serviço de autorização pertencer a um projeto diferente daquele que contém a instância do Cloud SQL, faça o seguinte:
- Em ambos os projetos, ative a API de administração do Cloud SQL.
- Para a conta de serviço no projeto que contém a instância do Cloud SQL, adicione as permissões do IAM .
- Certifique-se de que a instância do Cloud SQL criada anteriormente tenha um endereço IP privado. Para adicionar um endereço IP interno, consulte Configurar IP privado .
- Configure seu método de saída para se conectar à mesma rede VPC que sua instância do Cloud SQL. Observe as seguintes condições:
- A saída direta de VPC e o acesso VPC sem servidor oferecem suporte à comunicação com redes VPC conectadas usando Cloud VPN e VPC Network Peering .
- A saída direta de VPC e o acesso VPC sem servidor não oferecem suporte a redes legadas .
- A menos que você esteja usando uma VPC compartilhada , um conector deve compartilhar o mesmo projeto e região que o recurso que o utiliza, embora o conector possa enviar tráfego para recursos em regiões diferentes.
- Conecte-se usando o endereço IP privado da sua instância e a porta
5432
.
Conectar ao Cloud SQL
Depois de configurar o Cloud Run, você pode se conectar à sua instância do Cloud SQL.
IP público (padrão)
Para caminhos de IP públicos, o Cloud Run fornece criptografia e se conecta usando o Cloud SQL Auth Proxy de duas maneiras:
- Através de soquetes Unix
- Usando um conector Cloud SQL
Usar o Gerenciador Secreto
O Google recomenda que você use o Gerenciador de Segredos para armazenar informações confidenciais, como credenciais SQL. Você pode passar segredos como variáveis de ambiente ou montá-los como um volume com o Cloud Run.
Depois de criar um segredo no Secret Manager, atualize um serviço existente com o seguinte comando:
Linha de comando
gcloud run services update SERVICE_NAME \ --add-cloudsql-instances=INSTANCE_CONNECTION_NAME --update-env-vars=INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME_SECRET \ --update-secrets=DB_USER=DB_USER_SECRET:latest \ --update-secrets=DB_PASS=DB_PASS_SECRET:latest \ --update-secrets=DB_NAME=DB_NAME_SECRET:latest
Terraform
O seguinte cria recursos secretos para armazenar com segurança os valores de usuário, senha e nome do banco de dados usando google_secret_manager_secret
e google_secret_manager_secret_version
. Observe que você deve atualizar a conta de serviço de computação do projeto para ter acesso a cada segredo.
Atualize o recurso principal do Cloud Run para incluir os novos segredos.
Aplique as alterações digitando terraform apply
.
O comando de exemplo usa a versão secreta, latest ; no entanto, o Google recomenda fixar o segredo em uma versão específica, SECRET_NAME:v1 .
IP privado
Para caminhos IP privados, seu aplicativo se conecta diretamente à sua instância por meio de uma rede VPC. Este método usa TCP para se conectar diretamente à instância do Cloud SQL sem usar o Proxy de Autenticação do Cloud SQL.
Conecte-se com TCP
Conecte-se usando o endereço IP privado da sua instância do Cloud SQL como host e a porta 5432
.
Pitão
Para ver este snippet no contexto de um aplicativo web, veja o README no GitHub .
Java
Para ver este snippet no contexto de um aplicativo web, veja o README no GitHub .
Observação:
- CLOUD_SQL_CONNECTION_NAME deve ser representado como <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
- Usar o argumento ipTypes=PRIVATE forçará o SocketFactory a se conectar com o IP privado associado de uma instância
- Veja os requisitos de versão do factory de soquete JDBC para o arquivo pom.xml aqui .
Node.js
Para ver este snippet no contexto de um aplicativo web, veja o README no GitHub .
Ir
Para ver este snippet no contexto de um aplicativo web, veja o README no GitHub .
C#
Para ver este snippet no contexto de um aplicativo web, veja o README no GitHub .
Rubi
Para ver este snippet no contexto de um aplicativo web, veja o README no GitHub .
PHP
Para ver este snippet no contexto de um aplicativo web, veja o README no GitHub .
Melhores práticas e outras informações
Você pode usar o Cloud SQL Auth Proxy ao testar seu aplicativo localmente. Consulte o guia de início rápido sobre como usar o Cloud SQL Auth Proxy para obter instruções detalhadas.
Você também pode testar usando o Cloud SQL Proxy por meio de um contêiner do Docker .
Pools de conexão
As conexões com os bancos de dados subjacentes podem ser interrompidas, seja pelo próprio servidor de banco de dados ou pela infraestrutura da plataforma. Recomendamos o uso de uma biblioteca cliente que suporte pools de conexão que reconectam automaticamente as conexões de cliente interrompidas. Para obter exemplos mais detalhados sobre como usar pools de conexão, consulte a página Gerenciando conexões de banco de dados .Limites de conexão
As edições MySQL e PostgreSQL do Cloud SQL impõem um limite máximo de conexões simultâneas, e esses limites podem variar dependendo do mecanismo de banco de dados escolhido (consulte a página Cotas e limites do Cloud SQL ).As instâncias de contêiner do Cloud Run são limitadas a 100 conexões com um banco de dados Cloud SQL. Cada instância de um serviço ou tarefa do Cloud Run pode ter 100 conexões com o banco de dados e, à medida que esse serviço ou tarefa é escalonado, o número total de conexões por implantação pode aumentar.
Você pode limitar o número máximo de conexões usadas por instância usando um pool de conexões. Para obter exemplos mais detalhados sobre como limitar o número de conexões, consulte a página Gerenciando conexões de banco de dados .
Limites de cota da API
O Cloud Run fornece um mecanismo de conexão usando o Proxy de Autenticação do Cloud SQL, que utiliza a API de Administração do Cloud SQL. Os limites de cota da API se aplicam ao Proxy de Autenticação do Cloud SQL. A cota da API de Administração do Cloud SQL usada é aproximadamente duas vezes o número de instâncias do Cloud SQL configuradas pelo número de instâncias do Cloud Run de um serviço específico implantado simultaneamente. Você pode limitar ou aumentar o número de instâncias do Cloud Run para modificar a cota esperada da API consumida.O que vem a seguir
- Saiba mais sobre o Cloud Run .
- Saiba mais sobre como criar e implantar imagens de contêiner.
- Veja um exemplo completo em Python para usar o Cloud Run com PostgreSQL .