Menggunakan Apache Beam dan SpannerIO untuk terhubung ke Spanner Omni

Apache Beam adalah model open source terpadu untuk menentukan pipeline pemrosesan paralel data batch dan streaming. Dokumen ini menjelaskan cara menggunakan konektor SpannerIO dalam pipeline Apache Beam untuk membaca dari atau menulis ke database Spanner Omni.

Sebelum memulai

Untuk menghubungkan SpannerIO ke Spanner Omni, pastikan Anda memenuhi persyaratan berikut:

  • Lakukan inisialisasi database dalam lingkungan Spanner Omni Anda.

  • Jika Anda menggunakan enkripsi, pastikan Anda menggunakan Apache Beam versi yang kompatibel:

    • Untuk enkripsi TLS, versi 2.69.0 atau yang lebih baru.
    • Untuk enkripsi mutual TLS (mTLS), versi 2.75.0 atau yang lebih baru.

  • Siapkan kredensial autentikasi untuk lingkungan Anda.

Mengonfigurasi SpannerIO untuk terhubung ke Spanner Omni

Untuk menghubungkan SpannerIO ke Spanner Omni, konfigurasi SpannerConfig dengan detail database dan parameter koneksi Anda.

Untuk mengonfigurasi koneksi, pilih salah satu mode koneksi berikut:

Menghubungkan menggunakan komunikasi teks biasa

Untuk membuat koneksi teks biasa, tentukan endpoint Spanner Omni, aktifkan dukungan host eksperimental dengan metode withExperimentalHost(), dan konfigurasi pipeline dengan metode withUsingPlainTextChannel().

Contoh berikut menunjukkan cara mengonfigurasi koneksi teks biasa:

SpannerConfig spannerConfig =
    SpannerConfig.create()
        .withDatabaseId("DATABASE_ID")
        // Define the Spanner Omni endpoint
        .withExperimentalHost("http://ENDPOINT")
        // Use a plain-text connection
        .withUsingPlainTextChannel(true);

Ganti kode berikut:

  • DATABASE_ID: ID database Spanner Omni Anda, misalnya, test-db.

  • ENDPOINT: endpoint instance Spanner Omni Anda, misalnya, localhost:15000.

Menghubungkan menggunakan enkripsi

Untuk melindungi traffic database dan memastikan komunikasi yang aman antara Apache Beam dan Spanner Omni, Anda dapat terhubung menggunakan enkripsi TLS atau mTLS. Menggunakan enkripsi membantu menjaga kerahasiaan kredensial dan data Anda.

Menggunakan enkripsi TLS

Untuk melindungi traffic database antara Apache Beam dan Spanner Omni menggunakan enkripsi TLS, Anda tidak perlu menentukan properti kredensial di SpannerConfig. Sebagai gantinya, konfigurasi truststore Java dengan sertifikat CA Omni Spanner, lalu konfigurasi SpannerConfig untuk menggunakan endpoint TLS yang aman.

Langkah 1: Konfigurasi truststore Java

Untuk mengamankan komunikasi, Anda harus mengimpor sertifikat CA yang dibuat oleh Spanner Omni ke truststore Java. Gunakan salah satu opsi berikut:

Truststore Java default

Tambahkan sertifikat CA yang dihasilkan oleh Spanner Omni ke truststore Java standar dengan menjalankan perintah berikut:

sudo keytool -import -trustcacerts \
  -file ~/.spanner/certs/ca.crt \
  -alias spanner-ca \
  -keystore $JAVA_HOME/lib/security/cacerts

Truststore kustom

Untuk memastikan bahwa pipeline Anda tetap dapat terhubung ke database atau layanan lain yang menggunakan otoritas sertifikat (CA) standar, buat truststore kustom:

  1. Buat truststore kustom dengan menyalin truststore Java yang ada:

    cp $JAVA_HOME/lib/security/cacerts PATH_TO_CUSTOM_CA_CERTIFICATE

  2. Impor sertifikat CA ke truststore kustom Anda:

    keytool -import -trustcacerts \
  -file ~/.spanner/certs/ca.crt \
  -alias spanner-ca \
  -keystore PATH_TO_CUSTOM_CA_CERTIFICATE

  3. Teruskan penyimpanan sertifikat CA kustom saat Anda menjalankan pipeline:

    java -Djavax.net.ssl.trustStore=PATH_TO_CUSTOM_CA_CERTIFICATE \
  -Djavax.net.ssl.trustStorePassword=changeit \
  -jar PIPELINE_NAME.jar

