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 untuk menggunakan Proxy Auth Cloud SQL sebagai pengantar penggunaan dasar.

Anda juga dapat terhubung dengan atau tanpa Proxy Auth Cloud SQL menggunakan klien psql 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. Enable the Cloud SQL Admin API.

    Enable the 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.10.1/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.10.1/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.10.1/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.10.1/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.10.1/cloud-sql-proxy.x64.exe, lalu pilih Save Link As untuk mendownload Proxy Auth Cloud SQL. Ganti nama file menjadi cloud-sql-proxy.exe.

Windows 32 bit

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

Image Docker Proxy Auth Cloud SQL

Auth Proxy Cloud SQL memiliki image container yang berbeda, seperti distroless, alpine, dan buster. Image container Proxy Auth Cloud SQL default menggunakan distroless, yang tidak berisi shell. Jika Anda memerlukan shell atau alat terkait, download gambar berdasarkan alpine atau buster. Untuk mengetahui informasi selengkapnya, lihat Image Container Proxy Auth Cloud SQL.

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

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

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 soket Unix, atau image Docker Proxy Aut Cloud SQL tergantung pada bahasa dan lingkungan. Biner Proxy Auth Cloud SQL terhubung ke salah satu atau beberapa instance Cloud SQL yang ditentukan pada command line dan membuka koneksi lokal instance sebagai soket TCP atau Unix. Aplikasi atau layanan lain seperti kode aplikasi atau alat pengelolaan database klien dapat terhubung ke instance Cloud SQL melalui koneksi soket TCP atau Unix 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. Opsi ini dapat ditemukan pada halaman Ringkasan untuk instance di 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 5432 INSTANCE_CONNECTION_NAME
      
      Port yang ditentukan tidak boleh berupa port yang sedang digunakan, contohnya, 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 lebih lanjut terkait opsi Proxy Auth Cloud SQL, lihat Opsi untuk mengautentikasi Proxy Auth Cloud SQL dan Opsi untuk menentukan instance.

Soket Unix

Proxy Auth Cloud SQL dapat memproses soket Unix karena merupakan mekanisme standar Posix untuk menggunakan folder saat mengelola komunikasi antara dua proses berjalan pada host yang sama. Manfaat dari menggunakan soket Unix adalah peningkatan keamanan dan latensi yang rendah, namun Anda tidak dapat mengakses soket Unix dari mesin eksternal.

Untuk membuat dan menggunakan soket Unix, direktori target harus ada dan aplikasi serta Proxy Auth Cloud SQL harus memiliki akses baca dan tulis ke direktori tersebut.

  1. Jika Anda menggunakan spesifikasi instance eksplisit, salin INSTANCE_CONNECTION_NAME. Anda dapat menemukannya di halaman Ringkasan untuk instance pada konsol Google Cloud atau dengan menjalankan perintah berikut:

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

    Misalnya: myproject:myregion:myinstance.

  2. Buat direktori di tempat soket Proxy Auth Cloud SQL akan diaktifkan:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  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. Buka jendela terminal Cloud Shell baru dan mulai Proxy Auth Cloud SQL.

    Beberapa string pemanggilan Proxy Auth Cloud SQL memungkinkan untuk:

    • Menggunakan akun layanan dan menyertakan nama koneksi instance secara eksplisit (disarankan untuk lingkungan produksi):
      ./cloud-sql-proxy --unix-socket /cloudsql
      --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
    • Menggunakan autentikasi Cloud SDK dan penemuan instance otomatis:
      ./cloud-sql-proxy --unix-socket /cloudsql &

    Mulai Proxy Auth Cloud SQL pada terminal Cloud Shell itu sendiri sehingga Anda dapat memantau output tersebut tanpa bercampur dengan output program lain.

    Untuk informasi lebih lanjut terkait opsi Proxy Auth Cloud SQL, lihat Opsi untuk mengautentikasi Proxy Auth Cloud SQL dan Opsi untuk menentukan instance.

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:5432:5432 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.10.1 \\
  --address 0.0.0.0 --port 5432 \\
  --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.10.1 --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 terkait parameter Proxy Auth Cloud SQL.

Terhubung dengan klien psql

Debian/Ubuntu

Instal klien psql dari pengelola paket:

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

Instal klien psql dari pengelola paket:

sudo yum install postgresql

openSUSE

Instal klien psql dari pengelola paket:

sudo zypper install postgresql

Platform lainnya

  1. Download PostgreSQL Core Distribution untuk platform dari halaman Download PostgreSQL.
    Core Distribution sudah termasuk klien psql.
  2. Instal database PostgreSQL dengan mengikuti petunjuk di halaman download.

String koneksi yang Anda gunakan tergantung pada pilihan untuk memulai Proxy Auth Cloud SQL menggunakan soket TCP soket Unix, atau Docker.

