OpenSearch sink

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

OpenSearch sink

opensearch sink 플러그인을 사용해서 OpenSearch 클러스터, 레거시 Elasticsearch 클러스터, 또는 Amazon OpenSearch Service 도메인으로 데이터를 보낼 수 있어요.

이 플러그인은 OpenSearch 1.0 이상과 Elasticsearch 7.3 이상을 지원해요.

사용법

opensearch sink를 구성하려면 파이프라인 구성에서 opensearch 옵션을 지정해요.

pipeline:
  ...
  sink:
    opensearch:
      hosts: ["https://localhost:9200"]
      cert: path/to/cert
      username: YOUR_USERNAME
      password: YOUR_PASSWORD
      index_type: trace-analytics-raw
      dlq_file: /your/local/dlq-file
      max_retries: 20
      bulk_size: 4

Amazon OpenSearch Service sink를 구성하려면 다음 예시처럼 도메인 엔드포인트를 hosts 옵션으로 지정해요.

pipeline:
  ...
  sink:
    opensearch:
      hosts: ["https://your-amazon-opensearch-service-endpoint"]
      aws_sigv4: true
      cert: path/to/cert
      insecure: false
      index_type: trace-analytics-service-map
      bulk_size: 4

구성 옵션

Option	Required	Type	Description
`hosts`	Yes	List	작성할 OpenSearch 호스트 목록이에요. 예: `["https://localhost:9200", "https://remote-cluster:9200"]`.
`cert`	No	String	보안 인증서의 경로예요. 예를 들어, 클러스터가 OpenSearch Security 플러그인을 사용하는 경우 `"config/root-ca.pem"`이에요.
`username`	No	String	HTTP 기본 인증을 위한 사용자 이름이에요.
`password`	No	String	HTTP 기본 인증을 위한 비밀번호예요.
`aws`	No	AWS	AWS 구성이에요.
max_retries	No	Integer	`opensearch` 싱크가 실패로 간주하기 전에 OpenSearch 서버로 데이터를 푸시하려고 시도해야 하는 최대 횟수예요. 기본값은 `Integer.MAX_VALUE`예요. 제공되지 않으면 싱크가 OpenSearch 서버로 데이터를 무기한 푸시하려고 시도하고 지수 백오프가 재시도 전 대기 시간을 증가시켜요.
`aws_sigv4`	No	Boolean	Data Prepper 2.7에서 더 이상 사용되지 않아요. 기본값은 `false`예요. Amazon OpenSearch Service 도메인에 연결하기 위해 AWS Identity and Access Management(IAM) 서명을 사용할지 여부예요. 액세스 키, 비밀 키 및 선택적 세션 토큰의 경우 OpenSearch Data Prepper는 기본 자격 증명 체인(환경 변수, Java 시스템 속성, `~/.aws/credential`)을 사용해요.
`aws_region`	No	String	Data Prepper 2.7에서 더 이상 사용되지 않아요. Amazon OpenSearch Service에 연결할 때 도메인의 AWS 리전(예: `"us-east-1"`)이에요.
`aws_sts_role_arn`	No	String	Data Prepper 2.7에서 더 이상 사용되지 않아요. 플러그인이 Amazon OpenSearch Service로 전송된 요청에 서명하는 데 사용하는 IAM 역할이에요. 이 정보가 제공되지 않으면 플러그인은 기본 자격 증명을 사용해요.
`socket_timeout`	No	Integer	데이터가 반환될 때까지 기다리는 시간 제한 값(밀리초)이에요(두 개의 연속 데이터 패킷 사이의 최대 비활성 기간). 시간 제한 값 `0`은 무한 시간 제한으로 해석돼요. 이 시간 제한 값이 음수이거나 설정되지 않은 경우 기본 Apache HttpClient는 운영 체제 설정에 의존하여 소켓 시간 제한을 관리해요.
`connect_timeout`	No	Integer	연결 관리자에게 연결을 요청할 때 시간 제한 값(밀리초)이에요. 시간 제한 값 `0`은 무한 시간 제한으로 해석돼요. 이 시간 제한 값이 음수이거나 설정되지 않은 경우 기본 Apache HttpClient는 운영 체제 설정에 의존하여 연결 시간 제한을 관리해요.
`insecure`	No	Boolean	SSL 인증서를 확인할지 여부예요. `true`로 설정하면 인증 기관(CA) 인증서 확인이 비활성화되고 대신 안전하지 않은 HTTP 요청이 전송돼요. 기본값은 `false`예요.
`proxy`	No	String	포워드 HTTP 프록시 서버의 주소예요. 형식은 `"<hostname or IP>:<port>"`예요(예: `"example.com:8100"`, `"http://example.com:8100"`, `"112.112.112.112:8100"`). 포트 번호는 생략할 수 없어요.
`index`	Conditionally	String	내보내기 인덱스의 이름이에요. `index_type`이 `custom`인 경우에만 필요해요. 인덱스는 `my-index-name`과 같은 일반 문자열이거나, Java 날짜-시간 패턴을 포함할 수 있어요(예: `my-index-%{yyyy.MM.dd}` 또는 `my-%{yyyy-MM-dd-HH}-index`). 필드 값을 사용하여 형식을 지정할 수도 있어요(예: `my-index-${/my_field}`). 또는 Data Prepper 표현식을 사용할 수 있어요(예: `my-index-${getMetadata(\"my_metadata_field\"}`). 모든 형식 옵션을 결합하여 정적, 동적 및 롤링 인덱스를 생성할 때 유연성을 제공할 수 있어요.
`index_type`	No	String	싱크 플러그인이 처리하는 데이터 유형을 지정해요. 유효한 값은 `custom`, `trace-analytics-raw`, `trace-analytics-plain-raw`, `trace-analytics-service-map`, `log-analytics`, `log-analytics-plain`, `metric-analytics`, `metric-analytics-plain`, `management-disabled`예요. `output_format: otel`과 함께 `otel_logs_source`에서 Amazon Security Lake 호환 데이터를 생성하려면 `index_type`을 `log-analytics-plain`으로 설정해요. `output_format: otel`과 함께 `otel_metrics_source`의 경우 `index_type`을 `metric-analytics-plain`으로 설정해요. `output_format: otel`과 함께 `otel_trace_source`의 경우 `index_type`을 `trace-analytics-plain-raw`로 설정해요. 기본값은 `custom`이에요.

