חיבור באמצעות שרת proxy ל-Cloud SQL Auth

בדף הזה מוסבר איך להתחבר למכונה של Cloud SQL באמצעות Cloud SQL Auth Proxy.

מידע נוסף על Cloud SQL Auth Proxy

סקירה כללית

השיטה המומלצת להתחברות למכונה של Cloud SQL היא באמצעות Cloud SQL Auth Proxy. ‫Cloud SQL Auth Proxy:

  • פועל גם עם נקודות קצה של כתובות IP ציבוריות וגם עם נקודות קצה של כתובות IP פרטיות
  • מאמת את החיבורים באמצעות פרטי כניסה של משתמש או של חשבון שירות
  • עוטף את החיבור בשכבת הצפנה של SSL/TLS שמאושרת למכונה שלכם ב-Cloud SQL.

Google Cloud חלק מהשירותים והאפליקציות משתמשים ב-Cloud SQL Auth Proxy כדי לספק חיבורים לנתיבי IP ציבוריים עם הצפנה והרשאה, כולל:

אפליקציות שפועלות ב- Google Kubernetes Engine יכולות להתחבר באמצעות Cloud SQL Auth Proxy.

במדריך למתחילים בנושא שימוש ב-Cloud SQL Auth Proxy מוסבר איך להשתמש בו.

אפשר גם להתחבר, עם או בלי Cloud SQL Auth Proxy, באמצעות לקוח sqlcmd ממכונה מקומית או מ-Compute Engine.

לפני שמתחילים

לפני שמתחברים למכונה של Cloud SQL, צריך לבצע את הפעולות הבאות:

    • למשתמש או לחשבון שירות, צריך לוודא שלחשבון יש את התפקיד Cloud SQL Client. התפקיד הזה מכיל את ההרשאה cloudsql.instances.connect, שמאפשרת לחשבון משתמש להתחבר לכל המכונות של Cloud SQL בפרויקט.

      כניסה לדף IAM

    • אפשר לכלול תנאי IAM בקישור של מדיניות ה-IAM, שנותן לחשבון הרשאה להתחבר רק למכונה ספציפית אחת של Cloud SQL.

  2. מפעילים את Cloud SQL Admin API, אם הוא עדיין לא מופעל.

    התפקידים שנדרשים כדי להפעיל ממשקי API

    כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

    להפעלת ה-API

  3. מתקינים ומפעילים את ה-CLI של gcloud.
  4. זה שינוי אופציונלי. מתקינים את לקוח Docker של Cloud SQL Auth Proxy.

הורדת Cloud SQL Auth Proxy

לפני שמתחילים, צריך לזהות את הארכיטקטורה של המכונה.

אם אתם משתמשים ב-Linux או ב-Mac, אתם יכולים להריץ את הפקודה הבאה כדי למצוא את הכתובת:

  uname -a

‏Linux‏ 64 סיביות

  1. מורידים את Cloud SQL Auth Proxy: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.linux.amd64
  2. הופכים את Cloud SQL Auth Proxy לקובץ הפעלה: 
    chmod +x cloud-sql-proxy

‏Linux‏ 32 סיביות

  1. מורידים את Cloud SQL Auth Proxy: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.linux.386
  2. אם הפקודה curl לא נמצאה, מריצים את sudo apt install curl וחוזרים על פקודת ההורדה.
  3. הופכים את Cloud SQL Auth Proxy לקובץ הפעלה: 
    chmod +x cloud-sql-proxy

macOS‏ 64 סיביות

  1. מורידים את Cloud SQL Auth Proxy: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.darwin.amd64
  2. הופכים את Cloud SQL Auth Proxy לקובץ הפעלה: 
    chmod +x cloud-sql-proxy

Mac M1

  1. מורידים את Cloud SQL Auth Proxy: 
      curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.darwin.arm64
  2. הופכים את Cloud SQL Auth Proxy לקובץ הפעלה: 
      chmod +x cloud-sql-proxy

‏Windows‏ 64 סיביות

לוחצים לחיצה ימנית על https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.x64.exe ובוחרים באפשרות Save Link As כדי להוריד את Cloud SQL Auth Proxy. משנים את שם הקובץ ל-cloud-sql-proxy.exe.

‏Windows‏ 32 סיביות

לוחצים לחיצה ימנית על https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.26.2/cloud-sql-proxy.x86.exe ובוחרים באפשרות Save Link As כדי להוריד את Cloud SQL Auth Proxy. משנים את שם הקובץ ל-cloud-sql-proxy.exe.

