תבנית Pub/Sub ל-Splunk

התבנית Pub/Sub to Splunk היא פייפליין זורם שקורא הודעות ממינוי Pub/Sub וכותב את המטען הייעודי (payload) של ההודעה ב-Splunk באמצעות HTTP Event Collector‏ (HEC) של Splunk. התרחיש הנפוץ ביותר לשימוש בתבנית הזו הוא ייצוא יומנים ל-Splunk. במאמר פריסת ייצוא של יומנים שמוכנים לייצור ל-Splunk באמצעות Dataflow תוכלו לקרוא דוגמה לתהליך העבודה הבסיסי.

לפני הכתיבה ב-Splunk, אפשר גם להחיל פונקציה בהגדרת המשתמש (UDF) ב-JavaScript על המטען הייעודי (payload) של ההודעה. הודעות שלא עברו עיבוד מועברות לנושא Pub/Sub שלא עבר עיבוד, כדי לפתור את הבעיות ולעבד אותן מחדש.

כדי להוסיף שכבת הגנה לטוקן ה-HEC, אתם יכולים גם להעביר מפתח Cloud KMS יחד עם הפרמטר של טוקן ה-HEC בקידוד base64, שמוצפן באמצעות מפתח Cloud KMS. פרטים נוספים על הצפנת הפרמטר של אסימון ה-HEC זמינים בנקודת הקצה להצפנה של Cloud KMS API.

דרישות לגבי צינור עיבוד הנתונים

  • המינוי ל-Pub/Sub במקור חייב להיות קיים לפני שמפעילים את צינור עיבוד הנתונים.
  • הנושא שלא עבר עיבוד ב-Pub/Sub חייב להיות קיים לפני שמריצים את צינור עיבוד הנתונים.
  • צריכה להיות גישה לנקודת הקצה של Splunk HEC מהרשת של ה-workers ב-Dataflow.
  • צריך ליצור את הטוקן של Splunk HEC ולוודא שהוא זמין.

פרמטרים של תבניות

פרמטרים נדרשים

  • ‫inputSubscription: המינוי ל-Pub/Sub שממנו נקרא הקלט. לדוגמה, projects/your-project-id/subscriptions/your-subscription-name.
  • ‫url: כתובת ה-URL של Splunk HEC. צריך להיות אפשרי לנתב את כתובת ה-URL מ-VPC שבו פועל צינור עיבוד הנתונים. לדוגמה, https://splunk-hec-host:8088.
  • ‫outputDeadletterTopic: נושא Pub/Sub שאליו מועברות הודעות שלא ניתן לשלוח. לדוגמה, projects/<PROJECT_ID>/topics/<TOPIC_NAME>.