template_type | No | String | 사용할 OpenSearch 템플릿 유형을 정의해요. 사용 가능한 옵션은 v1과 index-template이에요. 기본값은 v1이며, _template API 엔드포인트에서 제공되는 원래 OpenSearch 템플릿을 사용해요. index-template 옵션은 OpenSearch _index_template API를 통해 사용할 수 있는 구성 가능한 인덱스 템플릿을 사용해요. 구성 가능한 인덱스 유형은 기본값보다 더 많은 유연성을 제공하며, OpenSearch 클러스터에 기존 인덱스 템플릿이 포함된 경우 필요해요. 구성 가능한 템플릿은 모든 버전의 OpenSearch와 일부 이후 버전의 Elasticsearch에서 사용할 수 있어요. distribution_version이 es6으로 설정된 경우 Data Prepper는 template_type을 v1으로 강제해요. template_file | No | String | index_type이 custom으로 설정된 경우 JSON 인덱스 템플릿 파일의 경로(예: /your/local/template-file.json)예요. 예제 템플릿 파일은 otel-v1-apm-span-index-template.json을 참조하세요. 템플릿 파일을 제공하는 경우 template_type 매개변수로 지정된 템플릿 형식과 일치해야 해요. template_content | No | JSON | 인덱스 인덱스 템플릿 내부에 있는 모든 인라인 JSON을 포함해요. 템플릿 콘텐츠의 예는 예제 템플릿 콘텐츠를 참조하세요. document_id_field | No | String | Data Prepper 2.7에서 document_id를 위해 더 이상 사용되지 않아요. index_type이 custom인 경우 OpenSearch 문서 ID에 사용할 소스 데이터의 필드(예: "my-field")예요. document_id | No | String | OpenSearch 문서에서 _id로 사용할 형식 문자열이에요. 이벤트에서 단일 필드를 지정하려면 ${/my_field}를 사용해요. Data Prepper 표현식을 사용하여 document_id를 구성할 수도 있어요(예: ${getMetadata(\"some_metadata_key\")}). 이러한 옵션은 ${/my_field}-test-${getMetadata(\"some_metadata_key\")}와 같은 더 복잡한 형식으로 결합할 수 있어요. document_version | No | String | OpenSearch 문서에서 _version으로 사용할 형식 문자열이에요. 이벤트에서 단일 필드를 지정하려면 ${/my_field}를 사용해요. Data Prepper 표현식을 사용하여 document_version을 구성할 수도 있어요(예: ${getMetadata(\"some_metadata_key\")}). 이러한 옵션은 ${/my_field}${getMetadata(\"some_metadata_key\")}와 같은 더 복잡한 버전으로 결합할 수 있어요. document_version 형식은 long 유형으로 평가되어야 하며 document_version_type이 external 또는 external_gte로 설정된 경우에만 사용할 수 있어요. document_version_type | No | String | 인덱스 작업에 대한 문서 버전 유형이에요. external, external_gte, internal 중 하나여야 해요. external 또는 external_gte로 설정된 경우 document_version이 필요해요. dlq_file | No | String | 선호하는 데드 레터 큐 파일의 경로(예: /your/local/dlq-file)예요. Data Prepper가 OpenSearch 클러스터에서 문서 인덱싱에 실패하면 이 파일에 써요. dlq | No | N/A | DLQ 구성이에요. bulk_size | No | Integer (long) | OpenSearch 클러스터로 전송되는 벌크 요청의 최대 크기(MiB)예요. 0 미만의 값은 무제한 크기를 나타내요. 단일 문서가 최대 벌크 요청 크기를 초과하면 Data Prepper가 각 요청을 개별적으로 보내요. 기본값은 5예요. ism_policy_file | No | String | ISM(Index State Management) 정책 JSON 파일의 절대 파일 경로예요. 이 정책 파일은 인덱스 유형에 대한 기본 제공 정책 파일이 없는 경우에만 적용돼요. 예를 들어 custom 인덱스 유형은 현재 기본 제공 정책 파일이 없는 유일한 유형이므로 이 매개변수를 통해 제공되면 이 정책 파일을 사용해요. 정책 JSON 파일에 대한 자세한 내용은 ISM 정책을 참조하세요. number_of_shards | No | Integer | 대상 OpenSearch 서버에서 인덱스가 가져야 할 기본 샤드 수예요. 이 매개변수는 template_file이 싱크 구성에 명시적으로 제공되거나 내장된 경우에만 적용돼요. 이 매개변수가 설정되면 인덱스 템플릿 파일의 값을 재정의해요. 자세한 내용은 인덱스 생성을 참조하세요. number_of_replicas | No | Integer | 대상 OpenSearch 서버에서 각 기본 샤드가 가져야 할 복제본 샤드 수예요. 예를 들어 기본 샤드가 4개이고 number_of_replicas를 3으로 설정하면 인덱스에는 12개의 복제본 샤드가 있어요. 이 매개변수는 template_file이 싱크 구성에 명시적으로 제공되거나 내장된 경우에만 적용돼요. 이 매개변수가 설정되면 인덱스 템플릿 파일의 값을 재정의해요. 자세한 내용은 인덱스 생성을 참조하세요. distribution_version | No | String | 싱크의 백엔드 버전이 Elasticsearch 6 이상인지 여부를 나타내요. es6는 Elasticsearch 6을 나타내요. default는 Elasticsearch 7.x, OpenSearch 1.x 또는 OpenSearch 2.x와 같은 최신 호환 백엔드 버전을 나타내요. 기본값은 default예요. enable_request_compression | No | Boolean | OpenSearch에 요청을 보낼 때 압축을 활성화할지 여부예요. distribution_version이 es6으로 설정된 경우 기본값은 false예요. 다른 모든 배포 버전의 경우 기본값은 true예요. action | No | String | 문서에 사용할 OpenSearch 벌크 액션이에요. create, index, update, upsert, delete 중 하나여야 해요. 기본값은 index예요. actions | No | List | action의 대안으로 사용할 수 있는 액션 목록이에요. 이는 이벤트에 대해 조건부로 수행할 벌크 액션을 결정하는 switch case 문으로 읽혀요. flush_timeout | No | Long | 벌크 요청을 플러시하기 전에 bulk_size까지 패킹을 시도하는 시간(밀리초)을 포함하는 long 클래스예요. 이 시간 제한이 벌크 요청이 bulk_size에 도달하기 전에 만료되면 요청이 플러시돼요. -1로 설정하면 플러시 시간 제한을 비활성화하고 각 배치 끝에 있는 내용을 플러시해요. 기본값은 60,000(1분)이에요. normalize_index | No | Boolean | true인 경우 OpenSearch 싱크가 동적 인덱스 이름을 생성하려고 시도해요. ${})에 지정된 형식 옵션이 있는 인덱스 이름은 인덱스 명명 제한에 따라 유효해요. 잘못된 문자는 제거돼요. 기본값은 false예요. routing | No | String | OpenSearch에 문서를 저장할 때 문서의 shard_id를 생성하기 위한 해시로 사용되는 문자열이에요. 각 수신 레코드가 검색돼요. 있는 경우 문자열이 문서의 라우팅 필드로 사용돼요. 없는 경우 OpenSearch는 문서를 저장할 때 기본 라우팅 메커니즘(document_id)을 사용해요. 이벤트의 필드 및 Data Prepper 표현식을 사용한 형식 지정을 지원해요(예: ${/my_field}-test-${getMetadata(\"some_metadata_key\")}). document_root_key | No | String | 이벤트에서 문서의 루트로 사용될 키예요. 기본값은 이벤트의 루트예요. 키가 존재하지 않으면 전체 이벤트가 문서로 작성돼요. document_root_key가 문자열이나 정수와 같은 기본 값 유형인 경우 문서는 {"data": <document_root_key의 값>} 구조를 가져요. serverless | No | Boolean | Data Prepper 2.7에서 더 이상 사용되지 않아요. 대신 aws 구성과 함께 이 옵션을 사용하세요. OpenSearch 백엔드가 Amazon OpenSearch Serverless인지 여부를 결정해요. opensearch 싱크의 대상이 Amazon OpenSearch Serverless 컬렉션인 경우 이 값을 true로 설정해요. 기본값은 false예요. serverless_options | No | Object | Data Prepper 2.7에서 더 이상 사용되지 않아요. 대신 aws 구성과 함께 이 옵션을 사용하세요. opensearch 싱크의 백엔드가 Amazon OpenSearch Serverless로 설정된 경우 사용 가능한 네트워크 구성 옵션이에요. 자세한 내용은 Serverless 옵션을 참조하세요. query_lookup | No | Object | 중복을 방지하기 위해 인덱싱 전에 기존 문서를 쿼리하기 위한 구성이에요. 자세한 내용은 쿼리 조회를 참조하세요.

Query lookup

query_lookup 구성은 새 문서를 인덱싱하기 전에 OpenSearch에서 기존 문서를 조회하여 중복을 제거해요. 이 기능은 두 가지 시나리오에서 중복을 방지하는 데 도움이 돼요.

조건부 조회: 인덱싱하기 전에 조건에 따라 문서를 조회해요.
오류 기반 조회: 소켓 타임아웃이나 500 내부 서버 오류와 같이 부분 성공을 초래할 수 있는 벌크 작업 오류가 발생하면 문서를 조회해요.

Query lookup 옵션

query_lookup 객체는 다음 옵션을 지원해요.

옵션	필수	유형	설명
`query_when`	아니요	String	인덱싱 전에 조회할 문서를 결정하는 Data Prepper 표현식이에요. 예를 들어, `getMetadata("potential_duplicate") == true`는 해당 메타데이터 필드가 `true`로 설정된 문서만 조회해요.
`query_term`	예	String	OpenSearch에서 기존 문서를 조회하는 데 사용할 문서의 고유 필드예요. 일반적으로 ID 필드예요.
`query_on_bulk_errors`	아니요	Boolean	`true`로 설정하면 복구 가능한 벌크 작업 오류(예: 소켓 타임아웃 또는 500 오류)가 발생한 문서를 즉시 재시도하지 않고 조회해요. 초기 인덱싱 요청이 부분적으로 성공했을 때 중복을 방지하는 데 도움이 돼요. 기본값은 `false`예요.
`query_duration`	아니요	Duration	문서를 인덱싱하기 전에 조회할 시간이에요. ISO 8601 기간 형식을 사용하며, 예를 들어 5분은 `PT5M`으로 표시해요. 기본값은 `PT5M`이에요.
`async_limit`	아니요	Integer	프로세서 작업자 스레드를 차단하기 전에 동시에 조회할 수 있는 최대 문서 수예요. 기본값은 `5000`이에요.

Query lookup 예제

다음 예제 구성은 인덱싱 전에 potential_duplicate 메타데이터 필드가 있는 문서를 조회해요.

pipeline:
  ...
  sink:
    opensearch:
      hosts: ["https://localhost:9200"]
      username: YOUR_USERNAME
      password: YOUR_PASSWORD
      index: my-index
      query_lookup:
        query_when: 'getMetadata("potential_duplicate") == true'
        query_term: 'document_id'
        query_on_bulk_errors: true
        query_duration: PT5M
        async_limit: 5000

이 구성에서:

potential_duplicate 메타데이터가 true로 설정된 문서는 인덱싱 전에 조회돼요.
document_id 필드는 조회를 위한 고유 식별자로 사용돼요.
벌크 작업에서 소켓 타임아웃이나 500 오류와 같은 오류가 발생하면 영향을 받은 문서를 즉시 재시도하지 않고 조회해요.
문서는 인덱싱되기 전에 최대 5분 동안 조회돼요.
최대 5,000개의 문서를 동시에 조회할 수 있어요.

문서가 이미 OpenSearch에 존재하면 해당 문서는 삭제되고 이벤트 핸들이 해제되어 중복을 방지해요.

aws

옵션	필수	유형	설명
`region`	아니요	String	자격 증명에 사용할 AWS 리전이에요. 기본값은 리전을 결정하는 표준 SDK 동작을 따라요.
`sts_role_arn`	아니요	String	Amazon SQS 및 Amazon S3 요청에 수임할 AWS Security Token Service(AWS STS) 역할이에요. 기본값은 `null`이며, 자격 증명에 대한 표준 SDK 동작을 사용해요.
`sts_header_overrides`	아니요	Map	싱크 플러그인을 위해 IAM 역할이 수임하는 헤더 재정의 맵이에요.
`sts_external_id`	아니요	String	AWS STS의 AssumeRole 요청에 첨부할 외부 ID예요.
`serverless`	아니요	Boolean	OpenSearch 백엔드가 Amazon OpenSearch Serverless인지 여부를 결정해요. `opensearch` 싱크의 대상이 Amazon OpenSearch Serverless 컬렉션인 경우 이 값을 `true`로 설정해요. 기본값은 `false`예요.
`serverless_options`	아니요	Object	`opensearch` 싱크의 백엔드가 Amazon OpenSearch Serverless로 설정된 경우 사용 가능한 네트워크 구성 옵션이에요. 자세한 내용은 Serverless 옵션을 참조해요.

actions

actions 옵션 내에서 다음 옵션을 사용할 수 있어요.

옵션	필수	유형	설명
`type`	예	String	`when` 조건이 true로 평가될 때 사용할 벌크 작업 유형이에요. `create`, `index`, `update`, `upsert`, `delete` 중 하나여야 해요.
`when`	아니요	String	이벤트가 `type`에 구성된 벌크 작업을 사용하여 OpenSearch로 전송될지 여부를 조건부로 평가하는 Data Prepper 표현식이에요. 비어 있으면 이벤트가 OpenSearch로 전송될 때 벌크 작업이 자동으로 선택돼요.

Serverless 옵션

serverless_options 객체에서 다음 옵션을 사용할 수 있어요.

옵션	필수	유형	설명
`network_policy_name`	예	String	생성할 네트워크 정책의 이름이에요.
`collection_name`	예	String	구성할 Amazon OpenSearch Serverless 컬렉션의 이름이에요.
`vpce_id`	예	String	소스가 연결되는 VPC 엔드포인트예요.

max_retries 구성

파이프라인 구성에 max_retries 옵션을 포함하여 소스가 지수 백오프를 사용하여 싱크에 쓰기를 시도하는 횟수를 제어할 수 있어요. 이 옵션을 포함하지 않으면 파이프라인이 계속 재시도해요.

max_retries를 지정하고 파이프라인에 데드 레터 큐(DLQ)가 구성된 경우, 파이프라인은 최대 재시도 횟수에 도달할 때까지 싱크에 쓰기를 계속 시도하고, 그 시점부터 실패한 데이터를 DLQ로 보내기 시작해요.

max_retries를 지정하지 않으면 싱크에서 거부된 데이터만 DLQ에 기록돼요. 파이프라인은 다른 모든 데이터를 싱크에 계속 쓰려고 시도해요.

승인을 사용한 오류 처리

파이프라인에서 엔드 투 엔드 승인이 활성화된 경우, 오류 처리는 두 가지 주요 구성에 의해 제어돼요.

DLQ 구성(강력 권장)

OpenSearch 싱크는 다음 경우에만 이벤트를 승인해요.

OpenSearch로 성공적으로 전송된 경우.
DLQ로 성공적으로 전송된 경우.

DLQ가 구성되지 않은 경우:

실패한 이벤트는 승인되지 않은 상태로 남아요.
소스가 재시도를 처리해야 해요.
재시도 불가능한 오류에 대해 무한 재처리 위험이 있어요.

예제: 승인이 있는 S3 소스

승인이 활성화된 S3 소스를 고려해보세요.

DLQ 없음:

단일 실패 이벤트로 인해 전체 S3 객체의 승인이 차단돼요.
전체 S3 객체를 다시 처리해야 해요.
재시도 불가능한 오류는 무한 재처리("포이즌 필")를 유발할 수 있어요.

max_retries는 있지만 DLQ 없음:

max_retries에 도달해도 여전히 승인이 차단돼요.
전체 S3 객체의 불필요한 재처리가 발생해요.

모범 사례---승인을 사용할 때는 항상 DLQ를 구성하여:

무한 재처리를 방지해요.
재시도 불가능한 오류를 적절히 처리해요.
불필요한 재처리를 최소화해요.

OpenSearch 클러스터 보안

opensearch 싱크 플러그인을 사용하여 OpenSearch 클러스터로 데이터를 보내려면 파이프라인 구성에 사용자 이름과 비밀번호를 지정해야 해요. 다음 예제 pipelines.yaml 파일은 관리자 보안 자격 증명을 지정하는 방법을 보여줘요.

sink:
  - opensearch:
      username: "admin"
      password: "admin"
      ...

또는 관리자 자격 증명 대신 다음 섹션에 나열된 최소 권한이 있는 역할에 매핑된 사용자의 자격 증명을 지정할 수 있어요.

클러스터 권한

cluster_all
indices:admin/template/get
indices:admin/template/put

대상이 OpenSearch 데이터 스트림인 경우 데이터 스트림 감지기에 다음 권한이 필요해요.

indices:admin/data_stream/get

인덱스 권한

인덱스: otel-v1*; 인덱스 권한: indices_all
인덱스: .opendistro-ism-config; 인덱스 권한: indices_all
인덱스: *; 인덱스 권한: manage_aliases

사용자를 역할에 매핑하는 방법에 대한 지침은 사용자를 역할에 매핑을 참조해요.

Amazon OpenSearch Service 도메인 보안

opensearch 싱크 플러그인은 IAM을 보안에 사용하는 Amazon OpenSearch Service 도메인으로 데이터를 보낼 수 있어요. 플러그인은 기본 자격 증명 체인을 사용해요. AWS Command Line Interface(AWS CLI)를 사용하여 aws configure를 실행하여 자격 증명을 설정해요.

구성하는 자격 증명에 필요한 IAM 권한이 있는지 확인해요. 다음 도메인 액세스 정책은 최소 필수 권한을 보여줘요.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AccountId>:user/data-prepper-user"
      },
      "Action": "es:ESHttp*",
      "Resource": [
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/otel-v1*",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_template/otel-v1*",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_plugins/_ism/policies/raw-span-policy",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_alias/otel-v1*",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_alias/_bulk"
      ]
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AccountId>:user/data-prepper-user"
      },
      "Action": "es:ESHttpGet",
      "Resource": "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_cluster/settings"
    }
  ]
}

