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

לקוח Cassandra Go ל-Spanner מחבר בין אפליקציות שנכתבו עבור מסד הנתונים של Apache Cassandra לבין Spanner. הלקוח פועל עם Spanner Omni באותו אופן שבו הוא פועל עם Spanner. ‫Spanner תומך באופן מובנה בפרוטוקול Cassandra v4 wire, ולכן הלקוח הזה מאפשר לאפליקציות Go שמשתמשות בדרייבר gocql, או לאפליקציות ולכלים שאינם Go, כמו cqlsh, להתחבר למסד נתונים של Spanner.

הלקוח הזה פועל כפרוקסי TCP מקומי. הוא מיירט את הבייטים של פרוטוקול Cassandra הגולמיים שנשלחים על ידי כלי של מנהל התקן או לקוח. לאחר מכן, הוא עוטף את הבייטים האלה ואת המטא-נתונים הדרושים בהודעות gRPC כדי לתקשר עם Spanner Omni. הלקוח מתרגם את התשובות מ-Spanner Omni בחזרה לפורמט Cassandra wire ושולח אותן בחזרה לדרייבר או לכלי המקוריים.

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

  • תלות בתהליך: משתמשים בשיטה הזו באפליקציות Go שכבר משתמשות במנהל ההתקנים gocql. הגישה הזו מטמיעה את הלקוח בתהליך הבקשה שלכם כדי לצמצם את השינויים בקוד.

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

מידע נוסף על אופן הפעולה של Apache Cassandra עם Spanner זמין במאמר בנושא ממשק Cassandra.

מתי כדאי להשתמש ב-Spanner Cassandra Go Client

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

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

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

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

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

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

  • מייבאים את חבילת Spanner לאפליקציית Go:

    import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"

  • משנים את הקוד ליצירת אשכול. במקום להשתמש ב-gocql.NewCluster, צריך להשתמש ב-spanner.NewCluster ולציין את האפשרויות הבאות שספציפיות ל-Spanner Omni:

    תקשורת בטקסט פשוט

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

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.UsePlainText = true

  cluster := spanner.NewCluster(opts)
  // ...
}

    חיבור TLS

    בדוגמה הבאה מוסבר איך ליצור חיבור TLS ל-Spanner Omni:

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"

  cluster := spanner.NewCluster(opts)
  // ...
}

    חיבור mTLS

    בדוגמה הבאה מוצג איך ליצור חיבור mTLS ל-Spanner Omni:

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"
  opts.ClientCertificate = "PATH_TO_CLIENT_CERT"
  opts.ClientKey = "PATH_TO_CLIENT_KEY"

  cluster := spanner.NewCluster(opts)
  // ...
}

פריסת הלקוח כקובץ עזר חיצוני

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

ההגדרה הזו שימושית כשצריך להשתמש בכלים חיצוניים של Cassandra או כשרוצים להימנע משינויים ישירים בקוד של האפליקציה.

אפשר להריץ את ה-proxy של ה-sidecar בדרכים הבאות:

הרצה מקומית באמצעות הפקודה run של Go

הפעלת פרוקסי מסוג sidecar כתהליך מקומי מקוד המקור שימושית בסביבות פיתוח ובדיקה שבהן רוצים לבצע איטרציות מהירות על האפליקציה ועל הגדרת הפרוקסי.

  1. משכפלים את המאגר:

    git clone https://github.com/googleapis/go-spanner-cassandra.git

  2. עוברים לספריית המאגר:

    cd go-spanner-cassandra

  3. מריצים את הפקודה cassandra_launcher.go עם הדגל -db הנדרש ועם הדגלים הספציפיים הבאים של Spanner Omni. מחליפים את הערך של -db בשם מסד הנתונים של Spanner Omni:

  • כדי להשתמש בתקשורת בטקסט פשוט, מריצים את הפקודה הבאה:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText
  • כדי להשתמש בחיבור TLS, מריצים את הפקודה הבאה:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT
  • לחיבור mTLS, מריצים את הפקודה הבאה:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY

הרצה עם קובץ אימג' של Docker שנבנה מראש

אנחנו ממליצים להריץ את קובץ העזר החיצוני כאפליקציה בקונטיינרים באמצעות קובץ אימג' של Docker שנבנה מראש לסביבות ייצור, כי הוא מספק סביבת זמן ריצה עקבית ומבודדת.

  1. שליפת התמונה ממאגר הרישום הרשמי:

    docker pull gcr.io/cloud-spanner-adapter/cassandra-adapter

  2. מריצים את התמונה עם הדגלים הנדרשים:

    תקשורת בטקסט פשוט

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

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText

    חיבור TLS

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

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT

    חיבור mTLS

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

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY