Menghubungkan ke instance menggunakan endpoint tulis

Ringkasan

Halaman ini menunjukkan cara menggunakan endpoint tulis untuk terhubung dari klien di jaringan Virtual Private Cloud (VPC) Anda ke instance Cloud SQL menggunakan akses layanan pribadi (PSA).

Endpoint tulis adalah nama domain name service (DNS) global yang di-resolve ke alamat IP instance utama saat ini secara otomatis. Jika terjadi operasi failover atau pengalihan replika, endpoint tulis ini akan otomatis mengalihkan koneksi masuk ke instance utama baru. Anda dapat menggunakan endpoint tulis dalam string koneksi SQL ke instance Cloud SQL, bukan menggunakan alamat IP. Dengan menggunakan endpoint tulis, Anda tidak perlu melakukan perubahan koneksi aplikasi saat melakukan operasi failover atau pengalihan replika untuk pemulihan pemadaman layanan region atau latihan disaster recovery.

Setiap instance Cloud SQL yang memenuhi syarat memiliki satu endpoint tulis bawaan yang nama, pembuatan, dan pembaruannya dikelola oleh Cloud SQL. Contoh berikut mengilustrasikan formatnya:

  103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
  

Endpoint tulis selalu diakhiri dengan akhiran .global.sql-psa.goog.. Anda tidak dapat mengubah nama atau format endpoint tulis ini yang dikelola oleh Cloud SQL.

Anda dapat menggunakan endpoint tulis untuk semua operasi tulis pada instance utama, termasuk penyisipan, pembaruan, penghapusan, dan perubahan DDL. Anda juga dapat menggunakan endpoint tulis untuk operasi baca, seperti kueri. Alamat IP pribadi yang ditunjuk oleh endpoint tulis akan otomatis diubah oleh Cloud SQL saat Anda melakukan operasi failover atau pengalihan replika untuk mempromosikan instance replika menjadi instance utama baru.

Membuat endpoint tulis

Jika Anda membuat instance Cloud SQL baru, Cloud SQL akan otomatis membuat endpoint tulis jika prasyarat berikut terpenuhi:

• API berikut harus diaktifkan di project Cloud de Confiance tempat instance Cloud SQL Anda berada:
  • Compute Engine API
  • Cloud DNS API

  Kegagalan mengaktifkan Cloud DNS API dalam project akan menyebabkan kegagalan pembuatan zona DNS peering yang akan membuat nama DNS tidak dapat digunakan.

  Setelah zona DNS peering berhasil dibuat, penting untuk tidak mengubahnya dengan cara apa pun. Setiap modifikasi, termasuk penghapusan, akan membuat DNS tidak dapat digunakan untuk koneksi database.

• Instance Cloud SQL harus berupa edisi Cloud SQL Enterprise Plus.
• Instance Cloud SQL harus dikonfigurasi untuk menggunakan IP pribadi dengan akses layanan pribadi (PSA) diaktifkan.
• Fitur ini memerlukan instance pada arsitektur jaringan baru. Umumnya, instance baru dibuat dengan arsitektur baru. Untuk memverifikasi hal ini, periksa arsitektur jaringan instance Anda.

Saat Anda mengupgrade instance edisi Cloud SQL Enterprise yang ada ke instance edisi Cloud SQL Enterprise Plus, Cloud SQL akan otomatis membuat endpoint tulis jika prasyarat yang tercantum sebelumnya terpenuhi. Jika instance yang ada berada dalam arsitektur jaringan lama, Anda harus mengupgrade instance ke arsitektur jaringan baru terlebih dahulu untuk mendapatkan endpoint tulis.

Jika Anda sudah memiliki instance edisi Cloud SQL Enterprise Plus tanpa endpoint tulis dan ingin Cloud SQL membuat endpoint tulis secara otomatis, buat replika yang diaktifkan untuk disaster recovery lanjutan.

Melihat endpoint tulis

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Endpoint tulis selalu diakhiri dengan akhiran .global.sql-psa.goog., mirip dengan contoh berikut:

  103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
  

Jika Anda tidak melihat endpoint tulis untuk instance yang memenuhi syarat, lihat Pemecahan masalah.

Menghubungkan ke instance Cloud SQL menggunakan endpoint tulis

    mysql -u root -h WRITE_ENDPOINT -p
  

