Pub/Sub to Splunk テンプレートは、Pub/Sub サブスクリプションからメッセージを読み取り、メッセージ ペイロードを Splunk の HTTP Event Collector(HEC)を介して Splunk に書き込むストリーミング パイプラインです。このテンプレートの最も一般的な使用例は Splunk へのログのエクスポートです。基盤となるワークフローの例については、Dataflow を使用して本番環境対応のログのエクスポートを Splunk にデプロイするをご覧ください。
Splunk に書き込む前に、メッセージ ペイロードに JavaScript ユーザー定義関数を適用することもできます。処理が失敗したメッセージは、トラブルシューティングと再処理のために Pub/Sub の未処理のトピックに転送されます。
HEC トークンの保護を強化するために、Base64 エンコードされた HEC トークン パラメータを Cloud KMS 鍵で暗号化して、この Cloud KMS 鍵とともに渡すこともできます。HEC トークン パラメータの暗号化の詳細については、Cloud KMS API 暗号化エンドポイントをご覧ください。
パイプラインの要件
- パイプラインの実行前にソース Pub/Sub サブスクリプションが存在している必要があります。
- パイプラインを実行する前に、Pub/Sub に未処理のトピックが存在している必要があります。
- Dataflow ワーカーのネットワークから Splunk の HEC エンドポイントにアクセスできる必要があります。
- Splunk の HEC トークンが生成済みで、利用可能である必要があります。
テンプレートのパラメータ
必須パラメータ
- inputSubscription: 入力の読み取り元になる Pub/Sub サブスクリプション(例: projects/your-project-id/subscriptions/your-subscription-name)。
- url: Splunk HEC URL。この 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 メッセージをペイロードに含めます。デフォルトは false(ペイロードにはデータ要素のみが含まれる)です。
- tokenKMSEncryptionKey: HEC トークン文字列の復号に使用する Cloud KMS 鍵。tokenSource が KMS に設定されている場合は、このパラメータを指定する必要があります。Cloud KMS 鍵を指定する場合は、HEC トークン文字列
must
を暗号化して渡す必要があります(例: projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name)。 - tokenSecretId: トークンの Secret Manager シークレット ID。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: Cloud Storage のルート CA 証明書の完全 URL。Cloud Storage で提供される証明書は DER でエンコードする必要があります。この証明書はバイナリまたは印刷可能(Base64)エンコードで提供できます。証明書を Base64 エンコードで提供する場合は、証明書を -----BEGIN CERTIFICATE----- と -----END CERTIFICATE----- で囲む必要があります。このパラメータを指定すると、このプライベート CA 証明書ファイルが取得され、Splunk HEC エンドポイントの SSL 証明書の検証用に Dataflow ワーカーのトラストストアに追加されます。このパラメータを指定しない場合は、デフォルトのトラストストアが使用されます(例: gs://mybucket/mycerts/privateCA.crt)。
- enableBatchLogs: Splunk に書き込まれたバッチに対してログを有効にするかどうかを指定します。デフォルト:
true
。 - enableGzipHttpCompression: Splunk HEC に送信される HTTP リクエストを圧縮するかどうか(gzip コンテンツをエンコードするかどうか)を指定します。デフォルト:
true
。 - javascriptTextTransformGcsPath: 使用する JavaScript ユーザー定義関数(UDF)を定義する .js ファイルの Cloud Storage URI。たとえば、
gs://my-bucket/my-udfs/my_file.js
のようにします。 - javascriptTextTransformFunctionName: 使用する JavaScript ユーザー定義関数(UDF)の名前。たとえば、JavaScript 関数コードが
myTransform(inJson) { /*...do stuff...*/ }
の場合、関数名はmyTransform
です。JavaScript UDF の例については、UDF の例(https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples)をご覧ください。 - javascriptTextTransformReloadIntervalMinutes: ワーカーが JavaScript UDF の変更を確認してファイルを再読み込みできる間隔を定義します。デフォルト値は 0 です。
ユーザー定義関数
必要であれば、ユーザー定義関数(UDF)を記述して、このテンプレートを拡張できます。このテンプレートは入力要素ごとに UDF を呼び出します。要素のペイロードは、JSON 文字列としてシリアル化されます。詳細については、Dataflow テンプレートのユーザー定義関数を作成するをご覧ください。
関数の仕様
UDF の仕様は次のとおりです。
- 入力: JSON 文字列としてシリアル化された Pub/Sub メッセージ データ フィールド。
- 出力: Splunk HEC イベント エンドポイントに送信されるイベントデータ。出力は、文字列または文字列化された JSON オブジェクトである必要があります。
テンプレートを実行する
コンソール
- Dataflow の [テンプレートからジョブを作成] ページに移動します。 [テンプレートからジョブを作成] に移動
- [ジョブ名] フィールドに、固有のジョブ名を入力します。
- (省略可)[リージョン エンドポイント] で、プルダウン メニューから値を選択します。デフォルトのリージョンは
us-central1
です。Dataflow ジョブを実行できるリージョンのリストについては、Dataflow のロケーションをご覧ください。
- [Dataflow テンプレート] プルダウン メニューから、[ the Pub/Sub to Splunk template] を選択します。
- 表示されたパラメータ フィールドに、パラメータ値を入力します。
- (省略可)1 回限りの処理から 1 回以上のストリーミング モードに切り替えるには、[1 回以上] を選択します。
- [ジョブを実行] をクリックします。
gcloud
シェルまたはターミナルで、テンプレートを実行します。
gcloud dataflow jobs run JOB_NAME \ --gcs-location gs://dataflow-templates-REGION_NAME/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-REGION_NAME/latest/)にあります。- バージョン名(例:
2023-09-12-00_RC00
)。特定のバージョンのテンプレートを使用します。このテンプレートは、バケット内で対応する日付の親フォルダ(gs://dataflow-templates-REGION_NAME/)にあります。
STAGING_LOCATION
: ローカル ファイルをステージングする場所(例:gs://your-bucket/staging
)INPUT_SUBSCRIPTION_NAME
: Pub/Sub サブスクリプション名TOKEN
: Splunk の Http Event Collector トークンURL
: Splunk の Http Event Collector の URL パス(例:https://splunk-hec-host:8088
)DEADLETTER_TOPIC_NAME
: Pub/Sub トピック名JAVASCRIPT_FUNCTION
: 使用する JavaScript ユーザー定義関数(UDF)の名前たとえば、JavaScript 関数コードが
myTransform(inJson) { /*...do stuff...*/ }
の場合、関数名はmyTransform
です。JavaScript UDF の例については、UDF の例をご覧ください。PATH_TO_JAVASCRIPT_UDF_FILE
: 使用する JavaScript ユーザー定義関数(UDF)を定義する.js
ファイルの Cloud Storage URI(例:gs://my-bucket/my-udfs/my_file.js
)BATCH_COUNT
: Splunk に複数のイベントを送信するために使用するバッチサイズPARALLELISM
: Splunk にイベントを送信するために使用する並列リクエストの数DISABLE_VALIDATION
: SSL 証明書の検証を無効にする場合、true
ROOT_CA_CERTIFICATE_PATH
: Cloud Storage のルート CA 証明書へのパス(例:gs://your-bucket/privateCA.crt
)。
API
REST API を使用してテンプレートを実行するには、HTTP POST リクエストを送信します。API とその認証スコープの詳細については、projects.templates.launch
をご覧ください。
POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/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
: Dataflow ジョブを実行する Google Cloud プロジェクトの IDJOB_NAME
: 一意の任意のジョブ名LOCATION
: Dataflow ジョブをデプロイするリージョン(例:us-central1
)VERSION
: 使用するテンプレートのバージョン使用できる値は次のとおりです。
latest
: 最新バージョンのテンプレートを使用します。このテンプレートは、バケット内で日付のない親フォルダ(gs://dataflow-templates-REGION_NAME/latest/)にあります。- バージョン名(例:
2023-09-12-00_RC00
)。特定のバージョンのテンプレートを使用します。このテンプレートは、バケット内で対応する日付の親フォルダ(gs://dataflow-templates-REGION_NAME/)にあります。
STAGING_LOCATION
: ローカル ファイルをステージングする場所(例:gs://your-bucket/staging
)INPUT_SUBSCRIPTION_NAME
: Pub/Sub サブスクリプション名TOKEN
: Splunk の Http Event Collector トークンURL
: Splunk の Http Event Collector の URL パス(例:https://splunk-hec-host:8088
)DEADLETTER_TOPIC_NAME
: Pub/Sub トピック名JAVASCRIPT_FUNCTION
: 使用する JavaScript ユーザー定義関数(UDF)の名前たとえば、JavaScript 関数コードが
myTransform(inJson) { /*...do stuff...*/ }
の場合、関数名はmyTransform
です。JavaScript UDF の例については、UDF の例をご覧ください。PATH_TO_JAVASCRIPT_UDF_FILE
: 使用する JavaScript ユーザー定義関数(UDF)を定義する.js
ファイルの Cloud Storage URI(例:gs://my-bucket/my-udfs/my_file.js
)BATCH_COUNT
: Splunk に複数のイベントを送信するために使用するバッチサイズPARALLELISM
: Splunk にイベントを送信するために使用する並列リクエストの数DISABLE_VALIDATION
: SSL 証明書の検証を無効にする場合、true
ROOT_CA_CERTIFICATE_PATH
: Cloud Storage のルート CA 証明書へのパス(例:gs://your-bucket/privateCA.crt
)。
次のステップ
- Dataflow テンプレートについて学習する。
- Google 提供のテンプレートのリストを確認する。