使用 Apache Beam 和 SpannerIO 連線至 Spanner Omni

Apache Beam 是開放原始碼形式的整合式模型，用於定義批次和串流資料平行處理管線。本文說明如何在 Apache Beam 管道中使用 SpannerIO 連接器，從 Spanner Omni 資料庫讀取資料或將資料寫入其中。

事前準備

如要將 SpannerIO 連線至 Spanner Omni，請確認您符合下列條件：

  • 在 Spanner Omni 環境中初始化資料庫。

  • 如果使用加密功能，請務必使用相容的 Apache Beam 版本：

    • 如要使用 TLS 加密，請使用 2.69.0 以上版本。
    • 如要使用相互傳輸層安全標準 (mTLS) 加密，請使用 2.75.0 以上版本。

  • 為環境設定驗證憑證。

設定 SpannerIO 以連線至 Spanner Omni

如要將 SpannerIO 連線至 Spanner Omni，請使用資料庫詳細資料和連線參數設定 SpannerConfig。

如要設定連線，請選擇下列其中一種連線模式：

使用純文字通訊連線

如要建立純文字連線，請指定 Spanner Omni 端點，使用 withExperimentalHost() 方法啟用實驗性主機支援，並使用 withUsingPlainTextChannel() 方法設定管道。

以下範例說明如何設定純文字連線：

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

更改下列內容：

  • DATABASE_ID：Spanner Omni 資料庫的 ID，例如 test-db。

  • ENDPOINT：Spanner Omni 執行個體的端點，例如 localhost:15000。

使用加密連線

如要保護資料庫流量，並確保 Apache Beam 與 Spanner Omni 之間的通訊安全無虞，您可以透過 TLS 或 mTLS 加密連線。加密功能可確保憑證和資料的機密性。

使用 TLS 加密

如要使用傳輸層安全標準 (TLS) 加密，保護 Apache Beam 和 Spanner Omni 之間的資料庫流量，您不需要在 SpannerConfig 中指定憑證屬性。請改為使用 Spanner Omni CA 憑證設定 Java Truststore，然後設定 SpannerConfig 使用安全的 TLS 端點。

步驟 1：設定 Java 信任儲存區

如要確保通訊安全，您必須將 Spanner Omni 產生的 CA 憑證匯入 Java 信任儲存庫。請使用下列其中一個選項：

預設 Java 信任儲存區

執行下列指令，將 Spanner Omni 產生的 CA 憑證新增至標準 Java 信任儲存區：

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

自訂信任存放區

如要確保管道仍可連線至使用標準憑證授權單位 (CA) 的其他資料庫或服務，請建立自訂信任儲存區：

  1. 複製現有的 Java 信任儲存區，建立自訂信任儲存區：

    cp $JAVA_HOME/lib/security/cacerts PATH_TO_CUSTOM_CA_CERTIFICATE

  2. 將 CA 憑證匯入自訂信任存放區：

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

  3. 執行管道時，傳遞自訂 CA 憑證存放區：

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

更改下列內容：

  • PATH_TO_CUSTOM_CA_CERTIFICATE：自訂 CA 憑證存放區的路徑。

  • PIPELINE_NAME：Apache Beam 管道的名稱。

步驟 2：設定 SpannerConfig

如要設定 SpannerConfig 使用安全的 TLS 連線，請在管道中新增下列程式碼：

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

更改下列內容：

  • DATABASE_ID：Spanner Omni 資料庫的 ID，例如 test-db。

  • ENDPOINT：Spanner Omni 執行個體的端點，例如 localhost:15000。

使用 mTLS 加密

如要使用 Apache Beam 建立相互傳輸層安全 (mTLS) 連線，您必須使用 CA 憑證設定 Java Truststore，產生或轉換用戶端私密金鑰為 PKCS#8 格式，然後使用用戶端憑證和金鑰路徑設定 SpannerConfig。

步驟 1：設定 Java 信任儲存區

按照本文件稍早的「步驟 1：設定 Java 信任儲存區」所述，使用 Spanner Omni CA 憑證設定 Java 信任儲存區。

步驟 2：轉換或產生用戶端私密金鑰

如要使用 mTLS 連線，請確認用戶端私密金鑰採用 PKCS#8 格式。請使用下列其中一種方式：

openssl

如要將 Spanner Omni 產生的用戶端金鑰轉換為符合 Java 的格式，請執行下列指令：

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

Spanner Omni CLI

使用 Spanner Omni CLI 搭配 --generate-pkcs8-key 標記建立用戶端憑證時，直接以 PKCS#8 格式產生金鑰。

如要產生 PKCS#8 格式的用戶端憑證和用戶端私密金鑰，請執行下列指令：

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

更改下列內容：

  • CLIENT_NAME：要產生憑證和私密金鑰的用戶端名稱。

  • PATH_TO_CA_CERTIFICATES：包含 CA 憑證的目錄路徑。

  • PATH_TO_PRIVATE_KEYS：包含 CA 私密金鑰的目錄路徑。

  • PATH_TO_CERTIFICATES：儲存用戶端憑證和私密金鑰的目錄路徑。

步驟 3：設定 SpannerConfig

在管道程式碼中，使用用戶端憑證和用戶端私密金鑰設定 SpannerConfig：

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

更改下列內容：

  • DATABASE_ID：Spanner Omni 資料庫的 ID，例如 test-db。

  • ENDPOINT：Spanner Omni 執行個體的端點，例如 localhost:15000。

  • PATH_TO_CLIENT_CERT：用戶端憑證檔案的路徑。

  • PATH_TO_CLIENT_CERT_KEY：用戶端私密金鑰檔案的路徑。

設定驗證權杖

不建議用戶端使用驗證權杖，因為 Spanner Omni 產生的權杖會過期，且需要使用 Spanner Omni CLI 手動更新。如要搭配 TLS 或 mTLS 設定，將驗證權杖用於 Spanner Omni 端點，請將 SPANNER_EXPERIMENTAL_HOST_AUTH_TOKEN 環境變數設為 Spanner Omni CLI 產生的驗證權杖值。如果連線不需要憑證，請將這個變數設為未設定。

後續步驟