使用 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 信任儲存庫，然後將 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 信任儲存庫、產生用戶端私密金鑰或將其轉換為 PKCS#8 格式，然後使用用戶端憑證和金鑰路徑設定 SpannerConfig。

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

使用 Spanner Omni CA 憑證設定 Java 信任儲存庫，如本文前述的「步驟 1：設定 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 手動更新。如要將驗證權杖與 Spanner Omni 端點的 TLS 或 mTLS 設定搭配使用，請將 SPANNER_EXPERIMENTAL_HOST_AUTH_TOKEN 環境變數設為 Spanner Omni CLI 產生的驗證權杖值。如果連線不需要憑證，請將這個變數留空。

後續步驟