Terhubung menggunakan Proxy Auth AlloyDB

Untuk membuat koneksi yang diizinkan dan dienkripsi ke instance AlloyDB untuk PostgreSQL, Anda dapat menggunakan Proxy Auth AlloyDB. Untuk mengetahui informasi selengkapnya, lihat Tentang Proxy Auth AlloyDB.

Untuk menggunakan Proxy Auth AlloyDB, Anda melakukan beberapa langkah penyiapan satu kali, lalu memulai klien Proxy Auth dan menggunakannya untuk terhubung ke database.

Sebelum memulai

Host klien harus memenuhi persyaratan berikut:

• Klien harus memiliki jalur jaringan ke instance AlloyDB berdasarkan metode koneksi Anda:

  • Akses layanan pribadi (default): Klien harus memiliki visibilitas jaringan ke jaringan Virtual Private Cloud (VPC) tempat instance berada. Host klien (seperti instance Compute Engine) di jaringan VPC ini secara inheren memiliki visibilitas jaringan ini. Host klien di jaringan eksternal (jaringan lokal atau jaringan VPC yang berbeda) memiliki visibilitas ini jika jaringan VPC instance AlloyDB terhubung ke jaringan eksternal menggunakan tunnel Cloud VPN atau lampiran VLAN untuk Dedicated Interconnect atau Partner Interconnect.
  • Private Service Connect: Jaringan VPC klien harus memiliki endpoint Private Service Connect dan data DNS pribadi yang cocok, dan Anda harus memulai klien Proxy Auth dengan flag --psc.
  • IP Publik: Instance harus memiliki IP Publik yang diaktifkan, dan Anda harus memulai klien Proxy Auth dengan flag --public-ip. Saat terhubung menggunakan Proxy Auth, Anda tidak perlu menambahkan alamat IP host klien ke Jaringan eksternal yang diizinkan.

• Jika host klien memiliki kebijakan firewall keluar, host tersebut harus mengizinkan koneksi keluar ke port 5433 pada alamat IP instance AlloyDB Anda dan mengizinkan koneksi keluar ke port 443 (port HTTPS standar) ke semua alamat IP.

• Jika Anda menggunakan instance Compute Engine sebagai host klien, instance tersebut harus memiliki cakupan akses https://www.googleapis.com/auth/cloud-platform agar dapat menggunakan AlloyDB API. Jika perlu, ubah cakupan aksesnya untuk menyertakan cakupan ini.

Mendownload klien Proxy Auth

Mesin tempat Anda mendownload klien Proxy Auth bergantung pada apakah Anda ingin terhubung ke instance AlloyDB dari dalam jaringan VPC-nya, atau dari luar jaringan tersebut.

Jika ingin terhubung ke cluster menggunakan akses layanan pribadi, Anda dapat mendownload klien Auth Proxy ke instance virtual machine (VM) Compute Engine yang berjalan dalam jaringan VPC yang memiliki akses layanan pribadi ke cluster Anda.

Jika Anda ingin terhubung ke cluster dari luar VPC, mesin tempat Anda menginstalnya bergantung pada strategi koneksi eksternal yang Anda gunakan. Misalnya, Anda dapat menginstal klien Proxy Auth ke mesin macOS atau Windows yang bersifat lokal untuk aplikasi Anda, lalu menggunakan server SOCKS yang berjalan dalam jaringan VPC AlloyDB Anda sebagai perantara koneksi. Untuk mengetahui informasi selengkapnya, lihat Terhubung ke cluster dari luar VPC-nya.

Catatan: Pastikan Anda menggunakan versi klien Proxy Auth terbaru. Google merilis versi baru klien Proxy Auth setiap bulan. Anda dapat menemukan versi saat ini dengan memeriksa halaman rilis GitHub klien Proxy Auth.

Linux

64-bit (AMD)

1. Download klien Proxy Auth:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

2. Buat klien Proxy Auth agar dapat dieksekusi:

   chmod +x alloydb-auth-proxy

