שימוש בלקוח Cassandra Java כדי להתחבר ל-Spanner Omni

‫Cassandra Java client for Spanner מקשר בין אפליקציות שנכתבו עבור מסד הנתונים של Apache Cassandra לבין Spanner. הלקוח עובד עם Spanner Omni באותה דרך שבה הוא עובד עם Spanner.

מכיוון ש-Spanner תומך באופן מקורי בפרוטוקול Cassandra v4 wire, לקוח Spanner Cassandra Java מתרגם את פרוטוקול Cassandra wire ל-Spanner gRPC API. כך תוכלו להעביר את אפליקציות Cassandra ל-Spanner עם שינויים מינימליים בקוד.

במאמר הזה מוסבר איך לשלב את הלקוח עם Spanner Omni באחת מהשיטות הבאות:

  • תלות בתהליך: משתמשים בשיטה הזו באפליקציות Java שכבר משתמשות ב-cassandra-java-driver. הגישה הזו מטמיעה את הלקוח בתהליך של האפליקציה כדי לצמצם למינימום את השינויים בקוד.

  • ‫קובץ עזר חיצוני: משתמשים בשיטה הזו באפליקציות שאינן Java או כשמשתמשים בכלים חיצוניים של Cassandra, כמו cqlsh. בגישה הזו, הלקוח פועל כתהליך עצמאי.

מידע נוסף מופיע במאמר בנושא ממשק Cassandra במסמכי התיעוד של Spanner.

מתי כדאי להשתמש בלקוח Spanner Cassandra Java

הלקוח הזה שימושי בתרחישים הבאים:

  • שימוש ב-Spanner עם מינימום שינויים בקוד. אתם רוצים להשתמש ב-Spanner כקצה העורפי של אפליקציית Java, אבל מעדיפים להמשיך להשתמש ב-cassandra-java-driver API המוכר כדי לגשת לנתונים.

  • משתמשים בכלים של Cassandra שאינם מבוססים על Java. אתם רוצים להתחבר ל-Spanner באמצעות כלים סטנדרטיים של Cassandra כמו cqlsh או אפליקציות שנכתבו בשפות אחרות שמשתמשות במנהלי התקנים של Cassandra.

שימוש בלקוח כתלות בתהליך

השיטה המומלצת לחיבור אפליקציות Java ל-Spanner Omni היא שילוב של לקוח Spanner Cassandra Java כתלות בתהליך. בהשוואה לשיטת ה-sidecar proxy, ההגדרה בתוך התהליך מספקת ביצועים טובים יותר כי היא מונעת דילוג נוסף ברשת ואת הסדרות והדה-סדרות של הנתונים שקשורים לדילוג הזה. בנוסף, היא מפשטת את ארכיטקטורת הפריסה כי לא צריך לנהל תהליך נפרד ועצמאי.

כדי להשתמש בלקוח כתלות בתהליך:

  1. מוסיפים את לקוח Spanner Cassandra Java כתלות לפרויקט:

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-cassandra</artifactId>
  <version>1.2.0</version>
