Terhubung menggunakan Proxy Auth Cloud SQL

Halaman ini menjelaskan cara terhubung ke instance Cloud SQL menggunakan Proxy Auth Cloud SQL.

Untuk informasi lebih lanjut, terkait cara kerja Proxy Auth Cloud SQL, lihat Tentang Proxy Auth Cloud SQL.

Ringkasan

Menggunakan Proxy Auth Cloud SQL adalah metode yang direkomendasikan untuk menghubungkan ke instance Cloud SQL. Proxy Auth Cloud SQL:

  • Berfungsi dengan endpoint IP pribadi dan publik
  • Memvalidasi koneksi menggunakan kredensial untuk akun pengguna atau layanan.
  • Menggabungkan koneksi dalam lapisan SSL/TLS yang diberi otorisasi untuk instance Cloud SQL.

Beberapa layanan dan aplikasi Google Cloud menggunakan Proxy Auth Cloud SQL untuk menyediakan koneksi bagi jalur IP publik dengan enkripsi dan otorisasi, termasuk:

Aplikasi yang berjalan di Google Kubernetes Engine dapat terhubung menggunakan Proxy Auth Cloud SQL.

Lihat Panduan memulai menggunakan Proxy Auth Cloud SQL untuk mengetahui pengenalan dasar penggunaannya.

Anda juga dapat terhubung, dengan atau tanpa Proxy Auth Cloud SQL, menggunakan klien mysql dari mesin lokal atau Compute Engine.

Sebelum memulai

Sebelum Anda dapat terhubung ke instance Cloud SQL, lakukan hal berikut:

    • Untuk akun pengguna atau layanan, pastikan akun tersebut memiliki peran Klien Cloud SQL. Peran ini berisi cloudsql.instances.connect izin, yang memberi otorisasi kepada akun utama untuk terhubung ke semua instance Cloud SQL dalam project.

      Buka halaman IAM

    • Anda dapat menyertakan kondisi IAM secara opsional dalam binding kebijakan IAM yang memberikan izin akun untuk terhubung hanya ke satu instance Cloud SQL tertentu.
  1. Aktifkan API Cloud SQL Admin.

    Mengaktifkan API

  2. Menginstal dan melakukan inisialisasi gcloud CLI.
  3. Opsional. Instal klien Docker Proxy Auth Cloud SQL.

Mendownload Proxy Auth Cloud SQL

Linux 64 bit

  1. Download Proxy Auth Cloud SQL:
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.linux.amd64
  2. Buat Proxy Auth Cloud SQL agar dapat dieksekusi:
    chmod +x cloud-sql-proxy

Linux 32 bit

  1. Download Proxy Auth Cloud SQL:
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.linux.386
  2. Jika perintah curl tidak ditemukan, jalankan sudo apt install curl dan ulangi perintah download.
  3. Buat Proxy Auth Cloud SQL agar dapat dieksekusi:
    chmod +x cloud-sql-proxy

macOS 64-bit

  1. Download Proxy Auth Cloud SQL:
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.darwin.amd64
  2. Buat Proxy Auth Cloud SQL agar dapat dieksekusi:
    chmod +x cloud-sql-proxy

Mac M1

  1. Download Proxy Auth Cloud SQL:
      curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.darwin.arm64
      
  2. Buat Proxy Auth Cloud SQL agar dapat dieksekusi:
      chmod +x cloud-sql-proxy
      

Windows 64 bit

Klik kanan https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x64.exe dan pilih Save Link As untuk mendownload Cloud SQL Auth Proxy. Ganti nama file menjadi cloud-sql-proxy.exe.

Windows 32 bit

Klik kanan https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x86.exe dan pilih Save Link As untuk mendownload Cloud SQL Auth Proxy. Ganti nama file menjadi cloud-sql-proxy.exe.

Image Docker Proxy Auth Cloud SQL

Proxy Auth Cloud SQL memiliki image penampung yang berbeda, seperti distroless, alpine, dan buster. Image container Cloud SQL Auth Proxy default digunakan distroless, yang tidak mengandung {i>shell<i}. Jika Anda membutuhkan {i>shell<i} atau alat terkait, maka unduh {i>image<i} berdasarkan alpine atau buster. Untuk mengetahui informasi selengkapnya, lihat Image Penampung Proxy Auth Cloud SQL.