도메인 액세스 정책 구성 방법에 대한 지침은 Amazon OpenSearch Service 설명서의 리소스 기반 정책을 참조해요.

세분화된 액세스 제어

OpenSearch Service 도메인이 세분화된 액세스 제어를 사용하는 경우 opensearch 싱크 플러그인에 몇 가지 추가 구성이 필요해요.

IAM ARN을 마스터 사용자로 사용

IAM Amazon Resource Name(ARN)을 마스터 사용자로 사용하는 경우 싱크 구성에 aws_sigv4 옵션을 포함해요.

...
sink:
    opensearch:
      hosts: ["https://your-fgac-amazon-opensearch-service-endpoint"]
      aws_sigv4: true

AWS CLI를 사용하여 aws configure를 실행하여 마스터 IAM 사용자 자격 증명을 사용해요. 마스터 사용자를 사용하지 않으려면 aws_sts_role_arn 옵션을 사용하여 다른 IAM 역할을 지정할 수 있어요. 그러면 플러그인이 이 역할을 사용하여 도메인 싱크로 전송되는 요청에 서명해요. 지정하는 ARN은 도메인 액세스 정책에 포함되어야 해요.

내부 사용자 데이터베이스의 마스터 사용자

도메인이 내부 사용자 데이터베이스의 마스터 사용자를 사용하는 경우 마스터 사용자 이름과 비밀번호 및 aws_sigv4 옵션을 지정해요.