Ganti kode berikut:

  • PATH_TO_CUSTOM_CA_CERTIFICATE: jalur ke penyimpanan sertifikat CA kustom Anda.

  • PIPELINE_NAME: nama pipeline Apache Beam Anda.

Langkah 2: Konfigurasikan SpannerConfig

Untuk mengonfigurasi SpannerConfig agar menggunakan koneksi TLS yang aman, tambahkan kode berikut ke pipeline Anda:

SpannerConfig spannerConfig =
    SpannerConfig.create()
        .withDatabaseId("DATABASE_ID")
        // Define the secure Spanner Omni endpoint
        .withExperimentalHost("https://ENDPOINT");

Ganti kode berikut:

  • DATABASE_ID: ID database Spanner Omni Anda, misalnya, test-db.

  • ENDPOINT: endpoint instance Spanner Omni Anda, misalnya, localhost:15000.

Menggunakan enkripsi mTLS

Untuk membuat koneksi TLS dua arah (mTLS) menggunakan Apache Beam, Anda harus mengonfigurasi truststore Java dengan sertifikat CA, membuat atau mengonversi kunci pribadi klien ke format PKCS#8, lalu mengonfigurasi SpannerConfig dengan jalur sertifikat dan kunci klien.

Langkah 1: Konfigurasi truststore Java

Konfigurasi truststore Java dengan sertifikat CA Omni Spanner seperti yang dijelaskan di Langkah 1: Mengonfigurasi truststore Java sebelumnya dalam dokumen ini.

Langkah 2: Konversi atau buat kunci pribadi klien

Untuk terhubung menggunakan mTLS, pastikan kunci pribadi klien Anda dalam format PKCS#8. Gunakan salah satu opsi berikut:

openssl

Untuk mengonversi kunci klien yang dihasilkan oleh Spanner Omni ke format yang kompatibel dengan Java, jalankan perintah berikut:

openssl pkcs8 -topk8 \
  -in ~/.spanner/certs/client.key \
  -out ~/.spanner/certs/java-client.key \
  -nocrypt

CLI Spanner Omni

Buat kunci langsung dalam format PKCS#8 saat membuat sertifikat klien dengan menggunakan Spanner Omni CLI dengan flag --generate-pkcs8-key.

Untuk membuat sertifikat klien dan kunci pribadi klien dalam format PKCS#8, jalankan perintah berikut:

spanner certificates create-client CLIENT_NAME \
  --ca-certificate-directory=PATH_TO_CA_CERTIFICATES \
  --ca-private-key-directory=PATH_TO_PRIVATE_KEYS \
  --output-directory=PATH_TO_CERTIFICATES \
  --generate-pkcs8-key

Ganti kode berikut:

  • CLIENT_NAME: nama klien untuk membuat sertifikat dan kunci pribadi.

  • PATH_TO_CA_CERTIFICATES: jalur ke direktori yang berisi sertifikat CA.

  • PATH_TO_PRIVATE_KEYS: jalur ke direktori yang berisi kunci pribadi CA.

  • PATH_TO_CERTIFICATES: jalur ke direktori tempat sertifikat klien dan kunci pribadi disimpan.

Langkah 3: Konfigurasikan SpannerConfig

Konfigurasi SpannerConfig dalam kode pipeline Anda dengan sertifikat klien dan kunci pribadi klien:

SpannerConfig spannerConfig =
    SpannerConfig.create()
        .withDatabaseId("DATABASE_ID")
        // Define the secure Spanner Omni endpoint
        .withExperimentalHost("https://ENDPOINT")
        // Specify the paths to the client certificate and private key
        .withClientCert(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_CERT_KEY");

Ganti kode berikut:

  • DATABASE_ID: ID database Spanner Omni Anda, misalnya, test-db.

  • ENDPOINT: endpoint instance Spanner Omni Anda, misalnya, localhost:15000.

  • PATH_TO_CLIENT_CERT: jalur ke file sertifikat klien Anda.

  • PATH_TO_CLIENT_CERT_KEY: jalur ke file kunci pribadi klien Anda.

Mengonfigurasi token autentikasi

Token autentikasi tidak direkomendasikan untuk digunakan klien karena token yang dibuat oleh Spanner Omni akan habis masa berlakunya dan memerlukan perpanjangan manual dengan Spanner Omni CLI. Untuk menggunakan token autentikasi dengan penyiapan TLS atau mTLS untuk endpoint Spanner Omni, tetapkan variabel lingkungan SPANNER_EXPERIMENTAL_HOST_AUTH_TOKEN ke nilai token autentikasi yang dihasilkan oleh Spanner Omni CLI. Biarkan variabel ini tidak disetel untuk koneksi yang tidak memerlukan kredensial.

Langkah berikutnya