Menghubungkan klien database dengan instance database menggunakan endpoint tulis melalui koneksi SSL/TLS

  mysql -uroot -pcloudsql -h 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. \
    --ssl-ca=SERVER_CA_SSL \
    --ssl-cert=SSL_CERT \
    --ssl-key=SSL_KEY \
    --ssl-verify-server-cert
  

Menghubungkan klien database ke instance menggunakan Cloud SQL Auth Proxy atau Cloud SQL Language Connectors

Saat Anda mengonfigurasi Proxy Auth Cloud SQL atau salah satu Cloud SQL Language Connectors menggunakan nama DNS endpoint tulis, konektor Cloud SQL akan secara berkala memeriksa operasi pengalihan atau failover. Saat konektor Cloud SQL mendeteksi bahwa nama DNS endpoint tulis merujuk ke instance yang berbeda, konektor tersebut akan menutup semua koneksi terbuka ke instance lama. Upaya koneksi berikutnya akan diarahkan ke instance baru.

Misalnya, sebuah aplikasi dikonfigurasi untuk terhubung menggunakan nama DNS endpoint tulis 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. Awalnya, zona DNS dikonfigurasi dengan data yang mengarah ke instance utama, my-project:region:instance-a. Aplikasi membuat koneksi ke instance Cloud SQL my-project:region:instance-a.

Saat failover atau pengalihan terjadi, Cloud SQL akan memperbarui data DNS dari my-project:region:instance-a ke instance replika DR yang ditetapkan: my-project:other-region:instance-b.

Konektor Cloud SQL yang digunakan oleh aplikasi akan mendeteksi perubahan pada data DNS ini. Saat aplikasi terhubung ke databasenya menggunakan nama DNS endpoint tulis 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog, aplikasi akan terhubung ke instance Cloud SQL my-project:other-region:instance-b.

Konektor atau Proxy Auth akan otomatis menutup semua koneksi yang ada ke my-project:region:instance-a. Tindakan ini memaksa setiap kumpulan koneksi yang digunakan oleh aplikasi untuk membuat koneksi baru. Hal ini juga dapat menyebabkan kueri database yang sedang berlangsung gagal.

Proxy Auth Cloud SQL melakukan polling untuk perubahan pada nama DNS setiap 30 detik.

Memperbarui konfigurasi jaringan instance

Jika instance Anda dibuat sebelum 8 Agustus 2025, Anda mungkin perlu memperbarui konfigurasi jaringan instance untuk Cloud SQL Language Connectors atau Cloud SQL Auth Proxy agar dapat menggunakan endpoint tulis. Anda hanya perlu menjalankan tugas update ini satu kali untuk setiap instance. Jalankan perintah berikut:

  # Update the primary instance DNS settings
  gcloud sql instances patch "PRIMARY_NAME" \
      --reconcile-psa-networking
  

Menghubungkan klien database ke instance menggunakan Proxy Auth Cloud SQL

Untuk terhubung ke instance Cloud SQL melalui endpoint tulisnya dan menggunakan Proxy Auth Cloud SQL, pertama-tama mulai proxy menggunakan endpoint tulis, bukan nama koneksi instance.

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

  mysql -uUSERNAME -h 127.0.0.1 -p PORT DATABASE_NAME
  

Menghubungkan menggunakan Cloud SQL Language Connectors

Untuk terhubung menggunakan salah satu Cloud SQL Language Connectors, konfigurasikan aplikasi Anda dengan mengikuti petunjuk dalam dokumentasi Terhubung menggunakan Cloud SQL Language Connectors. Kemudian, ubah koneksi database Anda untuk menggunakan endpoint tulis, bukan nama DNS instance.

  String jdbcUrl = "jdbc:mysql://WRITE_ENDPOINT/DATABASE_NAME?"
    +   "&socketFactory=com.google.cloud.sql.mysql.SocketFactory"
    +   "&user=USERNAME"
    +   "&password=PASSWORD";
  

    db, err := sql.Open(
        "cloudsql-mysql",
        "USERNAME:PASSWORD@cloudsql-mysql(WRITE_ENDPOINT)/DATABASE_NAME",
    )
  

  pool = sqlalchemy.create_engine(
      "mysql+pymysql://",
      creator=lambda: connector.connect(
          "WRITE_ENDPOINT",  # using DNS name
          "pymysql",
          user="USERNAME",
          password="PASSWORD",
          db="DATABASE_NAME"
      ),
  )
  

  import mysql from 'mysql2/promise';
  import {Connector} from '@google-cloud/cloud-sql-connector';

  const connector = new Connector();
  const clientOpts = await connector.getOptions({
    domainName: 'WRITE_ENDPOINT',
    ipType: 'PUBLIC',
  });

  const pool = await mysql.createPool({
    ...clientOpts,
    user: 'USERNAME',
    password: 'PASSWORD',
    database: 'DATABASE_NAME',
  });
  