3. Tambahkan klien Proxy Auth ke PATH Anda:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Untuk mempertahankan perubahan ini di seluruh sesi, tambahkan export PATH="$HOME/.local/bin:$PATH" ke file ~/.bashrc atau ~/.zshrc Anda.

32-bit (AMD)

1. Download klien Proxy Auth:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy

2. Buat klien Proxy Auth agar dapat dieksekusi:

   chmod +x alloydb-auth-proxy

3. Tambahkan klien Proxy Auth ke PATH Anda:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Untuk mempertahankan perubahan ini di seluruh sesi, tambahkan export PATH="$HOME/.local/bin:$PATH" ke file ~/.bashrc atau ~/.zshrc Anda.

64-bit (ARM)

1. Download klien Proxy Auth:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy

2. Buat klien Proxy Auth agar dapat dieksekusi:

   chmod +x alloydb-auth-proxy

3. Tambahkan klien Proxy Auth ke PATH Anda:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Untuk mempertahankan perubahan ini di seluruh sesi, tambahkan export PATH="$HOME/.local/bin:$PATH" ke file ~/.bashrc atau ~/.zshrc Anda.

32-bit (ARM)

1. Download klien Proxy Auth:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy

2. Buat klien Proxy Auth agar dapat dieksekusi:

   chmod +x alloydb-auth-proxy

3. Tambahkan klien Proxy Auth ke PATH Anda:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Untuk mempertahankan perubahan ini di seluruh sesi, tambahkan export PATH="$HOME/.local/bin:$PATH" ke file ~/.bashrc atau ~/.zshrc Anda.

macOS

ARM64

1. Download klien Proxy Auth:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.darwin.arm64

2. Buat klien Proxy Auth agar dapat dieksekusi:

   chmod +x alloydb-auth-proxy

3. Tambahkan klien Proxy Auth ke PATH Anda:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Untuk mempertahankan perubahan ini di seluruh sesi, tambahkan export PATH="$HOME/.local/bin:$PATH" ke file ~/.bashrc atau ~/.zshrc Anda.

AMD64

1. Download klien Proxy Auth:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.darwin.amd64

2. Buat klien Proxy Auth agar dapat dieksekusi:

   chmod +x alloydb-auth-proxy

3. Tambahkan klien Proxy Auth ke PATH Anda:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Untuk mempertahankan perubahan ini di seluruh sesi, tambahkan export PATH="$HOME/.local/bin:$PATH" ke file ~/.bashrc atau ~/.zshrc Anda.

Windows

64-bit

1. Klik kanan https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy-x64.exe dan pilih Save Link As untuk mendownload klien Proxy Auth. Ganti nama file menjadi alloydb-auth-proxy.exe.

2. Tambahkan klien Proxy Auth ke PATH Anda:

   New-Item -ItemType Directory -Force -Path "$HOME\bin"
   Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
   

32-bit

1. Klik kanan https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy-x86.exe dan pilih Save Link As untuk mendownload klien Proxy Auth. Ganti nama file menjadi alloydb-auth-proxy.exe.

2. Tambahkan klien Proxy Auth ke PATH Anda:

   New-Item -ItemType Directory -Force -Path "$HOME\bin"
   Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
   

Gambar docker

Guna mempermudah, beberapa image container yang berisi klien Proxy Auth tersedia di Artifact Registry.

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

docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest

OS Lainnya

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

Memilih akun utama Identity and Access Management (IAM) dan menyiapkannya untuk otorisasi

Proxy Auth AlloyDB mendukung penggunaan jenis akun utama IAM ini untuk mengizinkan koneksi antara klien Anda dan instance AlloyDB:

• Akun layanan terlampir. Jika host klien Anda berjalan di Google Cloud—misalnya, di instance Compute Engine—Anda dapat mengizinkan koneksi menggunakan akun layanan yang terpasang ke resource tersebut.

  Sebaiknya gunakan akun layanan untuk otorisasi di lingkungan produksi. Akun layanan terlampir adalah opsi yang paling aman karena tidak memerlukan kunci yang didownload.