Anda dapat menarik image terbaru ke mesin lokal Anda menggunakan Docker menggunakan perintah berikut:

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

OS Lainnya

Untuk sistem operasi lain yang tidak disertakan di sini, Anda dapat mengompilasi Proxy Auth Cloud SQL dari sumber.

Memulai Proxy Auth Cloud SQL

Anda dapat memulai Proxy Auth Cloud SQL menggunakan soket TCP atau image Docker Proxy Auth Cloud SQL. Biner Proxy Auth Cloud SQL terhubung ke satu atau beberapa instance Cloud SQL yang ditentukan pada command line, dan membuka koneksi lokal sebagai soket TCP. Aplikasi dan layanan lain, seperti kode aplikasi atau alat klien pengelolaan database Anda, dapat terhubung ke instance Cloud SQL melalui koneksi soket TCP tersebut.

Soket TCP

Proxy Auth Cloud SQL memproses localhost(127.0.0.1) secara default untuk koneksi TCP. Oleh karena itu, saat Anda menentukan --port PORT_NUMBER untuk instance, koneksi lokal berada di 127.0.0.1:PORT_NUMBER.

Anda dapat menentukan alamat yang berbeda untuk koneksi lokal sebagai alternatif lain. Sebagai contoh, berikut ini cara membuat Proxy Auth Cloud SQL memproses 0.0.0.0:1234 untuk koneksi lokal:

./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME
  1. Salin INSTANCE_CONNECTION_NAME. Ini dapat ditemukan pada halaman Overview untuk instance Anda dalam Konsol Google Cloud atau dengan menjalankan perintah berikut:

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

    Misalnya: myproject:myregion:myinstance.

  2. Apabila instance memiliki IP pribadi dan publik yang sudah dikonfigurasi kemudian ingin Proxy Auth Cloud SQL tersebut menggunakan alamat IP pribadi, Anda harus menyediakan opsi berikut saat memulai Proxy Auth Cloud SQL:
    --private-ip
  3. Apabila menggunakan akun layanan untuk mengautentikasi Proxy Auth Cloud SQL, perhatikan lokasi file kunci pribadi yang dibuat saat Anda mengelola akun layanan tersebut di komputer klien.
  4. Memulai Proxy Auth Cloud SQL.

    Beberapa string pemanggilan Proxy Auth Cloud SQL memungkinkan untuk:

    • Menggunakan autentikasi Cloud SDK:
      ./cloud-sql-proxy --port 1433 INSTANCE_CONNECTION_NAME
      Port yang ditentukan harus belum digunakan, misalnya, oleh server database lokal.
    • Menggunakan akun layanan dan menyertakan nama koneksi instance secara eksplisit (disarankan untuk lingkungan produksi):
      ./cloud-sql-proxy \
      --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

    Untuk informasi selengkapnya tentang opsi Proxy Auth Cloud SQL, lihat Opsi untuk mengautentikasi Proxy Auth Cloud SQL.

Docker

Untuk menjalankan Proxy Auth Cloud SQL pada container Docker, gunakan image Docker Proxy Auth Cloud SQL yang tersedia dari Google Container Registry.

Anda dapat memulai Proxy Auth Cloud SQL menggunakan soket TCP atau soket Unix, dengan perintah yang ditampilkan di bawah ini. Opsi tersebut menggunakan INSTANCE_CONNECTION_NAME sebagai string koneksi untuk mengidentifikasi instance Cloud SQL. Anda dapat menemukan INSTANCE_CONNECTION_NAME pada halaman Ringkasan untuk instance dalam konsol Google Cloud. atau dengan menjalankan perintah berikut:

gcloud sql instances describe INSTANCE_NAME
.

Misalnya: myproject:myregion:myinstance.

Anda dapat memulai Proxy Auth Cloud SQL menggunakan soket TCP atau soket Unix tergantung pada bahasa dan lingkungan. Soket Unix tidak didukung untuk aplikasi yang ditulis dalam bahasa pemrograman Java atau untuk lingkungan Windows.

Menggunakan soket 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.13.0 \\
  --address 0.0.0.0 --port 1433 \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Apabila Anda menggunakan kredensial yang disediakan oleh instance Compute Engine, jangan sertakan parameter --credentials-file dan baris. -v PATH_TO_KEY_FILE:/path/to/service-account-key.json

