Menghubungkan ke instance menggunakan Private Service Connect

Halaman ini menjelaskan cara menggunakan Private Service Connect untuk terhubung ke instance AlloyDB untuk PostgreSQL.

Anda dapat menggunakan Private Service Connect untuk terhubung ke instance AlloyDB utama atau replika bacanya, atau instance AlloyDB sekunder dari beberapa jaringan Virtual Private Cloud (VPC) yang tergabung dalam grup, tim, project, atau organisasi yang berbeda.

Peran yang diperlukan

Anda harus memberikan semua peran berikut kepada pengguna di jaringan VPC agar dapat terhubung ke instance AlloyDB.

Peran Deskripsi
compute.networkAdmin Memberikan kontrol penuh atas jaringan VPC yang memulai koneksi ke instance AlloyDB. Jika Anda menggunakan Private Service Connect untuk terhubung ke instance AlloyDB dari beberapa jaringan VPC, setiap jaringan memiliki administratornya sendiri.
dns.admin Memberikan kontrol penuh atas resource Cloud DNS, termasuk zona dan data DNS.
alloydb.admin Memberikan kontrol penuh atas instance AlloyDB dan mengontrol instance selama siklus prosesnya.
alloydb.databaseUser (Opsional) Memberikan akses ke instance AlloyDB. Jika terhubung melalui klien Proxy Auth AlloyDB, Anda harus memiliki peran Klien AlloyDB. Jika terhubung langsung, Anda tidak memerlukan peran dan izin Identity and Access Management (IAM).
Custom AlloyDB role (Opsional) Jika Anda menggunakan peran khusus, selain memberikan peran compute.networkAdmin dan dns.admin, berikan izin berikut:
  • alloydb.clusters.create: Memberikan akses untuk mengaktifkan Private Service Connect untuk cluster.
  • alloydb.instances.create & alloydb.instances.update: Memberikan akses untuk menambahkan daftar project yang diizinkan dan menetapkan URI lampiran jaringan untuk instance.

Mengaktifkan Private Service Connect

Untuk mengaktifkan konektivitas masuk, buat cluster AlloyDB dengan Private Service Connect yang diaktifkan. Saat membuat instance utama, tentukan project yang diizinkan untuk konektivitas. Untuk konektivitas keluar, berikan URI lampiran jaringan.

Membuat cluster utama AlloyDB

Contoh berikut menggunakan perintah gcloud alloydb clusters create dengan flag --enable-private-service-connect yang membuat cluster AlloyDB dengan Private Service Connect yang diaktifkan.

Proses pembuatan cluster tetap sama, kecuali untuk meneruskan flag --enable-private-service-connect. Untuk informasi mendetail tentang cara membuat cluster, lihat Membuat cluster dan instance utamanya.

Untuk membuat cluster, gunakan perintah gcloud alloydb clusters create.

  gcloud alloydb clusters create CLUSTER_ID \
    --password=PASSWORD \
    --region=REGION_ID \
    --project=PROJECT_ID \
    --enable-private-service-connect

Ganti kode berikut:

  • CLUSTER_ID: ID cluster yang Anda buat. Nama harus diawali dengan huruf kecil dan dapat berisi huruf kecil, angka, dan tanda hubung.

  • PASSWORD: sandi yang akan digunakan untuk pengguna postgres default.

  • REGION_ID: region tempat Anda ingin menempatkan cluster.

  • PROJECT_ID: ID project tempat Anda ingin menempatkan cluster.

Perintah ini memulai operasi yang berjalan lama, dan menampilkan ID operasi.

Cluster sekunder yang dibuat untuk cluster utama yang mengaktifkan Private Service Connect akan otomatis mewarisi konfigurasi Private Service Connect. Untuk mengetahui informasi selengkapnya, lihat Membuat cluster sekunder.

Membuat instance AlloyDB