Batasan

• Endpoint tulis tidak tersedia untuk pembuatan instance edisi Cloud SQL Enterprise.
• Endpoint tulis tidak tersedia untuk instance khusus IP publik atau instance khusus Private Service Connect.

Pemecahan masalah

Bagian berikut menjelaskan arsitektur endpoint tulis dan membahas masalah pemecahan masalah umum.

Arsitektur endpoint tulis

Saat Anda membuat instance yang memenuhi syarat, endpoint tulis akan dibuat secara default.

Untuk membuat endpoint tulis, Cloud SQL melakukan penyiapan berikut:

• Membuat zona DNS pribadi di jaringan VPC produsen Cloud SQL layanan
• Membuat zona DNS peering di jaringan VPC pelanggan
• Membuat data DNS di zona DNS pribadi dalam jaringan produsen layanan

Diagram berikut menggambarkan cara kerja proses ini:

Masalah resolusi DNS

Jika resolusi DNS tidak berfungsi, periksa setiap item berikut:

1. Pastikan semua prasyarat terpenuhi.
2. Pastikan klien tempat resolusi diharapkan berada di jaringan yang sama dengan tempat instance Cloud SQL terpasang. Untuk memeriksanya, gunakan perintah gcloud compute instances list:

   gcloud compute instances list \
      --format="table( name, zone.basename(), networkInterfaces[].network )" \
      --project=PROJECT_NAME

   Ganti PROJECT_NAME dengan nama project tempat jaringan konsumen DNS berada.

3. Pastikan zona peering ada. Untuk melakukannya, gunakan perintah gcloud dns managed-zones list:

   gcloud dns managed-zones list \
       --project=PROJECT_NAME

   Ganti PROJECT_NAME dengan nama project tempat jaringan konsumen DNS berada.

4. Jika zona peering tidak ada, Anda dapat memperbaiki masalah tersebut menggunakan perintah gcloud sql instances patch:

   gcloud sql instances patch INSTANCE_NAME --reconcile-psa-networking

   Ganti INSTANCE_NAME dengan nama instance Cloud SQL Anda.

Instance baru tidak memiliki endpoint tulis

Jika instance yang baru dibuat tidak berisi endpoint tulis, periksa setiap item berikut:

1. Pastikan semua prasyarat telah diselesaikan.
2. Pastikan tidak ada zona DNS peering yang tersisa dengan nama DNS sql-psa.goog..

   Zona DNS peering adalah zona DNS yang tersisa jika jaringan yang terkait dengan zona DNS tidak memiliki peering VPC dengan project ID peer dari zona DNS peering.

   Jika ada zona DNS peering yang tersisa dengan akhiran sql-psa.goog., hapus zona tersebut.

   Untuk memeriksa zona DNS peering yang tersisa, gunakan perintah gcloud dns managed-zones list:

   gcloud dns managed-zones list \
      --project=PROJECT_NAME

   Ganti PROJECT_NAME dengan nama project tempat jaringan konsumen DNS berada.

   Jika zona DNS ada dengan akhiran sql-psa.goog., hapus zona DNS setelah memeriksa kembali bahwa zona DNS peering adalah zona DNS sisa.

   Untuk menghapus zona DNS, gunakan perintah gcloud dns managed-zones delete:

   gcloud dns managed-zones delete ZONE_NAME

   Ganti ZONE_NAME dengan nama zona DNS yang terkait dengan endpoint tulis. Nilainya bersifat alfanumerik dan menggunakan format berikut: cloud-sql-psa-dns-1234567890.

3. Anda dapat memperbaiki endpoint tulis yang tidak ada untuk instance yang memenuhi syarat menggunakan perintah gcloud sql instances patch:

   gcloud sql instances patch INSTANCE_NAME --reconcile-psa-networking

   Ganti INSTANCE_NAME dengan nama instance Cloud SQL Anda.

Langkah berikutnya

• Pelajari lebih lanjut pemecahan masalah Cloud SQL.