פרמטרים אופציונליים

  • ‫token: אסימון האימות של Splunk HEC. חובה לציין את הפרמטר הזה אם הפרמטר tokenSource מוגדר כ-PLAINTEXT או כ-KMS.
  • ‫batchCount: גודל האצווה לשליחת כמה אירועים ל-Splunk. ברירת המחדל היא 1 (ללא אצווה).
  • ‫disableCertificateValidation: השבתת האימות של אישור ה-SSL. ברירת המחדל היא false (האימות מופעל). אם הערך הוא true, האישורים לא מאומתים (כל האישורים מהימנים) והמערכת מתעלמת מהפרמטר rootCaCertificatePath.
  • ‫parallelism: המספר המקסימלי של בקשות מקבילות. ברירת המחדל היא 1 (ללא מקביליות).
  • ‫includePubsubMessage: הכללת ההודעה המלאה של Pub/Sub במטען הייעודי (payload). ברירת המחדל היא false (רק רכיב הנתונים נכלל במטען הייעודי).
  • ‫tokenKMSEncryptionKey: המפתח של Cloud KMS שמשמש לפענוח מחרוזת הטוקן של HEC. צריך לספק את הפרמטר הזה כש-tokenSource מוגדר ל-KMS. אם מספקים את מפתח Cloud KMS, צריך להעביר את מחרוזת הטוקן של HEC כשהיא מוצפנת. לדוגמה, projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name.
  • ‫tokenSecretId: מזהה הסוד של הטוקן ב-Secret Manager. צריך לספק את הפרמטר הזה כשהערך של tokenSource מוגדר כ-SECRET_MANAGER. לדוגמה, projects/your-project-id/secrets/your-secret/versions/your-secret-version.
  • ‫tokenSource: מקור הטוקן. הערכים המותרים הם: PLAINTEXT,‏ KMS ו-SECRET_MANAGER. חובה לספק את הפרמטר הזה כשמשתמשים ב-Secret Manager. אם tokenSource מוגדר כ-KMS, tokenKMSEncryptionKey ומוצפן, צריך לספק את token. אם המדיניות tokenSource מוגדרת לערך SECRET_MANAGER, חובה לספק את tokenSecretId. אם המדיניות tokenSource מוגדרת לערך PLAINTEXT, חובה לספק את token.
  • ‫rootCaCertificatePath: כתובת ה-URL המלאה לאישור ה-CA הבסיסי ב-Cloud Storage. האישור שסופק ב-Cloud Storage צריך להיות בקידוד DER, ואפשר לספק אותו בקידוד בינארי או בקידוד שניתן להדפסה (Base64). אם האישור מסופק בקידוד Base64, הוא חייב להיות תחום בהתחלה על ידי -----BEGIN CERTIFICATE----- ובסוף על ידי -----END CERTIFICATE-----. אם הפרמטר הזה מסופק, קובץ אישור ה-CA הפרטי הזה מאוחזר ומתווסף למאגר האישורים של ה-worker של Dataflow כדי לאמת את אישור ה-SSL של נקודת הקצה של Splunk HEC. אם לא מציינים את הפרמטר הזה, המערכת משתמשת במאגר האישורים שמוגדר כברירת מחדל. לדוגמה, gs://mybucket/mycerts/privateCA.crt.
  • ‫enableBatchLogs: מציין אם צריך להפעיל יומנים לקבוצות שנכתבו ב-Splunk. ברירת המחדל: true.
  • ‫enableGzipHttpCompression: מציין אם בקשות HTTP שנשלחות ל-Splunk HEC צריכות להיות דחוסות (תוכן מקודד ב-gzip). ברירת המחדל: true.
  • ‫javascriptTextTransformGcsPath: ה-URI של Cloud Storage של קובץ ה-‎ .js שמגדיר את הפונקציה בהגדרת המשתמש (UDF) ב-JavaScript שבה רוצים להשתמש. לדוגמה, gs://my-bucket/my-udfs/my_file.js.
  • ‫javascriptTextTransformFunctionName: השם של הפונקציה בהגדרת המשתמש (UDF) ב-JavaScript שבה רוצים להשתמש. לדוגמה, אם קוד הפונקציה של JavaScript הוא myTransform(inJson) { /*...do stuff...*/ }, שם הפונקציה הוא myTransform. בקישור הבא תוכלו למצוא דוגמאות לפונקציות UDF ב-JavaScript‏ (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples).
  • ‫javascriptTextTransformReloadIntervalMinutes: מגדירים את מרווח הזמן שבו ה-workers יכולים לבדוק אם יש שינויים ב-UDF של JavaScript כדי לטעון מחדש את הקבצים. ברירת המחדל: 0.
  • ‫unwrapHecForDeadletter: כשהאפשרות הזו מופעלת, אם הודעה לא נכתבת ב-Splunk ונשלחת לתור ההודעות הבלתי ניתנות למסירה, המטען הייעודי (payload) המקורי יחולץ מהפורמט של Splunk HEC לפני הכתיבה לנושא של ההודעות הבלתי ניתנות למסירה. כך נמנעת הכללה של אירועים כשמפעילים מחדש הודעות. ברירת המחדל: false.

פונקציה בהגדרת המשתמש (UDF)

אם רוצים, אפשר להרחיב את התבנית הזו על ידי כתיבת פונקציה בהגדרת המשתמש (UDF). התבנית קוראת ל-UDF עבור כל רכיב קלט. המטענים הייעודיים של הרכיבים עוברים סריאליזציה למחרוזות JSON. מידע נוסף זמין במאמר יצירת פונקציות בהגדרת המשתמש (UDF) לתבניות Dataflow.

מפרט הפונקציה

המפרט של ה-UDF הוא:

  • קלט: שדה הנתונים של הודעת Pub/Sub, שעבר סריאליזציה כמחרוזת JSON.
  • ‫Output: נתוני האירוע שיישלחו לנקודת הקצה של אירועי Splunk HEC. הפלט חייב להיות מחרוזת או אובייקט JSON שהומר למחרוזת.