Selalu tentukan awalan 127.0.0.1 pada -p sehingga Proxy Auth Cloud SQL tidak diekspos ke luar host lokal. "0.0.0.0" pada parameter instance diperlukan agar port dapat diakses dari luar container Docker.

Menggunakan soket Unix

docker run -d -v /cloudsql:/cloudsql \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0 --unix-socket=/cloudsql \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Apabila Anda menggunakan kredensial yang disediakan oleh instance Compute Engine, jangan sertakan parameter --credentials-file dan baris. -v PATH_TO_KEY_FILE:/path/to/service-account-key.json

Apabila Anda menggunakan image yang dioptimalkan untuk container, gunakan direktori yang dapat ditulis sebagai pengganti /cloudsql, contohnya:

-v /mnt/stateful_partition/cloudsql:/cloudsql

Anda dapat menentukan lebih dari satu instance yang dipisahkan dengan koma. Anda juga dapat menggunakan metadata Compute Engine untuk menentukan instance yang akan dihubungkan secara dinamis. Pelajari lebih lanjut tentang parameter Proxy Auth Cloud SQL.

Terhubung dengan klien sqlcmd

Debian/Ubuntu

Untuk Debian/Ubuntu, instal alat command line SQL Server yang berlaku.

CentOS/RHEL

Untuk CentOS/RHEL, instal alat command line SQL Server yang berlaku.

OpenSUSE

Untuk openSUSE, instal alat command line SQL Server yang berlaku.

Platform lainnya

Lihat halaman landing untuk menginstal SQL Server, serta halaman download SQL Server.

String koneksi yang Anda gunakan bergantung pada apakah Anda memulai Proxy Auth Cloud SQL menggunakan soket TCP atau Docker.

Soket TCP

  1. Mulai klien sqlcmd:
    sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD

    Saat Anda terhubung menggunakan soket TCP, Proxy Auth Cloud SQL diakses melalui 127.0.0.1.

  2. Jika diminta, masukkan sandi.
  3. Perintah sqlcmd akan muncul.

Butuh bantuan? Untuk menemukan bantuan pemecahan masalah proxy, lihat Memecahkan masalah koneksi Proxy Auth Cloud SQL, atau lihat halaman Dukungan Cloud SQL.

Terhubung dengan aplikasi

Anda dapat terhubung ke Proxy Auth Cloud SQL dari bahasa apa pun yang memungkinkan untuk terhubung ke soket TCP. Berikut ini beberapa cuplikan kode dari contoh lengkap di GitHub untuk membantu Anda memahami cara kerjanya dalam aplikasi.

Menghubungkan dengan TCP

Pernyataan pemanggilan Proxy Auth Cloud SQL:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di 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

Untuk menemukan cuplikan ini dalam konteks aplikasi web, lihat README pada GitHub.

Catatan:

  • CLOUD-SQL-CONNECTION-NAME harus ditampilkan sebagai <MY-PROJECT>:<INSTANCE-REGION><INSTANCE-NAME>
  • Menggunakan argumen ipTypes=PRIVATE akan memaksa SocketFactory untuk terhubung dengan IP pribadi yang terkait dengan instance.
  • Lihat persyaratan versi factory soket JDBC untuk file pom.xml di sini .


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

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di 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);
};

Go

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di 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#

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di 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

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di 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

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di 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;
    }
}

Topik tambahan

Argumen command line Proxy Auth Cloud SQL

Contoh di atas termasuk kasus penggunaan paling umum, namun Proxy Auth Cloud SQL juga memiliki opsi konfigurasi lain yang dapat disetel dengan argumen command line. Untuk mendapatkan bantuan terkait argumen command line, gunakan flag --help untuk melihat dokumentasi terbaru:

./cloud-sql-proxy --help

Lihat README pada repositori GitHub Proxy Auth Cloud SQL untuk menemukan contoh tambahan terkait cara menggunakan opsi command line Proxy Auth Cloud SQL.

Opsi untuk mengautentikasi Proxy Auth Cloud SQL

Semua opsi ini menggunakan INSTANCE_CONNECTION_NAME sebagai string koneksi untuk mengidentifikasi instance Cloud SQL. Anda dapat menemukan INSTANCE_CONNECTION_NAME pada halaman Ringkasan untuk instance dalam konsol Google Cloud. atau dengan menjalankan perintah berikut:

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME.

