Estabeleça ligação a partir de funções do Cloud Run

Esta página contém informações e exemplos para estabelecer ligação a uma instância do Cloud SQL a partir de um serviço em execução nas funções do Cloud Run.

Para instruções passo a passo sobre como executar uma aplicação Web de exemplo de funções do Cloud Run ligada ao Cloud SQL, consulte o início rápido para estabelecer ligação a partir de funções do Cloud Run.

O Cloud SQL é um serviço de base de dados totalmente gerido que ajuda na configuração, manutenção, gestão e administração das suas bases de dados relacionais na nuvem.

As funções do Cloud Run são uma solução de computação leve para os programadores criarem funções autónomas de finalidade única que respondem a eventos do Google Cloud sem ter de gerir um servidor ou um ambiente de tempo de execução.

Configure uma instância do Cloud SQL

  1. Ative a API Cloud SQL Admin no Trusted Cloud projeto a partir do qual está a estabelecer ligação, se ainda não o tiver feito:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  2. Crie uma instância do Cloud SQL para MySQL. Recomendamos que escolha uma localização da instância do Cloud SQL na mesma região que o seu serviço do Cloud Run para ter uma melhor latência, evitar alguns custos de rede e reduzir os riscos de falhas entre regiões.

    Por predefinição, o Cloud SQL atribui um endereço IP público a uma nova instância. Também tem a opção de atribuir um endereço IP privado. Para mais informações sobre as opções de conetividade para ambos, consulte a página Vista geral da ligação.

  3. Quando cria a instância, pode escolher a hierarquia do certificado do servidor (AC) para a instância e, em seguida, configurar a hierarquia como a serverCaMode para a instância. Tem de selecionar a opção de AC por instância (GOOGLE_MANAGED_INTERNAL_CA) como o modo de AC do servidor para instâncias às quais quer estabelecer ligação a partir de aplicações Web.

Configure funções do Cloud Run

Os passos para configurar as funções do Cloud Run dependem do tipo de endereço IP que atribuiu à sua instância do Cloud SQL.

IP público (predefinição)

Para configurar funções do Cloud Run para ativar ligações a uma instância do Cloud SQL:

  • Confirme se a instância criada acima tem um endereço IP público. Pode confirmar esta situação na página Vista geral da instância na Trusted Cloud consola. Se precisar de adicionar um endereço IP público, consulte Configurar IP público.
  • Obtenha o INSTANCE_CONNECTION_NAME da instância. Este valor está disponível:
    • Na página Vista geral da instância, na Trusted Cloud consola ou
    • Executando o seguinte comando: gcloud sql instances describe [INSTANCE_NAME]
  • Configure a conta de serviço para a sua função. Se a conta de serviço de autorização pertencer a um projeto diferente da instância do Cloud SQL, tem de ativar a API Admin do Cloud SQL e adicionar a Cloud SQL Client função de IAM a ambos os projetos.
  • Confirme que a conta de serviço tem esta função para que a conta possa estabelecer ligação ao Cloud SQL.
  • Se estiver a usar funções do Cloud Run e não funções do Cloud Run (1.ª geração), são necessários os seguintes passos (consulte também Configurar o Cloud Run):
    1. Implemente inicialmente a sua função.
      Quando começa a criar uma função do Cloud Run na Trusted Cloud consola, o serviço do Cloud Run subjacente ainda não foi criado. Não pode configurar uma ligação do Cloud SQL até que esse serviço seja criado (através da implementação da função do Cloud Run).
    2. Na Trusted Cloud consola, na parte superior direita da página Detalhes da função, em Com tecnologia do Cloud Run, clique no link para aceder ao serviço do Cloud Run subjacente.
    3. Na página Detalhes do serviço do Cloud Run, selecione o separador Editar e implementar nova revisão.
    4. Siga os passos padrão (como no caso de qualquer alteração de configuração) para definir uma nova configuração para uma ligação do Cloud SQL.
      Esta ação cria uma nova revisão do Cloud Run e as revisões subsequentes recebem automaticamente esta ligação do Cloud SQL, a menos que a altere explicitamente.

IP privado

Se a conta de serviço de autorização pertencer a um projeto diferente do que contém a instância do Cloud SQL, faça o seguinte:

  • Em ambos os projetos, ative a API Admin do Cloud SQL.
  • Para a conta de serviço no projeto que contém a instância do Cloud SQL, adicione as autorizações IAM.
Um conetor do Acesso a VPC sem servidor usa endereços IP privados para processar a comunicação com a sua rede VPC. Para estabelecer ligação diretamente com endereços IP privados, tem de fazer o seguinte:
  1. Certifique-se de que a instância do Cloud SQL criada anteriormente tem um endereço IP privado. Se precisar de adicionar um, consulte as instruções em Configurar IP privado.
  2. Crie um conetor de acesso a VPC sem servidor na mesma rede VPC que a sua instância do Cloud SQL. Tenha em atenção as seguintes condições:
    • A menos que esteja a usar a VPC partilhada, o conector tem de estar no mesmo projeto e região que o recurso que o usa, mas pode enviar tráfego para recursos em regiões diferentes.
    • O Acesso a VPC sem servidor suporta a comunicação com redes VPC ligadas através do Cloud VPN e do intercâmbio de redes VPC.
    • O acesso a VPC sem servidor não suporta redes antigas.
  3. Configure as funções do Cloud Run para usar o conetor.
  4. Estabeleça ligação através do endereço IP privado e da porta da sua instância 3306.