הפעלת התבנית

המסוף

  1. נכנסים לדף Create job from template ב-Dataflow.
  2. כניסה לדף Create job from template
  3. בשדה Job name, מזינים שם ייחודי למשימה.
  4. אופציונלי: בשדה Regional endpoint, בוחרים ערך מהתפריט הנפתח. אזור ברירת המחדל הוא us-central1.

    רשימה של אזורים שבהם אפשר להריץ משימת Dataflow מופיעה במאמר מיקומי Dataflow.

  5. בתפריט הנפתח Dataflow template, בוחרים את התבנית Pub/Sub to Splunk.
  6. בשדות הפרמטרים שמופיעים, מזינים את ערכי הפרמטרים.
  7. אופציונלי: כדי לעבור מעיבוד של פעם אחת בדיוק למצב סטרימינג של פעם אחת לפחות, בוחרים באפשרות At Least Once.
  8. לוחצים על Run job.

gcloud

במעטפת או בטרמינל, מריצים את התבנית:

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates/VERSION/Cloud_PubSub_to_Splunk \
    --region REGION_NAME \
    --staging-location STAGING_LOCATION \
    --parameters \
inputSubscription=projects/PROJECT_ID/subscriptions/INPUT_SUBSCRIPTION_NAME,\
token=TOKEN,\
url=URL,\
outputDeadletterTopic=projects/PROJECT_ID/topics/DEADLETTER_TOPIC_NAME,\
javascriptTextTransformGcsPath=PATH_TO_JAVASCRIPT_UDF_FILE,\
javascriptTextTransformFunctionName=JAVASCRIPT_FUNCTION,\
batchCount=BATCH_COUNT,\
parallelism=PARALLELISM,\
disableCertificateValidation=DISABLE_VALIDATION,\
rootCaCertificatePath=ROOT_CA_CERTIFICATE_PATH

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

  • ‫JOB_NAME: שם ייחודי למשימה, לפי בחירתכם
  • ‫REGION_NAME: האזור שבו רוצים לפרוס את משימת Dataflow, לדוגמה us-central1
  • ‫VERSION: גרסת התבנית שבה רוצים להשתמש

    אפשר להשתמש בערכים הבאים:

    • latest כדי להשתמש בגרסה העדכנית של התבנית, שזמינה בתיקיית ההורה ללא תאריך בקטגוריה – gs://dataflow-templates/latest/
    • שם הגרסה, כמו 2023-09-12-00_RC00, כדי להשתמש בגרסה ספציפית של התבנית, שנמצאת בתיקיית הנתונים מתאריך ספציפי בקטגוריה – gs://dataflow-templates/
  • ‫STAGING_LOCATION: המיקום להכנת קבצים מקומיים (לדוגמה, gs://your-bucket/staging)
  • INPUT_SUBSCRIPTION_NAME: השם של המינוי ל-Pub/Sub
  • ‫TOKEN: אסימון של Splunk Http Event Collector
  • ‫URL: נתיב כתובת ה-URL של Http Event Collector של Splunk (לדוגמה, https://splunk-hec-host:8088)
  • ‫DEADLETTER_TOPIC_NAME: השם של נושא Pub/Sub
  • JAVASCRIPT_FUNCTION: השם של הפונקציה בהגדרת המשתמש (UDF) ב-JavaScript שבה רוצים להשתמש

    לדוגמה, אם קוד הפונקציה של JavaScript הוא myTransform(inJson) { /*...do stuff...*/ }, שם הפונקציה הוא myTransform. במאמר דוגמאות לפונקציות UDF תוכלו למצוא דוגמאות לפונקציות UDF ב-JavaScript.

  • ‫PATH_TO_JAVASCRIPT_UDF_FILE: ה-URI של Cloud Storage של קובץ ה-.js שמגדיר את הפונקציה בהגדרת המשתמש (UDF) ב-JavaScript שבה רוצים להשתמש – לדוגמה, gs://my-bucket/my-udfs/my_file.js
  • ‫BATCH_COUNT: גודל האצווה שמשמש לשליחת כמה אירועים ל-Splunk
  • ‫PARALLELISM: מספר הבקשות המקבילות שמשמשות לשליחת אירועים ל-Splunk
  • ‫DISABLE_VALIDATION: true אם רוצים להשבית את אימות אישור ה-SSL
  • ‫ROOT_CA_CERTIFICATE_PATH: הנתיב לאישור ה-CA ברמה הבסיסית (root) ב-Cloud Storage (לדוגמה, gs://your-bucket/privateCA.crt)

API

כדי להריץ את התבנית באמצעות ה-API ל-REST, שולחים בקשת HTTP POST. למידע נוסף על ה-API ועל היקפי ההרשאות שלו, קראו את המאמר projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates/VERSION/Cloud_PubSub_to_Splunk
{
   "jobName": "JOB_NAME",
   "environment": {
       "ipConfiguration": "WORKER_IP_UNSPECIFIED",
       "additionalExperiments": []
   },
   "parameters": {
       "inputSubscription": "projects/PROJECT_ID/subscriptions/INPUT_SUBSCRIPTION_NAME",
       "token": "TOKEN",
       "url": "URL",
       "outputDeadletterTopic": "projects/PROJECT_ID/topics/DEADLETTER_TOPIC_NAME",
       "javascriptTextTransformGcsPath": "PATH_TO_JAVASCRIPT_UDF_FILE",
       "javascriptTextTransformFunctionName": "JAVASCRIPT_FUNCTION",
       "batchCount": "BATCH_COUNT",
       "parallelism": "PARALLELISM",
       "disableCertificateValidation": "DISABLE_VALIDATION",
       "rootCaCertificatePath": "ROOT_CA_CERTIFICATE_PATH"
   }
}

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

  • ‫PROJECT_ID: Google Cloud מזהה הפרויקט שבו רוצים להריץ את משימת Dataflow
  • ‫JOB_NAME: שם ייחודי למשימה, לפי בחירתכם
  • ‫LOCATION: האזור שבו רוצים לפרוס את משימת Dataflow, לדוגמה us-central1
  • ‫VERSION: גרסת התבנית שבה רוצים להשתמש

    אפשר להשתמש בערכים הבאים:

    • latest כדי להשתמש בגרסה העדכנית של התבנית, שזמינה בתיקיית ההורה ללא תאריך בקטגוריה – gs://dataflow-templates/latest/
    • שם הגרסה, כמו 2023-09-12-00_RC00, כדי להשתמש בגרסה ספציפית של התבנית, שנמצאת בתיקיית הנתונים מתאריך ספציפי בקטגוריה – gs://dataflow-templates/
  • ‫STAGING_LOCATION: המיקום להכנת קבצים מקומיים (לדוגמה, gs://your-bucket/staging)
  • INPUT_SUBSCRIPTION_NAME: השם של המינוי ל-Pub/Sub
  • ‫TOKEN: אסימון של Splunk Http Event Collector
  • ‫URL: נתיב כתובת ה-URL של Http Event Collector של Splunk (לדוגמה, https://splunk-hec-host:8088)
  • ‫DEADLETTER_TOPIC_NAME: השם של נושא Pub/Sub
  • JAVASCRIPT_FUNCTION: השם של הפונקציה בהגדרת המשתמש (UDF) ב-JavaScript שבה רוצים להשתמש

    לדוגמה, אם קוד הפונקציה של JavaScript הוא myTransform(inJson) { /*...do stuff...*/ }, שם הפונקציה הוא myTransform. במאמר דוגמאות לפונקציות UDF תוכלו למצוא דוגמאות לפונקציות UDF ב-JavaScript.

  • ‫PATH_TO_JAVASCRIPT_UDF_FILE: ה-URI של Cloud Storage של קובץ ה-.js שמגדיר את הפונקציה בהגדרת המשתמש (UDF) ב-JavaScript שבה רוצים להשתמש – לדוגמה, gs://my-bucket/my-udfs/my_file.js
  • ‫BATCH_COUNT: גודל האצווה שמשמש לשליחת כמה אירועים ל-Splunk
  • ‫PARALLELISM: מספר הבקשות המקבילות שמשמשות לשליחת אירועים ל-Splunk
  • ‫DISABLE_VALIDATION: true אם רוצים להשבית את אימות אישור ה-SSL
  • ‫ROOT_CA_CERTIFICATE_PATH: הנתיב לאישור ה-CA ברמה הבסיסית (root) ב-Cloud Storage (לדוגמה, gs://your-bucket/privateCA.crt)

המאמרים הבאים