Contoh berikut menunjukkan cara membuat instance utama dengan daftar project yang diizinkan yang dikonfigurasi. Proses pembuatan instance tetap sama, kecuali meneruskan daftar project yang diizinkan menggunakan flag --allowed-psc-projects untuk cluster utama yang mengaktifkan Private Service Connect.

Untuk mengetahui informasi selengkapnya tentang cara membuat jenis instance lainnya, lihat Membuat instance kumpulan baca dan Membuat instance sekunder.

gcloud

Untuk menggunakan gcloud CLI, Anda dapat menginstal dan melakukan inisialisasi Google Cloud CLI, atau menggunakan Cloud Shell.

Untuk membuat instance utama, gunakan perintah gcloud alloydb instances create.

gcloud alloydb instances create INSTANCE_ID \
    --instance-type=PRIMARY \
    --cpu-count=CPU_COUNT \
    --availability-type=AVAILABILITY \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
    --project=PROJECT_ID \
    --allowed-psc-projects=ALLOWED_PROJECT_LIST
    --psc-network-attachment-uri=NETWORK_ATTACHMENT_URI

Ganti kode berikut:

  • INSTANCE_ID: ID instance yang Anda buat. ID ini harus diawali dengan huruf kecil dan dapat berisi huruf kecil, angka, dan tanda hubung.
  • CPU_COUNT: jumlah vCPU yang Anda inginkan untuk instance. Nilai yang valid mencakup hal berikut:
    • 2: 2 vCPU, RAM 16 GB
    • 4: 4 vCPU, RAM 32 GB
    • 8: 8 vCPU, RAM 64 GB
    • 16: 16 vCPU, RAM 128 GB
    • 32: 32 vCPU, RAM 256 GB
    • 64: 64 vCPU, RAM 512 GB
    • 96: 96 vCPU, RAM 768 GB
    • 128: 128 vCPU, RAM 864 GB
  • AVAILABILITY: menunjukkan apakah instance ini harus sangat tersedia (HA) atau tidak, dengan node di beberapa zona. Nilai yang valid mencakup:
    • REGIONAL: membuat instance HA dengan node aktif dan standby terpisah, serta failover otomatis di antara keduanya. Ini adalah nilai default, yang cocok untuk lingkungan produksi.
    • ZONAL: membuat instance dasar, yang hanya berisi satu node, dan tidak ada failover otomatis.
  • REGION_ID: region tempat Anda ingin menempatkan instance.
  • CLUSTER_ID: ID cluster yang Anda buat sebelumnya.
  • ALLOWED_PROJECT_LIST: daftar yang dipisahkan koma untuk project ID atau nomor project yang ingin Anda izinkan mengakses instance—misalnya, my-project-1, 12345,my-project-n.
  • NETWORK_ATTACHMENT_URI: nama resource lengkap URI lampiran jaringan yang Anda buat. Misalnya: projects/PROJECT_ID/regions/REGION_ID/networkAttachments/NETWORK_ATTACHMENT_ID

Terraform

Untuk membuat instance dalam cluster database, gunakan resource Terraform.

resource "google_alloydb_instance" "default" {
  cluster       = google_alloydb_cluster.default.name
  instance_id   = "alloydb-instance"
  instance_type = "PRIMARY"
  machine_config {
    cpu_count = 2
  }
  psc_instance_config {
  allowed_consumer_projects = ["123456789"]
  psc_interface_configs {
    network_attachment_resource = google_compute_network_attachment.default.id
  }
  }
}