</dependency>

  2. משנים את קוד היצירה של CqlSession ומוסיפים את האפשרויות הספציפיות לתקשורת עם Spanner Omni:

    טקסט פשוט

    בדוגמה הבאה מוצג איך ליצור חיבור בטקסט פשוט ל-Spanner Omni:

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(true)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    TLS

    כדי להשתמש בחיבור TLS, צריך לוודא שאישור ה-CA נוסף למאגר האישורים שבו האפליקציה משתמשת, כמו שמתואר במאמר הגדרת מאגר האישורים של Java:

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    mTLS

    כדי להשתמש בחיבור mTLS, צריך לוודא שאישור ה-CA נוסף למאגר האישורים שבו האפליקציה משתמשת, ושמפתח הלקוח הוא בפורמט PKCS#8. מידע נוסף זמין בהוראות בנושא mTLS ב-Java SDK.

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .setClientCertPathAndKey(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_KEY_PKCS8")
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

  session.close();

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫DATABASE_ID: המזהה של מסד הנתונים של Spanner Omni, לדוגמה, test-db.

    • ‫ENDPOINT: נקודת הקצה של מופע Spanner Omni, לדוגמה, localhost:15000.

    • ‫PATH_TO_CLIENT_CERT: הנתיב לקובץ אישור הלקוח.

    • ‫PATH_TO_CLIENT_KEY_PKCS8: הנתיב לקובץ המפתח הפרטי של הלקוח בפורמט PKCS#8.

תהליך עצמאי או Proxy מסוג Sidecar

פריסת לקוח Java של Spanner Cassandra כקובץ עזר חיצוני היא אפשרות יעילה לאפליקציות ולכלים שאינם Java, כמו cqlsh, להתחבר ל-Spanner Omni באמצעות דרייברים סטנדרטיים של Cassandra. בשיטה הזו, הלקוח מופעל כשרת proxy עצמאי של TCP שמיירט את תעבורת הנתונים של פרוטוקול Cassandra וממיר אותה ל-gRPC לצורך תקשורת עם Spanner Omni.

אפשר להריץ את קובץ העזר החיצוני באמצעות קובץ תצורה YAML או על ידי ציון מאפייני מערכת.

שימוש בקובץ הגדרות YAML

בהגדרות של סביבת ייצור, מומלץ להשתמש בקובץ YAML כדי להגדיר את המתאם. השיטה הזו תומכת בכמה מאזינים ובהגדרות גלובליות:

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

דוגמה config.yaml:

globalClientConfigs:
  enableBuiltInMetrics: false
  healthCheckEndpoint: "127.0.0.1:8080"
  spannerEndpoint: "ENDPOINT"
  instanceType: "omni"
  clientCertPath: "PATH_TO_CLIENT_CERT"
  clientKeyPath: "PATH_TO_CLIENT_KEY_PKCS8"
  usePlainText: "false"

listeners:
  - name: "listener_1"
    host: "127.0.0.1"
    port: 9042
    spanner:
      databaseUri: "DATABASE_ID"
      numGrpcChannels: 4
      maxCommitDelayMillis: 5
  - name: "listener_2"
    host: "127.0.0.2"
    port: 9043
    spanner:
      databaseUri: "DATABASE_ID_2"
      numGrpcChannels: 8

שימוש במאפייני המערכת

אם יש לכם מאזין יחיד או פריסות פשוטות יותר, אתם יכולים להריץ את שרת ה-Proxy של ה-sidecar כתהליך עצמאי ולהגדיר את ההגדרות שלו באמצעות מאפייני מערכת של Java.

בדוגמאות הבאות מוצגות דרכים להפעיל את פרוקסי ה-sidecar כתהליך עצמאי לכל הגדרת אבטחה נתמכת:

טקסט פשוט

כדי להריץ את הפקודה עם תקשורת בטקסט רגיל, מריצים את הפקודה הבאה:

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DspannerEndpoint=ENDPOINT \
-DinstanceType=omni \
-DusePlainText=true \
-jar PATH_TO_ADAPTER_JAR

TLS

כדי להריץ עם חיבור TLS, מריצים את הפקודה הבאה:

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DspannerEndpoint=ENDPOINT \
-DinstanceType=omni \
-jar PATH_TO_ADAPTER_JAR

mTLS

כדי להריץ עם חיבור mTLS, מריצים את הפקודה הבאה:

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DspannerEndpoint=ENDPOINT \
-DinstanceType=omni \
-DclientCertPath=PATH_TO_CLIENT_CERT \
-DclientKeyPath=PATH_TO_CLIENT_KEY_PKCS8 \
-jar PATH_TO_ADAPTER_JAR

מחליפים את מה שכתוב בשדות הבאים:

  • ‫DATABASE_ID: המזהה של מסד הנתונים של Spanner Omni, לדוגמה, test-db.

  • ‫ENDPOINT: נקודת הקצה של מופע Spanner Omni, לדוגמה, localhost:15000.

  • ‫PATH_TO_ADAPTER_JAR: הנתיב לקובץ ה-JAR של מתאם Cassandra.

  • ‫PATH_TO_CLIENT_CERT: הנתיב לקובץ אישור הלקוח.

  • ‫PATH_TO_CLIENT_KEY_PKCS8: הנתיב לקובץ המפתח הפרטי של הלקוח בפורמט PKCS#8.