Sebagai contoh: gcloud sql instances describe --project myproject myinstance .

Beberapa opsi ini menggunakan file kredensial JSON yang mencakup kunci pribadi RSA untuk akun tersebut. Untuk menemukan petunjuk terkait cara membuat file kredensial JSON untuk akun layanan, lihat Membuat akun layanan.

Proxy Auth Cloud SQL menyediakan beberapa alternatif untuk autentikasi tergantung pada lingkungan. Proxy Auth Cloud SQL menggunakan item pertama yang ditemukan saat percobaan autentikasi untuk mengecek setiap item sesuai urutan berikut:

  1. Kredensial yang disediakan oleh flag file kredensial.

    Gunakan akun layanan untuk membuat dan mendownload file JSON terkait dan tetapkan flag --credentials-file ke jalur file saat Anda memulai Proxy Auth Cloud SQL. Akun layanan harus memiliki izin yang diperlukan untuk instance Cloud SQL.

    Untuk menggunakan opsi ini pada command line, panggil perintah cloud-sql-proxy dengan flag --credentials-file yang ditetapkan ke nama file dan jalur file kredensial JSON. Jalur tersebut dapat bersifat absolut atau relatif sesuai direktori kerja saat ini. Contoh:

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

    Untuk informasi lebih lanjut terkait cara menambahkan peran IAM ke akun layanan, lihat Memberikan peran ke Akun Layanan.

    Untuk informasi lebih lanjut terkait peran yang didukung Cloud SQL, lihat Peran IAM untuk Cloud SQL.

  2. Kredensial yang disediakan oleh token akses.

    Buat token akses dan panggil perintah cloud-sql-proxy dengan flag --token yang ditetapkan ke token akses OAuth 2.0. Contoh:
    ./cloud-sql-proxy --token ACCESS_TOKEN \
    INSTANCE_CONNECTION_NAME
      
  3. Kredensial yang disediakan oleh variabel lingkungan.

    Opsi ini mirip dengan menggunakan flag --credentials-file, kecuali Anda menentukan file kredensial JSON yang ditetapkan dalam GOOGLE_APPLICATION_CREDENTIALS variabel lingkungan daripada menggunakan argumen command line --credentials-file.
  4. Kredensial dari klien gcloud CLI yang diautentikasi.

    Apabila Anda telah menginstal gcloud CLI dan melakukan autentikasi dengan akun pribadi, Proxy Auth Cloud SQL dapat menggunakan kredensial akun yang sama. Metode ini sangat membantu untuk mendapatkan lingkungan pengembangan dan menjalankannya.

    Untuk mengaktifkan Proxy Auth Cloud SQL AGAR dapat menggunakan kredensial gcloud CLI, gunakan perintah berikut untuk mengautentikasi gcloud CLI:

    gcloud auth application-default login
  5. Kredensial yang terkait dengan instance Compute Engine.

    Apabila terhubung ke Cloud SQL dari instance Compute Engine, Proxy Auth Cloud SQL dapat menggunakan akun layanan yang terkait dengan instance Compute Engine. Apabila akun layanan memiliki izin yang diperlukan untuk instance Cloud SQL, autentikasi Proxy Auth Cloud SQL akan berhasil.

    Apabila instance Compute Engine berada dalam project yang sama dengan instance Cloud SQL, akun layanan default untuk instance Compute Engine memiliki izin yang diperlukan untuk mengautentikasi Proxy Auth Cloud SQL. Apabila kedua instance berada di project berbeda, Anda harus menambahkan akun layanan instance Compute Engine ke project yang berisi instance Cloud SQL.

  6. Akun layanan default lingkungan

    Apabila Proxy Cloud SQL tidak dapat menemukan kredensial di tempat mana pun yang telah dibahas sebelumnya, proxy tersebut mengikuti logika yang didokumentasikan dalam Menyiapkan Autentikasi untuk Server ke Aplikasi Produksi Server. Beberapa lingkungan (seperti Compute Engine, App Engine, dan lainnya) menyediakan akun layanan default yang dapat digunakan oleh aplikasi untuk melakukan autentikasi secara default. Apabila menggunakan akun layanan, akun tersebut harus memiliki izin yang diuraikan dalam peran dan izin Untuk informasi lebih lanjut terkait pendekatan autentikasi Google Cloud, lihat Ringkasan autentikasi.