resource "google_compute_network" "default" {
    name = "alloydb-network"
    auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "default" {
    name = "alloydb-subnetwork"
    region = "us-central1"
    network = google_compute_network.default.id
    ip_cidr_range = "10.0.0.0/16"
}

resource "google_compute_network_attachment" "default" {
  name                  = "alloydb-network-attachment"
  region                = "us-central1"
  connection_preference = "ACCEPT_AUTOMATIC"
  subnetworks = [
    google_compute_subnetwork.default.self_link
  ]
}

data "google_project" "project" {}

Menyiapkan Cloud Shell

Untuk menerapkan konfigurasi Terraform di project Google Cloud, siapkan Cloud Shell sebagai berikut:

  1. Luncurkan Cloud Shell.
  2. Tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform.

    Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri, yang juga disebut modul root.

  1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus berupa file TF—misalnya, main.tf. Dalam dokumen ini, file ini disebut sebagai main.tf.
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf
  2. Salin kode contoh ke dalam main.tf yang baru dibuat. Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.
    git clone https://github.com/terraform-google-modules/terraform-docs-samples
  3. Di direktori terraform-docs-samples, buka direktori alloydb.
    cd terraform-docs-samples/alloydb
  4. Salin kode contoh ke dalam main.tf yang baru dibuat.
    cp SAMPLE_FILE
    Ganti <var>SAMPLE_FILE</var> dengan nama file contoh yang akan disalin—misalnya, main.tf.
  5. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
  6. Simpan perubahan Anda.
  7. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori.
    terraform init
    Opsional: Untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade:
    terraform init -upgrade

Menerapkan perubahan

  1. Tinjau konfigurasi untuk mengonfirmasi bahwa update Terraform sesuai dengan ekspektasi Anda:
    terraform plan
    Lakukan koreksi pada konfigurasi jika diperlukan.
  2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:
    terraform apply
    Tunggu hingga Terraform menampilkan pesan Apply complete!.

Buka project Google Cloud Anda untuk melihat hasilnya. Di konsol Google Cloud, buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Mengonfigurasi konektivitas masuk

Setelah mengaktifkan PSC untuk instance AlloyDB, Anda bisa mendapatkan URL lampiran layanan dan mengonfigurasi endpoint di VPC konsumsi untuk terhubung dengan aman ke instance AlloyDB.

Mendapatkan lampiran layanan

Setelah membuat instance AlloyDB dengan Private Service Connect yang diaktifkan, dapatkan URL lampiran layanan dan gunakan untuk membuat endpoint Private Service Connect.

Gunakan perintah gcloud alloydb instances describe untuk melihat detail tentang instance.

gcloud alloydb instances describe INSTANCE_ID \
 --cluster=CLUSTER_ID --region=REGION_ID

Ganti kode berikut:

  • INSTANCE_ID: ID instance.
  • CLUSTER_ID: ID cluster.
  • REGION_ID: region tempat cluster AlloyDB di-deploy.

Contoh respons untuk perintah ini adalah sebagai berikut:

  "pscInstanceConfig": {
    "serviceAttachmentLink:": "https://www.googleapis.com/compute/v1/projects/my-project/regions/my-region/serviceAttachments/my-service-attachment-id"
        "allowedConsumerProjects": {
          "45678",
          "12345",
              "67890",
            },
            "pscDnsName": "11111111-1111-1111-1111-111111111111.22222222-2222-2222-2222-222222222222.alloydb-psc.goog."
          }

Parameter serviceAttachmentLink menyimpan nilai URL lampiran layanan.

Membuat endpoint Private Service Connect

Untuk membuat endpoint Private Service Connect, teruskan URL lampiran layanan beserta nama endpoint yang unik. Untuk mengetahui informasi selengkapnya tentang cara membuat endpoint Private Service Connect, lihat Membuat endpoint.

Anda juga dapat mencadangkan alamat IP internal untuk endpoint Private Service Connect menggunakan perintah gcloud compute addresses create, lalu menggunakan alamat IP yang dicadangkan saat membuat endpoint.

Mengonfigurasi konektivitas keluar

Untuk mengaktifkan konektivitas keluar, tetapkan URI lampiran jaringan saat Anda membuat atau memperbarui instance AlloyDB. URI ini memungkinkan konektivitas aman antara project Anda dan instance AlloyDB selama operasi keluar seperti migrasi.

Membuat lampiran jaringan

Anda dapat membuat lampiran jaringan yang dapat menerima koneksi secara otomatis(ACCEPT_AUTOMATIC) atau manual (ACCEPT_MANUAL). Untuk informasi selengkapnya tentang cara membuat lampiran jaringan, lihat Membuat dan mengelola lampiran jaringan.

Jika memilih untuk membuat lampiran jaringan yang menerima koneksi secara otomatis, Anda tidak perlu menetapkan daftar project yang diterima secara eksplisit. Untuk menerima koneksi secara manual, Anda harus menambahkan nomor project milik layanan dari project tempat instance AlloyDB Anda berada ke daftar project yang diterima.

Untuk menemukan nomor project milik layanan, jalankan perintah berikut:

gcloud alpha alloydb clusters describe CLUSTER_ID --region=REGION_ID

Berikut adalah contoh respons:

pscConfig:
pscEnabled: true
serviceOwnedProjectNumber: 123456789012

Setelah Anda mengidentifikasi nomor project milik layanan, tambahkan project ke daftar project yang diterima, lalu buat lampiran jaringan.

Pastikan region lampiran jaringan sama dengan region instance AlloyDB. Selain itu, subnet yang digunakan untuk membuat lampiran jaringan harus termasuk dalam rentang IP RFC 1918, yaitu 10.0.0.0/8, 172.16.0.0/12, dan 192.168.0.0/16.

Mengupdate instance untuk konektivitas keluar

Untuk mengaktifkan konektivitas keluar untuk instance AlloyDB yang ada dengan Private Service Connect yang diaktifkan, teruskan parameter --psc-network-attachment-uri ke perintah gcloud alloydb instances update.

Instance AlloyDB yang dibuat sebelum 01 Maret 2025 tidak dapat diupdate untuk mengaktifkan koneksi keluar. Sebagai pendekatan alternatif, sebaiknya gunakan salah satu opsi berikut:


Menonaktifkan konektivitas keluar

Untuk menonaktifkan konektivitas keluar untuk instance AlloyDB yang ada, teruskan parameter --clear-psc-network-attachment-uri ke perintah gcloud alloydb instances update.

Menghubungkan ke instance AlloyDB

Anda dapat terhubung ke instance AlloyDB dengan Private Service Connect yang diaktifkan menggunakan salah satu opsi berikut:

  • alamat IP internal,
  • data DNS
  • Proxy Auth AlloyDB
  • AlloyDB Language Connector

Untuk terhubung menggunakan data DNS, Anda harus membuat data DNS di zona DNS pribadi pada jaringan VPC yang sesuai. Setelah membuat data DNS, Anda dapat menggunakan data ini untuk terhubung ke instance yang mengaktifkan Private Service Connect secara langsung menggunakan data DNS, menggunakan AlloyDB Auth Proxy, atau menggunakan AlloyDB Language Connector.

Mengonfigurasi zona DNS terkelola dan data DNS

Untuk mengonfigurasi zona DNS terkelola dan data DNS di jaringan Anda, ikuti langkah-langkah berikut:

  1. Untuk melihat informasi ringkasan tentang instance AlloyDB, termasuk nama DNS instance tersebut, gunakan perintah gcloud alloydb instances describe:

    gcloud alloydb instances describe INSTANCE_ID \
    --cluster=CLUSTER_ID --region=REGION_ID

    Ganti kode berikut:

    • INSTANCE_ID: ID instance.
    • CLUSTER_ID: ID cluster.

    Dalam respons, pastikan nama DNS muncul. Nama DNS memiliki pola INSTANCE_UID.PROJECT_UID.REGION_NAME.alloydb-psc.goog..

  2. Untuk membuat zona DNS pribadi, gunakan perintah gcloud dns managed-zones create. Zona ini dikaitkan dengan jaringan VPC yang digunakan untuk terhubung ke instance AlloyDB melalui endpoint Private Service Connect.

    gcloud dns managed-zones create ZONE_NAME \
    --project=PROJECT_ID \
    --description=DESCRIPTION \
    --dns-name=DNS_NAME \
    --networks=NETWORK_NAME \
    --visibility=private

    Ganti kode berikut:

    • ZONE_NAME: nama zona DNS.
    • PROJECT_ID: ID atau nomor project Google Cloud yang berisi zona.
    • DESCRIPTION: deskripsi zona (misalnya, zona DNS untuk instance AlloyDB).
    • DNS_NAME: nama DNS untuk zona, seperti INSTANCE_UID.PROJECT_UID.REGION_NAME.alloydb-psc.goog..
    • NETWORK_NAME: Nama jaringan VPC.
  3. Setelah Anda membuat endpoint Private Service Connect, untuk membuat data DNS di zona, gunakan perintah gcloud dns record-sets create:

    gcloud dns record-sets create DNS_NAME \
    --project=PROJECT_ID \
    --type=RRSET_TYPE \
    --rrdatas=RR_DATA \
    --zone=ZONE_NAME

    Ganti kode berikut:

    • DNS_NAME: nama DNS yang telah Anda ambil sebelumnya dalam prosedur ini.
    • RRSET_TYPE: jenis data resource dari kumpulan data DNS (misalnya, A).
    • RR_DATA: alamat IP yang dialokasikan untuk endpoint Private Service Connect (misalnya, 198.51.100.5). Anda juga dapat memasukkan beberapa nilai seperti rrdata1 rrdata2 rrdata3 (misalnya, 10.1.2.3 10.2.3.4 10.3.4.5).

Menghubungkan langsung menggunakan data DNS

Setelah membuat endpoint Private Service Connect, dan membuat data DNS, Anda dapat terhubung langsung menggunakan data DNS.

  1. Untuk mengambil data DNS endpoint Private Service Connect, gunakan perintah gcloud compute addresses describe:

    gcloud compute addresses describe DNS_RECORD \
    --project=PROJECT_ID \
    --region=REGION_NAME

    Ganti kode berikut:

    • DNS_RECORD: data DNS untuk endpoint.
    • PROJECT_ID: ID atau nomor project Google Cloud yang berisi endpoint.
    • REGION_NAME: nama region untuk endpoint.
  2. Untuk terhubung ke instance AlloyDB, gunakan data DNS.

    psql -U USERNAME -h DNS_RECORD

    Ganti kode berikut:

    • USERNAME: nama pengguna yang terhubung ke instance.
    • DNS_RECORD: data DNS endpoint.

Terhubung menggunakan Proxy Auth AlloyDB

Proxy Auth AlloyDB adalah konektor yang memungkinkan Anda membuat koneksi terenkripsi yang diotorisasi ke database AlloyDB. Proxy Auth AlloyDB bekerja dengan menjalankan klien lokal di lingkungan lokal. Aplikasi Anda berkomunikasi dengan Proxy Auth AlloyDB menggunakan protokol database standar yang digunakan oleh database Anda.

Saat Anda menetapkan flag --psc saat memulai klien Auth Proxy, Proxy Auth AlloyDB akan menggunakan data DNS yang Anda buat untuk terhubung ke instance yang mengaktifkan Private Service Connect.

Pastikan Anda memulai klien Auth Proxy dengan meneruskan URI instance yang Anda ambil menggunakan perintah gcloud alloydb instances list, dan menetapkan tanda --psc.

Untuk mengetahui informasi selengkapnya tentang cara menghubungkan ke instance menggunakan Auth Proxy, lihat Menghubungkan menggunakan Auth Proxy.

Menghubungkan menggunakan AlloyDB Language Connectors

AlloyDB Language Connectors adalah library yang menyediakan mTLS otomatis dengan TLS 1.3 dan otorisasi Identity and Access Management (IAM) saat terhubung ke instance AlloyDB.

Setelah menentukan bahwa instance mendukung Private Service Connect, Language Connector akan menggunakan data DNS yang Anda buat untuk terhubung ke instance.

Java

Jika Anda menggunakan Private Service Connect untuk terhubung ke instance AlloyDB, sertakan hal berikut:

config.addDataSourceProperty("alloydbIpType", "PSC");

Untuk mengetahui informasi selengkapnya tentang penggunaan endpoint Private Service Connect di Konektor Bahasa Java, lihat repositori GitHub.

Python (pg8000)

Jika Anda menggunakan Private Service Connect untuk terhubung ke instance AlloyDB, sertakan hal berikut:

  def getconn() -> pg8000.dbapi.Connection:
      conn: pg8000.dbapi.Connection = connector.connect(
          inst_uri,
          "pg8000",
          user=user,
          password=password,
          db=db,
          # use ip_type to specify PSC
          ip_type=IPTypes.PSC,
      )
      return conn

Untuk mengetahui informasi selengkapnya tentang penggunaan endpoint Private Service Connect di Konektor Bahasa Python, lihat repositori GitHub.

Python (asyncpg)

Jika Anda menggunakan Private Service Connect untuk terhubung ke instance AlloyDB, sertakan hal berikut:

  async def getconn() -> asyncpg.Connection:
    conn: asyncpg.Connection = await connector.connect(
        inst_uri,
        "asyncpg",
        user=user,
        password=password,
        db=db,
        # use ip_type to specify PSC
        ip_type=IPTypes.PSC,
    )
    return conn

Untuk mengetahui informasi selengkapnya tentang penggunaan endpoint Private Service Connect di Konektor Bahasa Python, lihat repositori GitHub.

Go (pgx)

Jika Anda menggunakan Private Service Connect untuk terhubung ke instance AlloyDB, sertakan hal berikut:

d.Dial(ctx, instURI, alloydbconn.WithPSC())

Untuk mengetahui informasi selengkapnya tentang penggunaan endpoint Private Service Connect di Konektor Bahasa Go, lihat repositori GitHub.

Go (database/sql)

Jika Anda menggunakan Private Service Connect untuk terhubung ke instance AlloyDB, sertakan hal berikut:

  cleanup, err := pgxv5.RegisterDriver(
    "alloydb",
    alloydbconn.WithDefaultDialOptions(alloydbconn.WithPSC())
)

Untuk mengetahui informasi selengkapnya tentang penggunaan endpoint Private Service Connect di Konektor Bahasa Go, lihat repositori GitHub.

Menghubungkan langsung melalui alamat IP internal

Setelah membuat endpoint Private Service Connect, Anda dapat langsung terhubung ke instance AlloyDB menggunakan alamat IP yang Anda konfigurasi.

  1. Untuk mengambil alamat IP endpoint Private Service Connect, gunakan perintah gcloud compute addresses describe:

    gcloud compute addresses describe ADDRESS_NAME \
    --project=PROJECT_ID \
    --region=REGION_NAME

    Ganti kode berikut:

    • ADDRESS_NAME: nama alamat IP endpoint.
    • PROJECT_ID: ID atau nomor project Google Cloud yang berisi endpoint.
    • REGION_NAME: nama region untuk endpoint.
  2. Untuk terhubung ke instance AlloyDB, gunakan alamat IP internal.

    psql -U USERNAME -h IP_ADDRESS"

    Ganti kode berikut:

    • USERNAME: nama pengguna yang terhubung ke instance.
    • IP_ADDRESS: alamat IP endpoint.

Batasan

  • Anda dapat menyiapkan hingga 20 endpoint Private Service Connect yang terhubung ke lampiran layanan instance AlloyDB dengan Private Service Connect yang diaktifkan.
  • Anda tidak dapat menggunakan tanda --network saat membuat cluster yang mengaktifkan Private Service Connect karena terkait dengan akses layanan pribadi.
  • Anda tidak dapat mengaktifkan atau menonaktifkan Private Service Connect pada instance yang ada.
  • Anda tidak dapat mengonfigurasi instance dengan Private Service Connect yang diaktifkan untuk menggunakan akses layanan pribadi.