Estabeleça ligação ao Cloud SQL

Depois de configurar as funções do Cloud Run, pode estabelecer ligação à sua instância do Cloud SQL.

IP público (predefinição)

Para caminhos de IP públicos, as funções do Cloud Run fornecem encriptação e estabelecem ligação através do proxy Auth do Cloud SQL de duas formas:

IP privado

Para caminhos de IP privado, a sua aplicação liga-se diretamente à sua instância através de uma rede VPC. Este método usa o TCP para se ligar diretamente à instância do Cloud SQL sem usar o proxy Auth do Cloud SQL.

Estabeleça ligação com TCP

Estabeleça ligação através do endereço IP privado da sua instância do Cloud SQL como anfitrião e porta 3306.

Python

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

import os

import sqlalchemy


def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of MySQL."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 3306

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # mysql+pymysql://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="mysql+pymysql",
            username=db_user,
            password=db_pass,
            host=db_host,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

Para ver este fragmento no contexto de uma app Web, consulte o LEIA-ME no GitHub.

Nota:


import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Saving credentials in environment variables is convenient, but not secure - consider a more
  // secure solution such as https://cloud.google.com/secret-manager/ to help keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:mysql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:mysql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "mysql"
    config.setPassword(DB_PASS); // e.g. "my-password"


    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

const mysql = require('promise-mysql');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of MySQL.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
    port: process.env.DB_PORT, // e.g. '3306'
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return mysql.createPool(dbConfig);
};

Ir

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

package cloudsql

import (
	"crypto/tls"
	"crypto/x509"
	"database/sql"
	"errors"
	"fmt"
	"log"
	"os"

	"github.com/go-sql-driver/mysql"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of MySQL.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
		dbPort    = mustGetenv("DB_PORT")       // e.g. '3306'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	)

	dbURI := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?parseTime=true",
		dbUser, dbPwd, dbTCPHost, dbPort, dbName)


	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("mysql", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

PHP

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

namespace Google\Cloud\Samples\CloudSQL\MySQL;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

            // Connect using TCP
            $dsn = sprintf('mysql:dbname=%s;host=%s', $dbName, $instanceHost);

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/mysql/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Práticas recomendadas e outras informações

Pode usar o proxy Auth do Cloud SQL quando testar a sua aplicação localmente. Consulte o início rápido para usar o proxy Auth do Cloud SQL para ver instruções detalhadas.

Conjuntos de ligações

As ligações às bases de dados subjacentes podem ser interrompidas pelo próprio servidor da base de dados ou pela infraestrutura subjacente às funções do Cloud Run. Recomendamos a utilização de uma biblioteca de cliente que suporte pools de ligações que restabeleçam automaticamente as ligações de cliente interrompidas. Além disso, recomendamos que use um conjunto de ligações com âmbito global para aumentar a probabilidade de a sua função reutilizar a mesma ligação para invocações subsequentes da função e fechar a ligação naturalmente quando a instância for removida (redução automática). Para ver exemplos mais detalhados de como usar pools de ligações, consulte o artigo Gerir ligações à base de dados.

Limites de ligação

O Cloud SQL impõe um limite máximo nas ligações simultâneas, e estes limites podem variar consoante o motor de base de dados escolhido (consulte as quotas e os limites do Cloud SQL). Recomendamos que use uma ligação com funções do Cloud Run, mas é importante definir o número máximo de ligações como 1.

Sempre que possível, deve ter cuidado para inicializar apenas um conjunto de ligações para funções que precisam de acesso à sua base de dados. Alguns conjuntos de ligações criam ligações preventivamente, o que pode consumir recursos em excesso e contar para os seus limites de ligações. Por este motivo, recomenda-se que use a inicialização tardia para atrasar a criação de um conjunto de ligações até ser necessário e inclua o conjunto de ligações apenas nas funções em que é usado.

Para ver exemplos mais detalhados sobre como limitar o número de associações, consulte o artigo Gerir associações de bases de dados.

Limites de quota da API

As funções do Cloud Run oferecem um mecanismo que se liga através do proxy Auth do Cloud SQL, que usa a API Admin do Cloud SQL. Os limites de quota da API aplicam-se ao proxy Auth do Cloud SQL. A quota da API Admin do Cloud SQL usada é aproximadamente duas vezes o número de instâncias do Cloud SQL configuradas vezes o número total de funções implementadas. Pode definir o número de invocações simultâneas máximas para modificar a quota da API esperada consumida. As funções do Cloud Run também impõem limites de taxa ao número de chamadas de API permitidas por 100 segundos.

O que se segue?