Membuat akun layanan

  1. Di Konsol Google Cloud, buka halaman Service accounts.

    Buka halaman Service accounts

  2. Pilih project yang berisi instance Cloud SQL.
  3. Klik Create service account.
  4. Pada kolom Nama akun layanan, masukkan nama deskriptif untuk akun tersebut.
  5. Ubah ID akun layanan menjadi nilai yang unik dan dapat dikenali, kemudian klik Buat dan lanjutkan.
  6. Klik kolom Pilih peran dan pilih salah satu dari peran berikut:
    • Cloud SQL > Klien Cloud SQL
    • Cloud SQL > Editor Cloud SQL
    • Cloud SQL > Admin Cloud SQL
  7. Klik Selesai untuk menyelesaikan pembuatan akun layanan.
  8. Klik menu tindakan untuk akun layanan baru kemudian pilih Mengelola kunci.
  9. Klik menu drop-down Tambahkan kunci kemudian klik Buat kunci baru.
  10. Lakukan konfirmasi bahwa jenis kunci tersebut adalah JSON kemudian klik Buat.

    File kunci pribadi telah didownload ke mesin. Anda dapat memindahkan file tersebut ke lokasi lain. Jaga agar file kunci tetap aman.

Menggunakan Proxy Auth Cloud SQL dengan IP pribadi

Untuk terhubung ke instance Cloud SQL menggunakan IP pribadi, Proxy Auth Cloud SQL harus berada pada resource dengan akses ke jaringan VPC yang sama sebagai instance.

Proxy Auth Cloud SQL menggunakan IP untuk membangun koneksi dengan instance Cloud SQL. Proxy Auth Cloud SQL mencoba untuk terhubung menggunakan alamat IPv4 publik secara default.

Apabila instance Cloud SQL hanya memiliki IP pribadi atau instance tersebut memiliki IP pribadi dan publik yang dikonfigurasi kemudian ingin Proxy Auth Cloud SQL tersebut menggunakan alamat IP pribadi, maka Anda harus menyediakan opsi berikut ketika memulai Proxy Auth Cloud SQL:

--private-ip

Menggunakan Proxy Auth Cloud SQL dengan instance yang mengaktifkan Private Service Connect

Anda dapat menggunakan Proxy Auth Cloud SQL untuk terhubung ke instance Cloud SQL dengan Private Service Connect yang diaktifkan.

Auth Proxy Cloud SQL adalah konektor yang menyediakan akses aman ke instance ini tanpa memerlukan jaringan yang diizinkan atau untuk mengonfigurasi SSL.

Untuk mengizinkan koneksi klien Proxy Auth Cloud SQL, Anda harus menyiapkan data DNS yang cocok dengan nama DNS yang direkomendasikan, yang disediakan untuk instance. Pencatatan DNS adalah pemetaan antara sumber daya DNS dan nama domain.

Untuk informasi selengkapnya tentang cara menggunakan Proxy Auth Cloud SQL untuk terhubung ke instance dengan Private Service Connect yang diaktifkan, lihat Menghubungkan menggunakan Proxy Auth Cloud SQL.

Menjalankan Proxy Auth Cloud SQL dalam proses terpisah

Menjalankan Proxy Auth Cloud SQL dalam proses terminal Cloud Shell terpisah berguna untuk menghindari percampuran output konsol tersebut dengan output program lainnya. Gunakan sintaksis yang ditampilkan di bawah ini untuk memanggil Proxy Auth Cloud SQL dalam proses terpisah.

Linux

Pada Linux atau macOS, gunakan tanda penghubung & pada command line untuk meluncurkan Proxy Auth Cloud SQL dalam proses terpisah:

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

Windows

Pada Windows PowerShell, gunakan perintah Start-Process untuk meluncurkan Proxy Auth Cloud SQL dalam proses terpisah:

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

Menjalankan Proxy Auth Cloud SQL di container Docker

Untuk menjalankan Proxy Auth Cloud SQL pada container Docker, gunakan image Docker Proxy Auth Cloud SQL yang tersedia dari Google Container Registry. Anda dapat menginstal image Docker Proxy Auth Cloud SQL dengan perintahgcloud ini:

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