sink:
    opensearch:
      hosts: ["https://your-fgac-amazon-opensearch-service-endpoint"]
      username: "master-username"
      password: "master-password"

자세한 내용은 Amazon OpenSearch Service 설명서의 권장 구성을 참조해요.

참고: all_access 권한이 있는 새 IAM 역할 또는 내부 사용자 데이터베이스 사용자를 생성하여 마스터 사용자 대신 사용할 수 있어요.

OpenSearch Serverless 컬렉션 보안

opensearch 싱크 플러그인은 Amazon OpenSearch Serverless 컬렉션으로 데이터를 보낼 수 있어요.

OpenSearch Serverless 컬렉션 싱크에는 다음과 같은 제한 사항이 있어요.

VPC 액세스를 사용하는 컬렉션에는 쓸 수 없어요. 컬렉션은 퍼블릭 네트워크에서 액세스할 수 있어야 해요.
OTel trace group 프로세서는 현재 컬렉션 싱크를 지원하지 않아요.

파이프라인 역할 생성

먼저 파이프라인이 컬렉션에 쓰기 위해 수임할 IAM 역할을 생성해요. 역할에는 다음과 같은 최소 권한이 있어야 해요.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "aoss:BatchGetCollection"
            ],
            "Resource": "*"
        }
    ]
}

