Pub/Sub to Splunk 템플릿

Pub/Sub to Splunk 템플릿은 Splunk의 HTTP Event Collector(HEC)를 통해 Pub/Sub 구독에서 메시지를 읽고 Splunk에 메시지 페이로드를 쓰는 스트리밍 파이프라인입니다. 이 템플릿의 가장 일반적인 사용 사례는 Splunk로 로그를 내보내는 것입니다. 기본 워크플로의 예시를 보려면 Dataflow를 사용하여 Splunk로 프로덕션에 즉시 사용 가능한 로그 내보내기 배포를 참조하세요.

Splunk에 쓰기 전에 자바스크립트 사용자 정의 함수를 메시지 페이로드에 적용할 수도 있습니다. 처리 실패가 발생한 메시지는 추가적인 문제 해결 및 재처리를 위해 Pub/Sub 처리 불가 주제로 전달됩니다.

HEC 토큰의 추가 보안 레이어로 Cloud KMS 키로 암호화된 base64 인코딩 HEC 토큰 매개변수와 함께 Cloud KMS 키를 전달할 수도 있습니다. HEC 토큰 매개변수 암호화에 대한 자세한 내용은 Cloud KMS API 암호화 엔드포인트를 참조하세요.

파이프라인 요구사항

  • 파이프라인을 실행하기 전에 소스 Pub/Sub 구독이 있어야 합니다.
  • 파이프라인을 실행하기 전에 Pub/Sub 처리되지 않은 주제가 있어야 합니다.
  • Splunk HEC 엔드포인트는 Dataflow 작업자 네트워크에서 액세스할 수 있어야 합니다.
  • Splunk HEC 토큰이 생성되고 사용 가능해야 합니다.

템플릿 매개변수

매개변수 설명
inputSubscription 입력을 읽어올 Pub/Sub 구독입니다. 예를 들면 projects/<project-id>/subscriptions/<subscription-name>입니다.
token 선택사항: Splunk HEC 인증 토큰입니다. tokenSource 매개변수가 PLAINTEXT 또는 KMS로 설정된 경우 제공해야 합니다.
url Splunk HEC URL입니다. 이 값은 파이프라인이 실행되는 VPC에서 라우팅할 수 있어야 합니다. 예를 들면 https://splunk-hec-host:8088입니다.
outputDeadletterTopic 전달할 수 없는 메시지를 전달할 Pub/Sub 주제입니다. 예를 들면 projects/<project-id>/topics/<topic-name>입니다.
javascriptTextTransformGcsPath 선택사항: 사용할 자바스크립트 사용자 정의 함수(UDF)를 정의하는 .js 파일의 Cloud Storage URI입니다. 예를 들면 gs://my-bucket/my-udfs/my_file.js입니다.
javascriptTextTransformFunctionName 선택사항: 사용할 자바스크립트 사용자 정의 함수(UDF)의 이름입니다. 예를 들어 자바스크립트 함수가 myTransform(inJson) { /*...do stuff...*/ }이면 함수 이름은 myTransform입니다. 샘플 JavaScript UDF는 UDF 예시를 참조하세요.
javascriptTextTransformReloadIntervalMinutes 선택사항: UDF를 새로고침할 빈도(분)를 지정합니다. 값이 0보다 크면 Dataflow가 Cloud Storage에서 UDF 파일을 주기적으로 검사하고 파일이 수정된 경우 UDF를 새로고침합니다. 이 매개변수를 사용하면 파이프라인이 실행 중일 때 작업을 다시 시작할 필요 없이 UDF를 업데이트할 수 있습니다. 값이 0이면 UDF 새로고침이 사용 중지됩니다. 기본값은 0입니다.
batchCount 선택사항: Splunk에 여러 이벤트를 전송하기 위한 배치 크기입니다. 기본값은 1(일괄 처리 없음)입니다.
parallelism 선택사항: 최대 동시 요청 수입니다. 기본값은 1(동시 처리 없음)입니다.
disableCertificateValidation 선택사항: SSL 인증서 유효성 검사를 사용 중지합니다. 기본값은 false(유효성 검사 사용)입니다. true인 경우 인증서가 검증되지 않고(모든 인증서를 신뢰할 수 있음) `rootCaCertificatePath` 매개변수가 무시됩니다.
includePubsubMessage 선택사항: 페이로드의 전체 Pub/Sub 메시지를 포함합니다. 기본값은 false입니다(데이터 요소만 페이로드에 포함됨).
tokenSource 토큰의 소스입니다. PLAINTEXT, KMS, SECRET_MANAGER 중 하나입니다. Secret Manager를 사용하는 경우 이 매개변수를 제공해야 합니다. tokenSource가 KMS로 설정된 경우 tokenKMSEncryptionKey 및 암호화된 token을 제공해야 합니다. tokenSource가 SECRET_MANAGER로 설정된 경우 tokenSecretId를 제공해야 합니다. tokenSource가 PLAINTEXT로 설정된 경우 token을 제공해야 합니다.
tokenKMSEncryptionKey 선택사항: HEC 토큰 문자열을 복호화할 Cloud KMS 키입니다. tokenSource가 KMS로 설정된 경우 이 매개변수를 제공해야 합니다. Cloud KMS 키가 제공되면 HEC 토큰 문자열이 암호화되어 전달되어야 합니다.
tokenSecretId 선택사항: 토큰의 Secret Manager 보안 비밀 ID입니다. tokenSource기 SECRET_MANAGER로 설정된 경우 이 매개변수를 제공해야 합니다. 다음 형식이어야 합니다. projects/<project-id>/secrets/<secret-name>/versions/<secret-version>
rootCaCertificatePath 선택사항: Cloud Storage의 루트 CA 인증서에 대한 전체 URL입니다. 예를 들면 gs://mybucket/mycerts/privateCA.crt입니다. Cloud Storage에서 제공하는 인증서는 DER로 인코딩되어야 하며 바이너리 또는 인쇄 가능한 (Base64) 인코딩으로 제공될 수 있습니다. 인증서가 Base64 인코딩으로 제공되는 경우 시작 부분에 -----BEGIN CERTIFICATE-----로 바인딩되고 마지막에 -----END CERTIFICATE-----로 바인딩되어야 합니다. 이 매개변수가 제공되면 Splunk HEC 엔드포인트의 SSL 인증서를 확인하기 위해 이 비공개 CA 인증서 파일을 가져와 Dataflow 작업자의 트러스트 저장소에 추가합니다. 이 매개변수를 제공하지 않으면 기본 트러스트 저장소가 사용됩니다.
enableBatchLogs 선택사항: Splunk에 기록된 배치에 대해 로그를 사용 설정할지 여부를 지정합니다. 기본값: true
enableGzipHttpCompression 선택사항: Splunk HEC로 전송된 HTTP 요청을 압축할지 여부를 지정합니다(gzip 콘텐츠 인코딩). 기본값: true