Anda dapat memulai Proxy Auth Cloud SQL menggunakan soket TCP atau soket Unix, dengan perintah yang ditampilkan di bawah ini.

Soket 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.13.0 \
      --address 0.0.0.0 \
      --credentials-file /path/to/service-account-key.json \
      INSTANCE_CONNECTION_NAME

Soket Unix

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0 --unix-socket /cloudsql \
      --credentials-file /path/to/service-account-key.json/PATH_TO_KEY_FILE \
      INSTANCE_CONNECTION_NAME

Apabila menggunakan image yang dioptimalkan untuk kontainer, gunakan direktori yang dapat ditulis sebagai pengganti /cloudsql, sebagai contoh:

v /mnt/stateful_partition/cloudsql:/cloudsql

Apabila menggunakan kredensial yang disediakan oleh instance Compute Engine, jangan sertakan parameter credential_file dan baris -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Menjalankan Proxy Auth Cloud SQL sebagai layanan

Menjalankan Proxy Auth Cloud SQL sebagai layanan latar belakang adalah opsi untuk pengembangan lokal dan beban kerja produksi. Ketika perlu mengakses instance Cloud SQL dalam pengembangan, Anda dapat memulai layanan di latar belakang dan menghentikannya setelah selesai.

Proxy Auth Cloud SQL saat ini tidak menyediakan dukungan bawaan untuk dijalankan sebagai layanan Windows, namun pengelola layanan pihak ketiga dapat digunakan untuk menjalankan proxy sebagai layanan untuk beban kerja produksi. Sebagai contoh, Anda dapat menggunakan NSSM untuk mengonfigurasi Proxy Auth Cloud SQL sebagai layanan Windows, kemudian NSSM memantau Proxy Auth Cloud SQL dan memulai ulang secara otomatis apabila berhenti merespons. Lihat Dokumentasi NSSM untuk informasi lebih lanjut.

Terhubung saat SSL diperlukan

Menerapkan penggunaan Proxy Auth Cloud SQL

Aktifkan penggunaan Proxy Auth Cloud SQL pada Cloud SQL menggunakan ConnectorEnforcement.

gcloud

Perintah berikut menerapkan penggunaan konektor Cloud SQL.

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

Untuk menonaktifkan penerapan tersebut, gunakan baris kode berikut: --connector-enforcement NOT_REQUIRED Pembaruan tidak akan memicu mulai ulang.

REST v1

Perintah berikut menerapkan konektor Cloud SQL

Sebelum menggunakan data permintaan apa pun, lakukan penggantian sebagai berikut:

  • project-id: Project ID.
  • instance-id: ID instance.

Metode HTTP dan URL:

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

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan menerima respon JSON serupa dengan yang berikut ini:

{
  "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"
}

Untuk menonaktifkan penerapan, gunakan "connectorEnforcement": "NOT_REQUIRED" sebagai gantinya. Pembaruan tersebut tidak memicu mulai ulang.

REST v1beta4

Perintah berikut menerapkan penggunaan konektor Cloud SQL.

Sebelum menggunakan data permintaan apa pun, lakukan penggantian sebagai berikut:

  • project-id: Project ID.
  • instance-id: ID instance.

Metode HTTP dan URL:

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

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan menerima respon JSON serupa dengan yang berikut ini:

{
  "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"
}

Untuk menonaktifkan penerapan, gunakan "connectorEnforcement": "NOT_REQUIRED" sebagai gantinya. Pembaruan tersebut tidak memicu mulai ulang.

Tips bekerja dengan Proxy Auth Cloud SQL

Menggunakan Proxy Auth Cloud SQL untuk terhubung ke beberapa instance

Anda dapat menggunakan satu klien Proxy Auth Cloud SQL lokal untuk terhubung dengan beberapa instance Cloud SQL. Cara melakukannya tergantung pada Anda apakah menggunakan soket Unix atau TCP.

Soket TCP

Ketika terhubung menggunakan TCP, Anda menentukan port pada mesin untuk Proxy Auth Cloud SQL yang akan dipantau selama memproses setiap instance Cloud SQL. Ketika menghubungkan ke berbagai instance Cloud SQL, setiap port yang telah ditentukan harus unik dan tersedia untuk digunakan pada mesin.

Contoh:

    # 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"
  