קובץ אימג' של Docker ל-Cloud SQL Auth Proxy

ל-Cloud SQL Auth Proxy יש קובצי אימג' שונים של קונטיינרים, כמו distroless,‏ alpine ו-buster. קובץ האימג' של הקונטיינר שמשמש כברירת מחדל ל-Cloud SQL Auth Proxy משתמש ב-distroless, שלא מכיל מעטפת. אם אתם צריכים מעטפת או כלים קשורים, הורידו קובץ אימג' שמבוסס על alpine או על buster. מידע נוסף מופיע במאמר קובצי אימג' של קונטיינרים של Cloud SQL Auth Proxy.

כדי להוריד את קובץ האימג' העדכני למחשב המקומי באמצעות Docker, משתמשים בפקודה הבאה:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.26.2

מערכת הפעלה אחרת

במערכות הפעלה אחרות שלא מופיעות כאן, אפשר להדר את Cloud SQL Auth Proxy מהמקור.

הפעלת Cloud SQL Auth Proxy

אפשר להפעיל את Cloud SQL Auth Proxy באמצעות שקעי TCP או קובץ האימג' של Docker ב-Cloud SQL Auth Proxy. הקובץ הבינארי של Cloud SQL Auth Proxy מתחבר למכונה אחת או יותר של Cloud SQL שצוינו בשורת הפקודה, ופותח חיבור מקומי כשקע TCP. אפליקציות ושירותים אחרים, כמו קוד האפליקציה או כלי לקוח לניהול מסדי נתונים, יכולים להתחבר למכונות של Cloud SQL דרך החיבור הזה לשקע TCP.

שקעי TCP

בחיבורי TCP, כברירת מחדל שרת ה-Proxy של Cloud SQL Auth מאזין ל-localhost(127.0.0.1). לכן, כשמציינים את --port PORT_NUMBER למכונה, החיבור המקומי הוא ב-127.0.0.1:PORT_NUMBER.

לחלופין, אפשר לציין כתובת אחרת לחיבור המקומי. לדוגמה, כך מגדירים את Cloud SQL Auth Proxy להאזין ב-0.0.0.0:1234 לחיבור המקומי:

./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME

  1. מעתיקים את INSTANCE_CONNECTION_NAME. אפשר למצוא את המידע הזה בדף Overview של המכונה במסוףGoogle Cloud , או באמצעות הרצת הפקודה הבאה:

        gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'

    לדוגמה: myproject:myregion:myinstance.

  2. אם למכונה מוגדרות גם כתובת IP ציבורית וגם כתובת IP פרטית, ואתם רוצים ש-Cloud SQL Auth Proxy ישתמש בכתובת ה-IP הפרטית, אתם צריכים לספק את האפשרות הבאה כשאתם מפעילים את Cloud SQL Auth Proxy: 
    --private-ip
  3. אם אתם משתמשים בחשבון שירות כדי לאמת את Cloud SQL Auth Proxy, שימו לב למיקום במכונת הלקוח של קובץ המפתח הפרטי שנוצר כשיצרתם את חשבון השירות.
  4. מפעילים את Cloud SQL Auth Proxy.

    כמה מחרוזות אפשריות להפעלה של Cloud SQL Auth Proxy:

    • שימוש באימות של Cloud SDK: 
      ./cloud-sql-proxy --port 1433 INSTANCE_CONNECTION_NAME
       היציאה שצוינה לא יכולה להיות בשימוש, למשל על ידי שרת מסד נתונים מקומי.
    • שימוש בחשבון שירות וציון מפורש של שם החיבור למכונה (מומלץ לסביבות ייצור): 
      ./cloud-sql-proxy \
--credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

    למידע נוסף על האפשרויות של Cloud SQL Auth Proxy, ראו אפשרויות לאימות של Cloud SQL Auth Proxy.

Docker

כדי להריץ את Cloud SQL Auth Proxy בקונטיינר של Docker, משתמשים בקובץ האימג' של Cloud SQL Auth Proxy ל-Docker שזמין ב-Google Container Registry.

כדי להפעיל את Cloud SQL Auth Proxy באמצעות שקעי TCP, משתמשים בפקודה הבאה. באפשרות הזו משתמשים ב-INSTANCE_CONNECTION_NAME כמחרוזת החיבור כדי לזהות מכונה של Cloud SQL. אפשר למצוא את הערך של INSTANCE_CONNECTION_NAME בדף Overview של המכונה במסוףGoogle Cloud , או על ידי הרצת הפקודה הבאה:

gcloud sql instances describe INSTANCE_NAME

לדוגמה: myproject:myregion:myinstance.

שימוש בשקעי TCP

docker run -d \
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
  -p 127.0.0.1:1433:1433 \
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.26.2 \
  --address 0.0.0.0 --port 1433 \
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

אם אתם משתמשים בפרטי הכניסה שסופקו על ידי המכונה של Compute Engine, אל תכללו את הפרמטר --credentials-file ואת השורה -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

תמיד צריך לציין את הקידומת 127.0.0.1 ב--p כדי ש-Cloud SQL Auth Proxy לא ייחשף מחוץ למארח המקומי. הדגל --address 0.0.0.0 נדרש כדי שהיציאה תהיה נגישה מחוץ לקונטיינר של Docker.

התחברות באמצעות הלקוח sqlcmd

מחרוזת החיבור שבה משתמשים תלויה בשאלה אם הפעלתם את Cloud SQL Auth Proxy באמצעות שקע TCP או Docker.

שקעי TCP

  1. מפעילים את הלקוח sqlcmd: 
    sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD

    כשמתחברים באמצעות שקעי TCP, הגישה ל-Cloud SQL Auth Proxy מתבצעת דרך 127.0.0.1.

  2. אם מתבקשים, מזינים את הסיסמה.
  3. מופיעה ההנחיה sqlcmd.

דרושה לך עזרה? לקבלת עזרה בפתרון בעיות ב-Cloud SQL Auth Proxy, אפשר לעיין במאמר פתרון בעיות בחיבורים של Cloud SQL Auth Proxy או בדף התמיכה ב-Cloud SQL.

קישור לאפליקציה

אפשר להתחבר ל-Cloud SQL Auth Proxy מכל שפה שמאפשרת להתחבר לשקע TCP. בהמשך מוצגים כמה קטעי קוד מדוגמאות פתורות ב-GitHub, כדי להסביר איך הם פועלים ביחד באפליקציה.

מתבצע חיבור באמצעות TCP

הצהרת הפעלה של Cloud SQL Auth Proxy:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין ב-README ב-GitHub.

import os

import sqlalchemy


