Halaman ini menjelaskan cara menggunakan klien psql, yang diinstal pada instance Compute Engine, untuk terhubung ke Cloud SQL.
Anda dapat menggunakan IP pribadi, IP publik, Proxy Auth Cloud SQL, atau image Docker Proxy Auth Cloud SQL.
Untuk mengetahui petunjuk langkah demi langkah cara menjalankan aplikasi web contoh Compute Engine yang terhubung ke Cloud SQL, baca panduan memulai untuk menghubungkan dari Compute Engine.
Sebelum memulai
Tugas ini tidak termasuk petunjuk untuk menyiapkan instance Compute Engine. Jika Anda memerlukan bantuan dalam membuat dan mengonfigurasi instance Compute Engine, baca dokumentasi Compute Engine.
IP Pribadi
Agar dapat terhubung ke Cloud SQL dari instance Compute Engine menggunakan IP pribadi, akses layanan pribadi harus disiapkan untuk lingkungan Anda, dan instance Cloud SQL Anda harus dikonfigurasi untuk menggunakan IP pribadi. Instance Compute Engine Anda harus berada di region yang sama dengan instance Cloud SQL, dan di jaringan yang dikonfigurasi untuk koneksi pribadi. Pelajari lebih lanjut.
1. Konfigurasikan instance Anda untuk menggunakan IP pribadi
Gunakan petunjuk di Mengonfigurasi Konektivitas IP Pribadi.
2. Buka koneksi terminal Cloud Shell ke instance Compute Engine Anda.
Gunakan petunjuk yang tepat, bergantung pada sistem operasi instance:
- Untuk Linux, lihat Menghubungkan ke VM Linux.
- Untuk Windows, lihat Menghubungkan ke VM Windows.
Jika instance Compute Engine Anda menjalankan image publik RHEL atau CentOS, SELinux mungkin akan memblokir koneksi proxy. Jika hal ini terjadi, Anda harus mengonfigurasi fitur SELinux untuk mengizinkan koneksi.
Untuk mengetahui informasi selengkapnya tentang SELinux untuk RHEL, lihat dokumentasi RHEL. Untuk informasi selengkapnya tentang SELinux untuk CentOS, lihat dokumentasi CentOS.
3. Instal klien psql pada instance Compute Engine, jika belum diinstal.
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
- Download PostgreSQL Core Distribution untuk platform dari
halaman Download PostgreSQL.
Core Distribution sudah termasuk klien psql. - Instal database PostgreSQL, dengan mengikuti petunjuk di halaman download.
4. Hubungkan dengan klien psql.
psql -h CLOUD_SQL_PRIVATE_IP_ADDRESS -U USERNAME
Anda dapat menemukan alamat IP pribadi di
halaman instance Cloud SQL atau dengan menjalankan perintah
gcloud
berikut:
gcloud sql instances list
IP Publik
Untuk terhubung menggunakan IP publik:
1. Tambahkan alamat IP IPv4 statis ke instance Compute Engine, jika belum memilikinya.
Anda tidak dapat terhubung ke Compute Engine menggunakan IPv6. Untuk mengetahui informasi tentang cara menambahkan alamat IP statis, lihat Mencadangkan alamat IP eksternal statis baru dalam dokumentasi Compute Engine.
2. Izinkan alamat IP statis instance Compute Engine sebagai jaringan yang dapat terhubung ke instance Cloud SQL Anda.
Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi akses untuk koneksi IP publik.
3. Buka koneksi terminal Cloud Shell ke instance Compute Engine Anda.
Gunakan petunjuk yang tepat, bergantung pada sistem operasi instance:
- Untuk Linux, lihat Menghubungkan ke VM Linux.
- Untuk Windows, lihat Menghubungkan ke VM Windows.
Jika instance Compute Engine Anda menjalankan image publik RHEL atau CentOS, SELinux mungkin akan memblokir koneksi proxy. Jika hal ini terjadi, Anda harus mengonfigurasi fitur SELinux untuk mengizinkan koneksi.
Untuk mengetahui informasi selengkapnya tentang SELinux untuk RHEL, lihat dokumentasi RHEL. Untuk mengetahui informasi selengkapnya tentang SELinux untuk CentOS, lihat dokumentasi CentOS.
4. Instal klien psql pada instance Compute Engine, jika belum diinstal.
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
- Download PostgreSQL Core Distribution untuk platform dari
halaman Download PostgreSQL.
Core Distribution sudah termasuk klien psql. - Instal database PostgreSQL, dengan mengikuti petunjuk di halaman download.
5. Hubungkan dengan klien psql.
psql -h CLOUD_SQL_PUBLIC_IP_ADDR -U USERNAME
Anda dapat menemukan alamat IP publik di
halaman instance Cloud SQL atau dengan menjalankan perintah
gcloud
berikut:
gcloud sql instances list
Untuk contoh cara menghubungkan menggunakan SSL, lihat Menghubungkan dengan SSL.
6. Perintah psql akan muncul.
7. Jika Anda perlu mengaktifkan koneksi yang tidak digunakan:
Setel keepalive TCP.
Untuk mengetahui informasi lebih lanjut, lihat Berkomunikasi antara instance dan Internet dalam dokumentasi Compute Engine.
Koneksi akan tetap aktif secara otomatis untuk instance.
Proxy Auth Cloud SQL
Untuk terhubung menggunakan Proxy Auth Cloud SQL dari Compute Engine:1. Aktifkan Cloud SQL Admin API.
2. Membuat akun layanan.
- Di Konsol Google Cloud, buka halaman Service accounts.
- Pilih project yang berisi instance Cloud SQL.
- Klik Create service account.
- Pada kolom Nama akun layanan, masukkan nama deskriptif untuk akun tersebut.
- Ubah ID akun layanan menjadi nilai yang unik dan dapat dikenali, kemudian klik Buat dan lanjutkan.
-
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
- Klik Selesai untuk menyelesaikan pembuatan akun layanan.
- Klik menu tindakan untuk akun layanan baru kemudian pilih Mengelola kunci.
- Klik menu drop-down Tambahkan kunci kemudian klik Buat kunci baru.
-
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. Simpan file kunci dengan aman.
Jika instance Compute Engine berada dalam project yang berbeda dengan instance Cloud SQL, pastikan akun layanannya memiliki izin yang tepat di project yang berisi instance Cloud SQL:
- Buka listingan instance Compute Engine di konsol Google Cloud.
- Jika perlu, pilih project yang berkatan dengan instance Compute Engine.
- Pilih instance Compute Engine untuk menampilkan propertinya.
- Di properti instance Compute Engine, salin nama akun layanan.
- Buka halaman Project IAM & Admin di konsol Google Cloud.
- Pilih project yang berisi instance Cloud SQL.
- Telusuri nama akun layanan.
-
Jika akun layanan sudah ada, dan memiliki peran yang menyertakan izin
cloudsql.instances.connect
, Anda dapat melanjutkan ke langkah 4.Peran
Cloud SQL Client
,Cloud SQL Editor
, danCloud SQL Admin
memberikan izin yang diperlukan, seperti halnya peran projectEditor
danOwner
lama. - Atau, tambahkan akun layanan dengan mengklik Tambahkan.
Pada dialog Add Principals, masukkan nama akun layanan dan pilih peran yang menyertakan izin
cloudsql.instances.connect
(peran Cloud SQL yang telah ditetapkan sebelumnya, selain Viewer, akan berfungsi).Sebagai alternatif, Anda dapat menggunakan peran Editor dasar dengan memilih Project > Editor, tetapi peran Editor mencakup izin di seluruh Google Cloud.
Jika tidak melihat peran ini, pengguna Google Cloud Anda mungkin tidak memiliki izin
resourcemanager.projects.setIamPolicy
. Anda dapat memeriksa izin dengan membuka halaman IAM di konsol Google Cloud dan menelusuri ID pengguna Anda.- Klik Tambahkan.
Sekarang Anda melihat akun layanan yang tercantum dengan peran yang ditentukan.
3. Buka koneksi terminal ke instance Compute Engine Anda.
Gunakan petunjuk yang tepat, bergantung pada sistem operasi instance:
- Untuk Linux, lihat Menghubungkan ke Instance Linux.
- Untuk Windows, lihat Menghubungkan ke Instance Windows.
Jika instance Compute Engine Anda menjalankan image publik RHEL atau CentOS, SELinux mungkin akan memblokir koneksi proxy. Jika hal ini terjadi, Anda harus mengonfigurasi fitur SELinux untuk mengizinkan koneksi.
Untuk mengetahui informasi selengkapnya tentang SELinux untuk RHEL, lihat dokumentasi RHEL. Untuk mengetahui informasi selengkapnya tentang SELinux untuk CentOS, lihat dokumentasi CentOS.
4. Instal klien psql pada instance Compute Engine, jika belum diinstal.
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
- Download PostgreSQL Core Distribution untuk platform dari
halaman Download PostgreSQL.
Core Distribution sudah termasuk klien psql. - Instal database PostgreSQL, dengan mengikuti petunjuk di halaman download.
5. Instal Proxy Auth Cloud SQL pada instance Compute Engine.
Linux 64 bit
- Download Proxy Auth Cloud SQL:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.linux.amd64
- Buat Proxy Auth Cloud SQL agar dapat dieksekusi:
chmod +x cloud-sql-proxy
Linux 32 bit
- Download Proxy Auth Cloud SQL:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.linux.386
- Jika perintah
curl
tidak ditemukan, jalankansudo apt install curl
dan ulangi perintah download. - Jadikan Proxy Auth Cloud SQL dapat dieksekusi:
chmod +x cloud-sql-proxy
Windows 64 bit
Klik kanan https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.x64.exe dan pilih Simpan Link Sebagai untuk mendownload Proxy Auth Cloud SQL. Ganti nama file menjadicloud-sql-proxy.exe
.
Windows 32 bit
Klik kanan https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.x86.exe dan pilih Simpan Link Sebagai untuk mendownload Proxy Auth Cloud SQL. Ganti nama file menjadicloud-sql-proxy.exe
.
Image Docker Proxy Auth Cloud SQL
Proxy Auth Cloud SQL memiliki image penampung yang berbeda, seperti distroless
, alpine
, dan buster
. Image penampung Proxy Auth Cloud SQL default menggunakan
distroless
, yang
tidak berisi shell. Jika Anda memerlukan shell atau alat terkait, download image berdasarkan
alpine
atau buster
.
Untuk mengetahui informasi selengkapnya, lihat
Image Penampung 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.14.1
OS Lainnya
Untuk sistem operasi lain yang tidak disertakan di sini, Anda dapat mengompilasi Proxy Auth Cloud SQL dari sumber.6. Mulai Proxy Auth Cloud SQL.
Bergantung pada bahasa dan lingkungan, Anda dapat memulai Proxy Auth Cloud SQL menggunakan soket TCP, soket Unix, atau image Docker Proxy Cloud SQL Auth. 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
Salin INSTANCE_CONNECTION_NAME. Opsi ini dapat ditemukan di 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.
- 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
- 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.
- Memulai Proxy Auth Cloud SQL.
Beberapa string pemanggilan Proxy Auth Cloud SQL memungkinkan untuk:
- Menggunakan autentikasi Cloud SDK:
Port yang ditentukan tidak boleh berupa port yang sedang digunakan, misalnya, oleh server database lokal../cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
- 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.
- Menggunakan autentikasi Cloud SDK:
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.
Salin INSTANCE_CONNECTION_NAME. Opsi ini dapat ditemukan di 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.
- Buat direktori di tempat soket Proxy Auth Cloud SQL akan diaktifkan:
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
- 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.
- Buka jendela terminal Cloud Shell baru dan mulai Proxy Auth Cloud SQL.
Beberapa string pemanggilan Proxy Auth Cloud SQL memungkinkan untuk:
- Menggunakan autentikasi Google Cloud SDK:
./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &
- Menggunakan akun layanan:
./cloud-sql-proxy --unix-socket /cloudsql --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
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 selengkapnya tentang opsi Proxy Auth Cloud SQL, lihat Opsi untuk mengautentikasi Proxy Auth Cloud SQL.
- Menggunakan autentikasi Google Cloud SDK:
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.14.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.14.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 tentang parameter Proxy Auth Cloud SQL.
7. Mulai sesi psql.
String koneksi yang digunakan bergantung pada apakah Anda memulai Proxy Auth Cloud SQL menggunakan soket TCP atau soket UNIX atau Docker.
Soket TCP
- Mulai klien psql:
psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
Meskipun parameter
sslmode
disetel kedisable
, Proxy Auth Cloud SQL menyediakan koneksi terenkripsi.Ketika Anda terhubung menggunakan soket TCP, Proxy Auth Cloud SQL akan diakses melalui
127.0.0.1
. - Masukkan sandi apabila diminta.
- Prompt psql akan muncul.
Menggunakan soket Unix
- Mulai klien psql:
psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
Meskipun parameter
sslmode
disetel kedisable
, Proxy Auth Cloud SQL menyediakan koneksi terenkripsi. - Masukkan sandi.
- Prompt psql akan muncul.
Butuh bantuan? Untuk mendapatkan bantuan dalam memecahkan masalah proxy, lihat Memecahkan masalah koneksi Proxy Auth Cloud SQL, atau lihat halaman Dukungan Cloud SQL kami.
Langkah berikutnya
- Dapatkan bantuan dalam memecahkan masalah koneksi untuk Proxy Auth Cloud SQL.
- Buat pengguna dan database.
- Pelajari lebih lanjut tentang IP pribadi.
- Pelajari tentang opsi untuk terhubung ke instance dari aplikasi Anda.
- Pelajari tentang klien psql.
- Pelajari tentang opsi untuk dukungan.