• Akun pengguna Anda. Anda dapat menggunakan akun pengguna IAM Anda sendiri untuk mengizinkan koneksi.

  Menggunakan akun pengguna Anda sendiri akan memudahkan di lingkungan pengembangan tempat Anda mengelola resource AlloyDB menggunakan gcloud CLI, mengembangkan database menggunakan alat seperti psql, dan mengembangkan kode aplikasi di host yang sama.

• Akun layanan yang dikelola pengguna. Anda dapat membuat akun layanan IAM untuk aplikasi Anda, lalu mengizinkan koneksi menggunakan akun layanan tersebut.

  Gunakan akun layanan yang dikelola pengguna saat host klien Anda berjalan di luar Google Cloud dan tidak dapat menggunakan akun layanan terlampir.

Setelah memilih akun utama IAM yang akan digunakan, pastikan akun tersebut memiliki izin IAM yang diperlukan dan kredensialnya tersedia di host klien Anda.

Izin IAM yang diperlukan

Akun utama IAM yang Anda gunakan untuk mengizinkan koneksi harus memiliki izin yang diberikan oleh peran yang telah ditetapkan roles/alloydb.client (Klien AlloyDB) dan roles/serviceusage.serviceUsageConsumer (Service Usage Consumer).

Catatan: Peran roles/alloydb.admin (Admin AlloyDB) juga memberikan izin yang diperlukan.

Untuk menetapkan peran Klien AlloyDB ke akun utama IAM:

• Cloud Resource Manager API harus diaktifkan di project Google Cloud .

• Anda harus memiliki peran IAM dasar roles/owner (Owner) di projectGoogle Cloud , atau peran yang memberikan izin berikut:

  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy

  Untuk mendapatkan izin ini sekaligus mengikuti prinsip hak istimewa terendah, minta administrator untuk memberi Anda peran roles/resourcemanager.projectIamAdmin (Project IAM Admin).

Menyediakan kredensial IAM di host klien

Klien Proxy Auth menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial IAM di host klien. Di sebagian besar lingkungan, kredensial ini sudah ada, sehingga Anda tidak perlu mengonfigurasi apa pun. Klien Proxy Auth mencari sumber kredensial berikut, secara berurutan:

• Akun pengguna Anda. Saat Anda melakukan pengembangan secara lokal, lakukan autentikasi dengan akun pengguna Anda sendiri dengan menjalankan perintah gcloud CLI berikut:

  gcloud auth application-default login
  

  Klien Proxy Auth mendeteksi dan menggunakan kredensial ini. Anda tidak perlu mendownload kunci akun layanan.

• Akun layanan terlampir. Saat host klien Anda berjalan di Google Cloud—misalnya, di instance Compute Engine—server metadata lingkungan menyediakan kredensial dari akun layanan yang terpasang. Klien Proxy Auth menemukan dan menggunakan kredensial ini tanpa konfigurasi tambahan.

Sumber kredensial lainnya

Gunakan metode berikut hanya jika Kredensial Default Aplikasi tidak tersedia—misalnya, saat Anda menjalankan klien Proxy Auth di luarGoogle Cloud, atau saat Anda perlu mengganti kredensial di lingkungan.

• Kunci akun layanan. Gunakan kunci akun layanan saat host klien Anda berjalan di luar Google Cloud—misalnya, di pusat data lokal atau di penyedia cloud lain—dan Anda tidak dapat menggunakan workload identity federation.

  Buat kunci akun layanan berformat JSON dan download ke host klien Anda. Kemudian, tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file kunci:

  export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
  

  Secara opsional, Anda dapat menentukan jalur dengan flag --credentials-file saat memulai klien Proxy Auth:

  alloydb-auth-proxy --credentials-file /path/to/service-account-key.json INSTANCE_URI
  

  Perhatian: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Sebelum Anda membuat kunci, pertimbangkan alternatif yang lebih aman.