사용자 정의 함수

선택적으로 사용자 정의 함수(UDF)를 작성하여 이 템플릿을 확장할 수 있습니다. 템플릿이 각 입력 요소에 대해 UDF를 호출합니다. 요소 페이로드는 JSON 문자열로 직렬화됩니다. 자세한 내용은 Dataflow 템플릿에 대한 사용자 정의 함수 만들기를 참조하세요.

함수 사양

UDF의 사양은 다음과 같습니다.

  • 입력: JSON 문자열로 직렬화된 Pub/Sub 메시지 데이터 필드입니다.
  • 출력: Splunk HEC 이벤트 엔드포인트로 전송할 이벤트 데이터입니다. 출력은 문자열 또는 문자열화된 JSON 객체여야 합니다.

템플릿 실행

콘솔

  1. Dataflow 템플릿에서 작업 만들기 페이지로 이동합니다.
    2. 템플릿에서 작업 만들기로 이동
  2. 작업 이름 필드에 고유한 작업 이름을 입력합니다.
  3. (선택사항): 리전 엔드포인트의 드롭다운 메뉴에서 값을 선택합니다. 기본 리전은 us-central1입니다.

    Dataflow 작업을 실행할 수 있는 리전 목록은 Dataflow 위치를 참조하세요.

  4. Dataflow 템플릿 드롭다운 메뉴에서 the Pub/Sub to Splunk template을 선택합니다.
  5. 제공된 매개변수 필드에 매개변수 값을 입력합니다.
  6. 선택사항: 정확히 한 번 처리에서 적어도 한 번 스트리밍 모드로 전환하려면 적어도 한 번를 선택합니다.
  7. 작업 실행을 클릭합니다.

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: 사용할 템플릿 버전입니다.

    다음 값을 사용할 수 있습니다.

  • 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: 사용할 자바스크립트 사용자 정의 함수(UDF)의 이름입니다.

    예를 들어 자바스크립트 함수가 myTransform(inJson) { /*...do stuff...*/ }이면 함수 이름은 myTransform입니다. 샘플 JavaScript UDF는 UDF 예시를 참조하세요.

  • PATH_TO_JAVASCRIPT_UDF_FILE: 사용할 자바스크립트 사용자 정의 함수(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 프로젝트 ID입니다.
  • JOB_NAME: 선택한 고유한 작업 이름입니다.
  • LOCATION: Dataflow 작업을 배포할 리전입니다(예: us-central1).
  • VERSION: 사용할 템플릿 버전입니다.

    다음 값을 사용할 수 있습니다.

  • 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: 사용할 자바스크립트 사용자 정의 함수(UDF)의 이름입니다.

    예를 들어 자바스크립트 함수가 myTransform(inJson) { /*...do stuff...*/ }이면 함수 이름은 myTransform입니다. 샘플 JavaScript UDF는 UDF 예시를 참조하세요.

  • PATH_TO_JAVASCRIPT_UDF_FILE: 사용할 자바스크립트 사용자 정의 함수(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)

다음 단계