Memecahkan masalah koneksi Proxy Auth Cloud SQL

Image Docker Proxy Auth Cloud SQL berdasarkan versi tertentu Proxy Auth Cloud SQL. Ketika versi terbaru Proxy Auth Cloud SQL tersedia, tarik image Docker Proxy Auth Cloud SQL versi baru untuk menjaga lingkungan tetap menjadi yang terbaru. Lihat versi terbaru Proxy Auth Cloud SQL dengan mengecek halaman rilis Proxy Auth Cloud SQL.

Jika mendapat masalah saat menghubungkan ke instance Cloud SQL menggunakan Proxy Auth Cloud SQL, the Cloud SQL Auth Proxy, berikut adalah beberapa hal yang dapat dilakukan untuk menemukan penyebab masalah tersebut.

  • Pastikan Anda menggunakan alamat IP untuk terhubung ke instance, bukan endpoint tulis.
  • Mengecek output Proxy Cloud SQL.

    Output Proxy Auth Cloud SQL sering kali dapat membantu menentukan sumber masalah dan bagaimana menyelesaikan masalah tersebut. Masukkan output ke file atau perhatikan terminal Cloud Shell tempat memulai Proxy Auth Cloud SQL.

  • Jika menemukan error 403 notAuthorized dan sedang menggunakan akun layanan untuk mengautentikasi Proxy Auth Cloud SQL, pastikan akun layanan tersebut memiliki izin yang tepat.

    Anda dapat mengecek akun layanan dengan menelusuri ID akun tersebut pada Halaman IAM. Akun tersebut harus memiliki izin cloudsql.instances.connect. Peran yang telah ditetapkan Cloud SQL Admin, Client dan Editor memiliki izin ini.

  • Jika terhubung dari App Engine dan menemukan 403 notAuthorized error, periksa nilai app.yaml cloud_sql_instances untuk mencari nama koneksi instance yang tidak tepat atau salah eja. Nama koneksi instance biasanya sesuai dengan format PROJECT:REGION:INSTANCE.

    Selain itu periksa apakah akun layanan App Engine memiliki peran IAM Klien Cloud SQL (sebagai contoh, $PROJECT_ID@appspot.gserviceaccount.com).

    Apabila layanan App Engine berada dalam salah satu project (project A) dan database berada di project lainnya (project B), error ini berarti akun layanan App Engine belum diberi peran IAM Klien Cloud SQL dalam project yang berisi database (project B).

  • Pastikan untuk mengaktifkan Cloud SQL Admin API.

    Jika tidak, Anda akan melihat output seperti Error 403: Access Not Configured dalam log Proxy Auth Cloud SQL.

  • Apabila menyertakan beberapa instance dalam daftar, pastikan untuk menggunakan koma sebagai pembatas tanpa spasi. Apabila menggunakan TCP, pastikan untuk menentukan port yang berbeda bagi setiap instance.

  • Apabila terhubung menggunakan soket Unix, lakukan konfirmasi bahwa soket tersebut telah dibuat dengan mencantumkan direktori yang disediakan saat memulai Proxy Auth Cloud SQL.

  • Apabila terdapat kebijakan firewall keluar, pastikan kebijakan tersebut mengizinkan koneksi ke port 3307 pada instance Cloud SQL target.

  • Anda dapat memastikan bahwa Proxy Auth Cloud SQL dimulai dengan benar dengan melihat log di bagian Operations > Logging > Logs explorer pada Google Cloud Console. Operasi yang berhasil akan terlihat seperti berikut:

    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
    
  • Masalah kuota: Apabila kuota Cloud SQL Admin API dilanggar, Proxy Auth Cloud SQL akan dimulai dengan pesan error berikut:

    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
    

    Setelah aplikasi terhubung ke proxy, akan muncul laporan error seperti berikut:

    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
    

    Solusi: Identifikasi sumber masalah kuota, sebagai contoh, aplikasi menyalahgunakan konektor dan membuat koneksi baru yang tidak perlu, atau hubungi dukungan untuk meminta peningkatan kuota Cloud SQL Admin API. Apabila error kuota muncul saat memulai, aplikasi harus di-deploy kembali untuk memulai ulang proxy. Apabila error kuota muncul setelah memulai, deploy ulang tidak perlu dilakukan.

Langkah berikutnya