• Token akses OAuth 2.0. Gunakan token akses saat sistem lain sudah menerbitkan token berumur pendek untuk Anda—misalnya, pipeline continuous integration yang mendapatkan token sebelum memulai klien Auth Proxy.

  Jika Anda sudah memiliki token akses OAuth 2.0 yang valid, teruskan token tersebut secara langsung saat Anda memulai klien Proxy Auth:

  alloydb-auth-proxy --token "ACCESS_TOKEN" INSTANCE_URI
  

• Kredensial gcloud CLI. Gunakan flag --gcloud-auth hanya jika Anda harus menggunakan kembali sesi gcloud auth login yang ada dan tidak dapat menjalankan gcloud auth application-default login.

  Flag --gcloud-auth membuat klien Proxy Auth menggunakan akun yang Anda autentikasi dengan gcloud auth login, bukan menggunakan Kredensial Default Aplikasi. Kami tidak merekomendasikan flag ini. Sebagai gantinya, jalankan gcloud auth application-default login.

Mengumpulkan URI koneksi untuk instance AlloyDB

Saat memulai klien Proxy Auth, Anda mengidentifikasi instance AlloyDB yang ingin Anda hubungkan menggunakan format URI koneksi ini:

projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Untuk melihat daftar semua URI koneksi instance Anda, gunakan perintah alloydb instances list gcloud CLI:

gcloud alloydb instances list \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
    --project=PROJECT_ID

Ganti kode berikut:

• REGION_ID: region tempat instance ditempatkan
• CLUSTER_ID: ID cluster tempat instance ditempatkan
• PROJECT_ID: ID project tempat cluster ditempatkan

Kumpulkan URI koneksi instance untuk setiap instance yang ingin Anda hubungkan.

Memulai klien Proxy Auth

Saat memulai klien Proxy Auth, Anda memberinya informasi tentang instance AlloyDB yang akan dihubungkan dan, jika perlu, informasi kredensial yang akan digunakan saat mengizinkan koneksi ini.

Saat dimulai, klien Proxy Auth:

• Mengizinkan koneksi ke instance AlloyDB menggunakan kredensial dan izin IAM dari akun utama IAM yang telah Anda konfigurasi. Library ini mencari kredensial dengan mengikuti urutan langkah tertentu.
• Memberi otorisasi koneksi IP publik ke jaringan sumber secara otomatis, jika instance mengaktifkan IP Publik.
• Mengonfigurasi koneksi mTLS 1.3 pribadi ke setiap server Proxy Auth instance.
• Mulai memproses permintaan koneksi klien lokal.

Secara default, klien Proxy Auth memproses koneksi TCP di alamat IP 127.0.0.1, dimulai dari port 5432 dan bertambah satu nomor port untuk setiap instance AlloyDB setelah instance pertama. Anda dapat menentukan alamat pemroses dan port yang berbeda saat memulai klien Proxy Auth.

Peringatan: Berhati-hatilah saat mengikat klien Proxy Auth ke antarmuka eksternal. Siapa pun yang memiliki akses ke antarmuka atau port tersebut akan diizinkan untuk terhubung ke instance.

Catatan: Google merekomendasikan agar Anda menjalankan klien Proxy Auth sebagai layanan persisten di lingkungan produksi.

Command line

alloydb-auth-proxy INSTANCE_URI... \
    [ --credentials-file PATH_TO_KEY_FILE \ ]
    [ --token OAUTH_ACCESS_TOKEN \ ]
    [ --port INITIAL_PORT_NUMBER \ ]
    [ --address LOCAL_LISTENER_ADDRESS \ ]
    [ --auto-iam-authn \ ]
    [ --psc \ ]
    [ --public-ip \ ]
    [ --disable-built-in-telemetry ]

Ganti kode berikut:

• INSTANCE_URI: URI koneksi instance dari instance AlloyDB yang akan dihubungkan, yang ditentukan menggunakan format ini:

  projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

  Anda dapat mengganti port pemroses lokal default yang akan digunakan klien Auth Proxy untuk instance dengan menambahkan parameter kueri port ke URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

• Opsional: PATH_TO_KEY_FILE: Jalur ke file kunci JSON dari akun layanan yang dikelola pengguna untuk digunakan dalam otorisasi koneksi.

• Opsional: OAUTH_ACCESS_TOKEN: Nilai token OAuth2 yang akan digunakan untuk otorisasi koneksi.

• Opsional: INITIAL_PORT_NUMBER: Nomor port awal yang akan digunakan, bukan port default 5432 saat memproses koneksi TCP lokal.

• Opsional: LOCAL_LISTENER_ADDRESS: Alamat pemroses yang akan digunakan, bukan 127.0.0.1 default, saat memproses koneksi TCP lokal.

Flag --auto-iam-authn opsional memungkinkan Anda melakukan autentikasi secara otomatis ke instance. Hal ini hanya berfungsi untuk pengguna database yang terkait dengan akun IAM yang menjalankan klien Proxy Auth. Untuk mengetahui informasi selengkapnya, lihat Melakukan autentikasi secara otomatis menggunakan Proxy Auth.

Flag --psc opsional memungkinkan Proxy Auth terhubung ke instance dengan Private Service Connect yang diaktifkan. Untuk mengetahui informasi selengkapnya tentang cara menyiapkan DNS dengan Private Service Connect, lihat Mengonfigurasi zona terkelola DNS dan data DNS.

Flag --public-ip opsional memungkinkan Proxy Auth terhubung ke instance dengan IP Publik yang diaktifkan menggunakan alamat IP Publik instance. Untuk mengetahui informasi selengkapnya tentang IP Publik, lihat Terhubung menggunakan IP Publik.

Flag --disable-built-in-telemetry opsional menonaktifkan pelapor metrik internal yang digunakan Proxy Auth untuk melaporkan kondisi koneksi dan jaringan. Secara default, Proxy Auth melaporkan operasi internalnya ke awalan metrik sistem alloydb.googleapis.com. Metrik ini membantu AlloyDB meningkatkan performa dan mengidentifikasi masalah konektivitas klien. Opsi ini berguna untuk aplikasi yang beroperasi di lingkungan dengan ekspor metrik keluar yang dibatasi. Untuk memilih tidak ikut telemetri ini, gunakan flag ini.

Container Docker

Mulai klien Proxy Auth menggunakan perintah docker run.

Jika Anda menggunakan kredensial yang disediakan oleh instance Compute Engine, Anda dapat menggunakan perintah yang mirip dengan berikut ini:

docker run \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  INSTANCE_URI

Ganti kode berikut:

• PORT: Port yang akan digunakan untuk koneksi lokal ke klien Proxy Auth. Defaultnya adalah 5432.

• INSTANCE_URI: URI koneksi instance dari instance AlloyDB yang akan dihubungkan, yang ditentukan menggunakan format berikut:

  projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

  Anda dapat mengganti port pemroses lokal default yang digunakan klien Auth Proxy untuk instance dengan menambahkan parameter kueri port ke URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

Selalu tentukan awalan 127.0.0.1 di flag --publish agar klien Proxy Auth tidak terekspos di luar host lokal.

Nilai 0.0.0.0 dalam flag --address diperlukan agar pemroses dapat diakses dari luar container Docker.

Untuk memberikan kredensial yang telah Anda simpan dalam file JSON lokal, sertakan flag --volume dan --credentials-file saat menjalankan perintah docker run:

docker run \
  --volume PATH_TO_KEY_FILE:/key.json \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  --credentials-file=/key.json \
  INSTANCE_URI

Ganti PATH_TO_KEY_FILE dengan jalur ke file kunci JSON dari akun layanan terkelola pengguna untuk digunakan dalam otorisasi koneksi.

Contoh Startup