역할에는 파이프라인이 수임할 수 있도록 하는 다음과 같은 신뢰 관계가 있어야 해요.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AccountId>:root"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

컬렉션 생성

다음으로, 다음 설정으로 컬렉션을 생성해요.

OpenSearch 엔드포인트와 OpenSearch Dashboards 모두에 대한 퍼블릭 네트워크 액세스.

파이프라인 역할에 필요한 권한을 부여하는 다음 데이터 액세스 정책:

[
 {
    "Rules":[
       {
          "Resource":[
             "index/collection-name/*"
          ],
          "Permission":[
             "aoss:CreateIndex",
             "aoss:UpdateIndex",
             "aoss:DescribeIndex",
             "aoss:WriteDocument"
          ],
          "ResourceType":"index"
       }
    ],
    "Principal":[
       "arn:aws:iam::<AccountId>:role/PipelineRole"
    ],
    "Description":"Pipeline role access"
 }
]

중요: Principal 요소의 ARN을 이전 단계에서 생성한 파이프라인 역할의 ARN으로 바꾸는 것을 잊지 마세요.

컬렉션 생성 방법에 대한 지침은 Amazon OpenSearch Service 설명서의 컬렉션 생성을 참조해요.

파이프라인 생성

pipelines.yaml 파일에서 OpenSearch Serverless 컬렉션 엔드포인트를 hosts 옵션으로 지정해요. 또한 serverless 옵션을 true로 설정해야 해요. sts_role_arn 옵션에 파이프라인 역할을 지정해요.