Soket TCP

  1. Mulai klien psql:
    psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
    

    Meskipun parameter sslmode disetel ke disable, Proxy Auth Cloud SQL menyediakan koneksi terenkripsi.

    Ketika Anda terhubung menggunakan soket TCP, Proxy Auth Cloud SQL akan diakses melalui127.0.0.1.

  2. Masukkan sandi apabila diminta.
  3. Prompt psql akan muncul.

Menggunakan soket Unix

  1. Mulai klien psql:
    psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
    

    Meskipun parameter sslmode disetel ke disable, Proxy Auth Cloud SQL menyediakan koneksi terenkripsi.

  2. Masukkan sandi.
  3. Prompt psql akan muncul.

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

Menghubungkan dengan aplikasi

Anda dapat terhubung ke Proxy Auth Cloud SQL dari berbagai bahasa yang membantu untuk terhubung ke soket Unix atau TCP. Di bawah ini terdapat beberapa cuplikan kode dari contoh lengkap di GitHub untuk membantu memahami cara kerja dalam aplikasi.

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. Di kolom Nama akun layanan, masukkan nama deskriptif untuk akun layanan.
  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 telah 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 mengetahui informasi selengkapnya tentang cara menggunakan Proxy Auth Cloud SQL untuk terhubung ke instance yang mengaktifkan Private Service Connect, lihat Terhubung 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.10.1

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:5432:5432 \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.10.1 \
      --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.10.1 --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.

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 salah satu data permintaan, lakukan penggantian 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 saat menggunakan Proxy Auth Cloud SQL

Memanggil Proxy Auth Cloud SQL

Semua contoh pemanggilan proxy memulai Proxy Auth Cloud SQL di latar belakang, sehingga prompt akan ditampilkan. Cadangkan terminal Cloud Shell untuk Proxy Auth Cloud SQL agar terhindar dari percampuran output tersebut dengan output program lain. Selain itu, output dari Proxy Auth Cloud SQL dapat membantu mendiagnosis masalah koneksi sehingga akan membantu merekam file log. Jika tidak memulai Proxy Auth Cloud SQL di latar belakang, output tersebut akan masuk ke stdout kecuali jika dialihkan.

Anda tidak perlu menggunakan /cloudsql sebagai direktori untuk soket Proxy Auth Cloud SQL. (Nama direktori tersebut dipilih untuk meminimalisir perbedaan dengan string koneksi App Engine.) Tetap perhatikan panjang keseluruhan minimum apabila ingin mengubah nama direktori; nama tersebut dimasukkan dalam string lebih panjang dengan batas panjang yang diberlakukan oleh sistem operasi. Batas panjang tersebut tergantung pada sistem, biasanya di antara 91-108 karakter. Di Linux, panjang tersebut ditetapkan sebagai 108 dan Anda dapat memeriksanya menggunakan perintah berikut:

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

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 pilihan untuk menggunakan soket Unix atau TCP.

Soket Unix

Untuk menghubungkan Proxy Auth Cloud SQL ke beberapa instance, Anda perlu menyediakan setiap nama koneksi instance sebagai argumen bagi Proxy Auth Cloud SQL dalam daftar yang dipisahkan spasi. Proxy Auth Cloud SQL terhubung ke setiap instance ketika dimulai.

Anda terhubung ke setiap instance menggunakan soket proxy tersebut di direktori yang telah ditentukan.

Contoh:

      ./cloud-sql-proxy --unix-socket /cloudsql \
      myProject:us-central1:myInstance myProject:us-central1:myInstance2 &
      psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2
  

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=5432" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 5432 on your machine:
    psql -U myUser -h 127.0.0.1  --port 5432

    # Connect to "myInstance2" using port 1234 on your machine:
    psql -U myUser -h 127.0.0.1  --port 1234
  

Pemanggilan Proxy Auth Cloud SQL dan string koneksi klien psql

Anda dapat menggunakan pemanggilan Proxy Auth Cloud SQL dan string koneksi, contohnya, dalam perintah untuk pengguna PostgreSQL myUser dan instance myInstance yang berada di us-central1 dalam project myProject.

Menggunakan penemuan instance otomatis dengan kredensial gcloud CLI:
    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
 
Menggunakan penemuan project dengan kredensial gcloud CLI:
    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
Untuk instance Compute Engine dengan spesifikasi instance yang eksplisit:
    ./cloud-sql-proxy --unix-socket /cloudsql myProject:us-central1:myInstance &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
Untuk Unix, menggunakan TCP:
    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" &
    psql -U myUser -h 127.0.0.1
Untuk Windows (pada prompt command line):
    cloud-sql-proxy.exe "myProject:us-central1:myInstance?port=5432"
    psql -U myUser -h 127.0.0.1

Untuk informasi lebih lanjut terkait string koneksi dan opsi Proxy Auth Cloud SQL, lihat Halaman GitHub Proxy Auth Cloud SQL.

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.

  • 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 mengonfirmasi bahwa Proxy Auth Cloud SQL dimulai dengan tepat dengan melihat log di bagian bawahOperasi > Logging > Logs Explorer pada konsol Google Cloud. Operasi yang berhasil akan terlihat seperti berikut:

    2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/5432 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 selanjutnya