def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of SQL Server."""
    # 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. 1433

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

    return pool

Java

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין ב-README ב-GitHub.

הערה:

  • הערך של CLOUD_SQL_CONNECTION_NAME צריך להיות מיוצג בתור <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
  • השימוש בארגומנט ipTypes=PRIVATE יאלץ את SocketFactory להתחבר לכתובת ה-IP הפרטית שמשויכת למכונה
  • דרישות הגרסה של JDBC socket factory לקובץ pom.xml 


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

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // 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.
  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();

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(
        String.format("jdbc:sqlserver://%s:%s;databaseName=%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "sqlserver"
    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

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין ב-README ב-GitHub.

const mssql = require('mssql');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of SQL Server.
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 = {
    server: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
    port: parseInt(process.env.DB_PORT), // e.g. 1433
    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'
    options: {
      trustServerCertificate: true,
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return mssql.connect(dbConfig);
};

המשך

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין ב-README ב-GitHub.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"
	"strings"

	_ "github.com/denisenkom/go-mssqldb"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of SQL Server.
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.\n", 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'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
		dbPort    = mustGetenv("DB_PORT")       // e.g. '1433'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("server=%s;user id=%s;password=%s;port=%s;database=%s;",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)


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

	// ...

	return dbPool, nil
}

C#‎

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין ב-README ב-GitHub.

using Microsoft.Data.SqlClient;
using System;

namespace CloudSql
{
    public class SqlServerTcp
    {
        public static SqlConnectionStringBuilder NewSqlServerTCPConnectionString()
        {
            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // 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.
                DataSource = Environment.GetEnvironmentVariable("INSTANCE_HOST"), // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = Environment.GetEnvironmentVariable("DB_USER"),         // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"),       // e.g. 'my-db-password'
                InitialCatalog = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance
                Encrypt = false,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין ב-README ב-GitHub.

tcp: &tcp
  adapter: sqlserver
  # Configure additional properties here.
  # 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: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 1433 }%>

PHP

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין ב-README ב-GitHub.

namespace Google\Cloud\Samples\CloudSQL\SQLServer;

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(
                'sqlsrv:server=%s;Database=%s',
                $instanceHost,
                $dbName
            );

            // 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/sqlserver/connect-external-app',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

נושאים נוספים

ארגומנטים של שורת הפקודה ב-Cloud SQL Auth Proxy

הדוגמאות שלמעלה כוללות את תרחישי השימוש הנפוצים ביותר, אבל ל-Cloud SQL Auth Proxy יש גם אפשרויות הגדרה אחרות שאפשר להגדיר באמצעות ארגומנטים של שורת הפקודה. כדי לקבל עזרה לגבי ארגומנטים של שורת הפקודה, אפשר להשתמש בדגל --help כדי להציג את המסמכים העדכניים:

./cloud-sql-proxy --help

ב-README במאגר של Cloud SQL Auth Proxy ב-GitHub יש דוגמאות נוספות לשימוש באפשרויות של שורת הפקודה של Cloud SQL Auth Proxy.

אפשרויות לאימות של Cloud SQL Auth Proxy

בכל האפשרויות האלה משתמשים ב-INSTANCE_CONNECTION_NAME כמחרוזת החיבור כדי לזהות מכונה של Cloud SQL. אפשר למצוא את INSTANCE_CONNECTION_NAME בדף Overview של המכונה במסוףGoogle Cloud , או על ידי הרצת הפקודה הבאה:

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME.

לדוגמה: gcloud sql instances describe --project myproject myinstance .

בחלק מהאפשרויות האלה משתמשים בקובץ פרטי כניסה בפורמט JSON, שכולל את המפתח הפרטי של RSA לחשבון. במאמר יצירת חשבון שירות מוסבר איך יוצרים קובץ פרטי כניסה בפורמט JSON לחשבון שירות.

‫Cloud SQL Auth Proxy מספק כמה חלופות לאימות, בהתאם לסביבה שלכם. ‫Cloud SQL Auth Proxy בודק כל אחד מהפריטים הבאים, לפי הסדר הבא, ומשתמש בפריט הראשון שהוא מוצא כדי לנסות לבצע אימות:

  1. פרטי כניסה שסופקו על ידי הדגל credentials-file.

    משתמשים בחשבון שירות כדי ליצור ולהוריד את קובץ ה-JSON המשויך, ומגדירים את הדגל --credentials-file לנתיב של הקובץ כשמפעילים את Cloud SQL Auth Proxy. לחשבון השירות צריכות להיות ההרשאות הנדרשות למכונה של Cloud SQL.

    כדי להשתמש באפשרות הזו בשורת הפקודה, מפעילים את הפקודה cloud-sql-proxy כשהדגל --credentials-file מוגדר לנתיב ולשם הקובץ של קובץ JSON שמכיל את פרטי הכניסה. הנתיב יכול להיות מוחלט או יחסי לספריית העבודה הנוכחית. לדוגמה: 

    ./cloud-sql-proxy --credentials-file PATH_TO_KEY_FILE \
INSTANCE_CONNECTION_NAME

    הוראות מפורטות להוספת תפקידי IAM לחשבון שירות מופיעות במאמר הקצאת תפקידים לחשבונות שירות.

    מידע נוסף על התפקידים שנתמכים ב-Cloud SQL זמין במאמר תפקידי IAM ב-Cloud SQL.

  2. פרטי כניסה שסופקו על ידי אסימון גישה.

    יוצרים אסימון גישה ומפעילים את הפקודה cloud-sql-proxy כשהדגל --token מוגדר לאסימון גישה מסוג OAuth 2.0. לדוגמה: 
    ./cloud-sql-proxy --token ACCESS_TOKEN \
INSTANCE_CONNECTION_NAME

  3. פרטי כניסה שסופקו על ידי משתנה סביבה.

    האפשרות הזו דומה לשימוש בדגל --credentials-file, אבל במקום להשתמש בארגומנט שורת הפקודה --credentials-file, מציינים את קובץ פרטי הכניסה בפורמט JSON שהגדרתם במשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS.

  4. פרטי כניסה מלקוח מאומת של ה-CLI של gcloud.

    אם התקנתם את ה-CLI של gcloud ואימתם את החשבון האישי שלכם, Cloud SQL Auth Proxy יכול להשתמש באותם פרטי כניסה לחשבון. השיטה הזו שימושית במיוחד להגדרה ולהפעלה של סביבת פיתוח.

    כדי לאפשר ל-Cloud SQL Auth Proxy להשתמש בפרטי הכניסה של ה-CLI של gcloud, צריך להשתמש בפקודה הבאה כדי לאמת את ה-CLI של gcloud:

    gcloud auth application-default login

  5. פרטי הכניסה שמשויכים למכונה של Compute Engine.

    אם אתם מתחברים ל-Cloud SQL ממכונה של Compute Engine, שרת ה-Cloud SQL Auth Proxy יכול להשתמש בחשבון השירות שמשויך למכונה של Compute Engine. אם לחשבון השירות יש את ההרשאות הנדרשות למכונה של Cloud SQL, האימות של Cloud SQL Auth Proxy יתבצע בהצלחה.

    אם המכונה של Compute Engine נמצאת באותו פרויקט כמו המכונה של Cloud SQL, לחשבון השירות שמוגדר כברירת מחדל למכונה של Compute Engine יש את ההרשאות שנדרשות לאימות של Cloud SQL Auth Proxy. אם שתי המכונות נמצאות בפרויקטים שונים, צריך להוסיף את חשבון השירות של המכונה ב-Compute Engine לפרויקט שמכיל את המכונה ב-Cloud SQL.

  6. חשבון השירות שמוגדר כברירת מחדל בסביבה

    אם Cloud SQL Auth Proxy לא מוצא את פרטי הכניסה באף אחד מהמקומות שצוינו קודם, הוא פועל לפי הלוגיקה שמתוארת במאמר הגדרת אימות לאפליקציות שרת-לשרת בסביבת הייצור. בסביבות מסוימות (כמו Compute Engine, ‏ App Engine ואחרות) יש חשבון שירות שמוגדר כברירת מחדל, שבו האפליקציה יכולה להשתמש כדי לבצע אימות. אם משתמשים בחשבון שירות שמוגדר כברירת מחדל, צריך להקצות לו את ההרשאות שמפורטות בקטע תפקידים והרשאות. למידע נוסף על גישת האימות של Google Cloud, קראו את הסקירה הכללית על אימות.

יצירה של חשבון שירות

  1. נכנסים לדף Service accounts במסוף Google Cloud .

    כניסה לדף Service accounts

  2. בוחרים את הפרויקט שמכיל את המכונה של Cloud SQL.
  3. לוחצים על Create service account.
  4. בשדה Service account name, מזינים שם תיאורי לחשבון השירות.
  5. משנים את הערך של Service account ID לערך ייחודי וקל לזיהוי, ולוחצים על Create and continue.
  6. לוחצים על השדה בחירת תפקיד ובוחרים אחד מהתפקידים הבאים:
    • Cloud SQL > Cloud SQL Client
    • Cloud SQL > Cloud SQL Editor
    • Cloud SQL > Cloud SQL Admin

  7. לוחצים על Done כדי לסיים ליצור את חשבון השירות.
  8. לוחצים על תפריט הפעולות של חשבון השירות החדש ובוחרים באפשרות Manage keys.
  9. לוחצים על התפריט הנפתח Add key ואז על Create new key.
  10. מוודאים שסוג המפתח הוא JSON ולוחצים על Create.

    קובץ המפתח הפרטי יורד למחשב. אפשר להעביר אותו למיקום אחר. שומרים על אבטחת קובץ המַפְתח.

שימוש ב-Cloud SQL Auth Proxy עם כתובת IP פרטית

כדי להתחבר למכונה של Cloud SQL באמצעות כתובת IP פרטית, ה-Cloud SQL Auth Proxy צריך להיות במשאב עם גישה לאותה רשת VPC כמו המכונה.

‫Cloud SQL Auth Proxy משתמש בכתובת IP כדי ליצור חיבור למכונה של Cloud SQL. כברירת מחדל, Cloud SQL Auth Proxy מנסה להתחבר באמצעות כתובת IPv4 ציבורית.

אם למכונה של Cloud SQL יש רק כתובת IP פרטית, או אם למכונה מוגדרות גם כתובת IP ציבורית וגם כתובת IP פרטית, ואתם רוצים ש-Cloud SQL Auth Proxy ישתמש בכתובת ה-IP הפרטית, אתם צריכים לספק את האפשרות הבאה כשאתם מפעילים את Cloud SQL Auth Proxy:

--private-ip

שימוש ב-Cloud SQL Auth Proxy כדי להתחבר לנקודת קצה לכתיבה

אתם יכולים להשתמש ב-Cloud SQL Auth Proxy כדי להתחבר למכונה ראשית של Cloud SQL שמוגדרת עם נקודת קצה לכתיבה. נקודת קצה לכתיבה היא שם דומיין גלובלי של שירות שמות דומיינים (DNS) שאפשר להשתמש בו לחיבורים במקום כתובת IP, לצורך תוכנית התאוששות מאסון (DR) מתקדמת, כמו ביצוע פעולת יתירות כשל או מעבר בין רפליקות. אם מתרחשת פעולת מעבר לגיבוי בעת כשל או פעולת החלפה של רפליקה במכונה הראשית, שרת ה-Proxy לאימות ב-Cloud SQL מזהה באופן אוטומטי שינויים ברשומת ה-DNS.

במאמר איך מחברים לקוחות של מסדי נתונים למכונות באמצעות Cloud SQL Auth Proxy או מחברי שפה של Cloud SQL מוסבר איך משתמשים ב-Cloud SQL Auth Proxy כדי להתחבר לנקודת קצה לכתיבה.

שימוש ב-Cloud SQL Auth Proxy עם מכונות שמופעל בהן Private Service Connect

אתם יכולים להשתמש ב-Cloud SQL Auth Proxy כדי להתחבר למכונה של Cloud SQL שמופעל בה Private Service Connect.

‫Cloud SQL Auth Proxy הוא מחבר שמספק גישה מאובטחת למכונה הזו בלי צורך ברשתות מורשות או בהגדרת SSL.

כדי לאפשר חיבורים של לקוחות Cloud SQL Auth Proxy, צריך להגדיר רשומת DNS שתואמת לשם ה-DNS המומלץ שסופק למכונה. רשומת ה-DNS היא מיפוי בין משאב DNS לבין שם דומיין.

מידע נוסף על השימוש ב-Cloud SQL Auth Proxy כדי להתחבר למכונות שמופעל בהן Private Service Connect זמין במאמר התחברות באמצעות Cloud SQL Auth Proxy.

הפעלת Cloud SQL Auth Proxy בתהליך נפרד

כדי לא לערבב את הפלט של מסוף Cloud SQL Auth Proxy עם פלט מתוכנות אחרות, כדאי להריץ אותו בתהליך נפרד של מסוף Cloud Shell. כדי להפעיל את Cloud SQL Auth Proxy בתהליך נפרד, משתמשים בתחביר שמוצג בהמשך.

Linux

ב-Linux או ב-macOS, משתמשים ב-& בסוף שורת הפקודה כדי להפעיל את Cloud SQL Auth Proxy בתהליך נפרד:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME
  --credentials-file PATH_TO_KEY_FILE &

Windows

ב-Windows PowerShell, משתמשים בפקודה Start-Process כדי להפעיל את Cloud SQL Auth Proxy בתהליך נפרד:

Start-Process --filepath "cloud-sql-proxy.exe"
  --ArgumentList "
  --credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

הפעלת Cloud SQL Auth Proxy בקונטיינר של Docker

כדי להריץ את Cloud SQL Auth Proxy בקונטיינר של Docker, משתמשים בקובץ האימג' של Cloud SQL Auth Proxy ל-Docker שזמין ב-Google Container Registry. כדי להתקין את קובץ האימג' של Cloud SQL Auth Proxy ב-Docker, משתמשים בפקודה הבאה:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.26.2
כדי להפעיל את Cloud SQL Auth Proxy באמצעות שקעי TCP, משתמשים בפקודה שמוצגת למטה.

שקעי TCP

docker run -d \
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
  -p 127.0.0.1:1433:1433 \
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.26.2 \
  --address 0.0.0.0 --port 1433 \
  --credentials-file /path/to/service-account-key.json \
  INSTANCE_CONNECTION_NAME

תמיד צריך לציין את הקידומת 127.0.0.1 ב--p כדי ש-Cloud SQL Auth Proxy לא ייחשף מחוץ למארח המקומי. הדגל --address 0.0.0.0 נדרש כדי שהיציאה תהיה נגישה מחוץ לקונטיינר של Docker.

אם אתם משתמשים בפרטי הכניסה שסופקו על ידי המכונה של Compute Engine, אל תכללו את הפרמטר --credentials-file ואת השורה -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

הפעלת Cloud SQL Auth Proxy כשירות

אפשר להריץ את Cloud SQL Auth Proxy כשירות שפועל ברקע לעומסי עבודה של פיתוח מקומי וייצור. במהלך הפיתוח, כשצריך לגשת למכונה של Cloud SQL, אפשר להפעיל את השירות ברקע ולהפסיק אותו בסיום.

בעומסי עבודה בסביבת ייצור, ל-Cloud SQL Auth Proxy אין כרגע תמיכה מובנית להפעלה כשירות של Windows, אבל אפשר להשתמש במנהלי שירות של צד שלישי כדי להפעיל אותו כשירות. לדוגמה, אפשר להשתמש ב-NSSM כדי להגדיר את Cloud SQL Auth Proxy כשירות של Windows, ו-NSSM עוקב אחרי Cloud SQL Auth Proxy ומפעיל אותו מחדש באופן אוטומטי אם הוא מפסיק להגיב. מידע נוסף מופיע במסמכי התיעוד של NSSM.

חיבור כשנדרש SSL

אכיפת השימוש במחברים של Cloud SQL

אתם יכולים לאכוף את השימוש ב-Cloud SQL Auth Proxy או במחברי השפה של Cloud SQL בחיבורים של מכונות Cloud SQL באמצעות ConnectorEnforcement.

אם אתם משתמשים במכונה שמופעל בה Private Service Connect, יש מגבלה. אם במכונה מופעלת אכיפת מחבר, אי אפשר ליצור רפליקות לקריאה בלבד של המכונה. באופן דומה, אם למכונה יש רפליקות לקריאה, אי אפשר להפעיל אכיפת מחברים במכונה.

gcloud

הפקודה הבאה אוכפת את השימוש במחברים של Cloud SQL.

    gcloud sql instances patch INSTANCE_NAME \
    --connector-enforcement REQUIRED

כדי להשבית את האכיפה, משתמשים בשורת הקוד הבאה: --connector-enforcement NOT_REQUIRED העדכון לא מפעיל הפעלה מחדש.

REST v1

הפקודה הבאה אוכפת את השימוש במחברים של Cloud SQL.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-id: מזהה הפרויקט.
  • ‫instance-id: מזהה המכונה.

ה-method של ה-HTTP וכתובת ה-URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

תוכן בקשת JSON: 

{
  "settings": {                     
    "connectorEnforcement": "REQUIRED"    
  }                                             
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

כדי להשבית את האכיפה, צריך להשתמש במדיניות "connectorEnforcement": "NOT_REQUIRED". העדכון לא מפעיל מחדש את המכשיר.

REST v1beta4

הפקודה הבאה אוכפת את השימוש במחברים של Cloud SQL.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-id: מזהה הפרויקט.
  • ‫instance-id: מזהה המכונה.

ה-method של ה-HTTP וכתובת ה-URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

תוכן בקשת JSON: 

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

כדי להשבית את האכיפה, צריך להשתמש במדיניות "connectorEnforcement": "NOT_REQUIRED". העדכון לא מפעיל מחדש את המכשיר.

טיפים לעבודה עם Cloud SQL Auth Proxy

שימוש ב-Cloud SQL Auth Proxy כדי להתחבר למספר מכונות

אתם יכולים להשתמש בלקוח מקומי אחד של Cloud SQL Auth Proxy כדי להתחבר לכמה מכונות של Cloud SQL. הדרך לעשות זאת תלויה בשאלה אם אתם משתמשים בשקעי Unix או ב-TCP.

שקעי TCP

כשמתחברים באמצעות TCP, מציינים יציאה במכונה שבה Cloud SQL Auth Proxy יאזין לכל מכונה של Cloud SQL. כשמתחברים לכמה מכונות של Cloud SQL, כל יציאה שמציינים צריכה להיות ייחודית וזמינה לשימוש במכונה.

לדוגמה:

    # Start the Cloud SQL Auth Proxy to connect to two different Cloud SQL instances.
    # Give the Cloud SQL Auth Proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=1433" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 1433 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1433"

    # Connect to "myInstance2" using port 1234 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1234"

פתרון בעיות בחיבורים של Cloud SQL Auth Proxy

קובץ האימג' של Cloud SQL Auth Proxy ב-Docker מבוסס על גרסה ספציפית של Cloud SQL Auth Proxy. כשגרסה חדשה של Cloud SQL Auth Proxy זמינה, צריך למשוך את הגרסה החדשה של קובץ האימג' של Cloud SQL Auth Proxy Docker כדי שהסביבה תהיה מעודכנת. כדי לראות את הגרסה הנוכחית של Cloud SQL Auth Proxy, אפשר להיכנס ל דף הגרסאות של Cloud SQL Auth Proxy ב-GitHub.

אם אתם לא מצליחים להתחבר למכונה של Cloud SQL באמצעות Cloud SQL Auth Proxy, נסו את הפתרונות הבאים כדי לגלות מה גורם לבעיה.

  • בודקים את הפלט של Cloud SQL Auth Proxy.

    במקרים רבים, הפלט של Cloud SQL Auth Proxy יכול לעזור לכם לזהות את מקור הבעיה ואת הדרך לפתור אותה. מעבירים את הפלט לקובץ או צופים בטרמינל של Cloud Shell שבו הפעלתם את Cloud SQL Auth Proxy.

  • אם מופיעה השגיאה 403 notAuthorized ואתם משתמשים בחשבון שירות כדי לאמת את Cloud SQL Auth Proxy, ודאו שלחשבון השירות יש את ההרשאות הנכונות.

    כדי לבדוק את חשבון השירות, מחפשים את המזהה שלו בדף IAM. צריכה להיות לו ההרשאה cloudsql.instances.connect. התפקידים המוגדרים מראש Cloud SQL Admin,‏ Client ו-Editor כוללים את ההרשאה הזו.

  • אם אתם מתחברים מ-App Engine ומופיעה השגיאה 403 notAuthorized, בדקו את הערך app.yaml של cloud_sql_instances כדי לוודא ששם החיבור של המכונה נכון ומאוית נכון. שמות החיבור של המכונות מוצגים תמיד בפורמט PROJECT:REGION:INSTANCE.

    בנוסף, צריך לוודא שלחשבון השירות של App Engine (לדוגמה, ‎$PROJECT_ID@appspot.gserviceaccount.com‎) יש את תפקיד הלקוח של Cloud SQL ב-IAM.

    אם שירות App Engine נמצא בפרויקט אחד (פרויקט א') ומסד הנתונים נמצא בפרויקט אחר (פרויקט ב'), השגיאה הזו מציינת שחשבון השירות של App Engine לא קיבל את תפקיד ה-IAM של לקוח Cloud SQL בפרויקט עם מסד הנתונים (פרויקט ב').

  • חשוב לוודא ש-Cloud SQL Admin API מופעל.

    אם לא, ביומנים של Cloud SQL Auth Proxy יופיע פלט כמו Error 403: Access Not Configured.

  • אם אתם כוללים כמה מכונות ברשימת המכונות, הקפידו להשתמש בפסיק כמפריד, ללא רווחים. אם אתם משתמשים ב-TCP, ודאו שאתם מציינים יציאות שונות לכל מכונה.

  • אם אתם מתחברים באמצעות שקעי UNIX, ודאו שהשקעים נוצרו על ידי הצגת הספרייה שסיפקתם כשהפעלתם את Cloud SQL Auth Proxy.

  • אם יש לכם מדיניות חומת אש לתעבורת נתונים יוצאת, ודאו שהיא מאפשרת חיבורים ליציאה 3307 במכונה של Cloud SQL.

  • כדי לוודא ש-Cloud SQL Auth Proxy הופעל כמו שצריך, אפשר לבדוק את היומנים בקטע Operations > Logging > Logs explorer במסוףGoogle Cloud . אם הפעולה בוצעה בהצלחה, התשובה תיראה כך:

    2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/1433 for $PROJECT_ID:$REGION:$INSTANCE_NAME
2021/06/14 15:47:56 Ready for new connections

  • בעיות במכסות: כשחורגים מהמכסה של Cloud SQL Admin API, ‏Cloud SQL Auth Proxy מופעל עם הודעת השגיאה הבאה:

    There was a problem when parsing a instance configuration but ignoring due
to the configuration. Error: googleapi: Error 429: Quota exceeded for quota
metric 'Queries' and limit 'Queries per minute per user' of service
'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID.,
rateLimitExceeded

    אחרי שאפליקציה מתחברת לשרת ה-proxy, שרת ה-proxy מדווח על השגיאה הבאה:

    failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME:
googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit
'Queries per minute per user' of service 'sqladmin.googleapis.com' for
consumer 'project_number:$PROJECT_ID., rateLimitExceeded

    פתרון: מזהים את המקור לבעיה במכסה (לדוגמה, אפליקציה שמשתמשת במחבר באופן שגוי ויוצרת חיבורים חדשים שלא לצורך), או פונים לתמיכה כדי לבקש להגדיל את המכסה של Cloud SQL Admin API. אם שגיאת המכסה מופיעה בזמן ההפעלה, צריך לפרוס מחדש את האפליקציה כדי להפעיל מחדש את שרת ה-proxy. אם שגיאת המכסה מופיעה אחרי ההפעלה, אין צורך לפרוס מחדש.

המאמרים הבאים