log-pipeline:
  source:
    http:
  processor:
    - date:
        from_time_received: true
        destination: "@timestamp"
  sink:
    - opensearch:
        hosts: [ "https://<serverless-public-collection-endpoint>" ]
        index: "my-serverless-index"
        aws:
          serverless: true
          sts_role_arn: "arn:aws:iam::<AccountId>:role/PipelineRole"
          region: "us-east-1"

template_content 및 actions 예제

다음 예제 파이프라인에는 template_content와 조건부 actions 목록이 모두 포함되어 있어요.

log-pipeline:
  source:
    http:
  processor:
    - date:
        from_time_received: true
        destination: "@timestamp"
  sink:
    - opensearch:
        hosts: [ "https://<serverless-public-collection-endpoint>" ]
        index: "my-serverless-index"
        template_type: index-template
        template_content: >
          {
            "template" : {
              "mappings" : {
                "properties" : {
                  "Data" : {
                    "type" : "binary"
                  },
                  "EncodedColors" : {
                    "type" : "binary"
                  },
                  "Type" : {
                    "type" : "keyword"
                  },
                  "LargeDouble" : {
                    "type" : "double"
                  }          
                }
              }
            }
          }
        # index is the default case  
        actions:
         - type: "delete"
           when: '/operation == "delete"'
         - type: "update"
           when: '/operation == "update"'
         - type: "index"
        aws:
          sts_role_arn: "arn:aws:iam::<AccountId>:role/PipelineRole"
          region: "us-east-1"

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/data-prepper/pipelines/configuration/sinks/opensearch/

OpenSearch sink

본문

OpenSearch sink

사용법

구성 옵션

Query lookup

Query lookup 옵션

Query lookup 예제

aws

actions

Serverless 옵션

max_retries 구성

승인을 사용한 오류 처리

DLQ 구성(강력 권장)

예제: 승인이 있는 S3 소스

OpenSearch 클러스터 보안

클러스터 권한

인덱스 권한

Amazon OpenSearch Service 도메인 보안

세분화된 액세스 제어

IAM ARN을 마스터 사용자로 사용

내부 사용자 데이터베이스의 마스터 사용자

OpenSearch Serverless 컬렉션 보안

파이프라인 역할 생성

컬렉션 생성

파이프라인 생성

template_content 및 actions 예제

더 알아보기 (Learn more)

함께 읽는 실무 이야기