Menggunakan Apache Beam dan SpannerIO untuk terhubung ke Spanner Omni

Apache Beam adalah model terpadu open source 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:

  • Melakukan inisialisasi database dalam lingkungan Spanner Omni Anda.

  • Jika Anda menggunakan enkripsi, pastikan Anda menggunakan versi Apache Beam 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, konfigurasikan 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 konfigurasikan 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. Penggunaan 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, konfigurasikan truststore Java dengan sertifikat CA Spanner Omni, lalu konfigurasikan SpannerConfig untuk menggunakan endpoint TLS yang aman.

Langkah 1: Konfigurasi truststore Java

Untuk mengamankan komunikasi, Anda harus mengimpor sertifikat CA yang dihasilkan 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 pipeline Anda masih dapat terhubung ke database atau layanan lain yang menggunakan certificate authority (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 mutual TLS (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 sertifikat klien dan jalur kunci.

Langkah 1: Konfigurasi truststore Java

Konfigurasikan truststore Java dengan sertifikat CA Spanner Omni seperti yang dijelaskan di Langkah 1: Konfigurasikan 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 sesuai dengan Java, jalankan perintah berikut:

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

Spanner Omni CLI

Buat kunci langsung dalam format PKCS#8 saat membuat sertifikat klien 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 yang akan dibuatkan sertifikat dan kunci pribadinya.

  • 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

Konfigurasikan 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 penggunaan klien karena token yang dihasilkan 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 ditetapkan untuk koneksi yang tidak memerlukan kredensial.

Langkah berikutnya