Contoh berikut menunjukkan berbagai cara untuk memulai klien Proxy Auth. Mereka menggunakan contoh URI koneksi instance berikut:

projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary

projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool

Startup dasar

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"

Dalam contoh ini, klien Proxy Auth mengizinkan koneksi dengan mengikuti urutan langkah otorisasi normalnya, lalu mulai memproses koneksi lokal ke instance myprimary di 127.0.0.1:5432.

Memulai menggunakan akun layanan yang dikelola pengguna

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --credentials-file "myappaccount/key.json"

Dalam contoh ini, klien Proxy Auth mengizinkan koneksi menggunakan kunci JSON akun layanan terkelola pengguna yang disimpan di myappaccount/key.json, lalu mulai memproses koneksi lokal ke instance myprimary di 127.0.0.1:5432.

Startup yang terhubung ke beberapa instance

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"

Dalam contoh ini, klien Proxy Auth mengizinkan koneksi dengan mengikuti urutan langkah otorisasi normalnya, lalu mulai memproses koneksi lokal ke instance myprimary di 127.0.0.1:5432 dan ke instance myreadpool di 127.0.0.1:5433.

Pemrosesan startup di port kustom

Menggunakan port kustom untuk klien Proxy Auth dapat berguna saat Anda perlu mencadangkan port 5432 untuk koneksi PostgreSQL lainnya.

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"

Dalam contoh ini, klien Proxy Auth mengizinkan koneksi dengan mengikuti urutan langkah otorisasi normalnya, lalu mulai memproses koneksi lokal ke instance myprimary di 127.0.0.1:5000 dan ke instance myreadpool di 127.0.0.1:5001.

Karena port kustom ini berurutan, efek yang sama dapat dicapai menggunakan perintah startup ini:

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
  --port 5000

Startup memproses permintaan di alamat IP kustom

alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --address "0.0.0.0"

Dalam contoh ini, klien Proxy Auth mengizinkan koneksi dengan mengikuti urutan langkah otorisasi normalnya, lalu mulai memproses koneksi lokal ke instance myprimary di 0.0.0.0:5432.

Menghubungkan aplikasi ke database menggunakan Proxy Auth AlloyDB

Contoh berikut menunjukkan cara menghubungkan aplikasi ke database menggunakan Proxy Auth AlloyDB.

Contoh psql memberikan contoh cara menghubungkan alat command line.

Menghubungkan ke instance AlloyDB menggunakan Proxy Auth, untuk beberapa bahasa pemrograman, sama dengan menghubungkan ke instance Cloud SQL untuk PostgreSQL menggunakan Proxy Auth Cloud SQL, sehingga contoh bahasanya sama dengan contoh untuk Cloud SQL untuk PostgreSQL.

Contoh ini didasarkan pada startup default klien Proxy Auth sehingga klien memproses koneksi TCP lokal di 127.0.0.1:5432.

Catatan: Dengan cluster baru, Anda dapat terhubung sebagai pengguna postgres, menggunakan sandi yang Anda tentukan saat membuat cluster.

psql

psql -h 127.0.0.1 -p 5432 -U DB_USER

Ganti DB_USER dengan pengguna database yang ingin Anda hubungkan, misalnya, postgres.

Tindakan ini akan meminta Anda memasukkan sandi pengguna DB_USER.

Python

import os

import sqlalchemy


# connect_tcp_socket initializes a TCP connection pool
# for an AlloyDB instance.
def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    # 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.
    INSTANCE_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. 5432

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

Java

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

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>l

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

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for an AlloyDB cluster.
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 = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Go

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat contoh Go di GitHub.

package alloydb

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

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v4 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

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

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

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

	// ...

	return dbPool, nil
}

C#

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // 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.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

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

Ruby

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

development:
  adapter: postgresql
  # Configure additional properties here.
  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("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT")  { 5432 }%>

PHP

Untuk melihat cuplikan ini dalam konteks aplikasi web, lihat README di GitHub.

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

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

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);