기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon OpenSearch Ingestion 개요
Amazon OpenSearch Ingestion은 Amazon OpenSearch Service 도메인과 OpenSearch Serverless 컬렉션에 실시간 로그, 지표 및 트레이스 데이터를 스트리밍하는 완전관리형 서버리스 데이터 수집기입니다.
이제 OpenSearch Ingestion을 사용하면 Logstash 또는 Jaeger와 같은 서드 파티 도구 없이도 데이터를 수집할 수 있습니다. 데이터 생산자를 구성하면 데이터를 OpenSearch Ingestion으로 전송하고, 사용자가 지정한 컬렉션에 해당 데이터를 자동으로 전송합니다. 전송 전에 데이터를 변환할 수도 있습니다.
OpenSearch Ingestion은 서버리스 방식이므로 인프라를 관리하거나 소프트웨어를 패치하거나 클러스터를 수동으로 확장할 필요가 없습니다. AWS Management Console에서 직접 수집 파이프라인을 프로비저닝할 수 있으며 OpenSearch Ingestion이 나머지를 처리합니다.
Amazon OpenSearch Service의 구성 요소인 OpenSearch Ingestion은 다운스트림 분석 및 시각화를 위해 데이터를 필터링, 보강, 변환, 정규화, 집계하는 오픈 소스 데이터 수집기인 Data Prepper로 구동됩니다.
![\[OpenSearch Ingestion pipelines showing data flow from sources to Amazon OpenSearch Service domains.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/Ingestion.png)
# Amazon OpenSearch Ingestion의 주요 개념
OpenSearch Ingestion 사용을 시작하기 전에 이러한 주요 개념을 이해하는 것이 좋습니다.
**파이프라인**
OpenSearch Ingestion 관점에서 볼 때 *파이프라인*은 OpenSearch Service 내에서 사용자가 생성하는 프로비저닝된 단일 데이터 수집기를 말합니다. 이는 하나 이상의 하위 파이프라인이 포함된 전체 YAML 구성 파일이라고 생각하면 됩니다. 수집 파이프라인을 만드는 단계는 [파이프라인 생성](creating-pipeline.md#create-pipeline)을 참조하세요.
**하위 파이프라인**
YAML 구성 파일 *내에서* 하위 파이프라인을 정의합니다. 각 하위 파이프라인은 소스, 버퍼, 0개 이상의 프로세서, 1개 이상의 싱크의 조합입니다. YAML 파일 하나에 각각 고유한 소스, 프로세서, 싱크가 있는 여러 개의 하위 파이프라인을 정의할 수 있습니다. CloudWatch 및 기타 서비스를 통한 모니터링을 지원하려면 모든 하위 파이프라인과 구별되는 파이프라인 이름을 지정하는 것이 좋습니다.
단일 YAML 파일 내에 여러 하위 파이프라인을 함께 문자화하여 한 하위 파이프라인의 소스가 다른 하위 파이프라인이고 해당 싱크가 세 번째 하위 파이프라인이 되도록 할 수 있습니다. 예제는 [OpenTelemetry Collector와 함께 OpenSearch Ingestion 파이프라인 사용](configure-client-otel.md) 섹션을 참조하세요.
**소스**
하위 파이프라인의 입력 구성 요소입니다. 파이프라인이 레코드를 소비하는 메커니즘을 정의합니다. 소스는 HTTPS를 통해 이벤트를 수신하거나 Amazon S3와 같은 외부 엔드포인트에서 읽어 이벤트를 소비할 수 있습니다. 소스에는 *푸시 기반*과 *풀 기반*의 두 가지 유형이 있습니다. [HTTP](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/http-source/) 및 [OTel 로그](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-logs-source/)와 같은 푸시 기반 소스는 레코드를 수집 엔드포인트로 스트리밍합니다. [OTel 추적](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-trace/) 및 [S3](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/s3/)와 같은 풀 기반 소스는 소스에서 데이터를 가져옵니다.
**Processors**
레코드를 싱크에 게시하기 전에 원하는 형식으로 필터링, 변환 및 보강할 수 있는 중간 처리 장치입니다. 프로세서는 파이프라인의 선택적 구성 요소입니다. 프로세서를 정의하지 않으면 소스에 정의된 형식으로 레코드가 게시됩니다. 프로세서가 하나 이상 있을 수 있습니다. 파이프라인은 사용자가 정의한 순서대로 프로세서를 실행합니다.
**Sink**
하위 파이프라인의 출력 구성 요소입니다. 하위 파이프라인이 레코드를 게시하는 하나 이상의 대상을 정의합니다. OpenSearch Ingestion은 OpenSearch Service 도메인을 싱크로 지원합니다. 또한 하위 파이프라인을 싱크로 지원합니다. 즉, 단일 OpenSearch Ingestion 파이프라인(YAML 파일) 내에서 여러 하위 파이프라인을 하나로 묶을 수 있습니다. 자체 관리형 OpenSearch 클러스터는 싱크로 지원되지 않습니다.
**Buffer**
소스와 싱크 사이의 계층 역할을 하는 프로세서의 일부입니다. 파이프라인 내에서 수동으로 버퍼를 구성할 수 없습니다. OpenSearch Ingestion은 기본 버퍼 구성을 사용합니다.
**경로**
파이프라인 작성자가 특정 조건에 맞는 이벤트만 다른 싱크로 전송할 수 있도록 하는 프로세서의 일부입니다.
유효한 하위 파이프라인 정의에는 소스와 싱크가 포함되어야 합니다. 각 파이프라인 요소에 대한 자세한 내용은 [구성 참조](pipeline-config-reference.md#ingestion-parameters)를 참조하세요.
## Amazon OpenSearch Ingestion의 이점
OpenSearch Ingestion에는 다음과 같은 주요 이점이 있습니다.
+ 자체 프로비저닝된 파이프라인을 수동으로 관리할 필요가 없습니다.
+ 정의한 용량 한도에 따라 파이프라인을 자동으로 확장합니다.
+ 보안 및 버그 패치를 통해 파이프라인을 최신 상태로 유지합니다.
+ 추가 보안 계층을 위해 파이프라인을 Virtual Private Cloud(VPC)에 연결하는 옵션을 제공합니다.
+ 파이프라인을 중지하고 시작하여 비용을 제어할 수 있습니다.
+ 자주 사용되는 사용 사례에 대한 파이프라인 구성 청사진을 제공하여 더 빠르게 시작하고 실행할 수 있도록 지원합니다.
+ 다양한 AWS SDKs 및 OpenSearch Ingestion API를 통해 프로그래밍 방식으로 파이프라인과 상호 작용할 수 있습니다.
+ Amazon CloudWatch의 성능 모니터링과 CloudWatch Logs의 오류 로깅을 지원합니다.
# Amazon OpenSearch Ingestion의 제한 사항
OpenSearch Ingestion에는 다음과 같은 제한 사항이 있습니다.
+ OpenSearch 1.0 이상 또는 Elasticsearch 6.8 이상을 실행하는 도메인으로만 데이터를 수집할 수 있습니다. [OTel 추적](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-trace/) 소스를 사용하는 경우 [OpenSearch 대시보드 플러그인 ](https://opensearch.org/docs/latest/observability-plugin/trace/ta-dashboards/)을 사용할 수 있도록 Elasticsearch 7.9 이상을 사용하는 것이 좋습니다.
+ 파이프라인이 VPC 내에 있는 OpenSearch Service 도메인에 쓰는 경우 파이프라인은 도메인 AWS 리전 과 동일한에서 생성되어야 합니다.
+ 파이프라인 정의 내에서 단일 데이터 소스만 구성할 수 있습니다.
+ [자체 관리형 OpenSearch 클러스터](https://opensearch.org/docs/latest/about/#clusters-and-nodes)를 싱크로 지정할 수 없습니다.
+ [사용자 지정 엔드포인트](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/customendpoint.html)를 싱크로 지정할 수 없습니다. 사용자 지정 엔드포인트가 활성화된 도메인에도 계속해서 쓸 수 있지만 표준 엔드포인트를 지정해야 합니다.
+ [옵트인 리전](https://docs.aws.amazon.com//controltower/latest/userguide/opt-in-region-considerations.html) 내의 리소스를 소스 또는 싱크로 지정할 수 없습니다.
+ 파이프라인 구성에 포함할 수 있는 파라미터에는 몇 가지 제약이 있습니다. 자세한 내용은 [구성 요구 사항 및 제약 조건](pipeline-config-reference.md#ingestion-parameters) 단원을 참조하십시오.
## 지원되는 Data Prepper 버전
OpenSearch Ingestion은 현재 다음과 같은 메이저 버전의 Data Prepper를 지원합니다.
+ 2.x
Code Editor로 파이프라인을 생성할 때 필요한 `version` 옵션을 사용하여 사용할 Data Prepper의 메이저 버전을 지정하세요. 예를 들어 `version: "2"`입니다. OpenSearch Ingestion은 해당 메이저 버전의 지원되는 최신 *마이너* 버전을 검색하고 해당 버전으로 파이프라인을 프로비저닝합니다.
Code Editor를 사용하여 파이프라인을 생성하지 않으면 OpenSearch Ingestion은 지원되는 최신 버전으로 파이프라인을 자동으로 프로비저닝합니다.
현재 OpenSearch Ingestion은 Data Prepper 버전 2.7로 파이프라인을 프로비저닝합니다. 자세한 내용은 [2.7 release notes](https://github.com/opensearch-project/data-prepper/releases/tag/2.7.0)를 참조하세요. OpenSearch Ingestion이 특정 메이저 버전의 모든 마이너 버전을 지원하는 것은 아닙니다.
파이프라인의 구성을 업데이트할 때 Data Prepper의 새로운 마이너 버전에 대한 지원이 있는 경우 OpenSearch Ingestion은 파이프라인을 파이프라인 구성에 지정된 메이저 버전에서 지원되는 최신 마이너 버전으로 자동 업그레이드합니다. 예를 들어, 파이프라인 구성에 `version: "2"`이 있고 OpenSearch Ingestion이 처음에 파이프라인을 버전 2.6.0으로 프로비저닝했을 수 있습니다. 버전 2.7.0에 대한 지원이 추가되고 파이프라인 구성을 변경하면 OpenSearch Ingestion은 파이프라인을 버전 2.7.0으로 업그레이드합니다. 이 프로세스를 통해 최신 버그를 수정하고 성능을 개선하여 파이프라인을 최신 상태로 유지할 수 있습니다. OpenSearch Ingestion은 파이프라인 구성 내에서 `version` 옵션을 수동으로 변경하지 않는 한 파이프라인의 메이저 버전을 업데이트할 수 없습니다. 자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인 업데이트](update-pipeline.md) 단원을 참조하십시오.
# Amazon OpenSearch Ingestion에서 파이프라인 규모 조정
OpenSearch Ingestion은 사용자가 지정한 최소 및 최대 Ingestion OpenSearch Compute Units(수집 OCU)를 기반으로 파이프라인 용량을 자동으로 조정합니다. 따라서 수동으로 프로비저닝 및 관리할 필요가 없습니다.
각 Ingestion OCU는 약 15GiB의 메모리와 2개의 vCPUs. 파이프라인의 최소 및 최대 OCU 값을 지정할 수 있으며, OpenSearch Ingestion은 이러한 제한에 따라 파이프라인 용량을 자동으로 조정합니다.
파이프라인을 생성할 때 다음 값을 지정합니다.
+ **최소 용량** - 파이프라인은 이 Ingestion OCU 수만큼 용량을 줄일 수 있습니다. 지정된 최소 용량은 파이프라인의 시작 용량이기도 합니다.
+ **최대 용량** - 파이프라인은 이 Ingestion OCU 수만큼 용량을 늘릴 수 있습니다.
![\[Edit capacity interface for pipeline capacity with min and max OCU settings.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/pipeline-scaling.png)
파이프라인의 최대 용량이 워크로드의 급증을 처리할 수 있을 만큼 충분히 높고, 최소 용량이 파이프라인의 사용량이 많지 않을 때 비용을 최소화할 수 있을 만큼 낮추세요. 설정에 따라 OpenSearch Ingestion은 파이프라인이 수집 워크로드를 처리하기 위해 Ingestion OCU 수를 자동으로 조정합니다. 특정 시간에 파이프라인에서 활발하게 사용 중인 Ingestion OCU에 대해서만 비용이 청구됩니다.
OpenSearch Ingestion 파이프라인에 할당된 용량은 파이프라인의 처리 요구 사항 및 클라이언트 애플리케이션에서 생성된 로드에 따라 확장 및 축소됩니다. 용량이 제한된 경우 OpenSearch Ingestion은 더 많은 컴퓨팅 유닛(GiB 메모리)을 할당하여 규모를 확장합니다. 파이프라인이 더 작은 워크로드를 처리하거나 데이터를 전혀 처리하지 않는 경우에는 구성된 최소 Ingestion OCU로 스케일 다운할 수있습니다.
상태 비저장 파이프라인에는 최소 1개의 Ingestion OCU와 최대 96개의 Ingestion OCU를, 상태 저장 파이프라인에는 최대 48개의 Ingestion OCU를 지정할 수 있습니다. 푸시 기반 소스의 경우 최소 2개 이상의 Ingestion OCU를 사용하는 것이 좋습니다. 영구 버퍼링이 활성화된 경우 최소 2개에서 최대 384개의 Ingestion OCU를 지정할 수 있습니다.
단일 소스, 간단한 Grok 패턴, 싱크가 있는 표준 로그 파이프라인의 경우 각 컴퓨팅 유닛은 초당 최대 2MiB를 지원할 수 있습니다. 프로세서가 여러 개 있는 더 복잡한 로그 파이프라인의 경우 각 컴퓨팅 유닛이 더 적은 수집 부하를 지원할 수 있습니다. 파이프라인 용량과 리소스 사용률을 기반으로 OpenSearch Ingestion 규모 조정 프로세스가 시작됩니다.
고가용성을 보장하기 위해 Ingestion OCU는 가용 영역(AZ)에 분산됩니다. AZ 수는 지정한 최소 용량에 따라 달라집니다.
예를 들어 최소 2개의 컴퓨팅 유닛을 지정하는 경우 특정 시점에 사용 중인 Ingestion OCU가 2개의 AZ에 균등하게 분배됩니다. 최소 3개 이상의 컴퓨팅 유닛을 지정하는 경우 Ingestion OCU는 3개의 AZ에 균등하게 분배됩니다. 수집 파이프라인의 99.9% 가용성을 보장하려면 *최소 2개의 이상의* Ingestion OCU를 프로비저닝하는 것이 좋습니다.
파이프라인이 `Create failed`, `Creating`, `Deleting`, 및 `Stopped` 상태일 때는 Ingestion OCU에 대한 요금이 청구되지 않습니다.
파이프라인의 용량 설정을 구성하고 검색하는 방법에 대한 지침은 [파이프라인 생성](creating-pipeline.md#create-pipeline)을 참조하세요.
## OpenSearch Ingestion 가격
특정 시기에는 파이프라인에 할당된 Ingestion OCU 수에 대해서만 비용을 지불합니다. 단, 파이프라인을 통한 데이터 흐름 여부와 상관없습니다. OpenSearch Ingestion은 사용량에 따라 파이프라인 용량을 늘리거나 줄여 워크로드를 즉시 수용합니다.
자세한 내용은 [Amazon OpenSearch Service 요금](https://aws.amazon.com/opensearch-service/pricing/)을 참조하세요.
## 지원됨 AWS 리전
OpenSearch Ingestion은 OpenSearch Service를 사용할 수 AWS 리전 있는의 하위 집합에서 사용할 수 있습니다. 지원되는 리전 목록은 *AWS 일반 참조*의 [Amazon OpenSearch Service 엔드포인트 및 할당량](https://docs.aws.amazon.com/general/latest/gr/opensearch-service.html)을 참조하세요.
# Amazon OpenSearch Ingestion 내 역할 및 사용자 설정
Amazon OpenSearch Ingestion은 소스 애플리케이션이 파이프라인에 쓸 수 있도록 허용하고 파이프라인이 싱크에 쓸 수 있도록 허용하기 위해 다양한 권한 모델과 IAM 역할을 사용합니다. 데이터 수집을 시작하려면 먼저 사용 사례에 따라 특정 권한을 가진 하나 이상의 IAM 역할을 생성해야 합니다.
성공적인 파이프라인을 설정하려면 최소한 다음과 같은 역할이 필요합니다.
| 이름 | 설명 |
| --- | --- |
| [**파이프라인 역할**](#pipeline-security-sink) | 파이프라인 역할은 파이프라인이 소스에서 읽고 도메인 또는 컬렉션 싱크에 쓰는 데 필요한 권한을 제공합니다. 파이프라인 역할을 수동으로 생성하거나, OpenSearch Ingestion에서 자동으로 생성되도록 할 수 있습니다. |
| [**수집 역할**](#pipeline-security-same-account) | 수집 역할에는 파이프라인 리소스에 대한 `osis:Ingest` 권한이 포함됩니다. 이 권한을 사용하면 푸시 기반 소스가 데이터를 파이프라인으로 수집할 수 있습니다. |
다음 이미지는 Amazon S3 또는 Fluent Bit와 같은 데이터 소스가 다른 계정의 파이프라인에 쓰는 일반적인 파이프라인 설정을 보여줍니다. 이 경우 클라이언트가 수집 역할을 맡아야 파이프라인에 액세스할 수 있습니다. 자세한 내용은 [계정 간 수집](#pipeline-security-different-account) 단원을 참조하십시오.
![\[Cross-account data ingestion pipeline showing client application, roles, and OpenSearch sink.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/pipeline-security.png)
간단한 설정 안내서는 [튜토리얼: Amazon OpenSearch Ingestion을 사용하여 도메인에 데이터 수집](osis-get-started.md)을 참조하세요.
**주제**
+ [파이프라인 역할](#pipeline-security-sink)
+ [수집 역할](#pipeline-security-same-account)
+ [계정 간 수집](#pipeline-security-different-account)
## 파이프라인 역할
파이프라인이 소스에서 읽고 싱크에 쓰려면 특정 권한이 필요합니다. 이러한 권한은 클라이언트 애플리케이션 또는 파이프라인에 쓰 AWS 서비스 는 , 싱크가 OpenSearch Service 도메인인지, OpenSearch Serverless 컬렉션인지 또는 Amazon S3인지에 따라 달라집니다. 또한 파이프라인에는 소스 애플리케이션에서 물리적으로 *가져올* 권한(소스가 풀 기반 플러그인인 경우)과 S3 DLQ(Dead Letter Queue)에 쓸 수 있는 권한(활성화된 경우)이 필요할 수 있습니다.
파이프라인을 생성할 때 수동으로 생성한 기존 IAM 역할을 지정하거나, OpenSearch Ingestion에서 소스 및 선택한 싱크에 따라 파이프라인 역할이 자동으로 생성되도록 할 수 있습니다. 다음 이미지는 AWS Management Console에서 파이프라인 역할을 지정하는 방법을 보여줍니다.
![\[Pipeline role selection interface with options to create new or use existing IAM role.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/pipeline-role.png)
**Topics**
+ [
### 파이프라인 역할 생성 자동화
](#pipeline-role-auto-create)
+ [
### 수동으로 파이프라인 역할 생성
](#pipeline-role-manual-create)
### 파이프라인 역할 생성 자동화
OpenSearch Ingestion이 파이프라인 역할을 생성하도록 선택할 수 있습니다. 구성된 소스 및 싱크에 따라 역할에 필요한 권한을 자동으로 식별합니다. 접두사 `OpenSearchIngestion-`과 입력한 접미사를 사용하여 IAM 역할을 생성합니다. 예를 들어 `PipelineRole`을 접미사로 입력하면 OpenSearch Ingestion은 `OpenSearchIngestion-PipelineRole`이라는 역할을 생성합니다.
파이프라인 역할을 자동으로 생성하면 설정 프로세스가 간소화되고 구성 오류가 발생할 가능성이 줄어듭니다. 역할 생성을 자동화하면 권한을 수동으로 할당하지 않고도 보안 구성 오류 위험 없이 올바른 정책이 적용되도록 할 수 있습니다. 또한 여러 파이프라인 배포에서 일관성을 유지하면서 모범 사례를 적용하여 시간을 절약하고 보안 규정 준수를 개선할 수 있습니다.
AWS Management Console에서만 OpenSearch Ingestion이 파이프라인 역할을 자동으로 생성하도록 할 수 있습니다. AWS CLI, OpenSearch Ingestion API 또는 SDKs 중 하나를 사용하는 경우 수동으로 생성된 파이프라인 역할을 지정해야 합니다.
OpenSearch에서 역할을 자동으로 생성하려면 **새 서비스 역할 생성 및 사용**을 선택합니다.
**중요**
파이프라인 역할에 대한 액세스 권한을 부여하려면 도메인 또는 컬렉션 액세스 정책을 수동으로 수정해야 합니다. 세분화된 액세스 제어를 사용하는 도메인의 경우 파이프라인 역할도 백엔드 역할에 매핑해야 합니다. 파이프라인을 생성하기 전이나 후에 이 단계를 수행할 수 있습니다.
지침은 다음 주제를 참조하세요.
[도메인의 데이터 액세스 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-domain-access.html#pipeline-access-domain)
[컬렉션의 데이터 및 네트워크 액세스 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-domain-access.html#pipeline-collection-acces)
### 수동으로 파이프라인 역할 생성
특정 보안 또는 규정 준수 요구 사항을 충족하기 위해 권한을 더 세부적으로 제어해야 하는 경우 파이프라인 역할을 수동으로 생성하는 것이 좋습니다. 수동 생성을 통해 기존 인프라 또는 액세스 관리 전략에 맞게 역할을 조정할 수 있습니다. 수동 설정을 선택하여 역할을 다른와 통합 AWS 서비스 하거나 고유한 운영 요구 사항에 맞게 조정할 수도 있습니다.
수동으로 생성된 파이프라인 역할을 선택하려면 **기존 IAM 역할 사용**을 선택하고 기존 역할을 선택합니다. 역할에는 선택한 소스에서 데이터를 수신하고 선택한 싱크에 쓰는 데 필요한 모든 권한이 부여되어 있어야 합니다. 다음 섹션에서는 파이프라인 역할을 수동으로 생성하는 방법을 간략하게 설명합니다.
**Topics**
+ [
#### 소스에서 읽을 권한
](#pipeline-security--source)
+ [
#### 도메인 싱크에 쓸 권한
](#pipeline-security-domain-sink)
+ [
#### 컬렉션 싱크에 쓸 권한
](#pipeline-security--collection-sink)
+ [
#### Amazon S3 또는 Dead Letter Queue(DLQ)에 쓸 권한
](#pipeline-security-dlq)
#### 소스에서 읽을 권한
OpenSearch Ingestion 파이프라인에는 지정된 소스에서 데이터를 읽고 수신할 권한이 필요합니다. 예를 들어 Amazon DynamoDB 소스의 경우 `dynamodb:DescribeTable` 및 `dynamodb:DescribeStream`과 같은 권한이 필요합니다. Amazon S3, Fluent Bit 및 OpenTelemetry Collector와 같은 일반적인 소스에 대한 샘플 파이프라인 역할 액세스 정책은 [Amazon OpenSearch Ingestion 파이프라인을 다른 서비스 및 애플리케이션과 통합](configure-client.md) 섹션을 참조하세요.
#### 도메인 싱크에 쓸 권한
OpenSearch Ingestion 파이프라인에는 싱크로 구성된 OpenSearch Service 도메인에 쓸 수 있는 권한이 필요합니다. 이러한 권한에는 도메인을 설명하고 도메인에 HTTP 요청을 보내는 기능이 포함됩니다. 이러한 권한은 퍼블릭 및 VPC 도메인에서 동일합니다. 파이프라인 역할을 생성하고 도메인 액세스 정책에서 지정하는 지침은 [파이프라인의 도메인 액세스 허용](pipeline-domain-access.md)을 참조하세요.
#### 컬렉션 싱크에 쓸 권한
OpenSearch Ingestion 파이프라인에는 싱크로 구성된 OpenSearch Serverless 컬렉션에 쓸 수 있는 권한이 필요합니다. 이러한 권한에는 컬렉션을 설명하고 컬렉션에 HTTP 요청을 보내는 기능이 포함됩니다.
먼저 파이프라인 역할 액세스 정책이 필요한 권한을 부여하는지 확인합니다. 그런 다음 이 역할을 데이터 액세스 정책에 포함시키고 컬렉션 내에서 인덱스 생성, 인덱스 업데이트, 인덱스 설명, 문서 작성 등의 권한을 부여합니다. 각 단계를 완료하기 위한 지침은 [파이프라인의 컬렉션 액세스 허용](pipeline-collection-access.md)을 참조하세요.
#### Amazon S3 또는 Dead Letter Queue(DLQ)에 쓸 권한
Amazon S3를 파이프라인의 싱크 대상으로 지정하거나 [Dead Letter Queue](https://opensearch.org/docs/latest/data-prepper/pipelines/dlq/)(DLQ)를 활성화하는 경우 파이프라인 역할은 대상으로 지정한 S3 버킷에 액세스하도록 허용해야 합니다.
DLQ 액세스를 제공하는 파이프라인 역할에 별도의 권한 정책을 연결합니다. 최소한 역할에 버킷 리소스에 대한 `S3:PutObject` 작업 권한이 부여되어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "WriteToS3DLQ",
"Effect": "Allow",
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::my-dlq-bucket/*"
}
]
}
```
------
## 수집 역할
수집 역할은 외부 서비스가 OpenSearch Ingestion 파이프라인과 안전하게 상호 작용하고 데이터를 전송할 수 있도록 하는 IAM 역할입니다. Amazon Security Lake와 같은 푸시 기반 소스의 경우 이 역할은 `osis:Ingest`를 비롯하여 파이프라인으로 데이터를 푸시할 권한을 부여해야 합니다. Amazon S3와 같은 풀 기반 소스의 경우 역할은 이 작업을 맡고 필요한 권한으로 데이터에 액세스하도록 OpenSearch Ingestion을 활성화해야 합니다.
**Topics**
+ [
### 푸시 기반 소스에 대한 수집 역할
](#ingestion-role-push-based)
+ [
### 풀 기반 소스에 대한 수집 역할
](#ingestion-role-pull-based)
+ [
### 계정 간 수집
](#pipeline-security-different-account)
### 푸시 기반 소스에 대한 수집 역할
푸시 기반 소스의 경우 데이터는 Amazon Security Lake, Amazon DynamoDB 등의 다른 서비스에서 수집 파이프라인으로 전송되거나 푸시됩니다. 이 시나리오에서 수집 역할에는 최소한 파이프라인과 상호 작용하기 위한 `osis:Ingest` 권한이 필요합니다.
다음 IAM 액세스 정책은 수집 역할에 이 권한을 부여하는 방법을 보여줍니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"osis:Ingest"
],
"Resource": "arn:aws:osis:us-east-1:111122223333:pipeline/pipeline-name/*"
}
]
}
```
------
### 풀 기반 소스에 대한 수집 역할
풀 기반 소스의 경우 OpenSearch Ingestion 파이프라인은 Amazon S3와 같은 외부 소스에서 데이터를 능동적으로 가져오거나 가져옵니다. 이 경우 파이프라인은 데이터 소스에 액세스하는 데 필요한 권한을 부여하는 IAM 파이프라인 역할을 맡아야 합니다. 이 시나리오에서 *수집 역할*은 *파이프라인 역할*과 동의어입니다.
역할에는 OpenSearch Ingestion이 이 작업을 맡 수 있도록 허용하는 신뢰 관계와 데이터 소스와 관련된 권한이 포함되어야 합니다. 자세한 내용은 [소스에서 읽을 권한](#pipeline-security--source) 단원을 참조하십시오.
### 계정 간 수집
애플리케이션 계정과 AWS 계정같은 다른에서 파이프라인으로 데이터를 수집해야 할 수 있습니다. 계정 간 수집을 구성하려면 파이프라인과 동일한 계정 내에 수집 역할을 정의하고 수집 역할과 애플리케이션 계정 간에 신뢰 관계를 설정하세요.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:root"
},
"Action": "sts:AssumeRole"
}]
}
```
------
그런 다음, 수집 역할을 맡도록 애플리케이션을 구성하세요. 애플리케이션 계정은 파이프라인 계정의 수집 역할에 대한 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) 권한을 애플리케이션 역할에 부여해야 합니다.
자세한 단계 및 예제 IAM 정책은 [교차 계정 수집 액세스 제공](configure-client.md#configure-client-cross-account)을 참조하세요.
# 도메인에 대한 Amazon OpenSearch Ingestion 파이프라인 액세스 권한 부여
Amazon OpenSearch Ingestion 파이프라인에는 싱크로 구성된 OpenSearch Service 도메인에 쓸 수 있는 권한이 필요합니다. 액세스를 제공하려면 파이프라인이 데이터를 전송하는 도메인에 대한 액세스를 제한하는 제한적인 권한 정책을 사용하여 AWS Identity and Access Management (IAM) 역할을 구성합니다. 예를 들어 수집 파이프라인을 사용 사례를 지원하는 데 필요한 도메인과 인덱스로만 제한할 수 있습니다.
**중요**
파이프라인 역할을 수동으로 생성하도록 선택하거나 파이프라인 생성 중에 OpenSearch Ingestion에서 생성되도록 할 수 있습니다. 자동 역할 생성을 선택하면 OpenSearch Ingestion은 선택한 소스 및 싱크를 기반으로 파이프라인 역할 액세스 정책에 필요한 모든 권한을 추가합니다. 접두사 `OpenSearchIngestion-`과 사용자가 입력한 접미사를 사용하여 IAM에 파이프라인 역할을 생성합니다. 자세한 내용은 [파이프라인 역할](pipeline-security-overview.md#pipeline-security-sink) 단원을 참조하십시오.
OpenSearch Ingestion이 파이프라인 역할을 생성하더라도 파이프라인을 생성하기 전이나 후에 도메인 액세스 정책에 역할을 포함하고 백엔드 역할(도메인이 세분화된 액세스 제어를 사용하는 경우)에 매핑해야 합니다. 지침은 2단계를 참조하세요.
**Topics**
+ [
## 1단계: 파이프라인 역할 생성
](#pipeline-access-configure)
+ [
## 2단계: 도메인의 데이터 액세스 구성
](#pipeline-access-domain)
## 1단계: 파이프라인 역할 생성
파이프라인 역할에는 도메인 싱크로 데이터를 전송할 수 있는 권한 정책이 첨부되어 있어야 합니다. 또한 OpenSearch Ingestion이 그 역할을 수임할 수 있도록 하는 신뢰 관계도 있어야 합니다. 정책을 역할에 연결하는 지침은 *IAM 사용 설명서*의 [IAM 자격 증명 권한 추가](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policies-console)를 참조하세요.
다음 샘플 정책은 단일 도메인에 쓸 수 있도록 파이프라인 역할에서 제공할 수 있는 [최소 권한](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege)을 보여줍니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "es:DescribeDomain",
"Resource": "arn:aws:es:*:111122223333:domain/*"
},
{
"Effect": "Allow",
"Action": "es:ESHttp*",
"Resource": "arn:aws:es:*:111122223333:domain/domain-name/*"
}
]
}
```
------
역할을 재사용하여 여러 도메인에 쓸 계획이라면 도메인 이름을 와일드카드 문자(`*`)로 대체하여 정책을 더 광범위하게 적용할 수 있습니다.
역할에는 다음과 같은 [신뢰 관계](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy)가 있어야 합니다. 그러면 OpenSearch Ingestion이 파이프라인 역할을 맡을 수 있습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Principal":{
"Service":"osis-pipelines.amazonaws.com"
},
"Action":"sts:AssumeRole"
}
]
}
```
------
## 2단계: 도메인의 데이터 액세스 구성
파이프라인이 도메인에 데이터를 쓰려면 파이프라인 역할이 도메인에 액세스할 수 있도록 허용하는 [도메인 수준 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)이 도메인에 있어야 합니다.
다음 샘플 도메인 액세스 정책은 `pipeline-role`이라는 파이프라인 역할을 사용하여 `ingestion-domain`이라는 도메인에 데이터를 쓸 수 있도록 허용합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/pipeline-role"
},
"Action": [
"es:DescribeDomain",
"es:ESHttp*"
],
"Resource": "arn:aws:es:us-east-1:111122223333:domain/domain-name/*"
}
]
}
```
------
### 파이프라인 역할 매핑(세분화된 액세스 제어를 사용하는 도메인에만 해당)
도메인에서 인증에 [세분화된 액세스 제어](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html)를 사용하는 경우 도메인에 대한 파이프라인 액세스 권한을 제공하기 위해 수행해야 하는 추가 단계가 있습니다. 단계는 도메인 구성에 따라 다릅니다.
+ **시나리오 1: 다른 마스터 역할 및 파이프라인 역할** — IAM Amazon 리소스 이름(ARN)을 마스터 사용자로 사용하고 있고 이것이 파이프라인 역할과 *다른* 경우, 파이프라인 역할을 OpenSearch `all_access` 백엔드 역할에 매핑해야 합니다. 이렇게 하면 파이프라인 역할이 추가 마스터 사용자로 추가됩니다. 자세한 내용은 [추가 마스터 사용자](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-more-masters)를 참조하세요.
+ **시나리오 2: 내부 사용자 데이터베이스의 마스터 사용자** - 도메인에서 내부 사용자 데이터베이스의 마스터 사용자와 OpenSearch Dashboard의 HTTP 기본 인증을 사용하는 경우 마스터 사용자 이름과 비밀번호를 파이프라인 구성으로 직접 전달할 수 없습니다. 대신 파이프라인 역할을 OpenSearch `all_access` 백엔드 역할에 매핑합니다. 이렇게 하면 파이프라인 역할이 추가 마스터 사용자로 추가됩니다. 자세한 내용은 [추가 마스터 사용자](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-more-masters)를 참조하세요.
+ **시나리오 3: 동일한 마스터 역할 및 파이프라인 역할(흔하지 않음)** - IAM ARN을 마스터 사용자로 사용하고 있고 파이프라인 역할로 사용하는 것과 동일한 ARN인 경우 추가 조치를 취할 필요가 없습니다. 파이프라인에는 도메인에 쓰는 데 필요한 권한이 있습니다. 대부분의 환경에서 관리자 역할이나 다른 역할을 마스터 역할로 사용하기 때문에 이 시나리오는 흔하지 않습니다.
다음 이미지는 파이프라인 역할을 백엔드 역할에 매핑하는 방법을 보여줍니다.
![\[Backend roles section showing an AWSIAM role ARN for a pipeline role with a Remove option.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/ingestion-fgac.png)
# 컬렉션에 대한 액세스 권한을 Amazon OpenSearch Ingestion 파이프라인에 부여
Amazon OpenSearch Ingestion 파이프라인은 OpenSearch Serverless 퍼블릭 컬렉션 또는 VPC 컬렉션에 쓸 수 있습니다. 컬렉션에 대한 액세스를 제공하려면 컬렉션에 대한 액세스 권한을 부여하는 권한 정책을 사용하여 AWS Identity and Access Management (IAM) 파이프라인 역할을 구성합니다. 파이프라인은 OpenSearch Serverless 컬렉션 싱크에 대한 요청에 서명하기 위해 이 역할을 맡습니다.
**중요**
파이프라인 역할을 수동으로 생성하도록 선택하거나 파이프라인 생성 중에 OpenSearch Ingestion에서 생성되도록 할 수 있습니다. 자동 역할 생성을 선택하면 OpenSearch Ingestion은 선택한 소스 및 싱크를 기반으로 파이프라인 역할 액세스 정책에 필요한 모든 권한을 추가합니다. 접두사 `OpenSearchIngestion-`과 사용자가 입력한 접미사를 사용하여 IAM에 파이프라인 역할을 생성합니다. 자세한 내용은 [파이프라인 역할](pipeline-security-overview.md#pipeline-security-sink) 단원을 참조하십시오.
OpenSearch Ingestion이 파이프라인 역할을 생성하더라도 파이프라인을 생성하기 전이나 후에 컬렉션의 데이터 액세스 정책에 역할을 포함해야 합니다. 지침은 2단계를 참조하세요.
파이프라인 생성 중에 OpenSearch Ingestion은 파이프라인과 OpenSearch Serverless 컬렉션 간에 AWS PrivateLink 연결을 생성합니다. 파이프라인의 모든 트래픽은 이 VPC 엔드포인트를 통과하여 컬렉션으로 라우팅됩니다. 컬렉션에 도달하려면 네트워크 액세스 정책을 통해 컬렉션에 대한 액세스 권한을 엔드포인트에 부여해야 합니다.
![\[OpenSearch Ingestion pipeline connecting to OpenSearch Serverless collection via PrivateLink VPC endpoint.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/osis-aoss-permissions.png)
**Topics**
+ [
## 1단계: 파이프라인 역할 생성
](#pipeline-collection-access-configure)
+ [
## 2단계: 컬렉션의 데이터 및 네트워크 액세스 구성
](#pipeline-access-collection)
## 1단계: 파이프라인 역할 생성
파이프라인 역할에는 컬렉션 싱크로 데이터를 전송할 수 있는 권한 정책이 첨부되어 있어야 합니다. 또한 OpenSearch Ingestion이 그 역할을 수임할 수 있도록 하는 신뢰 관계도 있어야 합니다. 정책을 역할에 연결하는 지침은 *IAM 사용 설명서*의 [IAM 자격 증명 권한 추가](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policies-console)를 참조하세요.
다음 샘플 정책은 컬렉션에 쓸 수 있도록 파이프라인 역할 액세스 정책에서 제공할 수 있는 [최소 권한](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege)을 보여줍니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Action": [
"aoss:APIAccessAll",
"aoss:BatchGetCollection",
"aoss:CreateSecurityPolicy",
"aoss:GetSecurityPolicy",
"aoss:UpdateSecurityPolicy"
],
"Resource": "*"
}
]
}
```
------
OpenSearch Ingestion이 역할을 수임할 수 있도록 하는 다음 [신뢰 관계](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy)가 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "osis-pipelines.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
## 2단계: 컬렉션의 데이터 및 네트워크 액세스 구성
다음 설정을 사용하여 OpenSearch Serverless 컬렉션을 생성합니다. 컬렉션 생성 지침은 [컬렉션 생성](serverless-create.md) 섹션을 참조하세요.
### 데이터 액세스 정책
파이프라인 역할에 필요한 권한을 부여하는 컬렉션에 대한 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 생성합니다. 예제:
```
[
{
"Rules": [
{
"Resource": [
"index/collection-name/*"
],
"Permission": [
"aoss:CreateIndex",
"aoss:UpdateIndex",
"aoss:DescribeIndex",
"aoss:WriteDocument"
],
"ResourceType": "index"
}
],
"Principal": [
"arn:aws:iam::account-id:role/pipeline-role"
],
"Description": "Pipeline role access"
}
]
```
**참고**
`Principal` 요소에서 파이프라인 역할의 Amazon 리소스 이름(ARN)을 지정합니다.
### 네트워크 액세스 정책
OpenSearch Serverless에서 생성하는 각 컬렉션에는 하나 이상의 네트워크 액세스 정책이 연결되어 있습니다. 네트워크 액세스 정책은 퍼블릭 네트워크에서 인터넷을 통해 컬렉션에 액세스할 수 있는지 아니면 프라이빗 액세스로 액세스해야 하는지 여부를 결정합니다. 네트워크 정책에 대한 자세한 내용은 [Amazon OpenSearch Serverless에 대한 네트워크 액세스](serverless-network.md) 섹션을 참조하세요.
네트워크 액세스 정책 내에서 OpenSearch Serverless 관리형 VPC 엔드포인트만 지정할 수 있습니다. 자세한 내용은 [를 통한 데이터 영역 액세스 AWS PrivateLink](serverless-vpc.md) 단원을 참조하십시오. 그러나 파이프라인에서 컬렉션에 쓰려면 OpenSearch Ingestion이 파이프라인과 컬렉션 간에 자동으로 생성하는 VPC 엔드포인트에 대한 액세스 권한도 정책에 부여해야 합니다. 따라서 파이프라인의 대상 싱크로 OpenSearch Serverless 컬렉션을 선택하는 경우 네트워크 정책 이름 필드에 연결된 **네트워크 정책의 이름**을 입력해야 합니다.
파이프라인 생성 중에 OpenSearch Ingestion은 지정된 네트워크 정책이 있는지 확인합니다. 존재하지 않는 경우 OpenSearch Ingestion에서 생성합니다. 존재하는 경우 OpenSearch Ingestion은 새 규칙을 추가하여 업데이트합니다. 이 규칙에서 파이프라인과 컬렉션을 연결하는 VPC 엔드포인트에 대한 액세스 권한을 부여합니다.
예제:
```
{
"Rules":[
{
"Resource":[
"collection/my-collection"
],
"ResourceType":"collection"
}
],
"SourceVPCEs":[
"vpce-0c510712627e27269" # The ID of the VPC endpoint that OpenSearch Ingestion creates between the pipeline and collection
],
"Description":"Created by Data Prepper"
}
```
콘솔에서 OpenSearch Ingestion이 네트워크 정책에 추가하는 모든 규칙의 이름은 **Data Prepper에서 생성됨**으로 지정됩니다.
![\[Configuration details for OpenSearch endpoint access, including VPC endpoint and resources.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/osis-aoss-network.png)
**참고**
일반적으로 컬렉션에 대한 퍼블릭 액세스를 지정하는 규칙은 프라이빗 액세스를 지정하는 규칙을 재정의합니다. 따라서 정책에 이미 *퍼블릭* 액세스가 구성된 경우 OpenSearch Ingestion이 추가하는 이 새 규칙은 실제로 정책의 동작을 변경하지 않습니다. 자세한 내용은 [정책 우선순위](serverless-network.md#serverless-network-precedence) 단원을 참조하십시오.
파이프라인을 중지하거나 삭제하면 OpenSearch Ingestion은 파이프라인과 컬렉션 사이의 VPC 엔드포인트를 삭제합니다. 또한 허용된 엔드포인트 목록에서 VPC 엔드포인트를 제거하도록 네트워크 정책을 수정합니다. 파이프라인을 다시 시작하면 VPC 엔드포인트가 다시 생성되고 네트워크 정책이 엔드포인트 ID로 다시 업데이트됩니다.
# Amazon OpenSearch Ingestion 시작하기
Amazon OpenSearch Ingestion은 관리형 OpenSearch Service 도메인 및 OpenSearch Serverless 컬렉션으로의 데이터 수집을 지원합니다. 다음 자습서에서는 파이프라인을 시작하고 실행하기 위한 기본 단계를 안내합니다.
첫 번째 자습서에서는 Amazon OpenSearch Ingestion을 사용하여 간단한 파이프라인을 구성하고 Amazon OpenSearch Service 도메인으로 데이터를 수집하는 방법을 보여줍니다.
두 번째 자습서에서는 Amazon OpenSearch Ingestion을 사용하여 간단한 파이프라인을 구성하고 Amazon OpenSearch Serverless 컬렉션으로 데이터를 수집하는 방법을 보여줍니다.
**참고**
올바른 권한을 설정하지 않으면 파이프라인 생성이 실패합니다. 파이프라인을 생성하기 전에 필요한 역할을 더 잘 이해하려면 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md)(을)를 참조하세요.
**Topics**
+ [
# 튜토리얼: Amazon OpenSearch Ingestion을 사용하여 도메인에 데이터 수집
](osis-get-started.md)
+ [
# 튜토리얼: Amazon OpenSearch Ingestion을 사용하여 컬렉션에 데이터 수집
](osis-serverless-get-started.md)
# 튜토리얼: Amazon OpenSearch Ingestion을 사용하여 도메인에 데이터 수집
이 튜토리얼에서는 Amazon OpenSearch Ingestion을 사용하여 간단한 파이프라인을 구성하고 Amazon OpenSearch Service 도메인에 데이터를 수집하는 방법을 보여줍니다. *파이프라인*은 OpenSearch Ingestion이 프로비저닝하고 관리하는 리소스입니다. 파이프라인을 사용하여 OpenSearch Service의 다운스트림 분석 및 시각화를 위해 데이터를 필터링, 강화, 변환, 정규화 및 집계할 수 있습니다.
이 튜토리얼은 파이프라인을 준비하여 빠르게 실행하기 위한 기본 단계를 안내합니다. 자세한 지침은 [파이프라인 생성](creating-pipeline.md#create-pipeline) 섹션을 참조하세요.
이 튜토리얼에서는 다음 단계를 완료합니다.
1. [도메인 생성](#osis-get-started-access).
1. [파이프라인 생성](#osis-get-started-pipeline).
1. [일부 샘플 데이터 수집](#osis-get-started-ingest).
이 튜토리얼에서는 다음 리소스를 생성합니다.
+ 파이프라인이 데이터를 쓸 `ingestion-domain`이라는 도메인입니다.
+ `ingestion-pipeline`이라는 파이프라인
## 필수 권한
이 자습서를 완료하려면 사용자 또는 역할에 다음과 같은 최소 권한이 포함된 연결된 [자격 증명 기반 정책](security-iam-serverless.md#security-iam-serverless-id-based-policies)이 있어야 합니다. 이러한 권한을 가지고 파이프라인 역할을 생성하고, 정책(`iam:Create*` 및 `iam:Attach*`)을 연결하고, 도메인(`es:*`)을 생성 또는 수정하고, 파이프라인(`osis:*`) 작업을 수행할 수 있습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Resource":"*",
"Action":[
"osis:*",
"iam:Create*",
"iam:Attach*",
"es:*"
]
},
{
"Resource":[
"arn:aws:iam::111122223333:role/OpenSearchIngestion-PipelineRole"
],
"Effect":"Allow",
"Action":[
"iam:CreateRole",
"iam:AttachRolePolicy",
"iam:PassRole"
]
}
]
}
```
------
## 1단계: 파이프라인 역할 생성
먼저 OpenSearch Serverless 도메인 싱크에 액세스하기 위해 파이프라인이 맡을 역할을 생성합니다. 이 튜토리얼의 뒷부분에서 파이프라인 구성에 이 역할을 포함시킬 것입니다.
**파이프라인 역할을 생성하려면**
1. [https://console.aws.amazon.com/iamv2/](https://console.aws.amazon.com/iamv2/ ) AWS Identity and Access Management 콘솔을 엽니다.
1. **정책**을 선택한 후 **정책 생성**을 선택합니다.
1. 이 튜토리얼에서는 다음 단계에서 생성할 `ingestion-domain`이라는 도메인으로 데이터를 수집해 보겠습니다. **JSON**을 선택한 후 다음 정책을 편집기에 붙여넣습니다. `your-account-id`(을)를 계정 ID로 바꾸고 필요한 경우 리전을 수정하세요.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "es:DescribeDomain",
"Resource": "arn:aws:es:us-east-1:111122223333:domain/ingestion-domain"
},
{
"Effect": "Allow",
"Action": "es:ESHttp*",
"Resource": "arn:aws:es:us-east-1:111122223333:domain/ingestion-domain/*"
}
]
}
```
------
*기존* 도메인에 데이터를 쓰려면 `ingestion-domain`(을)를 도메인 이름으로 바꾸세요.
**참고**
이 자습서에서는 간단한 설명을 위해 광범위한 액세스 정책을 사용합니다. 하지만 프로덕션 환경에서는 파이프라인 역할에 보다 제한적인 액세스 정책을 적용하는 것이 좋습니다. 필요한 최소 권한을 제공하는 예제 정책은 [도메인에 대한 Amazon OpenSearch Ingestion 파이프라인 액세스 권한 부여](pipeline-domain-access.md)(을)를 참조하세요.
1. **다음**을 선택하고 **다음**을 선택한 후, 정책 이름을 **파이프라인-정책**으로 지정합니다.
1. **정책 생성**을 선택합니다.
1. 다음으로, 역할을 생성하여 역할에 정책을 연결합니다. **역할**을 선택한 다음 **역할 생성**을 선택합니다.
1. **사용자 지정 신뢰 정책**을 선택하고 다음 정책을 편집기에 붙여넣습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Principal":{
"Service":"osis-pipelines.amazonaws.com"
},
"Action":"sts:AssumeRole"
}
]
}
```
------
1. **다음**을 선택합니다. 그런 다음 방금 생성한 **파이프라인-정책**을 검색하여 선택합니다.
1. **다음**을 선택하고 역할 이름을 **PipelineRole**로 지정합니다.
1. **역할 생성**을 선택합니다.
역할의 Amazon 리소스 이름(ARN)을 기억하세요(예: `arn:aws:iam::your-account-id:role/PipelineRole`). 파이프라인을 생성할 때 사용합니다.
## 2단계: 도메인 생성
먼저 데이터를 수집할 `ingestion-domain`이라는 도메인을 생성합니다.
[ https://console.aws.amazon.com/aos/home ](https://console.aws.amazon.com/aos/home)에서 Amazon OpenSearch Service 콘솔로 이동하여 다음 필요 조건을 충족하는 [도메인을 생성](createupdatedomains.md)합니다.
+ OpenSearch 1.0 이상 또는 Elasticsearch 7.4 이상을 실행합니다
+ 퍼블릭 액세스 사용
+ 세분화된 액세스 제어 사용 금지
**참고**
이러한 요구 사항은 이 튜토리얼에서 단순성을 보장하기 위한 것입니다. 프로덕션 환경에서는 VPC 액세스가 가능한 도메인을 구성하거나 세분화된 액세스 제어를 사용할 수 있습니다. 세분화된 액세스 제어를 사용하려면 [파이프라인 역할 매핑](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-domain-access.html#pipeline-access-domain)을 참조하세요.
도메인에는 다음 단계에서 OpenSearch Service가 생성하는 `OpenSearchIngestion-PipelineRole` IAM 역할에 권한을 부여하는 액세스 정책이 있어야 합니다. 파이프라인은 도메인 싱크로 데이터를 전송하기 위해이 역할을 맡습니다.
도메인에 대한 파이프라인 역할 액세스 권한을 부여하는 다음과 같은 도메인 수준 액세스 정책이 도메인에 적용되었는지 확인하세요. 을 리전으로 바꾸고 를 계정 ID로 바꿉니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/OpenSearchIngestion-PipelineRole"
},
"Action": "es:*",
"Resource": "arn:aws:es:us-east-1:111122223333:domain/ingestion-domain/*"
}
]
}
```
------
도메인 수준 액세스 정책 생성에 대한 자세한 내용은 [리소스 기반 정책](ac.md#ac-types-resource) 섹션을 참조하세요.
이미 도메인을 생성한 경우 기존의 액세스 정책을 수정하여 위의 권한을 `OpenSearchIngestion-PipelineRole`에 제공하세요.
## 3단계: 파이프라인 생성
이제 도메인이 있으므로 파이프라인을 생성할 수 있습니다.
**파이프라인을 만들려면**
1. Amazon OpenSearch Service 콘솔 내 왼쪽 탐색 창에서 **파이프라인**을 선택합니다.
1. [**파이프라인 생성**]을 선택합니다.
1. **빈** 파이프라인을 선택한 다음, **블루프린트 선택**을 선택합니다.
1. 이 자습서에서는 [HTTP 소스](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/http-source/) 플러그인을 사용하는 파이프라인을 만들어 봅니다. 플러그인은 JSON 배열 형식의 로그 데이터를 받아들입니다. 단일 OpenSearch Serverless 컬렉션을 싱크로 지정하고 모든 데이터를 `application_logs` 인덱스로 수집합니다.
**소스** 메뉴에서 **HTTP**를 선택합니다. **경로**에 **/logs**를 입력합니다.
1. 이 튜토리얼에서는 간소화를 위해 파이프라인에 대한 공개 액세스를 구성해 보겠습니다. **소스 네트워크 옵션**에서 **퍼블릭 액세스**를 선택합니다. VPC에 대한 액세스를 구성하는 방법에 대한 자세한 정보는 [Amazon OpenSearch Ingestion 파이프라인에 대한 VPC 액세스 구성](pipeline-security.md) 섹션을 참조하세요.
1. **다음**을 선택합니다.
1. **프로세서**에 **날짜**를 입력하고 **추가**를 선택합니다.
1. **수신된 시작 시간**을 활성화합니다. 다른 모든 설정은 기본값으로 둡니다.
1. **다음**을 선택합니다.
1. 싱크 세부 정보를 구성합니다. **OpenSearch 리소스 유형**에서 **관리형 클러스터**를 선택합니다. 그런 다음, 이전 섹션에서 생성한 OpenSearch Service 도메인을 선택합니다.
**인덱스 이름**에 **application\$1logs**를 입력합니다. 아직 없는 경우 OpenSearch Ingestion이 도메인에 이 인덱스를 자동으로 생성합니다.
1. **다음**을 선택합니다.
1. 파이프라인 이름을 **ingestion-pipeline**으로 지정합니다. 용량 설정을 기본값으로 둡니다.
1. **파이프라인 역할**에서 **새 서비스 역할 생성 및 사용**을 선택합니다. 이 파이프라인 역할은 파이프라인이 도메인 싱크에 쓰고 풀 기반 소스에서 읽는 데 필요한 권한을 제공합니다. 이 옵션을 선택하면 IAM에서 역할을 수동으로 생성하는 대신 OpenSearch Ingestion이 역할을 생성하도록 허용할 수 있습니다. 자세한 내용은 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md) 단원을 참조하십시오.
1. **서비스 역할 이름 접미사**에 **PipelineRole**을 입력합니다. IAM에서 역할은 `arn:aws:iam::your-account-id:role/OpenSearchIngestion-PipelineRole` 형식입니다.
1. **다음**을 선택합니다. 파이프라인 구성을 검토하고 **파이프라인 생성**을 선택합니다. 파이프라인이 활성화되려면 5\$110분이 걸립니다.
## 4단계: 일부 샘플 데이터 수집
파이프라인이 `Active` 상태가 되면 데이터 수집을 시작할 수 있습니다. [서명 버전 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)를 사용하여 파이프라인에 대한 모든 HTTP 요청에 서명해야 합니다. [Postman](https://www.getpostman.com/) 또는 [awscurl](https://github.com/okigan/awscurl)과 같은 HTTP 도구를 사용하여 파이프라인에 일부 데이터를 전송하세요. 데이터를 컬렉션에 직접 인덱싱하는 것과 마찬가지로, 파이프라인으로 데이터를 수집하려면 항상 IAM 역할 또는 [IAM 액세스 키와 암호 키](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html)가 필요합니다.
**참고**
요청에 서명하는 주체에게는 `osis:Ingest` IAM 권한이 있어야 합니다.
먼저 **파이프라인 설정** 페이지에서 수집 URL을 가져옵니다.
![\[Pipeline settings page showing ingestion URL and other configuration details.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/pipeline-endpoint.png)
그런 다음 일부 샘플 데이터를 수집하세요. 다음 샘플 요청은 [awscurl](https://github.com/okigan/awscurl)을 사용하여 단일 로그 파일을 파이프라인에 보냅니다.
```
awscurl --service osis --region us-east-1 \
-X POST \
-H "Content-Type: application/json" \
-d '[{"time":"2014-08-11T11:40:13+00:00","remote_addr":"122.226.223.69","status":"404","request":"GET http://www.k2proxy.com//hello.html HTTP/1.1","http_user_agent":"Mozilla/4.0 (compatible; WOW64; SLCC2;)"}]' \
https://pipeline-endpoint.us-east-1.osis.amazonaws.com/logs
```
`200 OK` 응답이 표시되어야 합니다. 인증 오류가 발생하는 경우 파이프라인이 있는 별도의 계정에서 데이터를 수집하고 있기 때문일 수 있습니다. [권한 문제 해결](#osis-get-started-troubleshoot)을(를) 참조하세요.
이제 `application_logs` 인덱스를 쿼리하여 로그 항목이 성공적으로 수집되었는지 확인하세요.
```
awscurl --service es --region us-east-1 \
-X GET \
https://search-ingestion-domain.us-east-1.es.amazonaws.com/application_logs/_search | json_pp
```
**샘플 응답**:
```
{
"took":984,
"timed_out":false,
"_shards":{
"total":1,
"successful":5,
"skipped":0,
"failed":0
},
"hits":{
"total":{
"value":1,
"relation":"eq"
},
"max_score":1.0,
"hits":[
{
"_index":"application_logs",
"_type":"_doc",
"_id":"z6VY_IMBRpceX-DU6V4O",
"_score":1.0,
"_source":{
"time":"2014-08-11T11:40:13+00:00",
"remote_addr":"122.226.223.69",
"status":"404",
"request":"GET http://www.k2proxy.com//hello.html HTTP/1.1",
"http_user_agent":"Mozilla/4.0 (compatible; WOW64; SLCC2;)",
"@timestamp":"2022-10-21T21:00:25.502Z"
}
}
]
}
}
```
## 권한 문제 해결
자습서의 단계를 따랐지만 데이터를 수집하려고 할 때 여전히 인증 오류가 표시되는 경우 파이프라인에 쓰는 역할이 파이프라인 자체 AWS 계정 와 다른에 있기 때문일 수 있습니다. 이 경우 데이터를 수집할 수 있도록 특별히 지원하는 [역할을 만들고 수임](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html)해야 합니다. 지침은 [교차 계정 수집 액세스 제공](configure-client.md#configure-client-cross-account) 섹션을 참조하세요.
## 관련 리소스
이 튜토리얼에서는 HTTP를 통해 단일 문서를 수집하는 간단한 사용 사례를 제시했습니다. 프로덕션 시나리오에서는 하나 이상의 파이프라인으로 데이터를 전송하도록 클라이언트 애플리케이션(예: Fluent Bit, Kubernetes 또는 OpenTelemetry Collector)을 구성합니다. 파이프라인은 이 튜토리얼의 간단한 예제보다 더 복잡할 수 있습니다.
클라이언트 구성 및 데이터 수집을 시작하려면 다음 리소스를 참조하세요.
+ [파이프라인 생성 및 관리](creating-pipeline.md#create-pipeline)
+ [OpenSearch Ingestion으로 데이터를 전송하도록 클라이언트 구성](configure-client.md)
+ [Data Prepper 설명서](https://opensearch.org/docs/latest/clients/data-prepper/index/)
# 튜토리얼: Amazon OpenSearch Ingestion을 사용하여 컬렉션에 데이터 수집
이 튜토리얼에서는 Amazon OpenSearch Ingestion을 사용하여 간단한 파이프라인을 구성하고 Amazon OpenSearch Serverless 컬렉션에 데이터를 수집하는 방법을 보여줍니다. *파이프라인*은 OpenSearch Ingestion이 프로비저닝하고 관리하는 리소스입니다. 파이프라인을 사용하여 OpenSearch Service의 다운스트림 분석 및 시각화를 위해 데이터를 필터링, 강화, 변환, 정규화 및 집계할 수 있습니다.
프로비저닝된 OpenSearch Service *도메인*으로 데이터를 수집하는 방법을 보여주는 튜토리얼은 [튜토리얼: Amazon OpenSearch Ingestion을 사용하여 도메인에 데이터 수집](osis-get-started.md)을 참조하세요.
이 자습서에서는 다음 단계를 완료합니다.
1. [모음을 만듭니다](#osis-serverless-get-started-access).
1. [파이프라인 생성](#osis-serverless-get-started-pipeline).
1. [일부 샘플 데이터 수집](#osis-serverless-get-started-ingest).
이 튜토리얼에서는 다음 리소스를 생성합니다.
+ 파이프라인이 쓸 `ingestion-collection`이라는 컬렉션입니다.
+ `ingestion-pipeline-serverless`이라는 파이프라인
## 필수 권한
이 자습서를 완료하려면 사용자 또는 역할에 다음과 같은 최소 권한이 포함된 연결된 [자격 증명 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/security-iam-serverless.html#security-iam-serverless-id-based-policies)이 있어야 합니다. 이러한 권한을 가지고 파이프라인 역할을 생성하고, 정책(`iam:Create*` 및 `iam:Attach*`)을 연결하고, 컬렉션(`aoss:*`)을 생성 또는 수정하고, 파이프라인(`osis:*`) 작업을 수행할 수 있습니다.
또한 파이프라인 역할을 자동으로 생성하고 컬렉션에 데이터를 쓰도록 OpenSearch Ingestion에 전달하려면 몇 가지 IAM 권한이 필요합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Resource":"*",
"Action":[
"osis:*",
"iam:Create*",
"iam:Attach*",
"aoss:*"
]
},
{
"Resource":[
"arn:aws:iam::111122223333:role/OpenSearchIngestion-PipelineRole"
],
"Effect":"Allow",
"Action":[
"iam:CreateRole",
"iam:AttachRolePolicy",
"iam:PassRole"
]
}
]
}
```
------
## 1단계: 컬렉션 생성
먼저, 데이터를 수집할 컬렉션을 생성합니다. 컬렉션 이름을 `ingestion-collection`로 지정하겠습니다.
1. [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home)에서 Amazon OpenSearch Service 콘솔로 이동합니다.
1. 왼쪽 탐색에서 **컬렉션**을 선택하고 ** 컬렉션 생성**을 선택합니다.
1. 컬렉션 이름을 **ingestion-collection**으로 지정하세요.
1. **보안**에서 **표준 생성**을 선택합니다.
1. **네트워크 액세스 설정**에서 액세스 유형을 **공개**로 변경합니다.
1. 다른 모든 설정을 기본값으로 유지하고 **Next**(다음)를 선택합니다.
1. 이제 컬렉션에 대한 데이터 액세스 정책을 구성합니다. **액세스 정책 설정 자동 매칭**을 선택 취소합니다.
1. **정의 방법**에는 **JSON**을 선택하고 편집기에 다음 정책을 붙여 넣습니다. 이 정책은 두 가지 기능을 합니다.
+ 파이프라인 역할이 컬렉션에 쓸 수 있도록 허용합니다.
+ 컬렉션에서 *읽을* 수 있도록 허용합니다. 나중에 일부 샘플 데이터를 파이프라인으로 수집한 후 컬렉션을 쿼리하여 데이터가 성공적으로 수집되고 인덱스에 기록되었는지 확인합니다.
```
[
{
"Rules": [
{
"Resource": [
"index/ingestion-collection/*"
],
"Permission": [
"aoss:CreateIndex",
"aoss:UpdateIndex",
"aoss:DescribeIndex",
"aoss:ReadDocument",
"aoss:WriteDocument"
],
"ResourceType": "index"
}
],
"Principal": [
"arn:aws:iam::your-account-id:role/OpenSearchIngestion-PipelineRole",
"arn:aws:iam::your-account-id:role/Admin"
],
"Description": "Rule 1"
}
]
```
1. AWS 계정 ID를 포함하도록 `Principal` 요소를 수정합니다. 두 번째 위탁자는 나중에 컬렉션을 쿼리하는 데 사용할 수 있는 사용자 또는 역할을 지정합니다.
1. **다음**을 선택합니다. 액세스 정책 이름을 **pipeline-collection-access**로 지정하고 **다음**을 다시 선택합니다.
1. 컬렉션 구성을 검토하고 **Submit**(제출)을 선택합니다.
## 2단계: 파이프라인 생성
이제 컬렉션이 있으므로 파이프라인을 생성할 수 있습니다.
**파이프라인을 만들려면**
1. Amazon OpenSearch Service 콘솔 내 왼쪽 탐색 창에서 **파이프라인**을 선택합니다.
1. [**파이프라인 생성**]을 선택합니다.
1. **빈** 파이프라인을 선택한 다음, **블루프린트 선택**을 선택합니다.
1. 이 자습서에서는 [HTTP 소스](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/http-source/) 플러그인을 사용하는 파이프라인을 만들어 봅니다. 플러그인은 JSON 배열 형식의 로그 데이터를 받아들입니다. 단일 OpenSearch Serverless 컬렉션을 싱크로 지정하고 모든 데이터를 `my_logs` 인덱스로 수집하겠습니다.
**소스** 메뉴에서 **HTTP**를 선택합니다. **경로**에 **/logs**를 입력합니다.
1. 이 튜토리얼에서는 간소화를 위해 파이프라인에 대한 공개 액세스를 구성해 보겠습니다. **소스 네트워크 옵션**에서 **퍼블릭 액세스**를 선택합니다. VPC에 대한 액세스를 구성하는 방법에 대한 자세한 정보는 [Amazon OpenSearch Ingestion 파이프라인에 대한 VPC 액세스 구성](pipeline-security.md) 섹션을 참조하세요.
1. **다음**을 선택합니다.
1. **프로세서**에 **날짜**를 입력하고 **추가**를 선택합니다.
1. **수신된 시작 시간**을 활성화합니다. 다른 모든 설정은 기본값으로 둡니다.
1. **다음**을 선택합니다.
1. 싱크 세부 정보를 구성합니다. **OpenSearch 리소스 유형**에서 **컬렉션(서버리스)**을 선택합니다. 그런 다음 이전 섹션에서 생성한 OpenSearch Service 컬렉션을 선택합니다.
네트워크 정책 이름을 기본값으로 둡니다. **인덱스 이름**에 **my\$1logs**를 입력합니다. 아직 없는 경우 OpenSearch Ingestion이 컬렉션에 이 인덱스를 자동으로 생성합니다.
1. **다음**을 선택합니다.
1. 파이프라인 이름을 **ingestion-pipeline-serverless**로 지정합니다. 용량 설정을 기본값으로 둡니다.
1. **파이프라인 역할**에서 **새 서비스 역할 생성 및 사용**을 선택합니다. 이 파이프라인 역할은 파이프라인이 컬렉션 싱크에 쓰고 풀 기반 소스에서 읽는 데 필요한 권한을 제공합니다. 이 옵션을 선택하면 IAM에서 역할을 수동으로 생성하는 대신 OpenSearch Ingestion이 역할을 생성하도록 허용할 수 있습니다. 자세한 내용은 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md) 단원을 참조하십시오.
1. **서비스 역할 이름 접미사**에 **PipelineRole**을 입력합니다. IAM에서 역할은 `arn:aws:iam::your-account-id:role/OpenSearchIngestion-PipelineRole` 형식입니다.
1. **다음**을 선택합니다. 파이프라인 구성을 검토하고 **파이프라인 생성**을 선택합니다. 파이프라인이 활성화되려면 5\$110분이 걸립니다.
## 3단계: 일부 샘플 데이터 수집
파이프라인이 `Active` 상태가 되면 데이터 수집을 시작할 수 있습니다. [서명 버전 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)를 사용하여 파이프라인에 대한 모든 HTTP 요청에 서명해야 합니다. [Postman](https://www.getpostman.com/) 또는 [awscurl](https://github.com/okigan/awscurl)과 같은 HTTP 도구를 사용하여 파이프라인에 일부 데이터를 전송하세요. 데이터를 컬렉션에 직접 인덱싱하는 것과 마찬가지로, 파이프라인으로 데이터를 수집하려면 항상 IAM 역할 또는 [IAM 액세스 키와 암호 키](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html)가 필요합니다.
**참고**
요청에 서명하는 주체에게는 `osis:Ingest` IAM 권한이 있어야 합니다.
먼저 **파이프라인 설정** 페이지에서 수집 URL을 가져옵니다.
![\[Pipeline settings page showing ingestion URL and other configuration details.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/pipeline-endpoint.png)
그런 다음 일부 샘플 데이터를 수집 경로로 전송합니다. 다음 샘플 요청은 [awscurl](https://github.com/okigan/awscurl)을 사용하여 단일 로그 파일을 파이프라인에 보냅니다.
```
awscurl --service osis --region us-east-1 \
-X POST \
-H "Content-Type: application/json" \
-d '[{"time":"2014-08-11T11:40:13+00:00","remote_addr":"122.226.223.69","status":"404","request":"GET http://www.k2proxy.com//hello.html HTTP/1.1","http_user_agent":"Mozilla/4.0 (compatible; WOW64; SLCC2;)"}]' \
https://pipeline-endpoint.us-east-1.osis.amazonaws.com/logs
```
`200 OK` 응답이 표시되어야 합니다.
이제 `my_logs` 인덱스를 쿼리하여 로그 항목이 성공적으로 수집되었는지 확인하세요.
```
awscurl --service aoss --region us-east-1 \
-X GET \
https://collection-id.us-east-1.aoss.amazonaws.com/my_logs/_search | json_pp
```
**샘플 응답**:
```
{
"took":348,
"timed_out":false,
"_shards":{
"total":0,
"successful":0,
"skipped":0,
"failed":0
},
"hits":{
"total":{
"value":1,
"relation":"eq"
},
"max_score":1.0,
"hits":[
{
"_index":"my_logs",
"_id":"1%3A0%3ARJgDvIcBTy5m12xrKE-y",
"_score":1.0,
"_source":{
"time":"2014-08-11T11:40:13+00:00",
"remote_addr":"122.226.223.69",
"status":"404",
"request":"GET http://www.k2proxy.com//hello.html HTTP/1.1",
"http_user_agent":"Mozilla/4.0 (compatible; WOW64; SLCC2;)",
"@timestamp":"2023-04-26T05:22:16.204Z"
}
}
]
}
}
```
## 관련 리소스
이 튜토리얼에서는 HTTP를 통해 단일 문서를 수집하는 간단한 사용 사례를 제시했습니다. 프로덕션 시나리오에서는 하나 이상의 파이프라인으로 데이터를 전송하도록 클라이언트 애플리케이션(예: Fluent Bit, Kubernetes 또는 OpenTelemetry Collector)을 구성합니다. 파이프라인은 이 튜토리얼의 간단한 예제보다 더 복잡할 수 있습니다.
클라이언트 구성 및 데이터 수집을 시작하려면 다음 리소스를 참조하세요.
+ [파이프라인 생성 및 관리](creating-pipeline.md#create-pipeline)
+ [OpenSearch Ingestion으로 데이터를 전송하도록 클라이언트 구성](configure-client.md)
+ [Data Prepper 설명서](https://opensearch.org/docs/latest/clients/data-prepper/index/)
# Amazon OpenSearch Ingestion 파이프라인 기능 개요
Amazon OpenSearch Ingestion은 소스, 버퍼, 0개 이상의 프로세서, 하나 이상의 싱크로 구성된 *파이프라인*을 프로비저닝합니다. 수집 파이프라인은 데이터 엔진인 Data Prepper에 의해 구동됩니다. 파이프라인의 다양한 구성 요소에 대한 개요는 [Amazon OpenSearch Ingestion의 주요 개념](ingestion-process.md)(을)를 참조하세요.
다음 섹션에는 Amazon OpenSearch Ingestion에서 가장 일반적으로 사용되는 기능 중 일부에 대한 개요가 나와 있습니다.
**참고**
이 목록은 파이프라인에서 사용할 수 있는 기능 중 전체 목록이 아닙니다. 사용 가능한 모든 파이프라인 기능에 대한 포괄적인 설명서는 [Data Prepper 설명서](https://opensearch.org/docs/latest/data-prepper/pipelines/pipelines/)를 참조하세요. 참고로 OpenSearch Ingestion은 사용할 수 있는 플러그인과 옵션에 몇 가지 제약을 가합니다. 자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인에 지원되는 플러그인 및 옵션](pipeline-config-reference.md) 단원을 참조하십시오.
**Topics**
+ [
## 영구 버퍼링
](#persistent-buffering)
+ [
## 분할
](#osis-features-splitting)
+ [
## Chaining
](#osis-features-chaining)
+ [
## Dead Letter Queue(DLQ)
](#osis-features-dlq)
+ [
## 인덱스 관리
](#osis-features-index-management)
+ [
## 엔드 투 엔드 승인
](#osis-features-e2e)
+ [
## 소스 역압
](#osis-features-backpressure)
## 영구 버퍼링
영구 버퍼는 여러 가용 영역에 걸쳐 디스크 기반 버퍼에 데이터를 저장하여 데이터 내구성을 강화합니다. 영구 버퍼링을 사용하여 독립 실행형 버퍼를 설정하지 않고도 지원되는 모든 푸시 기반 소스에서 데이터를 수집할 수 있습니다. 이러한 소스에는 로그, 추적 및 지표에 대한 HTTP 및 OpenTelemetry가 포함됩니다. 영구 버퍼링을 활성화하려면 파이프라인을 생성하거나 업데이트할 때 **영구 버퍼 활성화**를 선택합니다. 자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인 생성](creating-pipeline.md) 단원을 참조하십시오.
OpenSearch Ingestion은 영구 버퍼링, 데이터 소스, 스트리밍 변환, 싱크 대상 등을 고려하여 사용할 OCU 수를 동적으로 결정합니다. 일부 OCU를 버퍼링에 할당하므로 동일한 수집 처리량을 유지하기 위해 최소 및 최대 OCU를 늘려야 할 수 있습니다. 파이프라인은 최대 72시간 동안 버퍼에 데이터를 유지합니다.
파이프라인의 영구 버퍼링을 활성화할 경우 기본 최대 요청 페이로드 크기는 다음과 같습니다.
+ **HTTP 소스** - 10MB
+ **OpenTelemetry 소스** - 4MB
HTTP 소스의 경우 최대 페이로드 크기를 20MB로 늘릴 수 있습니다. 요청 페이로드 크기는 일반적으로 여러 이벤트를 포함하는 전체 HTTP 요청의 크기입니다. 각 이벤트는 3.5MB를 초과할 수 없습니다.
영구 버퍼링이 활성화된 파이프라인은 구성된 파이프라인 단위가 컴퓨팅 단위와 버퍼 단위로 분할됩니다. 파이프라인이 grok, 키-값 또는 분할 문자열과 같은 CPU 집약적 프로세서를 사용하는 경우 단위를 1:1 버퍼-컴퓨팅 비율로 할당합니다. 그렇지 않으면 3:1 비율로 할당되어 항상 컴퓨팅 단위가 우선합니다.
예제:
+ grok 및 최대 2개의 단위가 있는 파이프라인 - 컴퓨팅 단위 1개 및 버퍼 단위 1개
+ grok 및 최대 5개의 단위가 있는 파이프라인 - 컴퓨팅 단위 3개 및 버퍼 단위 2개
+ 프로세서가 없고 최대 2개의 단위가 있는 파이프라인 - 컴퓨팅 단위 1개 및 버퍼 단위 1개
+ 프로세서가 없고 최대 4개의 단위가 있는 파이프라인 - 컴퓨팅 단위 1개 및 버퍼 단위 3개
+ grok 및 최대 5개의 단위가 있는 파이프라인 - 컴퓨팅 단위 2개 및 버퍼 단위 3개
기본적으로 파이프라인은를 사용하여 버퍼 데이터를 암호화 AWS 소유 키 합니다. 이 파이프라인에는 파이프라인 역할에 대한 추가 권한이 필요하지 않습니다.
또는 고객 관리형 키를 지정하고 파이프라인 역할에 다음 IAM 권한을 추가할 수 있습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "KeyAccess",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKeyWithoutPlaintext"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/ASIAIOSFODNN7EXAMPLE"
}
]
}
```
------
자세한 내용은 *AWS Key Management Service 개발자 안내서*의 [고객 관리형 키](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk)를 참조하세요.
**참고**
영구 버퍼링을 비활성화하는 경우 파이프라인이 완전히 인 메모리 버퍼링에서 실행되기 시작합니다.
## 분할
수신 이벤트를 하위 파이프라인으로 *분할*하도록 OpenSearch Ingestion 파이프라인을 구성하여 동일한 수신 이벤트에 대해 다양한 유형의 처리를 수행할 수 있습니다.
다음 예제 파이프라인은 수신 이벤트를 두 개의 하위 파이프라인으로 분할합니다. 각 하위 파이프라인은 자체 프로세서를 사용하여 데이터를 보강하고 조작한 다음 데이터를 다양한 OpenSearch 인덱스로 보냅니다.
```
version: "2"
log-pipeline:
source:
http:
...
sink:
- pipeline:
name: "logs_enriched_one_pipeline"
- pipeline:
name: "logs_enriched_two_pipeline"
logs_enriched_one_pipeline:
source:
pipeline:
name: "log-pipeline"
processor:
...
sink:
- opensearch:
# Provide a domain or collection endpoint
# Enable the 'serverless' flag if the sink is an OpenSearch Serverless collection
aws:
...
index: "enriched_one_logs"
logs_enriched_two_pipeline:
source:
pipeline:
name: "log-pipeline"
processor:
...
sink:
- opensearch:
# Provide a domain or collection endpoint
# Enable the 'serverless' flag if the sink is an OpenSearch Serverless collection
aws:
...
index: "enriched_two_logs"
```
## Chaining
데이터 처리 및 보강을 청크 단위로 수행하기 위해 여러 하위 파이프라인을 함께 *연결*할 수 있습니다. 즉, 수신 이벤트를 하나의 하위 파이프라인에서 특정 처리 기능으로 보강한 다음 다른 하위 파이프라인으로 전송하여 다른 프로세서로 추가 보강하고 마지막으로 해당 OpenSearch 싱크로 보낼 수 있습니다.
다음 예제에서 `log_pipeline` 하위 파이프라인은 수신 로그 이벤트를 프로세서 집합으로 보강한 `enriched_logs`이라는 OpenSearch 인덱스로 이벤트를 보냅니다. 파이프라인은 동일한 이벤트를 `log_advanced_pipeline` 하위 파이프라인으로 전송하며, 이는 해당 이벤트를 처리하여 `enriched_advanced_logs`이라는 다른 OpenSearch 인덱스로 보냅니다.
```
version: "2"
log-pipeline:
source:
http:
...
processor:
...
sink:
- opensearch:
# Provide a domain or collection endpoint
# Enable the 'serverless' flag if the sink is an OpenSearch Serverless collection
aws:
...
index: "enriched_logs"
- pipeline:
name: "log_advanced_pipeline"
log_advanced_pipeline:
source:
pipeline:
name: "log-pipeline"
processor:
...
sink:
- opensearch:
# Provide a domain or collection endpoint
# Enable the 'serverless' flag if the sink is an OpenSearch Serverless collection
aws:
...
index: "enriched_advanced_logs"
```
## Dead Letter Queue(DLQ)
DLQ(Dead Letter Queue)는 파이프라인이 싱크에 기록하지 못하는 이벤트의 대상입니다. OpenSearch Ingestion에서는 DLQ로 사용할 적절한 쓰기 권한이 있는 Amazon S3 버킷을 지정해야 합니다. 파이프라인 내의 모든 싱크에 DLQ 구성을 추가할 수 있습니다. 파이프라인에서 쓰기 오류가 발생하면 구성된 S3 버킷에 DLQ 객체가 생성됩니다. DLQ 객체는 JSON 파일 내에 실패한 이벤트의 배열로 존재합니다.
다음 조건 중 하나가 충족되면 파이프라인이 DLQ에 이벤트를 기록합니다.
+ OpenSearch 싱크의 **최대 재시도** 횟수가 소진되었습니다. OpenSearch Ingestion에서 이 설정을 사용하려면 최소 16개가 필요합니다.
+ 오류 상태로 인해 싱크에서 이벤트가 거부됩니다.
### 구성
하위 파이프라인의 Dead Letter Queue(DLQ)를 구성하려면 싱크 대상을 구성할 때 **S3 DLQ 활성화**를 선택합니다. 그런 다음 대기열에 필요한 설정을 지정합니다. 자세한 내용은 Data Prepper DLQ 설명서의 [구성](https://opensearch.org/docs/latest/data-prepper/pipelines/dlq/#configuration)을 참조하세요.
이 S3 DLQ에 기록되는 파일은 다음과 같은 이름 지정 패턴을 갖습니다.
```
dlq-v${version}-${pipelineName}-${pluginId}-${timestampIso8601}-${uniqueId}
```
DLQ가 데이터를 쓰는 S3 버킷에 대한 액세스를 허용하도록 파이프라인 역할을 수동으로 구성하는 지침은 [Amazon S3 또는 Dead Letter Queue(DLQ)에 쓸 권한](pipeline-security-overview.md#pipeline-security-dlq) 섹션을 참조하세요.
### 예제
다음 예제 DLQ 파일을 고려하세요.
```
dlq-v2-apache-log-pipeline-opensearch-2023-04-05T15:26:19.152938Z-e7eb675a-f558-4048-8566-dac15a4f8343
```
다음은 싱크에 기록되지 않고 추가 분석을 위해 DLQ S3 버킷으로 전송되는 데이터의 예입니다.
```
Record_0
pluginId "opensearch"
pluginName "opensearch"
pipelineName "apache-log-pipeline"
failedData
index "logs"
indexId null
status 0
message "Number of retries reached the limit of max retries (configured value 15)"
document
log "sample log"
timestamp "2023-04-14T10:36:01.070Z"
Record_1
pluginId "opensearch"
pluginName "opensearch"
pipelineName "apache-log-pipeline"
failedData
index "logs"
indexId null
status 0
message "Number of retries reached the limit of max retries (configured value 15)"
document
log "another sample log"
timestamp "2023-04-14T10:36:01.071Z"
```
## 인덱스 관리
Amazon OpenSearch Ingestion에는 다음을 비롯한 다양한 인덱스 관리 기능이 있습니다.
### 인덱스 만들기
파이프라인 싱크에 인덱스 이름을 지정할 수 있으며, OpenSearch Ingestion은 파이프라인을 프로비저닝할 때 인덱스를 생성합니다. 인덱스가 이미 있는 경우 파이프라인은 해당 인덱스를 사용하여 수신하는 이벤트를 인덱싱합니다. 파이프라인을 중지했다가 다시 시작하거나 YAML 구성을 업데이트하면 파이프라인은 새 인덱스가 아직 없는 경우 새 인덱스를 만들려고 시도합니다. 파이프라인은 인덱스를 삭제할 수 없습니다.
다음 예제 싱크는 파이프라인이 프로비저닝될 때 두 개의 인덱스를 생성합니다.
```
sink:
- opensearch:
index: apache_logs
- opensearch:
index: nginx_logs
```
### 인덱스 이름 및 패턴 생성
수신 이벤트 필드의 변수를 사용하여 동적 인덱스 이름을 생성할 수 있습니다. 싱크 구성에서는 형식 `string${}`을 사용하여 문자열 보간을 알리고 JSON 포인터를 사용하여 이벤트에서 필드를 추출합니다. `index_type`의 옵션은 `custom` 또는 `management_disabled`입니다. OpenSearch 도메인의 `custom`과 OpenSearch 서버리스 컬렉션의 `management_disabled`에는 `index_type` 기본값이 사용되므로 설정하지 않은 상태로 둘 수 있습니다.
예를 들어 다음 파이프라인은 수신 이벤트에서 `metadataType` 필드를 선택하여 인덱스 이름을 생성합니다.
```
pipeline:
...
sink:
opensearch:
index: "metadata-${metadataType}"
```
다음 구성은 매일 또는 1시간마다 새 인덱스를 계속 생성합니다.
```
pipeline:
...
sink:
opensearch:
index: "metadata-${metadataType}-%{yyyy.MM.dd}"
pipeline:
...
sink:
opensearch:
index: "metadata-${metadataType}-%{yyyy.MM.dd.HH}"
```
인덱스 이름은 `my-index-%{yyyy.MM.dd}`와 같은 접미사로 날짜-시간 패턴을 포함하는 일반 문자열일 수도 있습니다. 싱크가 OpenSearch로 데이터를 보내면 날짜-시간 패턴을 UTC 시간으로 바꾸고 각 날짜에 대해 `my-index-2022.01.25`와 같은 새 인덱스를 생성합니다. 자세한 내용은 [DateTimeformatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html) 클래스를 참조하세요.
이 인덱스 이름은 `my-${index}-name`(와)과 같은 접미사로 날짜-시간 패턴을 포함 또는 미포함하는 문자열 형식일 수도 있습니다. 싱크가 OpenSearch로 데이터를 보내면 `"${index}"` 부분이 처리 중인 이벤트의 값으로 바뀝니다. 형식이 `"${index1/index2/index3}"`인 경우 필드 `index1/index2/index3`가 이벤트의 값으로 대체합니다.
### 문서 ID 생성
파이프라인은 문서를 OpenSearch에 인덱싱하는 동안 문서 ID를 생성할 수 있습니다. 수신 이벤트 내의 필드에서 이러한 문서 ID를 유추할 수 있습니다.
이 예제에서는 수신 이벤트의 `uuid` 필드를 사용하여 문서 ID를 생성합니다.
```
pipeline:
...
sink:
opensearch:
index_type: custom
index: "metadata-${metadataType}-%{yyyy.MM.dd}"
"document_id": "uuid"
```
다음 예제에서 [항목 추가](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/add-entries/) 프로세서는 수신 이벤트의 `uuid` 및 `other_field` 필드를 병합하여 문서 ID를 생성합니다.
`create` 작업을 수행하면 ID가 동일한 문서를 덮어쓰지 않습니다. 파이프라인은 재시도 또는 DLQ 이벤트 없이 중복 문서를 삭제합니다. 기존 문서를 업데이트하지 않는 것이 목적이므로 이 작업을 사용하는 파이프라인 작성자에게는 이 작업을 예상하는 것이 합리적입니다.
```
pipeline:
...
processor:
- add_entries:
entries:
- key: "my_doc_id_field"
format: "${uuid}-${other_field}"
sink:
- opensearch:
...
action: "create"
document_id: "my_doc_id"
```
이벤트의 문서 ID를 하위 객체의 필드로 설정하고 싶을 수도 있습니다. 다음 예제에서 OpenSearch 싱크 플러그인은 하위 개체 `info/id`를 사용하여 문서 ID를 생성합니다.
```
sink:
- opensearch:
...
document_id: info/id
```
다음 이벤트가 발생하면 파이프라인은 `json001`로 설정된 `_id` 필드로 문서를 생성합니다.
```
{
"fieldA":"arbitrary value",
"info":{
"id":"json001",
"fieldA":"xyz",
"fieldB":"def"
}
}
```
### 라우팅 ID 생성
OpenSearch 싱크 플러그인 내 `routing_field` 옵션을 사용하여 문서 라우팅 속성(`_routing`)의 값을 수신 이벤트의 값으로 설정할 수 있습니다.
라우팅은 JSON 포인터 구문을 지원하므로 최상위 필드뿐 아니라 중첩된 필드도 사용할 수 있습니다.
```
sink:
- opensearch:
...
routing_field: metadata/id
document_id: id
```
다음 이벤트가 발생하면 플러그인은 `abcd`로 설정된 `_routing` 필드로 문서를 생성합니다.
```
{
"id":"123",
"metadata":{
"id":"abcd",
"fieldA":"valueA"
},
"fieldB":"valueB"
}
```
파이프라인이 인덱스 생성 중에 사용할 수 있는 인덱스 템플릿을 만드는 방법에 대한 지침은 [인덱스 템플릿](https://opensearch.org/docs/latest/im-plugin/index-templates/)을 참조하세요.
## 엔드 투 엔드 승인
OpenSearch Ingestion은 *엔드 투 엔드 승인*을 사용하여 상태 비저장 파이프라인의 소스에서 싱크까지의 데이터 전달을 추적함으로써 데이터의 내구성과 신뢰성을 보장합니다.
**참고**
현재는 [S3 소스](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/s3/) 플러그인만 엔드 투 엔드 승인을 지원합니다.
엔드 투 엔드 승인을 통해 파이프라인 소스 플러그인은 *승인 세트*를 생성하여 이벤트 배치를 모니터링합니다. 이벤트가 싱크로 성공적으로 전송되면 긍정적인 승인을 받고, 싱크로 전송할 수 없는 이벤트가 있을 때는 부정적인 승인을 받습니다.
파이프라인 구성 요소에 장애 또는 충돌이 발생하거나 소스가 승인을 받지 못하는 경우 소스는 제한 시간이 초과되어 실패 재시도 또는 로깅과 같은 필요한 조치를 취합니다. 파이프라인에 싱크가 여러 개 있거나 하위 파이프라인이 여러 개 구성된 경우 이벤트가 *모든* 하위 파이프라인의 *모든* 싱크에 전송된 후에만 이벤트 수준 승인이 전송됩니다. 싱크에 DLQ가 구성된 경우 엔드 투 엔드 승인은 DLQ에 기록된 이벤트도 추적합니다.
엔드 투 엔드 승인을 활성화하려면 Amazon S3 소스 구성에서 **추가 옵션**을 확장하고 **엔드 투 엔드 메시지 승인 활성화**를 선택합니다.
## 소스 역압
파이프라인이 데이터를 처리하느라 바쁠 때, 싱크가 일시적으로 다운되거나 데이터 수집 속도가 느릴 경우 역압이 발생할 수 있습니다. OpenSearch Ingestion은 파이프라인이 사용하는 소스 플러그인에 따라 배압을 처리하는 방법이 다릅니다.
### HTTP 소스
[HTTP 소스](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/http-source/) 플러그인을 사용하는 파이프라인은 혼잡한 파이프라인 구성 요소에 따라 배압을 다르게 처리합니다.
+ **버퍼** - 버퍼가 가득 차면 파이프라인이 오류 코드 408과 함께 HTTP 상태 `REQUEST_TIMEOUT`를 소스 엔드포인트로 반환하기 시작합니다. 버퍼가 비워지면 파이프라인은 HTTP 이벤트 처리를 다시 시작합니다.
+ **소스 스레드** — 모든 HTTP 소스 스레드가 요청을 실행하는 중이고 처리되지 않은 요청 대기열 크기가 허용된 최대 요청 수를 초과하면 파이프라인은 오류 코드 429와 함께 HTTP 상태 `TOO_MANY_REQUESTS`를 소스 엔드포인트로 반환하기 시작합니다. 요청 대기열이 최대 허용 대기열 크기 아래로 떨어지면 파이프라인은 요청 처리를 다시 시작합니다.
### OTel 소스
OpenTelemetry 소스([OTel 로그](https://github.com/opensearch-project/data-prepper/tree/main/data-prepper-plugins/otel-logs-source), [oTel 지표](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-metrics-source/), [OTel 추적](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-trace/))를 사용하는 파이프라인의 버퍼가 가득 차면 파이프라인은 오류 코드 408과 함께 HTTP 상태 `REQUEST_TIMEOUT`를 소스 엔드포인트에 반환하기 시작합니다. 버퍼가 비워지면 파이프라인은 이벤트 처리를 다시 시작합니다.
### S3 소스
[S3](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/s3/) 소스가 있는 파이프라인의 버퍼가 가득 차면 파이프라인의 SQS 알림 처리가 중지됩니다. 버퍼가 비워지면 파이프라인에서 알림 처리를 다시 시작합니다.
싱크가 중단되거나 데이터를 수집할 수 없고 소스에 대한 포괄적인 승인이 활성화된 경우 파이프라인은 모든 싱크로부터 성공적인 승인을 받을 때까지 SQS 알림 처리를 중단합니다.
# Amazon OpenSearch Ingestion 파이프라인 생성
*파이프라인*은 Amazon OpenSearch Ingestion이 데이터를 *소스*(데이터의 출처)에서 *싱크 *(데이터가 이동하는 곳)로 이동하는 데 사용하는 메커니즘입니다. OpenSearch Ingestion에서 싱크는 항상 단일 Amazon OpenSearch Service 도메인이지만, 데이터 소스는 Amazon S3, Fluent Bit 또는 OpenTelemetry Collector와 같은 클라이언트일 수 있습니다.
자세한 내용은 OpenSearch 설명서의 [파이프라인](https://opensearch.org/docs/latest/clients/data-prepper/pipelines/)을 참조하세요.
**Topics**
+ [
## 사전 조건 및 필요한 IAM 역할
](#manage-pipeline-prerequisites)
+ [
## 필수 IAM 권한
](#create-pipeline-permissions)
+ [
## 파이프라인 버전 지정
](#pipeline-version)
+ [
## 수집 경로 지정
](#pipeline-path)
+ [
## 파이프라인 생성
](#create-pipeline)
+ [
## 파이프라인 생성 상태 추적
](#get-pipeline-progress)
+ [
# 블루프린트 작업
](pipeline-blueprint.md)
## 사전 조건 및 필요한 IAM 역할
OpenSearch Ingestion 파이프라인을 생성하려면 다음과 같은 리소스가 있어야 합니다.
+ 싱크에 쓰기 위해 OpenSearch Ingestion이 맡게 되는, *파이프라인 역할*이라는 IAM 역할. 이 역할을 미리 생성하거나 파이프라인을 생성하는 동안 OpenSearch Ingestion에서 자동으로 생성되도록 할 수 있습니다.
+ 싱크 역할을 하는 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션입니다. 도메인에 쓰는 경우 OpenSearch 1.0 이상 또는 Elasticsearch 7.4 이상이 실행되고 있어야 합니다. 싱크에는 IAM 파이프라인 역할에 적절한 권한을 부여하는 액세스 정책이 있어야 합니다.
이러한 리소스를 만드는 방법 설명은 다음 주제를 참조하세요.
+ [도메인에 대한 Amazon OpenSearch Ingestion 파이프라인 액세스 권한 부여](pipeline-domain-access.md)
+ [컬렉션에 대한 액세스 권한을 Amazon OpenSearch Ingestion 파이프라인에 부여](pipeline-collection-access.md)
**참고**
세분화된 액세스 제어를 사용하는 도메인에 쓰는 경우 완료해야 할 추가 단계가 있습니다. [파이프라인 역할 매핑(세분화된 액세스 제어를 사용하는 도메인에만 해당)](pipeline-domain-access.md#pipeline-access-domain-fgac)을(를) 참조하세요.
## 필수 IAM 권한
OpenSearch Ingestion은 다음 IAM 권한을 사용하여 파이프라인을 생성합니다.
+ `osis:CreatePipeline` - 파이프라인을 생성합니다.
+ `osis:ValidatePipeline`— 파이프라인 구성이 유효한지 확인하세요.
+ `iam:CreateRole` 및 `iam:AttachPolicy` - OpenSearch Ingestion이 자동으로 파이프라인 역할을 생성하도록 합니다.
+ `iam:PassRole` - OpenSearch Ingestion에 파이프라인 역할을 전달하여 도메인에 데이터를 쓸 수 있도록 합니다. 이 권한은 [파이프라인 역할 리소스](pipeline-domain-access.md#pipeline-access-configure)에 있어야 하며, 각 파이프라인에서 다른 역할을 사용하려는 경우 `*`로 지정합니다.
예를 들어 다음 정책에서 파이프라인을 호출할 권한을 부여합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Resource":"*",
"Action":[
"osis:CreatePipeline",
"osis:ListPipelineBlueprints",
"osis:ValidatePipeline"
]
},
{
"Resource":[
"arn:aws:iam::111122223333:role/pipeline-role"
],
"Effect":"Allow",
"Action":[
"iam:CreateRole",
"iam:AttachRolePolicy",
"iam:PassRole"
]
}
]
}
```
------
OpenSearch Ingestion에는 [서명 버전 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)를 사용하여 파이프라인에 서명된 요청을 보내는 데 필요한 `osis:Ingest` 권한도 포함되어 있습니다. 자세한 내용은 [수집 역할 생성](configure-client.md#configure-client-auth) 단원을 참조하십시오.
**참고**
또한 계정에서 파이프라인을 생성하는 첫 번째 사용자에게 `iam:CreateServiceLinkedRole` 작업에 대한 권한이 있어야 합니다. 자세한 내용은 [파이프라인 역할 리소스](pipeline-security.md#pipeline-vpc-slr)를 참조하세요.
각 권한에 대한 자세한 내용은 *서비스 권한 부여 참조*에서 [OpenSearch Ingestion에 대한 작업, 리소스 및 조건 키](https://docs.aws.amazon.com/service-authorization/latest/reference/list_opensearchingestionservice.html)에 대한 액션, 리소스 및 조건 키를 참조하세요.
## 파이프라인 버전 지정
구성 편집기를 사용하여 파이프라인을 생성할 때 파이프라인이 실행할 [Data Prepper의 메이저 버전](https://github.com/opensearch-project/data-prepper/releases)을 지정해야 합니다. 버전을 지정하려면 파이프라인 구성에 `version` 옵션을 포함하세요.
```
version: "2"
log-pipeline:
source:
...
```
**생성**을 선택하면 OpenSearch Ingestion은 지정한 메이저 버전의 사용 가능한 최신 *마이너* 버전을 확인하고 해당 버전으로 파이프라인을 프로비저닝합니다. 예를 들어 `version: "2"`을 지정하고 Data Prepper의 최신 지원 버전이 2.1.1인 경우 OpenSearch Ingestion은 파이프라인을 버전 2.1.1로 프로비저닝합니다. 파이프라인이 실행 중인 마이너 버전은 공개적으로 표시하지 않습니다.
Data Prepper의 새 메이저 버전이 출시될 때 파이프라인을 업그레이드하려면 파이프라인 구성을 편집하고 새 버전을 지정하세요. 파이프라인을 이전 버전으로 다운그레이드할 수 없습니다.
**참고**
OpenSearch Ingestion은 새 버전의 Data Prepper가 출시되자마자 바로 지원되지는 않습니다. 새 버전이 공개되는 시점과 OpenSearch Ingestion에서 새 버전이 지원되는 시점 사이에는 약간의 지연이 있을 수 있습니다. 또한 OpenSearch Ingestion은 명시적으로 특정 메이저 또는 마이너 버전을 모두 지원하지 않을 수도 있습니다. 포괄적인 목록은 [지원되는 Data Prepper 버전](ingestion.md#ingestion-supported-versions) 섹션을 참조하십시오.
블루/그린 배포를 시작하는 파이프라인을 변경할 때마다 OpenSearch Ingestion은 파이프라인에 현재 구성되어 있는 메이저 버전의 최신 마이너 버전으로 업그레이드할 수 있습니다. 자세한 내용은 [파이프라인 업데이트를 위한 블루/그린 배포](update-pipeline.md#pipeline-bg) 단원을 참조하십시오. OpenSearch Ingestion은 파이프라인 구성 내에서 `version` 옵션을 명시적으로 업데이트하지 않는 한 파이프라인의 메이저 버전을 변경할 수 없습니다.
## 수집 경로 지정
[OTel 추적](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-trace/) 및 [oTel 지표](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-metrics-source/)와 같은 풀 기반 소스의 경우 OpenSearch Ingestion을 사용하려면 소스 구성에 `path` 옵션이 추가로 필요합니다. 경로는 수집을 위한 URI 경로를 나타내는 `/log/ingest`와 같은 문자열입니다. 이 경로는 파이프라인으로 데이터를 전송하는 데 사용하는 URI를 정의합니다.
예를 들어 HTTP 소스가 있는 파이프라인에 대해 다음 경로를 지정한다고 가정해 보겠습니다.
![\[Input field for specifying the path for ingestion, with an example path entered.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/ingestion-path.png)
파이프라인으로 [데이터를 수집](configure-client.md)할 때는 클라이언트 구성에서 `https://pipeline-name-abc123.us-west-2.osis.amazonaws.com/my/test_path`와 같은 엔드포인트를 지정해야 합니다.
경로는 슬래시(/) 로 시작해야 하며 특수 문자 '-', '\$1', '.', '/'를 비롯해 `${pipelineName}` 자리 표시자를 포함할 수 있습니다. `${pipelineName}`(예:`/${pipelineName}/test_path`)를 사용하면 OpenSearch Ingestion은 변수를 관련 하위 파이프라인의 이름으로 대체합니다.
## 파이프라인 생성
이 섹션에서는 OpenSearch Service 콘솔 및 AWS CLI을 사용하여 OpenSearch Ingestion 파이프라인을 생성하는 방법을 설명합니다.
### 콘솔
파이프라인을 생성하려면 [https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) Amazon OpenSearch Service 콘솔에 로그인하고 **파이프라인 생성을** 선택합니다.
빈 파이프라인을 선택하거나 구성 블루프린트를 선택합니다. 블루프린트에는 다양한 공통 사용 사례를 위한 사전 구성된 파이프라인이 포함됩니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
**블루프린트 선택**을 선택합니다.
#### 소스를 구성합니다.
1. 빈 파이프라인에서 시작하는 경우 드롭다운 메뉴에서 소스를 선택합니다. 사용 가능한 소스에는 기타 AWS 서비스, OpenTelemetry 또는 HTTP가 포함될 수 있습니다. 자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인을 다른 서비스 및 애플리케이션과 통합](configure-client.md) 단원을 참조하십시오.
1. 선택한 소스에 따라 소스에 대한 추가 설정을 구성합니다. 예를 들어 Amazon S3를 소스로 사용하려면 파이프라인에서 메시지를 수신하는 Amazon SQS 대기열의 URL을 지정해야 합니다. 지원되는 소스 플러그인 및 설명서 링크 목록은 [Amazon OpenSearch Ingestion 파이프라인에 지원되는 플러그인 및 옵션](pipeline-config-reference.md) 섹션을 참조하세요.
1. 일부 소스의 경우 **소스 네트워크 옵션**을 지정해야 합니다. **VPC 액세스** 또는 **퍼블릭 액세스**를 선택합니다. **퍼블릭 액세스(Public access)**를 선택한 경우, 다음 단계로 건너뜁니다. **VPC 액세스**를 선택하는 경우 다음 설정을 구성하세요.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/creating-pipeline.html)
자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인에 대한 VPC 액세스 구성](pipeline-security.md) 단원을 참조하십시오.
1. **다음**을 선택합니다.
#### 프로세서 구성
파이프라인에 프로세서를 하나 이상 추가합니다. 프로세서는 하위 파이프라인 내의 구성 요소로, 도메인 또는 컬렉션 싱크에 레코드를 게시하기 전에 이벤트를 필터링, 변환, 보강할 수 있습니다. 지원되는 프로세서 및 설명서 링크 목록은 [Amazon OpenSearch Ingestion 파이프라인에 지원되는 플러그인 및 옵션](pipeline-config-reference.md) 섹션을 참조하세요.
**작업**을 선택하고 다음을 추가할 수 있습니다.
+ **조건부 라우팅** - 특정 조건에 따라 이벤트를 다른 싱크로 라우팅합니다. 자세한 내용은 [조건부 라우팅](https://opensearch.org/docs/latest/data-prepper/pipelines/pipelines/#conditional-routing)을 참조하세요.
+ **하위 파이프라인** – 각 하위 파이프라인은 단일 소스, 0개 이상의 프로세서, 단일 싱크의 조합입니다. 외부 소스는 하나의 하위 파이프라인에만 있을 수 있습니다. 다른 모든 하위 파이프라인에는 전체 파이프라인 구성 내의 다른 하위 파이프라인인 소스가 있어야 합니다. 단일 파이프라인 구성은 1\$110개의 하위 파이프라인을 포함할 수 있습니다.
**다음**을 선택합니다.
#### 싱크 구성
파이프라인이 레코드를 게시하는 대상을 선택합니다. 모든 하위 파이프라인에는 하나 이상의 싱크가 포함되어야 합니다. 파이프라인에는 최대 10개의 싱크를 추가할 수 있습니다.
OpenSearch의 경우 다음 필드를 구성합니다.
| 설정 | 설명 |
| --- | --- |
| 네트워크 정책 이름(서버리스 싱크만 해당) | OpenSearch Serverless 컬렉션을 선택한 경우 **네트워크 정책 이름**을 입력합니다. OpenSearch Ingestion은 정책이 없는 경우 정책을 생성하거나, 파이프라인과 컬렉션을 연결하는 VPC 엔드포인트에 대한 액세스 권한을 부여하는 규칙으로 정책을 업데이트합니다. 자세한 내용은 [컬렉션에 대한 액세스 권한을 Amazon OpenSearch Ingestion 파이프라인에 부여](pipeline-collection-access.md) 단원을 참조하십시오. |
| 인덱스 이름 | 파이프라인이 데이터를 전송하는 인덱스의 이름입니다. OpenSearch Ingestion은 인덱스가 아직 없는 경우 이 인덱스를 생성합니다. |
| 인덱스 매핑 옵션 | 파이프라인이 문서와 해당 필드를 OpenSearch 싱크에 저장하고 인덱싱하는 방법을 선택합니다. **동적 매핑**을 선택하면 문서를 인덱싱할 때 OpenSearch가 자동으로 필드를 추가합니다. **매핑 사용자 지정**을 선택한 경우에는 인덱스 매핑 템플릿을 입력합니다. 자세한 내용은 [인덱스 템플릿](https://opensearch.org/docs/latest/im-plugin/index-templates/)을 참조하세요. |
| DLQ 활성화 | 파이프라인의 Amazon S3 Dead Letter Queue(DLQ)를 구성합니다. 자세한 내용은 [Dead Letter Queue(DLQ)](osis-features-overview.md#osis-features-dlq) 단원을 참조하십시오. |
| 추가 설정 | OpenSearch 싱크에 대한 고급 옵션을 구성합니다. 자세한 내용은 Data Prepper 설명서의 [구성 옵션](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/opensearch/#configuration-options)을 참조하세요. |
Amazon S3 싱크를 추가하려면 **싱크 추가**와 **Amazon S3**를 차례로 선택합니다. 자세한 내용은 [대상으로서의 Amazon S3](configure-client-s3.md#s3-destination) 단원을 참조하십시오.
**다음**을 선택합니다.
#### 파이프라인 구성
다음 추가 파이프라인 설정을 구성합니다.
| 설정 | 설명 |
| --- | --- |
| 파이프라인 이름 | 파이프라인의 고유 이름입니다. |
| 영구 버퍼 | 영구 버퍼는 여러 가용 영역 간에서 디스크 기반 버퍼에 데이터를 저장합니다. 자세한 내용은 [영구 버퍼링](osis-features-overview.md#persistent-buffering) 단원을 참조하십시오. 영구 버퍼링을 활성화하는 경우 버퍼 데이터를 암호화할 AWS Key Management Service 키를 선택합니다. |
| 파이프라인 용량 | Ingestion OpenSearch Compute Units(OCU)의 최소 및 최대 파이프라인 용량입니다. 자세한 내용은 [Amazon OpenSearch Ingestion에서 파이프라인 규모 조정](ingestion-scaling.md) 단원을 참조하십시오. |
| 파이프라인 역할 | 파이프라인이 싱크에 쓰고 풀 기반 소스에서 읽는 데 필요한 권한을 제공하는 IAM 역할입니다. 역할을 직접 생성하거나, 선택한 사용 사례에 따라 OpenSearch Ingestion이 역할을 생성하도록 할 수 있습니다. 자세한 내용은 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md) 단원을 참조하십시오. |
| Tags | 파이프라인에 하나 이상의 태그를 추가합니다. 자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인 태그 지정](tag-pipeline.md) 단원을 참조하십시오. |
| 로그 게시 옵션 | Amazon CloudWatch Logs로의 파이프라인 로그 게시를 활성화합니다. 파이프라인 문제를 보다 쉽게 해결할 수 있도록 로그 게시를 활성화하는 것이 좋습니다. 자세한 내용은 [파이프라인 모니터링](monitoring-pipeline-logs.md) 단원을 참조하십시오. |
**다음**을 선택한 후 파이프라인 구성을 검토하고 **파이프라인 생성**을 선택합니다.
OpenSearch Ingestion은 비동기 프로세스를 실행하여 파이프라인을 구축합니다. 파이프라인이 `Active` 상태가 되면 데이터 수집을 시작할 수 있습니다.
### AWS CLI
[create-pipeline](https://docs.aws.amazon.com/cli/latest/reference/osis/create-pipeline.html) 명령어는 파이프라인 구성을 문자열로, 아니면 .yaml 또는 .json 파일 내에서 받아들입니다. 구성을 문자열로 제공하는 경우 각 새 줄을 `\n`로 이스케이프해야 합니다. 예: `"log-pipeline:\n source:\n http:\n processor:\n - grok:\n ...`
다음 샘플 명령은 다음과 같은 구성으로 파이프라인을 생성합니다.
+ 최소 4개의 Ingestion OCU, 최대 10개의 Ingestion OCU
+ Virtual Private Cloud(VPC) 내에서 프로비저닝됨
+ 로그 게시 활성
```
aws osis create-pipeline \
--pipeline-name my-pipeline \
--min-units 4 \
--max-units 10 \
--log-publishing-options IsLoggingEnabled=true,CloudWatchLogDestination={LogGroup="MyLogGroup"} \
--vpc-options SecurityGroupIds={sg-12345678,sg-9012345},SubnetIds=subnet-1212234567834asdf \
--pipeline-configuration-body "file://pipeline-config.yaml" \
--pipeline-role-arn arn:aws:iam::1234456789012:role/pipeline-role
```
OpenSearch Ingestion은 비동기 프로세스를 실행하여 파이프라인을 구축합니다. 파이프라인이 `Active` 상태가 되면 데이터 수집을 시작할 수 있습니다. 파이프라인 상태를 확인하려면 [GetPipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_GetPipeline.html) 명령을 사용하세요.
### OpenSearch Ingestion API
OpenSearch Ingestion API를 사용하여 OpenSearch Ingestion 파이프라인을 생성하려면 [CreatePipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_CreatePipeline.html) 작업을 호출하세요.
파이프라인이 성공적으로 생성되면 클라이언트를 구성하고 OpenSearch Service 도메인으로 데이터 수집을 시작할 수 있습니다. 자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인을 다른 서비스 및 애플리케이션과 통합](configure-client.md) 단원을 참조하십시오.
## 파이프라인 생성 상태 추적
OpenSearch Ingestion이 파이프라인을 프로비저닝하고 데이터 수집을 준비할 때 파이프라인의 상태를 추적할 수 있습니다.
### 콘솔
파이프라인을 처음 생성한 후에는 OpenSearch Ingestion에서 데이터 수집을 준비하면서 여러 단계를 거칩니다. 파이프라인 생성의 다양한 단계를 보려면 파이프라인 이름을 선택하여 해당 **파이프라인 설정** 페이지를 확인하세요. **상태**에서 **세부 정보 보기**를 선택합니다.
파이프라인은 다음 단계를 거친 후 데이터를 수집할 수 있게 됩니다.
+ **검증** — 파이프라인 구성을 검증합니다. 이 단계가 완료되면 모든 검증이 성공한 것입니다.
+ **환경 조성** — 리소스를 준비 및 프로비저닝합니다. 이 단계가 완료되면 새 파이프라인 환경이 만들어진 것입니다.
+ **파이프라인 배포** - 파이프라인을 배포합니다. 이 단계가 완료되면 파이프라인이 성공적으로 배포된 것입니다.
+ **파이프라인 상태 확인** - 파이프라인 상태를 확인합니다. 이 단계가 완료되면 모든 상태 확인이 통과된 것입니다.
+ **트래픽 활성화** - 파이프라인이 데이터를 수집할 수 있도록 합니다. 이 단계가 완료되면 파이프라인으로 데이터 수집을 시작할 수 있습니다.
### CLI
파이프라인 상태를 확인하려면 [get-pipeline-change-progress](https://docs.aws.amazon.com/cli/latest/reference/osis/get-pipeline-change-progress.html) 명령을 사용하세요. 다음 AWS CLI 요청은 라는 파이프라인의 상태를 확인합니다`my-pipeline`.
```
aws osis get-pipeline-change-progress \
--pipeline-name my-pipeline
```
**응답**:
```
{
"ChangeProgressStatuses": {
"ChangeProgressStages": [
{
"Description": "Validating pipeline configuration",
"LastUpdated": 1.671055851E9,
"Name": "VALIDATION",
"Status": "PENDING"
}
],
"StartTime": 1.671055851E9,
"Status": "PROCESSING",
"TotalNumberOfStages": 5
}
}
```
### OpenSearch Ingestion API
OpenSearch Ingestion API를 사용하여 파이프라인 생성 상태를 추적하려면 [GetPipelineChangeProgress](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_GetPipelineChangeProgress.html) 작업을 호출하세요.
# 블루프린트 작업
파이프라인 정의를 처음부터 생성하는 대신 Trace Analytics 또는 Apache 로그와 같은 일반적인 수집 시나리오를 위해 사전 구성된 템플릿인 *구성 청사진*을 사용할 수 있습니다. 구성 청사진을 사용하면 구성을 처음부터 작성하지 않고도 파이프라인을 쉽게 프로비저닝할 수 있습니다.
## 콘솔
**파이프라인 청사진 사용**
1. [https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) OpenSearch Ingestion 콘솔에 로그인합니다. 파이프라인 페이지에 표시됩니다.
1. [**파이프라인 생성**]을 선택합니다.
1. 사용 사례 목록에서 블루프린트를 선택한 다음, **블루프린트 선택**을 선택합니다. 파이프라인 구성은 선택한 사용 사례의 하위 파이프라인으로 채워집니다.
파이프라인 청사진은 현재 상태로는 유효하지 않습니다. 선택한 소스에 따라 추가 설정을 지정해야 합니다.
## CLI
를 사용하여 사용 가능한 모든 블루프린트 목록을 가져오려면 [list-pipeline-blueprints](https://docs.aws.amazon.com/cli/latest/reference/osis/list-pipeline-blueprints.html) 요청을 AWS CLI보냅니다.
```
aws osis list-pipeline-blueprints
```
이 요청은 사용 가능한 모든 청사진의 목록을 반환합니다.
특정 청사진에 대한 자세한 정보를 얻으려면 [get-pipeline-blueprint](https://docs.aws.amazon.com/cli/latest/reference/osis/get-pipeline-blueprint.html) 명령어를 사용하세요.
```
aws osis get-pipeline-blueprint --blueprint-name AWS-ApacheLogPipeline
```
이 요청은 Apache 로그 파이프라인 청사진의 콘텐츠를 반환합니다.
```
{
"Blueprint":{
"PipelineConfigurationBody":"###\n # Limitations: https://docs.aws.amazon.com/opensearch-service/latest/ingestion/ingestion.html#ingestion-limitations\n###\n###\n # apache-log-pipeline:\n # This pipeline receives logs via http (e.g. FluentBit), extracts important values from the logs by matching\n # the value in the 'log' key against the grok common Apache log pattern. The grokked logs are then sent\n # to OpenSearch to an index named 'logs'\n###\n\nversion: \"2\"\napache-log-pipeline:\n source:\n http:\n # Provide the path for ingestion. ${pipelineName} will be replaced with pipeline name configured for this pipeline.\n # In this case it would be \"/apache-log-pipeline/logs\". This will be the FluentBit output URI value.\n path: \"/${pipelineName}/logs\"\n processor:\n - grok:\n match:\n log: [ \"%{COMMONAPACHELOG_DATATYPED}\" ]\n sink:\n - opensearch:\n # Provide an AWS OpenSearch Service domain endpoint\n # hosts: [ \"https://search-mydomain-1a2a3a4a5a6a7a8a9a0a9a8a7a.us-east-1.es.amazonaws.com\" ]\n aws:\n # Provide the region of the domain.\n # region: \"us-east-1\"\n # Enable the 'serverless' flag if the sink is an Amazon OpenSearch Serverless collection\n # serverless: true\n index: \"logs\"\n # Enable the S3 DLQ to capture any failed requests in an S3 bucket\n # dlq:\n # s3:\n # Provide an S3 bucket\n # bucket: \"your-dlq-bucket-name\"\n # Provide a key path prefix for the failed requests\n # key_path_prefix: \"${pipelineName}/logs/dlq\"\n # Provide the region of the bucket.\n # region: \"us-east-1\"\n # Provide a Role ARN with access to the bucket. This role should have a trust relationship with osis-pipelines.amazonaws.com\n"
"BlueprintName":"AWS-ApacheLogPipeline"
}
}
```
## OpenSearch Ingestion API
OpenSearch Ingestion API를 사용하여 파이프라인 청사진에 대한 정보를 가져오려면 [ListPipelineBlueprints](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_ListPipelineBlueprints.html) 및 [GetPipelineBlueprint](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_GetPipelineBlueprint.html) 작업을 사용하세요.
# Amazon OpenSearch Ingestion 파이프라인 보기
AWS Management Console, AWS CLI또는 OpenSearch Ingestion API를 사용하여 Amazon OpenSearch Ingestion 파이프라인에 대한 세부 정보를 확인할 수 있습니다.
## 콘솔
**파이프라인을 보려면**
1. [https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) Amazon OpenSearch Service 콘솔에 로그인합니다. 파이프라인 페이지에 표시됩니다.
1. (선택 사항) 특정 상태의 파이프라인을 보려면 **모든 상태**를 선택하고 필터링 기준으로 사용할 상태를 선택합니다.
파이프라인은 다음과 같은 상태일 수 있습니다.
+ `Active`— 파이프라인이 활성 상태이며 데이터를 수집할 준비가 되었습니다.
+ `Creating`— 파이프라인이 생성되고 있습니다.
+ `Updating`— 파이프라인이 업데이트되고 있습니다.
+ `Deleting`— 파이프라인이 삭제되고 있습니다.
+ `Create failed`— 파이프라인을 생성할 수 없습니다.
+ `Update failed` - 파이프라인을 업데이트할 수 없습니다.
+ `Stop failed` - 파이프라인을 중지할 수 없습니다.
+ `Start failed` - 파이프라인을 시작할 수 없습니다.
+ `Stopping`— 파이프라인이 중지되고 있습니다.
+ `Stopped`— 파이프라인이 중지되었으며 언제든지 다시 시작할 수 있습니다.
+ `Starting`— 파이프라인이 시작되고 있습니다.
파이프라인이 `Create failed`, `Creating`, `Deleting`, 및 `Stopped` 상태일 때는 Ingestion OCU에 대한 요금이 청구되지 않습니다.
## CLI
를 사용하여 파이프라인을 보려면 [list-pipelines](https://docs.aws.amazon.com/cli/latest/reference/osis/list-pipelines.html) 요청을 AWS CLI보냅니다.
```
aws osis list-pipelines
```
요청은 기존의 모든 파이프라인 목록을 반환합니다.
```
{
"NextToken": null,
"Pipelines": [
{,
"CreatedAt": 1.671055851E9,
"LastUpdatedAt": 1.671055851E9,
"MaxUnits": 4,
"MinUnits": 2,
"PipelineArn": "arn:aws:osis:us-west-2:123456789012:pipeline/log-pipeline",
"PipelineName": "log-pipeline",
"Status": "ACTIVE",
"StatusReason": {
"Description": "The pipeline is ready to ingest data."
}
},
"CreatedAt": 1.671055851E9,
"LastUpdatedAt": 1.671055851E9,
"MaxUnits": 2,
"MinUnits": 8,
"PipelineArn": "arn:aws:osis:us-west-2:123456789012:pipeline/another-pipeline",
"PipelineName": "another-pipeline",
"Status": "CREATING",
"StatusReason": {
"Description": "The pipeline is being created. It is not able to ingest data."
}
}
]
}
```
단일 파이프라인에 대한 정보를 가져오려면 [get-pipeline](https://docs.aws.amazon.com/cli/latest/reference/osis/get-pipeline.html) 명령을 사용하세요.
```
aws osis get-pipeline --pipeline-name "my-pipeline"
```
요청은 지정된 파이프라인의 구성 정보를 반환합니다.
```
{
"Pipeline": {
"PipelineName": "my-pipeline",
"PipelineArn": "arn:aws:osis:us-east-1:123456789012:pipeline/my-pipeline",
"MinUnits": 9,
"MaxUnits": 10,
"Status": "ACTIVE",
"StatusReason": {
"Description": "The pipeline is ready to ingest data."
},
"PipelineConfigurationBody": "log-pipeline:\n source:\n http:\n processor:\n - grok:\n match:\nlog: [ '%{COMMONAPACHELOG}' ]\n - date:\n from_time_received: true\n destination: \"@timestamp\"\n sink:\n - opensearch:\n hosts: [ \"https://search-mdp-performance-test-duxkb4qnycd63rpy6svmvyvfpi.us-east-1.es.amazonaws.com\" ]\n index: \"apache_logs\"\n aws_sts_role_arn: \"arn:aws:iam::123456789012:role/my-domain-role\"\n aws_region: \"us-east-1\"\n aws_sigv4: true",,
"CreatedAt": "2022-10-01T15:28:05+00:00",
"LastUpdatedAt": "2022-10-21T21:41:08+00:00",
"IngestEndpointUrls": [
"my-pipeline-123456789012.us-east-1.osis.amazonaws.com"
]
}
}
```
## OpenSearch Ingestion API
OpenSearch Ingestion API를 사용하여 OpenSearch Ingestion 파이프라인을 보려면 [ListPipelines](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_ListPipelines.html) 및 [GetPipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_GetPipeline.html) 작업을 호출하세요.
# Amazon OpenSearch Ingestion 파이프라인 업데이트
AWS Management Console AWS CLI, 또는 OpenSearch Ingestion API를 사용하여 Amazon OpenSearch Ingestion 파이프라인을 업데이트할 수 있습니다. OpenSearch Ingestion은 파이프라인 구성을 업데이트할 때 블루/그린 배포를 시작합니다. 자세한 내용은 [파이프라인 업데이트를 위한 블루/그린 배포](#pipeline-bg) 단원을 참조하십시오.
**Topics**
+ [
## 고려 사항
](#update-pipeline-considerations)
+ [
## 필요한 권한
](#update-pipeline-permissions)
+ [
## 파이프라인 업데이트
](#update-pipeline-steps)
+ [
## 파이프라인 업데이트를 위한 블루/그린 배포
](#pipeline-bg)
## 고려 사항
파이프라인을 업데이트할 때 다음 사항을 고려하세요.
+ 파이프라인의 이름이나 네트워크 설정은 업데이트할 수 없습니다.
+ 파이프라인이 VPC 도메인 싱크에 쓰는 경우, 파이프라인이 생성된 후에는 되돌아가서 다른 VPC 도메인으로 싱크를 변경할 수 없습니다. 파이프라인을 삭제하고 새 싱크로 재생성해야 합니다. VPC 도메인에서 퍼블릭 도메인으로, 퍼블릭 도메인에서 VPC 도메인으로 또는 퍼블릭 도메인에서 다른 퍼블릭 도메인으로 싱크를 전환할 수 있습니다.
+ 퍼블릭 OpenSearch Service 도메인과 OpenSearch Serverless 컬렉션 간에 언제든지 파이프라인 싱크를 전환할 수 있습니다.
+ OpenSearch Ingestion은 파이프라인의 소스, 프로세서 또는 싱크 구성을 업데이트할 때 블루/그린 배포를 시작합니다. 자세한 내용은 [파이프라인 업데이트를 위한 블루/그린 배포](#pipeline-bg) 단원을 참조하십시오.
+ 파이프라인의 소스, 프로세서 또는 싱크 구성을 업데이트하면 OpenSearch Ingestion은 파이프라인을 파이프라인이 실행 중인 Data Prepper 메이저 버전에 대해 지원되는 최신 마이너 버전으로 자동 업그레이드합니다. 이 프로세스를 통해 최신 버그를 수정하고 성능을 개선하여 파이프라인을 최신 상태로 유지할 수 있습니다.
+ 파이프라인이 중지된 후에도 여전히 파이프라인을 업데이트할 수 있습니다.
## 필요한 권한
OpenSearch Ingestion은 다음 IAM 권한을 사용하여 파이프라인을 업데이트합니다.
+ `osis:UpdatePipeline` - 파이프라인을 업데이트합니다.
+ `osis:ValidatePipeline`— 파이프라인 구성이 유효한지 확인하세요.
+ `iam:PassRole` - OpenSearch Ingestion에 파이프라인 역할을 전달하여 도메인에 데이터를 쓸 수 있도록 합니다. 이 권한은 파이프라인 구성을 업데이트하는 경우에만 필요하며 로그 게시나 용량 제한과 같은 다른 설정을 수정하는 경우에는 필요하지 않습니다.
예를 들어 다음 정책에서 파이프라인을 업데이트할 권한을 부여합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Resource": "*",
"Action": [
"osis:UpdatePipeline",
"osis:ValidatePipeline"
]
},
{
"Resource": [
"arn:aws:iam::111122223333:role/pipeline-role"
],
"Effect": "Allow",
"Action": [
"iam:PassRole"
]
}
]
}
```
------
## 파이프라인 업데이트
AWS Management Console AWS CLI, 또는 OpenSearch Ingestion API를 사용하여 Amazon OpenSearch Ingestion 파이프라인을 업데이트할 수 있습니다.
### 콘솔
**파이프라인을 업데이트하려면**
1. [https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) Amazon OpenSearch Service 콘솔에 로그인합니다. 파이프라인 페이지에 표시됩니다.
1. 파이프라인을 선택하여 해당 설정을 엽니다. 그런 다음 **편집** 옵션 중 하나를 선택합니다.
1. 변경 작업을 마치면 **저장**을 선택합니다.
### CLI
를 사용하여 파이프라인을 업데이트하려면 [업데이트 파이프라인](https://docs.aws.amazon.com/cli/latest/reference/osis/update-pipeline.html) 요청을 AWS CLI보냅니다. 다음 샘플 요청은 새 구성 파일을 업로드하고 최소 및 최대 용량 값을 업데이트합니다.
```
aws osis update-pipeline \
--pipeline-name "my-pipeline" \
--pipline-configuration-body "file://new-pipeline-config.yaml" \
--min-units 11 \
--max-units 18
```
### OpenSearch Ingestion API
OpenSearch Ingestion API를 사용하여 OpenSearch Ingestion 파이프라인을 업데이트하려면 [UpdatePipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_UpdatePipeline.html) 작업을 호출하세요.
## 파이프라인 업데이트를 위한 블루/그린 배포
OpenSearch Ingestion은 파이프라인 구성을 업데이트할 때 *블루/그린* 배포 프로세스를 시작합니다.
블루/그린은 파이프라인 업데이트용으로 새 환경을 만들고 업데이트가 완료되면 트래픽을 새 환경으로 라우팅하는 관행을 지칭합니다. 이렇게 하면 가동 중지가 최소화되고, 새로운 환경에 배포하는 데 실패하더라도 원래의 환경이 유지됩니다. 블루/그린 배포 자체는 성능에 영향을 주지 않지만, 파이프라인 구성이 성능을 변경하는 방식으로 변경되면 성능이 변경될 수 있습니다.
OpenSearch Ingestion은 블루/그린 배포 중에 Auto Scaling을 차단합니다. 새 파이프라인으로 리디렉션되기 전까지는 이전 파이프라인으로 향하는 트래픽에 대해서만 계속 요금이 부과됩니다. 트래픽이 리디렉션되면 새 파이프라인에 대한 비용만 청구됩니다. 두 파이프라인에 대해 동시에 요금이 청구되는 일은 없습니다.
파이프라인의 소스, 프로세서 또는 싱크 구성을 업데이트하면 OpenSearch Ingestion은 파이프라인을 파이프라인이 실행 중인 메이저 버전의 지원되는 최신 마이너 버전으로 자동 업그레이드합니다. 예를 들어, 파이프라인 구성에 `version: "2"`이 있고 OpenSearch Ingestion이 처음에 파이프라인을 버전 2.1.0으로 프로비저닝했을 수 있습니다. 버전 2.1.1에 대한 지원이 추가되고 파이프라인 구성을 변경하면 OpenSearch Ingestion은 파이프라인을 버전 2.1.1로 업그레이드합니다.
이 프로세스를 통해 최신 버그를 수정하고 성능을 개선하여 파이프라인을 최신 상태로 유지할 수 있습니다. OpenSearch Ingestion은 파이프라인 구성 내에서 `version` 옵션을 수동으로 변경하지 않는 한 파이프라인의 메이저 버전을 업데이트할 수 없습니다.
# Amazon OpenSearch Ingestion 파이프라인 비용 관리
Amazon OpenSearch Ingestion에서 필요에 따라 수집 파이프라인을 시작하고 중지하여 데이터 흐름을 제어할 수 있습니다. 파이프라인을 중지하면 구성을 유지하면서 데이터 처리가 중단되므로, 다시 구성하지 않고도 재시작할 수 있습니다. 이를 통해 비용을 최적화하거나, 리소스 사용량을 관리하거나, 문제를 해결할 수 있습니다. 파이프라인을 중지하면 OpenSearch Ingestion이 수신 데이터를 처리하지 않지만 이전에 수집된 데이터는 OpenSearch에서 계속 사용할 수 있습니다.
시작 및 중지를 사용하면 개발, 테스트 또는 연속 가용성을 필요로 하지 않는 유사한 활동에 사용하는 파이프라인의 설정 및 해제 프로세스가 간소화됩니다. 파이프라인이 중지된 동안에는 Insting OCU 시간에 대해 요금이 부과되지 않습니다. 중지된 파이프라인은 계속 업데이트할 수 있으며, 자동 마이너 버전 업데이트와 보안 패치를 받게 됩니다.
파이프라인을 중지하고 시작하면 풀 기반 파이프라인(DDB, S3, DocDB 등)에 대해 처음부터 모든 데이터가 재처리됩니다. 파이프라인을 중지하면 파이프라인에서 생성한 모든 서비스 관리형 VPC 엔드포인트가 제거됩니다. 자체 관리형 VPC 엔드포인트가 있는 파이프라인의 경우 파이프라인을 다시 시작할 때 계정에서 VPC 엔드포인트를 다시 생성해야 합니다. 자세한 내용은 [자체 관리형 VPC 엔드포인트](pipeline-security.md#pipeline-vpc-self-managed) 단원을 참조하십시오.
**참고**
파이프라인의 용량이 초과되었지만 계속 작동해야 하는 경우에는 최대 용량 제한을 중지했다가 다시 시작하는 것보다 이 용량을 조정하는 것이 좋습니다. 이를 통해 비용을 관리하는 동시에 파이프라인이 데이터를 효율적으로 계속 처리하도록 보장할 수 있습니다. 자세한 내용은 [Amazon OpenSearch Ingestion에서 파이프라인 규모 조정](ingestion-scaling.md) 섹션을 참조하세요.
다음 주제에서는 AWS Management Console AWS CLI및 OpenSearch Ingestion API를 사용하여 파이프라인을 시작하고 중지하는 방법을 설명합니다.
**Topics**
+ [
# Amazon OpenSearch Ingestion 파이프라인 중지
](pipeline--stop.md)
+ [
# Amazon OpenSearch Ingestion 파이프라인 시작
](pipeline--start.md)
# Amazon OpenSearch Ingestion 파이프라인 중지
OpenSearch Ingestion 파이프라인을 사용하거나 관리를 수행하려면 항상 활성 파이프라인으로 시작한 다음 파이프라인을 중지하고 파이프라인을 다시 시작해야 합니다. 파이프라인이 중지된 동안에는 Ingestion OCU 시간에 대해 요금이 부과되지 않습니다.
## 콘솔
**파이프라인 중지**
1. [https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) Amazon OpenSearch Service 콘솔에 로그인합니다. 파이프라인 페이지에 표시됩니다.
1. 파이프라인을 선택합니다. 이 페이지에서 중지 작업을 수행하거나 중지하려는 파이프라인의 세부 정보 페이지로 이동하세요.
1. **작업**에서 **파이프라인 중지**를 선택합니다.
파이프라인을 중지하거나 시작할 수 없는 경우 **파이프라인 중지** 작업을 사용할 수 없습니다.
## AWS CLI
를 사용하여 파이프라인을 중지하려면 다음 파라미터와 함께 [stop-pipeline](https://docs.aws.amazon.com/cli/latest/reference/osis/stop-pipeline.html) 명령을 AWS CLI호출합니다.
+ `--pipeline-name` - 파이프라인의 이름.
**Example**
```
aws osis stop-pipeline --pipeline-name my-pipeline
```
## OpenSearch Ingestion API
OpenSearch Ingestion API를 사용하여 파이프라인을 중지하려면 다음 파라미터와 함께 [StopPipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_StopPipeline.html) 작업을 호출하세요.
+ `PipelineName` - 파이프라인의 이름.
# Amazon OpenSearch Ingestion 파이프라인 시작
이미 중지 상태인 파이프라인으로 시작하는 OpenSearch Ingestion 파이프라인을 항상 시작합니다. 파이프라인은 용량 제한, 네트워크 설정 및 로그 게시 옵션과 같은 구성 설정을 유지합니다.
파이프라인을 다시 시작하려면 일반적으로 몇 분 정도 걸립니다.
## 콘솔
**파이프라인 시작**
1. [https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) Amazon OpenSearch Service 콘솔에 로그인합니다. 파이프라인 페이지에 표시됩니다.
1. 파이프라인을 선택합니다. 이 페이지에서 시작 작업을 수행하거나 시작하려는 파이프라인의 세부 정보 페이지로 이동하세요.
1. **작업**에는 **파이프라인 시작**을 선택합니다.
## AWS CLI
를 사용하여 파이프라인을 시작하려면 다음 파라미터와 함께 [start-pipeline](https://docs.aws.amazon.com/cli/latest/reference/osis/start-pipeline.html) 명령을 AWS CLI호출합니다.
+ `--pipeline-name` - 파이프라인의 이름.
**Example**
```
aws osis start-pipeline --pipeline-name my-pipeline
```
## OpenSearch Ingestion API
OpenSearch Ingestion API를 사용하여 OpenSearch Ingestion 파이프라인을 시작하려면 다음 파라미터와 함께 [StartPipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_StartPipeline.html) 작업을 호출하세요.
+ `PipelineName` - 파이프라인의 이름.
# Amazon OpenSearch Ingestion 파이프라인 삭제
AWS Management Console AWS CLI, 또는 OpenSearch Ingestion API를 사용하여 Amazon OpenSearch Ingestion 파이프라인을 삭제할 수 있습니다. `Creating` 또는 `Updating` 상태인 경우 파이프라인을 삭제할 수 없습니다.
## 콘솔
**파이프라인 삭제**
1. [https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) Amazon OpenSearch Service 콘솔에 로그인합니다. 파이프라인 페이지에 표시됩니다.
1. 삭제하려는 파이프라인을 선택하고 **작업**, **삭제**를 선택합니다.
1. 삭제를 확인하고 **삭제**를 선택합니다.
## CLI
를 사용하여 파이프라인을 삭제하려면 다음과 같이 [파이프라인 삭제](https://docs.aws.amazon.com/cli/latest/reference/osis/delete-pipeline.html) 요청을 AWS CLI보냅니다.
```
aws osis delete-pipeline --pipeline-name "my-pipeline"
```
## OpenSearch Ingestion API
OpenSearch Ingestion API를 사용하여 OpenSearch Ingestion 파이프라인을 시작하려면 다음 파라미터와 함께 [DeletePipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_DeletePipeline.html) 작업을 호출하세요.
+ `PipelineName` - 파이프라인의 이름.
# Amazon OpenSearch Ingestion 파이프라인에 지원되는 플러그인 및 옵션
Amazon OpenSearch Ingestion은 오픈 소스 [OpenSearch Data Prepper](https://opensearch.org/docs/latest/data-prepper/) 내 소스, 프로세서 및 싱크의 하위 집합을 지원합니다. 또한 OpenSearch Ingestion은 지원되는 각 플러그인의 사용 가능한 옵션에 적용하는 몇 가지 제약이 있습니다. 다음 섹션에서는 OpenSearch Ingestion 기능이 지원하는 플러그인 및 관련 옵션에 대해 설명합니다.
**참고**
OpenSearch Ingestion은 기본 버퍼를 자동으로 구성하므로 어떤 버퍼 플러그인도 지원하지 않습니다. 파이프라인 구성에 버퍼를 포함하면 유효성 검사 오류가 발생합니다.
**Topics**
+ [
## 지원되는 플러그인
](#ingestion-plugins)
+ [
## 상태 비저장 프로세서와 상태 저장 프로세서 비교
](#processor-stateful-stateless)
+ [
## 구성 요구 사항 및 제약 조건
](#ingestion-parameters)
## 지원되는 플러그인
OpenSearch Ingestion은 다음과 같은 Data Prepper 플러그인을 지원합니다.
**소스**:
+ [documentdb](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/documentdb/)
+ [DynamoDB](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/dynamo-db/)
+ [HTTP](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/http-source/)
+ [Kafka](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/kafka/)
+ [Kinesis](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/kinesis/)
+ [OpenSearch](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/opensearch/)
+ [OTel 로그](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-logs-source/)
+ [OTel 지표](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-metrics-source/)
+ [OTel 추적](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-trace/)
+ [S3](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/s3/)
**Processors**:
+ [항목 추가](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/add-entries/)
+ [집계](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/aggregate/)
+ [이상 탐지기](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/anomaly-detector/)
+ [AWS Lambda](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/aws-lambda/)
+ [항목 유형 변환](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/convert-entry-type/)
+ [값 복사](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/copy-values/)
+ [CSV](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/csv/)
+ [날짜](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/date/)
+ [지연](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/delay/)
+ [압축 해제](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/decompress/)
+ [항목 삭제](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/delete-entries/)
+ [해체](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/dissect/)
+ [이벤트 삭제](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/drop-events/)
+ [평면화](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/flatten/)
+ [지리적 IP](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/geoip/)
+ [Grok](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/grok/)
+ [키 값](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/key-value/)
+ [매핑을 위해 나열](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/list-to-map/)
+ [소문자 문자열](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/lowercase-string/)
+ [목록에 매핑](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/map-to-list/)
+ [이벤트 변형](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/mutate-event/)(프로세서 시리즈)
+ [문자열 변형](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/mutate-string/)(프로세서 시리즈)
+ [난독화](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/obfuscate/)
+ [OTel 지표](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/otel-metrics/)
+ [OTel 추적 그룹](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/otel-trace-group/)
+ [OTel 추적](https://docs.opensearch.org/latest/data-prepper/common-use-cases/trace-analytics/)
+ [Ion 구문 분석](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/parse-ion/)
+ [JSON 구문 분석](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/parse-json/)
+ [XML 구문 분석](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/parse-xml/)
+ [키 이름 변경](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/rename-keys/)
+ [항목 선택](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/select-entries/)
+ [서비스 맵](https://docs.opensearch.org/latest/data-prepper/common-use-cases/trace-analytics/)
+ [이벤트 분할](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/split-event/)
+ [문자열 분할](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/split-string/)
+ [문자열 변환기](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/string-converter/)
+ [문자열 대체](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/substitute-string/)
+ [추적 피어 전달자](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/trace-peer-forwarder/)
+ [[Translate]](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/translate/)
+ [문자열 자르기](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/trim-string/)
+ [자르기](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/truncate/)
+ [대문자 문자열](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/uppercase-string/)
+ [사용자 에이전트](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/user-agent/)
+ [JSON 쓰기](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/write-json/)
**싱크**:
+ [OpenSearch](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/opensearch/)(OpenSearch Service, OpenSearch Serverless, Elasticsearch 6.8 이상 지원)
+ [S3](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/s3/)
**싱크 코덱**:
+ [Avro](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/s3/#avro-codec)
+ [NDJSON](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/s3/#ndjson-codec)
+ [JSON](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/s3/#json-codec)
+ [PARQUET](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/s3/#parquet-codec)
## 상태 비저장 프로세서와 상태 저장 프로세서 비교
*상태 비저장* 프로세서는 변환 및 필터링과 같은 작업을 수행하는 반면, *상태 저장* 프로세서는 이전 실행 결과를 기억하는 집계와 같은 작업을 수행합니다. OpenSearch Ingestion은 상태 저장 프로세서 [집계](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/aggregate/) 및 [서비스-맵](https://docs.opensearch.org/latest/data-prepper/pipelines/configuration/processors/service-map/)을 지원합니다. 지원되는 다른 모든 프로세서는 상태 비저장 프로세서입니다.
상태 비저장 프로세서만 포함하는 파이프라인의 경우 최대 용량 제한은 96개의 Ingestion OCU입니다. 파이프라인이 상태 비저장 프로세서를 포함하는 경우 최대 용량 제한은 48개의 Ingestion OCU입니다. 그러나 파이프라인에 [영구 버퍼링](osis-features-overview.md#persistent-buffering)이 활성화된 경우 상태 비저장 프로세서만 있는 최대 384개의 Ingestion OCU 또는 상태 저장 프로세서를 포함하는 경우 192개의 Ingestion OCU를 보유할 수 있습니다. 자세한 내용은 [Amazon OpenSearch Ingestion에서 파이프라인 규모 조정](ingestion-scaling.md) 단원을 참조하십시오.
엔드 투 엔드 승인은 상태 비저장 프로세서에서만 지원됩니다. 자세한 내용은 [엔드 투 엔드 승인](osis-features-overview.md#osis-features-e2e) 단원을 참조하십시오.
## 구성 요구 사항 및 제약 조건
아래에 달리 명시되지 않는 한, 위에 나열된 지원 플러그인의 Data Prepper 구성 참조에 설명된 모든 옵션은 OpenSearch Ingestion 파이프라인에서 허용됩니다. 다음 섹션에서는 OpenSearch Ingestion이 특정 플러그인 옵션에 적용하는 제약 조건에 대해 설명합니다.
**참고**
OpenSearch Ingestion은 기본 버퍼를 자동으로 구성하므로 어떤 버퍼 플러그인도 지원하지 않습니다. 파이프라인 구성에 버퍼를 포함하면 유효성 검사 오류가 발생합니다.
OpenSearch Ingestion은 다양한 옵션을 내부적으로 구성하고 관리합니다 (예: `authentication` 및 `acm_certificate_arn`). `thread_count` 및 `request_timeout`와 같은 다른 옵션은 수동으로 변경할 경우 성능에 영향을 미칩니다. 따라서 파이프라인의 성능을 최적화하기 위해 이러한 값이 내부적으로 설정됩니다.
마지막으로 `ism_policy_file` 및 `sink_template`와 같은 일부 옵션은 OpenSearch Ingestion으로 전달할 수 없습니다. 오픈 소스 Data Prepper에서 실행할 경우 로컬 파일이기 때문입니다. 이 값은 지원되지 않습니다.
**Topics**
+ [
### 일반 파이프라인 옵션
](#ingestion-params-general)
+ [
### Grok 프로세서
](#ingestion-params-grok)
+ [
### HTTP 소스
](#ingestion-params-http)
+ [
### OpenSearch sink
](#ingestion-params-opensearch)
+ [
### OTel 지표 소스, OTel 추적 소스 및 OTel 로그 소스
](#ingestion-params-otel-source)
+ [
### OTel 추적 그룹 프로세서
](#ingestion-params-otel-trace)
+ [
### OTel 추적 프로세서
](#ingestion-params-otel-raw)
+ [
### 서비스 맵 프로세서
](#ingestion-params-servicemap)
+ [
### S3 소스
](#ingestion-params-s3)
### 일반 파이프라인 옵션
다음 [일반 파이프라인 옵션](https://docs.opensearch.org/latest/data-prepper/pipelines/pipelines/)은 OpenSearch Ingestion에서 설정되며 파이프라인 구성에서는 지원되지 않습니다.
+ `workers`
+ `delay`
### Grok 프로세서
다음 [과 같은 공급자](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/grok/) 옵션이 지원됩니다.
+ `patterns_directories`
+ `patterns_files_glob`
### HTTP 소스
[HTTP](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/http-source/) 소스 플러그인에는 다음과 같은 요구 사항 및 제약이 있습니다.
+ 옵션은 `path` *필수입니다*. 경로는 수집을 위한 URI 경로를 나타내는 `/log/ingest`와 같은 문자열입니다. 이 경로는 파이프라인으로 데이터를 전송하는 데 사용하는 URI를 정의합니다. 예를 들어 `https://log-pipeline.us-west-2.osis.amazonaws.com/log/ingest`입니다. 경로는 슬래시(/)로 시작해야 하며 특수 문자 '-', '\$1', '.', '/'를 비롯해 `${pipelineName}` 자리 표시자를 포함할 수 있습니다.
+ 다음 HTTP 소스 옵션은 OpenSearch Ingestion에서 설정되며 파이프라인 구성에서는 지원되지 않습니다.
+ `port`
+ `ssl`
+ `ssl_key_file`
+ `ssl_certificate_file`
+ `aws_region`
+ `authentication`
+ `unauthenticated_health_check`
+ `use_acm_certificate_for_ssl`
+ `thread_count`
+ `request_timeout`
+ `max_connection_count`
+ `max_pending_requests`
+ `health_check_service`
+ `acm_private_key_password`
+ `acm_certificate_timeout_millis`
+ `acm_certificate_arn`
### OpenSearch sink
[OpenSearch](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/opensearch/) 싱크 플러그인에는 다음과 같은 요구 사항 및 제한 사항이 있습니다.
+ `aws` 옵션은 *필수*이며 다음 옵션을 포함해야 합니다.
+ `sts_role_arn`
+ `region`
+ `hosts`
+ `serverless`(싱크가 OpenSearch Serverless 컬렉션인 경우)
+ `sts_role_arn` 옵션은 YAML 정의 파일 내 각 싱크에 대해 동일한 역할을 가리켜야 합니다.
+ `hosts` 옵션은 OpenSearch Service 도메인 엔드포인트 또는 OpenSearch Serverless 컬렉션 엔드포인트를 지정해야 합니다. 도메인의 [사용자 지정 엔드포인트](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/customendpoint.html)는 지정할 수 없으며 표준 엔드포인트여야 합니다.
+ `hosts` 옵션이 서버리스 컬렉션 엔드포인트인 경우 `serverless` 옵션을 `true`로 설정해야 합니다. 또한 YAML 정의 파일에 `index_type` 옵션이 포함된 경우 `management_disabled`로 설정해야 합니다. 그렇지 않으면 검증이 실패합니다.
+ 다음 옵션은 JSON에서 지원되지 않습니다.
+ `username`
+ `password`
+ `cert`
+ `proxy`
+ `dlq_file` - 실패한 이벤트를 DLQ(Dead Letter Queue)로 오프로드하려면 `dlq` 옵션을 사용하고 S3 버킷을 지정해야 합니다.
+ `ism_policy_file`
+ `socket_timeout`
+ `template_file`
+ `insecure`
### OTel 지표 소스, OTel 추적 소스 및 OTel 로그 소스
[OTel 지표](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-metrics-source/) 소스, [OTel 추적](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-trace/) 소스 및 [OTel 로그](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-logs-source/) 소스 플러그인에는 다음과 같은 요구 사항 및 제한 사항이 있습니다.
+ 옵션은 `path` *필수입니다*. 경로는 수집을 위한 URI 경로를 나타내는 `/log/ingest`와 같은 문자열입니다. 이 경로는 파이프라인으로 데이터를 전송하는 데 사용하는 URI를 정의합니다. 예를 들어 `https://log-pipeline.us-west-2.osis.amazonaws.com/log/ingest`입니다. 경로는 슬래시(/)로 시작해야 하며 특수 문자 '-', '\$1', '.', '/'를 비롯해 `${pipelineName}` 자리 표시자를 포함할 수 있습니다.
+ 다음 옵션은 OpenSearch Ingestion에서 설정되며 파이프라인 구성에서는 지원되지 않습니다.
+ `port`
+ `ssl`
+ `sslKeyFile`
+ `sslKeyCertChainFile`
+ `authentication`
+ `unauthenticated_health_check`
+ `useAcmCertForSSL`
+ `unframed_requests`
+ `proto_reflection_service`
+ `thread_count`
+ `request_timeout`
+ `max_connection_count`
+ `acmPrivateKeyPassword`
+ `acmCertIssueTimeOutMillis`
+ `health_check_service`
+ `acmCertificateArn`
+ `awsRegion`
### OTel 추적 그룹 프로세서
[OTel 추적 그룹](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/otel-trace-group/) 프로세서에는 다음과 같은 요구 사항 및 제한 사항이 있습니다.
+ `aws` 옵션은 *필수*이며 다음 옵션을 포함해야 합니다.
+ `sts_role_arn`
+ `region`
+ `hosts`
+ `sts_role_arn` 옵션은 OpenSearch 싱크 구성에서 지정하는 파이프라인 역할과 동일한 역할을 지정합니다.
+ `username`, `password`, `cert`, `insecure` 옵션은 지원되지 않습니다.
+ `aws_sigv4` 옵션은 필수이며 true로 설정되어야 합니다.
+ OpenSearch 싱크 플러그인 내의 `serverless` 옵션은 지원되지 않습니다. OTel 추적 그룹 프로세서는 현재 OpenSearch Serverless 컬렉션과 함께 작동하지 않습니다.
+ 파이프라인 구성 본문 내의 `otel_trace_group` 프로세서 수는 8개를 초과할 수 없습니다.
### OTel 추적 프로세서
[OTel 추적](https://docs.opensearch.org/latest/data-prepper/pipelines/configuration/processors/otel-traces/) 프로세서에는 다음과 같은 요구 사항 및 제한 사항이 있습니다.
+ `trace_flush_interval` 옵션 값은 300초를 초과할 수 없습니다.
### 서비스 맵 프로세서
[서비스-맵](https://docs.opensearch.org/latest/data-prepper/pipelines/configuration/processors/service-map/) 프로세서에는 다음과 같은 요구 사항 및 제한 사항이 있습니다.
+ `window_duration` 옵션 값은 300초를 초과할 수 없습니다.
### S3 소스
[S3](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/s3/) 소스 플러그인에는 다음과 같은 요구 사항 및 제한 사항이 있습니다.
+ `aws` 옵션은 *필수*이며 `region` 및 `sts_role_arn` 옵션을 포함해야 합니다.
+ `records_to_accumulate` 옵션 값은 200초를 초과할 수 없습니다.
+ `maximum_messages` 옵션 값은 10초를 초과할 수 없습니다.
+ 지정된 경우 `disable_bucket_ownership_validation` 옵션은 false로 설정되어야 합니다.
+ 지정된 경우 `input_serialization` 옵션은 `parquet`(으)로 설정되어야 합니다.
# Amazon OpenSearch Ingestion 파이프라인을 다른 서비스 및 애플리케이션과 통합
Amazon OpenSearch Ingestion 파이프라인으로 데이터를 성공적으로 수집하려면 파이프라인 엔드포인트로 데이터를 전송하도록 클라이언트 애플리케이션(*소스*)을 구성해야 합니다. 소스는 Fluent Bit 로그, OpenTelemetry Collector 또는 간단한 S3 버킷과 같은 클라이언트일 수 있습니다. 정확한 구성은 각 클라이언트마다 다릅니다.
소스 구성 중 중요한 차이점은 (OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션으로 직접 데이터를 전송하는 것과 비교하여) AWS 서비스 이름(`osis`)과 호스트 엔드포인트이며, 이는 파이프라인 엔드포인트여야 합니다.
## 수집 엔드포인트 구성
파이프라인으로 데이터를 수집하려면 데이터를 수집 엔드포인트로 전송합니다. 수집 URL의 위치를 찾으려면 **파이프라인 설정** 페이지로 이동한 다음 **수집 URL**을 복사합니다.
![\[Pipeline settings page showing details like status, capacity, and ingestion URL for data input.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/pipeline-endpoint.png)
[OTel 추적](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-trace/) 및 [OTel 메트릭](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-metrics-source/)과 같은 풀 기반 소스에 대한 전체 수집 엔드포인트를 구성하려면 파이프라인 구성의 수집 경로를 수집 URL에 추가하세요.
예를 들어 파이프라인 구성의 수집 경로가 다음과 같다고 가정해 보겠습니다.
![\[Input field for HTTP source path with example "/my/test_path" entered.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/ingestion-path.png)
클라이언트 구성에서 지정하는 전체 수집 엔드포인트는 `https://ingestion-pipeline-abcdefg.us-east-1.osis.amazonaws.com/my/test_path`와 같은 형식을 취합니다.
## 수집 역할 생성
OpenSearch Ingestion에 대한 모든 요청은 [서명 버전 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)로 서명되어야 합니다. 요청에 서명하는 역할에는 최소한 `osis:Ingest` 작업에 대한 권한이 부여되어야 하며, 해당 역할은 OpenSearch Ingestion 파이프라인으로 데이터를 보낼 수 있습니다.
예를 들어, 다음 AWS Identity and Access Management (IAM) 정책은 해당 역할이 단일 파이프라인으로 데이터를 전송하도록 허용합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "osis:Ingest",
"Resource": "arn:aws:osis:us-east-1:111122223333:pipeline/pipeline-name"
}
]
}
```
------
**참고**
*모든* 파이프라인에 이 역할을 사용하려면 `Resource` 요소의 ARN을 와일드카드(\$1)로 바꾸세요.
### 교차 계정 수집 액세스 제공
**참고**
VPC 파이프라인이 아닌 퍼블릭 파이프라인에 대한 교차 계정 수집 액세스만 제공할 수 있습니다.
소스 애플리케이션을 포함하는 계정 AWS 계정과 같은 다른에서 파이프라인으로 데이터를 수집해야 할 수 있습니다. 파이프라인에 쓰는 보안 주체가 파이프라인 자체와 다른 계정에 있는 경우, 파이프라인으로 데이터를 수집하는 다른 IAM 역할을 신뢰할 수 있도록 보안 주체를 구성해야 합니다.
**교차 계정 수집 권한 구성**
1. 파이프라인과 동일한 내에 `osis:Ingest` 권한(이전 섹션에서 설명)을 AWS 계정 사용하여 수집 역할을 생성합니다. 자세한 내용은 [IAM 역할 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)을 참조하세요.
1. 다른 계정의 보안 주체가 이를 수임할 수 있도록 수집 역할에 [신뢰 정책](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy)을 연결하세요.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
},
"Action": "sts:AssumeRole"
}]
}
```
------
1. 다른 계정에서는 수집 역할을 맡도록 클라이언트 애플리케이션(예: Fluent Bit)을 구성하세요. 이 기능을 사용하려면 애플리케이션 계정이 애플리케이션 사용자 또는 역할에 수집 역할을 맡을 수 있는 권한을 부여해야 합니다.
다음 예제 ID 기반 정책은 연결된 보안 주체가 파이프라인 계정에서 `ingestion-role`을 수임하도록 허용합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/ingestion-role"
}
]
}
```
------
그러면 클라이언트 애플리케이션이 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) 작업을 사용하여 `ingestion-role`을 수임하고 관련 파이프라인으로 데이터를 수집할 수 있습니다.
# Atlassian 서비스에서 OpenSearch Ingestion 파이프라인 사용
Atlassian Jira 및 Confluence 소스 플러그인을 사용하여 OpenSearch Ingestion 파이프라인으로 데이터를 수집할 수 있습니다. 이러한 통합을 통해 전체 Jira 프로젝트와 Confluence 스페이스를 동기화하는 동시에, 업데이트의 지속적인 모니터링 및 자동 동기화를 통해 실시간 연관성을 유지하여 검색 가능한 통합 지식 기반을 생성할 수 있습니다.
------
#### [ Integrating with Jira ]
Jira 콘텐츠를 OpenSearch에 통합하여 강력한 컨텍스트 검색 기능으로 Jira 경험을 혁신합니다. Data Prepper [Atlassian Jira](https://www.atlassian.com/software/jira) 소스 플러그인을 사용하면 업데이트의 지속적인 모니터링 및 자동 동기화를 통해 실시간 연관성을 유지하면서 전체 Jira 프로젝트를 동기화하여 검색 가능한 통합 지식 기반을 생성할 수 있습니다. 이 통합을 통해 특정 프로젝트, 문제 유형 및 상태에 대한 유연한 필터링 옵션을 통해 데이터를 동기화할 수 있으므로 필요한 정보만 가져올 수 있게 됩니다.
안전하고 안정적인 연결을 보장하기 위해 플러그인은 기본 API 키 인증 및 OAuth2 인증을 비롯한 여러 인증 방법을 지원하며, AWS Secrets Manager에 저장된 보안 암호를 사용하여 자격 증명을 관리하는 보안 기능이 추가되었습니다. 또한 중단 없는 액세스를 위한 자동 토큰 갱신 기능을 제공하여 지속적인 작업을 보장합니다. Atlassian의 [API 버전 2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#version%22%3Eapi-version-2)를 기반으로 구축된 이 통합을 통해 팀은 OpenSearch의 고급 검색 기능을 통해 Jira 데이터에서 귀중한 인사이트를 얻을 수 있습니다.
------
#### [ Integrating with Confluence ]
Data Prepper의 Confluence 소스 플러그인을 통해 [Atlassian Confluence](https://www.atlassian.com/software/confluence) 콘텐츠를 OpenSearch에 통합하여 팀의 지식 관리 및 협업 기능을 개선합니다. 이 통합을 통해 검색 가능한 중앙 집중식 집단 지식 리포지토리를 생성하여 정보 검색과 팀 생산성을 개선할 수 있습니다. 이 플러그인은 Confluence 콘텐츠를 동기화하고 업데이트를 지속적으로 모니터링하여 OpenSearch 인덱스를 포괄적이고 최신의 상태로 유지합니다.
통합은 유연한 필터링 옵션을 제공하므로 특정 스페이스 또는 페이지 유형에서 콘텐츠를 선택적으로 가져와 조직의 니즈에 맞게 동기화된 콘텐츠를 조정할 수 있습니다. 이 플러그인은 기본 API 키와 OAuth2 인증 방법을 모두 지원하며, AWS Secrets Manager를 통해 자격 증명을 안전하게 관리할 수 있습니다. 플러그인의 자동 토큰 갱신 기능은 중단 없는 액세스와 원활한 운영을 보장합니다. Atlassian의 Confluence [API](https://developer.atlassian.com/cloud/confluence/rest/v1/intro/#auth)를 기반으로 구축된 이 통합을 통해 팀은 Confluence 콘텐츠에 OpenSearch의 고급 검색 기능을 활용하여 조직 내 정보 접근성과 활용도를 높일 수 있습니다.
------
**Topics**
+ [
## 사전 조건
](#atlassian-prerequisites)
+ [
## 파이프라인 역할 구성
](#atlassian-pipeline-role)
+ [
## Jira 커넥터 파이프라인 구성
](#jira-connector-pipeline)
+ [
## Confluence 커넥터 파이프라인 구성
](#confluence-connector-pipeline)
+ [
## 데이터 일관성
](#data-consistency)
+ [
## 제한 사항
](#limitations)
+ [
## Atlassian 커넥터에 대한 CloudWatch의 지표
](#metrics)
+ [
# OAuth 2.0을 사용하여 Atlassian Jira 또는 Confluence에 Amazon OpenSearch Ingestion 파이프라인 연결
](configure-client-atlassian-OAuth2-setup.md)
## 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 완료합니다.
1. 다음 옵션 중 하나를 선택하여 Jira 사이트의 자격 증명을 준비합니다. OpenSearch Ingestion은 콘텐츠에 대한 `ReadOnly` 권한만 필요로 합니다.
1. **옵션 1: API 키** - Atlassian 계정에 로그인하고 다음 주제의 정보를 사용하여 API 키를 생성합니다.
+ [Atlassian 계정의 API 토큰 관리](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
1. **옵션 2: OAuth2** - Atlassian 계정에 로그인하고 [OAuth 2.0을 사용하여 Atlassian Jira 또는 Confluence에 Amazon OpenSearch Ingestion 파이프라인 연결](configure-client-atlassian-OAuth2-setup.md)의 정보를 사용합니다.
1. 이전 단계에서 생성한 자격 증명을 저장할 [AWS Secrets Manager의 보안 암호](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) 를 생성합니다. 절차에 따라 다음을 선택합니다.
+ **보안 암호 유형**에서 **다른 유형의 보안 암호**를 선택합니다.
+ **키/값 페어**에서 선택한 권한 부여 유형에 따라 다음 페어를 생성합니다.
------
#### [ API key ]
```
{
"username": user-name-usualy-email-id,
"password": api-key
}
```
------
#### [ OAuth 2.0 ]
```
{
"clientId": client-id
"clientSecret": client-secret
"accessKey": access-key
"refreshKey": refresh-key
}
```
------
보안 암호를 생성한 후 보안 암호의 Amazon 리소스 이름(ARN)을 복사합니다. 이 ARN을 파이프라인 역할 권한 정책에 포함하게 됩니다.
## 파이프라인 역할 구성
사전 조건 섹션에서 생성된 보안 암호를 읽고 쓰려면 파이프라인에 전달된 역할에 다음 정책이 연결되어 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretReadWrite",
"Effect": "Allow",
"Action": [
"secretsmanager:GetResourcePolicy",
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret",
"secretsmanager:PutSecretValue",
"secretsmanager:ListSecretVersionIds"
],
"Resource": "arn:aws:secretsmanager:us-east-1:111122223333:secret:secret-name-random-6-characters"
}
]
}
```
------
이 역할에는 선택한 싱크에 액세스하고 쓸 수 있도록 하는 정책도 연결되어 있어야 합니다. 예를 들어 싱크로 OpenSearch를 선택하면 정책은 다음과 유사합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "OpenSearchWritePolicy",
"Effect": "Allow",
"Action": "aoss:*",
"Resource": "arn:aws:aoss:us-east-1:111122223333:collection/collection-id"
}
]
}
```
------
## Jira 커넥터 파이프라인 구성
사전 구성된 Atlassian Jira 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
*자리 표시자*를 자신의 정보로 바꿉니다.
```
version: "2"
extension:
aws:
secrets:
jira-account-credentials:
secret_id: "secret-arn"
region: "secret-region"
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
atlassian-jira-pipeline:
source:
jira:
# We only support one host url for now
hosts: ["jira-host-url"]
acknowledgments: true
authentication:
# Provide one of the authentication method to use. Supported methods are 'basic' and 'oauth2'.
# For basic authentication, password is the API key that you generate using your jira account
basic:
username: ${{aws_secrets:jira-account-credentials:username}}
password: ${{aws_secrets:jira-account-credentials:password}}
# For OAuth2 based authentication, we require the following 4 key values stored in the secret
# Follow atlassian instructions at the below link to generate these keys.
# https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/
# If you are using OAuth2 authentication, we also require, write permission to your AWS secret to
# be able to write the renewed tokens back into the secret.
# oauth2:
# client_id: ${{aws_secrets:jira-account-credentials:clientId}}
# client_secret: ${{aws_secrets:jira-account-credentials:clientSecret}}
# access_token: ${{aws_secrets:jira-account-credentials:accessToken}}
# refresh_token: ${{aws_secrets:jira-account-credentials:refreshToken}}
filter:
project:
key:
include:
# This is not project name.
# It is an alphanumeric project key that you can find under project details in Jira.
- "project-key"
- "project-key"
# exclude:
# - "project-key"
# - "project-key"
issue_type:
include:
- "issue-type"
# - "Story"
# - "Bug"
# - "Task"
# exclude:
# - "Epic"
status:
include:
- "ticket-status"
# - "To Do"
# - "In Progress"
# - "Done"
# exclude:
# - "Backlog"
sink:
- opensearch:
# Provide an Amazon OpenSearch Service domain endpoint
hosts: [ "https://search-mydomain-1a2a3a4a5a6a7a8a9a0a9a8a7a.us-east-1.es.amazonaws.com" ]
index: "index_${getMetadata(\"project\")}"
# Ensure adding unique document id which is the unique ticket id in this case
document_id: '${/id}'
aws:
# Provide a Role ARN with access to the domain. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
# Provide the region of the domain.
region: "us-east-1"
# Enable the 'serverless' flag if the sink is an Amazon OpenSearch Serverless collection
serverless: false
# serverless_options:
# Specify a name here to create or update network policy for the serverless collection
# network_policy_name: "network-policy-name"
# Enable the 'distribution_version' setting if the Amazon OpenSearch Service domain is of version Elasticsearch 6.x
# distribution_version: "es6"
# Enable and switch the 'enable_request_compression' flag if the default compression setting is changed in the domain.
# See Amazon OpenSearch Service에서 HTTP 요청 압축
# enable_request_compression: true/false
# Optional: Enable the S3 DLQ to capture any failed requests in an S3 bucket. Delete this entire block if you don't want a DLQ.
dlq:
s3:
# Provide an S3 bucket
bucket: "your-dlq-bucket-name"
# Provide a key path prefix for the failed requests
# key_path_prefix: "kinesis-pipeline/logs/dlq"
# Provide the region of the bucket.
region: "us-east-1"
# Provide a Role ARN with access to the bucket. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
```
Jira 소스의 속성에 대한 키:
1. **hosts**: Jira 클라우드 또는 온프레미스 URL입니다. 일반적으로 `https://your-domain-name.atlassian.net/`과 같습니다.
1. **acknowledgments**: 싱크까지 데이터가 전송되도록 보장합니다.
1. **authentication**: 파이프라인이 Jira 인스턴스에 액세스하는 방법을 설명합니다. `Basic` 또는 `OAuth2`를 선택하고 AWS 보안 암호의 키를 참조하는 해당 키 속성을 지정합니다.
1. **filter**: 이 섹션에은 추출하고 동기화할 Jira 데이터 부분을 선택하는 데 도움이 됩니다.
1. **project**: `include` 섹션에서 동기화하려는 프로젝트 키를 나열합니다. 그렇지 않으면 `exclude` 섹션에서 제외하려는 프로젝트를 나열합니다. 항상 포함 또는 제외 옵션 중 하나만 제공합니다.
1. **issue\$1type**: 동기화하려는 특정 문제 유형입니다. 니즈에 맞는 유사한 `include` 또는 `exclude` 패턴을 따릅니다. 첨부 파일은 원래 첨부 파일에 대한 앵커 링크로 표시되지만 첨부 파일 콘텐츠는 추출되지 않습니다.
1. **status**: 데이터 추출 쿼리에 적용할 특정 상태 필터입니다. `include`를 지정하면 해당 상태의 티켓만 동기화됩니다. `exclude`를 지정하면 제외된 상태가 나열된 티켓을 제외한 모든 티켓이 동기화됩니다.
## Confluence 커넥터 파이프라인 구성
사전 구성된 Atlassian Confluence 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
```
version: "2"
extension:
aws:
secrets:
confluence-account-credentials:
secret_id: "secret-arn"
region: "secret-region"
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
atlassian-confluence-pipeline:
source:
confluence:
# We currently support only one host URL.
hosts: ["confluence-host-url"]
acknowledgments: true
authentication:
# Provide one of the authentication method to use. Supported methods are 'basic' and 'oauth2'.
# For basic authentication, password is the API key that you generate using your Confluence account
basic:
username: ${{aws_secrets:confluence-account-credentials:confluenceId}}
password: ${{aws_secrets:confluence-account-credentials:confluenceCredential}}
# For OAuth2 based authentication, we require the following 4 key values stored in the secret
# Follow atlassian instructions at the following link to generate these keys:
# https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/
# If you are using OAuth2 authentication, we also require write permission to your AWS secret to
# be able to write the renewed tokens back into the secret.
# oauth2:
# client_id: ${{aws_secrets:confluence-account-credentials:clientId}}
# client_secret: ${{aws_secrets:confluence-account-credentials:clientSecret}}
# access_token: ${{aws_secrets:confluence-account-credentials:accessToken}}
# refresh_token: ${{aws_secrets:confluence-account-credentials:refreshToken}}
filter:
space:
key:
include:
# This is not space name.
# It is a space key that you can find under space details in Confluence.
- "space key"
- "space key"
# exclude:
# - "space key"
# - "space key"
page_type:
include:
- "content type"
# - "page"
# - "blogpost"
# - "comment"
# exclude:
# - "attachment"
sink:
- opensearch:
# Provide an Amazon OpenSearch Service domain endpoint
hosts: [ "https://search-mydomain-1a2a3a4a5a6a7a8a9a0a9a8a7a.us-east-1.es.amazonaws.com" ]
index: "index_${getMetadata(\"space\")}"
# Ensure adding unique document id which is the unique ticket ID in this case.
document_id: '${/id}'
aws:
# Provide the Amazon Resource Name (ARN) for a role with access to the domain. This role should have a trust relationship with osis-pipelines.amazonaws.com.
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
# Provide the Region of the domain.
region: "us-east-1"
# Enable the 'serverless' flag if the sink is an Amazon OpenSearch Serverless collection
serverless: false
# serverless_options:
# Specify a name here to create or update network policy for the serverless collection.
# network_policy_name: "network-policy-name"
# Enable the 'distribution_version' setting if the Amazon OpenSearch Service domain is of version Elasticsearch 6.x
# distribution_version: "es6"
# Enable and switch the 'enable_request_compression' flag if the default compression setting is changed in the domain.
# For more information, see Amazon OpenSearch Service에서 HTTP 요청 압축.
# enable_request_compression: true/false
# Optional: Enable the S3 DLQ to capture any failed requests in an S3 bucket. Delete this entire block if you don't want a DLQ.
dlq:
s3:
# Provide an S3 bucket
bucket: "your-dlq-bucket-name"
# Provide a key path prefix for the failed requests
# key_path_prefix: "kinesis-pipeline/logs/dlq"
# Provide the Rregion of the bucket.
region: "us-east-1"
# Provide the Amazon Resource Name (ARN) for a role with access to the bucket. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::123456789012:role/Example-Role"
```
Confluence 소스의 주요 속성:
1. **hosts**: Confluence 클라우드 또는 온프레미스 URL입니다. 일반적으로 `https://your-domain-name.atlassian.net/`과 같습니다.
1. **acknowledgments**: 싱크까지 데이터가 전송되도록 보장합니다.
1. **authentication**: 파이프라인이 Confluence 인스턴스에 액세스하는 방법을 설명합니다. `Basic` 또는 `OAuth2`를 선택하고 AWS 보안 암호의 키를 참조하는 해당 키 속성을 지정합니다.
1. **filter**: 이 섹션에은 추출하고 동기화할 Confluence 데이터 부분을 선택하는 데 도움이 됩니다.
1. **space**: `include` 섹션에서 동기화하려는 스페이스 키를 나열합니다. 그렇지 않으면 `exclude` 섹션에서 제외하려는 스페이스를 나열합니다. 항상 포함 또는 제외 옵션 중 하나만 제공합니다.
1. **page\$1type**: 동기화하려는 특정 페이지 유형(예: 페이지, 블로그 게시물 또는 첨부 파일)입니다. 니즈에 맞는 유사한 `include` 또는 `exclude` 패턴을 따릅니다. 첨부 파일은 원래 첨부 파일에 대한 앵커 링크로 표시되지만 첨부 파일 콘텐츠는 추출되지 않습니다.
## 데이터 일관성
파이프라인 YAML에 지정된 필터를 기반으로 선택한 프로젝트(또는 공백)가 한 번 추출되고 대상 싱크에 완전히 동기화됩니다. 그런 다음 지속적인 변경 모니터링을 통해 변경 사항이 발생할 때 이를 캡처하고 싱크의 데이터를 업데이트합니다. 한 가지 예외는 변경 모니터링이 `create` 및 `update` 작업만 동기화하고 `delete` 작업은 동기화하지 않는다는 것입니다.
## 제한 사항
+ 사용자 삭제 작업은 동기화되지 않습니다. 싱크에 기록된 데이터는 싱크에 남아 있습니다. ID 매핑이 싱크 설정에 지정된 경우 업데이트는 기존 콘텐츠를 새 변경 사항으로 덮어씁니다.
+ 다음 API를 지원하지 않는 이전 버전의 Atlassian 소프트웨어를 사용하는 온프레미스 인스턴스는 이 소스와 호환되지 않습니다.
+ Jira Search API 버전 3
+ `rest/api/3/search`
+ `rest/api/3/issue`
+ Confluence
+ `wiki/rest/api/content/search`
+ `wiki/rest/api/content`
+ `wiki/rest/api/settings/systemInfo`
## Atlassian 커넥터에 대한 CloudWatch의 지표
**유형: Jira 커넥터 지표**
| 소스 | 지표 | 지표 유형 |
| --- | --- | --- |
| acknowledgementSetSuccesses.count | Counter | 승인이 활성화된 경우 이 지표는 성공적으로 동기화된 티켓 수를 제공합니다. |
| acknowledgementSetFailures.count | Counter | 승인이 활성화된 경우 이 지표는 동기화에 실패한 티켓 수를 제공합니다. |
| crawlingTime.avg | 타이머 | 모든 새 변경 사항을 크롤링하는 데 걸린 시간입니다. |
| ticketFetchLatency.avg | 타이머 | 이 티켓은 평균 API 지연 시간을 가져옵니다. |
| ticketFetchLatency.max | 타이머 | 이 티켓은 최대 API 지연 시간을 가져옵니다. |
| ticketsRequested.count | Counter | 수행된 티켓 가져오기 요청 수입니다. |
| ticketRequestedFailed.count | Counter | 실패한 티켓 가져오기 요청 수입니다. |
| ticketRequestedSuccess.count | Counter | 성공한 티켓 가져오기 요청 수입니다. |
| searchCallLatency.avg | 타이머 | 평균 API 호출 지연 시간을 검색합니다. |
| searchCallLatency.max | 타이머 | 최대 API 호출 지연 시간을 검색합니다. |
| searchResultsFound.count | Counter | 해당 검색 직접 호출에서 발견된 항목 수입니다. |
| searchRequestFailed.count | Counter | 검색 API 직접 호출 실패 횟수입니다. |
| authFailures.count | Counter | 인증 실패 횟수입니다. |
**유형: Confluence 커넥터 지표**
| 소스 | 지표 | 지표 유형 |
| --- | --- | --- |
| acknowledgementSetSuccesses.count | Counter | 승인이 활성화된 경우 이 지표는 성공적으로 동기화된 페이지 수를 제공합니다. |
| acknowledgementSetFailures.count | Counter | 승인이 활성화된 경우 이 지표는 동기화에 실패한 페이지 수를 제공합니다. |
| crawlingTime.avg | 타이머 | 모든 새 변경 사항을 크롤링하는 데 걸린 시간입니다. |
| pageFetchLatency.avg | 타이머 | 콘텐츠 가져오기 API 지연 시간(평균)입니다. |
| pageFetchLatency.max | 타이머 | 콘텐츠 가져오기 API 지연 시간(최대)입니다. |
| pagesRequested.count | Counter | API를 가져오는 콘텐츠의 간접 호출 횟수입니다. |
| pageRequestFailed.count | Counter | 콘텐츠 가져오기 API의 실패한 요청 수입니다. |
| pageRequestedSuccess.count | Counter | 콘텐츠 가져오기 API의 성공한 요청 수입니다. |
| searchCallLatency.avg | 타이머 | 평균 API 호출 지연 시간을 검색합니다. |
| searchCallLatency.max | 타이머 | 최대 검색 API 호출 지연 시간입니다. |
| searchResultsFound.count | Counter | 해당 검색 직접 호출에서 발견된 항목 수입니다. |
| searchRequestsFailed.count | Counter | 검색 API 직접 호출 실패 횟수입니다. |
| authFailures.count | Counter | 인증 실패 횟수입니다. |
# OAuth 2.0을 사용하여 Atlassian Jira 또는 Confluence에 Amazon OpenSearch Ingestion 파이프라인 연결
이 주제의 정보를 참조하면 OAuth 2.0 인증을 사용하여 Amazon OpenSearch Ingestion 파이프라인을 구성하고 Jira 또는 Confluence 계정에 연결하는 데 도움이 됩니다. 이 Atlassian Services에서 OpenSearch Ingestion 파이프라인을 사용하기 위해 [사전 조건](configure-client-atlassian.md#atlassian-prerequisites)를 완료하는 경우 이 작업을 수행하되 API 키 자격 증명을 사용하지 않도록 선택합니다.
**Topics**
+ [
## OAuth 2.0 통합 앱 생성
](#create-OAuth2-integration-app)
+ [
## Atlassian Developer 액세스 토큰 생성 및 새로 고침
](#generate-and-refresh-jira-access-token)
## OAuth 2.0 통합 앱 생성
다음 절차에 따라 Atlassian Developer 웹 사이트에서 OAuth 2.0 통합 앱을 생성합니다.
**OAuth 2.0 통합 앱을 생성하려면**
1. [https://developer.atlassian.com/console/myapps/](https://developer.atlassian.com/console/myapps/)에서 Atlassian Developer 계정에 로그인합니다.
1. **생성**, **OAuth 2.0 통합**을 선택합니다.
1. **이름**에 앱의 용도를 식별할 수 있는 이름을 입력합니다.
1. **Atlassian의 개발자 약관을 준수하는 데 동의합니다** 확인란을 선택하고 **생성**을 선택합니다.
1. 왼쪽 탐색 창에서 **권한 부여**를 선택한 다음 **추가**를 선택합니다.
1. **콜백 URL**에 **https://www.amazon.com** 또는 **https://www.example.com**과 같은 URL을 입력한 다음 **변경 사항 저장**을 선택합니다.
1. 왼쪽 탐색 메뉴에서 **권한** 페이지를 선택하고 Jira API 행에서 **추가**를 선택한 후 **구성**을 선택하고 모든 클래식 범위 읽기 권한(아래에 나와 있음)을 선택한 다음 저장을 선택합니다.
1. **세분화된 범위** 탭을 선택한 다음 **범위 편집**을 선택하여 **Jira API 편집** 대화 상자를 엽니다.
1. 사용 중인 소스 플러그인에 대한 권한을 선택합니다.
------
#### [ Jira ]
```
read:audit-log:jira
read:issue:jira
read:issue-meta:jira
read:attachment:jira
read:comment:jira
read:comment.property:jira
read:field:jira
read:field.default-value:jira
read:field.option:jira
read:field-configuration-scheme:jira
read:field-configuration:jira
read:issue-link:jira
read:issue-link-type:jira
read:issue-link-type:jira
read:issue.remote-link:jira
read:issue.property:jira
read:resolution:jira
read:issue-details:jira
read:issue-type:jira
read:issue-worklog:jira
read:issue-field-values:jira
read:issue.changelog:jira
read:issue.transition:jira
read:issue.vote:jira
read:jira-expressions:jira
```
------
#### [ Confluence ]
```
read:content:confluence
read:content-details:confluence
read:space-details:confluence
read:audit-log:confluence
read:page:confluence
read:blogpost:confluence
read:custom-content:confluence
read:comment:confluence
read:space:confluence
read:space.property:confluence
read:space.setting:confluence
read:content.property:confluence
read:content.metadata:confluence
read:task:confluence
read:whiteboard:confluence
read:app-data:confluence
manage:confluence-configuration
```
------
1. **저장**을 선택합니다.
자세한 내용은 Atlassian Developer 웹 사이트에서 [Implementing OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/) 및 [Determining the scopes required for an operation](https://developer.atlassian.com/cloud/oauth/getting-started/determining-scopes/)을 참조하세요.
## Atlassian Developer 액세스 토큰 생성 및 새로 고침
다음 절차를 참조하면 Atlassian Developer 웹 사이트에서 Atlassian Developer 액세스 토큰을 생성하고 새로 고치는 데 도움이 됩니다.
**Jira 액세스 토큰을 생성하고 새로 고치려면**
1. [https://developer.atlassian.com/console/myapps/](https://developer.atlassian.com/console/myapps/)에서 Atlassian Developer 계정에 로그인합니다.
1. [OAuth 2.0 통합 앱 생성](#create-OAuth2-integration-app)에서 생성한 앱을 선택합니다.
1. 왼쪽 탐색 메뉴에서 **권한 부여**를 선택합니다.
1. 페이지 하단에서 세분화된 Atlassian API 권한 부여 URL 값을 복사하여 원하는 텍스트 편집기에 붙여 넣습니다.
URL의 형식은 다음과 같습니다.
```
https://auth.atlassian.com/authorize?
audience=api.atlassian.com
&client_id=YOUR_CLIENT_ID
&scope=REQUESTED_SCOPE%20REQUESTED_SCOPE_TWO
&redirect_uri=https://YOUR_APP_CALLBACK_URL
&state=YOUR_USER_BOUND_VALUE
&response_type=code
&prompt=consent
```
1. `state=YOUR_USER_BOUND_VALUE`의 파라미터 값을 state="**sample\$1text**"와 같이 선택한 항목으로 변경합니다.
자세한 내용은 Atlassian Developer 웹 사이트의 [What is the state parameter used for?](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#what-is-the-state-parameter-used-for-)를 참조하세요.
1. `scope` 섹션에는 이전 작업에서 선택한 세분화된 범위가 나열됩니다. 예: `scope=read%3Ajira-work%20read%3Ajira-user%20offline_access`
`offline_access`는 `refresh_token`을 생성하고자 함을 나타냅니다.
1. 웹 브라우저 창을 열고 복사한 권한 부여 URL을 브라우저 창의 주소 표시줄에 입력합니다.
1. 대상 페이지가 열리면 정보가 올바른지 확인한 다음 **수락**을 선택하여 Jira 또는 Confluence 홈 페이지로 리디렉션합니다.
1. 홈 페이지를 로드한 후 이 페이지의 URL을 복사합니다. 이 URL에는 애플리케이션의 권한 부여 코드가 포함되어 있습니다. 이 코드를 사용하여 액세스 토큰을 생성하게 됩니다. `code=` 다음의 섹션 전체가 권한 부여 코드입니다.
1. 다음 cURL 명령을 사용하여 액세스 토큰을 생성합니다. *자리 표시자*를 자신의 정보로 바꿉니다.
**작은 정보**
Postman과 같은 서드 파티 서비스를 사용할 수도 있습니다.
```
curl --request POST --url 'https://auth.atlassian.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "AUTHORIZATION_CODE",
"redirect_uri": "YOUR_CALLBACK_URL"}'
```
이 명령에 대한 응답에는 `access_code` 및 `refresh_token` 값이 포함됩니다.
# Amazon Aurora에서 OpenSearch Ingestion 파이프라인 사용
Amazon Aurora와 함께 OpenSearch Ingestion 파이프라인을 사용하여 기존 데이터를 내보내고 변경 사항(예: 생성, 업데이트 및 삭제)을 Amazon OpenSearch Service 도메인 및 컬렉션으로 스트리밍할 수 있습니다. OpenSearch Ingestion 파이프라인은 변경 데이터 캡처(CDC) 인프라를 통합하여 지연 시간을 최소화하면서 대규모로 Amazon Aurora에서 데이터를 지속적으로 스트리밍할 수 있도록 합니다. Aurora MySQL과 Aurora PostgreSQL을 지원되지 않습니다.
Amazon Aurora를 데이터 처리를 위한 소스로 사용하는 두 가지 방법(전체 초기 스냅샷 사용 또는 사용 안 함)이 있습니다. 전체 초기 스냅샷은 지정된 테이블의 스냅샷이며, 이 스냅샷은 Amazon S3로 내보내집니다. 그러면 OpenSearch Ingestion 파이프라인이 이 스냅샷을 도메인의 한 인덱스로 보내거나 분할하여 도메인의 여러 인덱스로 보냅니다. Amazon Aurora와 OpenSearch의 데이터를 일관되게 유지하기 위해 파이프라인에서는 Amazon Aurora 클러스터의 테이블에 있는 모든 생성, 업데이트 및 삭제 이벤트를 하나 이상의 OpenSearch 인덱스에 저장된 문서와 동기화합니다.
전체 초기 스냅샷을 사용하는 경우 OpenSearch Ingestion 파이프라인에서는 먼저 스냅샷을 수집한 다음, Amazon Aurora 변경 스트림에서 데이터를 읽기 시작합니다. 실제로 처리의 시간 차이가 거의 없기 때문에 Amazon Aurora와 OpenSearch 간에 실시간에 가까운 데이터 일관성이 유지됩니다.
또한 Amazon Aurora와의 OpenSearch Ingestion 통합을 사용하여 변경 데이터 캡처를 추적하고 Aurora에서 OpenSearch로의 모든 업데이트를 수집할 수 있습니다. 다른 메커니즘의 전체 스냅샷이 이미 있거나 Amazon Aurora 클러스터의 데이터에 대한 모든 변경 사항을 캡처하려는 경우 이 옵션을 선택합니다.
이 옵션을 선택하면 [Aurora MySQL에 대한 이진 로깅을 구성](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_LogAccess.MySQL.BinaryFormat.html)하거나 [클러스터에서 Aurora PostgreSQL에 대한 논리적 복제를 설정](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Replication.Logical.Configure.html)해야 합니다.
**Topics**
+ [
# Aurora MySQL
](aurora-mysql.md)
+ [
# Aurora PostgreSQL
](aurora-PostgreSQL.md)
# Aurora MySQL
Amazon Aurora for Aurora MySQL을 사용하여 OpenSearch Ingestion 파이프라인을 구성하려면 다음 단계를 완료합니다.
**Topics**
+ [
## Aurora MySQL 사전 조건
](#aurora-mysql-prereqs)
+ [
## 1단계: 파이프라인 역할 구성
](#aurora-mysql-pipeline-role)
+ [
## 2단계: 파이프라인 생성
](#aurora-mysql-pipeline)
+ [
## 데이터 일관성
](#aurora-mysql-pipeline-consistency)
+ [
## 데이터 형식 매핑
](#aurora-mysql-pipeline-mapping)
+ [
## 제한 사항
](#aurora-mysql-pipeline-limitations)
+ [
## 권장되는 CloudWatch 경보
](#aurora-mysql-pipeline-metrics)
## Aurora MySQL 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. [Amazon Aurora에서 사용자 지정 Aurora DB 클러스터 파라미터 그룹을 생성하여 바이너리 로깅을 구성합니다](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/zero-etl.setting-up.html#zero-etl.parameters).
```
aurora_enhanced_binlog=1
binlog_backup=0
binlog_format=ROW
binlog_replication_globaldb=0
binlog_row_image=full
binlog_row_metadata=full
```
또한 `binlog_transaction_compression` 파라미터가 `ON`으로 설정되어 있지 않고 `binlog_row_value_options` 파라미터가 `PARTIAL_JSON`으로 설정되어 있지 않아야 합니다.
1. [Aurora MySQL DB 클러스터를 선택하거나 생성하고](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_GettingStartedAurora.CreatingConnecting.Aurora.html) 이전 단계에서 생성한 파라미터 그룹을 DB 클러스터와 연결합니다.
1. [바이너리 로그 보존을 24시간 이상으로 구성합니다](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/mysql-stored-proc-configuring.html).
1. [Aurora 및 AWS Secrets Manager에서 암호 관리를 사용](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/rds-secrets-manager.html)하여 Amazon Aurora 클러스터에서 사용자 이름과 암호 인증을 설정합니다. [Secrets Manager 보안 암호를 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)하여 사용자 이름/암호 조합을 생성할 수도 있습니다.
1. 전체 초기 스냅샷 기능을 사용하는 경우 Amazon Aurora에서 Amazon S3로 데이터를 내보내기 위한 AWS KMS key 및 IAM 역할을 생성합니다.
이 IAM 역할에는 다음과 같은 권한 정책도 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ExportPolicy",
"Effect": "Allow",
"Action": [
"s3:PutObject*",
"s3:ListBucket",
"s3:GetObject*",
"s3:DeleteObject*",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::s3-bucket-used-in-pipeline",
"arn:aws:s3:::s3-bucket-used-in-pipeline/*"
]
}
]
}
```
------
이 역할에는 다음과 같은 신뢰 관계도 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "export.rds.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 선택하거나 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html#createdomains) 및 [컬렉션 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-manage.html#serverless-create)을 참조하세요.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 Amazon Aurora DB 클러스터의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
## 1단계: 파이프라인 역할 구성
Amazon Aurora 파이프라인 사전 조건을 설정한 후 [파이프라인 구성에 사용할 파이프라인 역할을 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security-overview.html#pipeline-security-sink)합니다. 또한 Amazon Aurora 소스에 대한 다음 권한을 역할에 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "allowReadingFromS3Buckets",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:DeleteObject",
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::s3_bucket",
"arn:aws:s3:::s3_bucket/*"
]
},
{
"Sid": "allowNetworkInterfacesActions",
"Effect": "Allow",
"Action": [
"ec2:AttachNetworkInterface",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DetachNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"arn:aws:ec2:*:111122223333:network-interface/*",
"arn:aws:ec2:*:111122223333:subnet/*",
"arn:aws:ec2:*:111122223333:security-group/*"
]
},
{
"Sid": "allowDescribeEC2",
"Effect": "Allow",
"Action": [
"ec2:Describe*"
],
"Resource": "*"
},
{
"Sid": "allowTagCreation",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:111122223333:network-interface/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/OSISManaged": "true"
}
}
},
{
"Sid": "AllowDescribeInstances",
"Effect": "Allow",
"Action": [
"rds:DescribeDBInstances"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:db:*"
]
},
{
"Sid": "AllowDescribeClusters",
"Effect": "Allow",
"Action": [
"rds:DescribeDBClusters"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:cluster:DB-id"
]
},
{
"Sid": "AllowSnapshots",
"Effect": "Allow",
"Action": [
"rds:DescribeDBClusterSnapshots",
"rds:CreateDBClusterSnapshot",
"rds:AddTagsToResource"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:cluster:DB-id",
"arn:aws:rds:us-east-2:111122223333:cluster-snapshot:DB-id*"
]
},
{
"Sid": "AllowExport",
"Effect": "Allow",
"Action": [
"rds:StartExportTask"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:cluster:DB-id",
"arn:aws:rds:us-east-2:111122223333:cluster-snapshot:DB-id*"
]
},
{
"Sid": "AllowDescribeExports",
"Effect": "Allow",
"Action": [
"rds:DescribeExportTasks"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": "us-east-2",
"aws:ResourceAccount": "111122223333"
}
}
},
{
"Sid": "AllowAccessToKmsForExport",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:Encrypt",
"kms:DescribeKey",
"kms:RetireGrant",
"kms:CreateGrant",
"kms:ReEncrypt*",
"kms:GenerateDataKey*"
],
"Resource": [
"arn:aws:kms:us-east-2:111122223333:key/export-key-id"
]
},
{
"Sid": "AllowPassingExportRole",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": [
"arn:aws:iam::111122223333:role/export-role"
]
},
{
"Sid": "SecretsManagerReadAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:*:111122223333:secret:*"
]
}
]
}
```
------
## 2단계: 파이프라인 생성
다음과 유사한 OpenSearch Ingestion 파이프라인을 구성합니다. 이 파이프라인 예는 Amazon Aurora 클러스터를 소스로 지정합니다.
```
version: "2"
aurora-mysql-pipeline:
source:
rds:
db_identifier: "cluster-id"
engine: aurora-mysql
database: "database-name"
tables:
include:
- "table1"
- "table2"
s3_bucket: "bucket-name"
s3_region: "bucket-region"
s3_prefix: "prefix-name"
export:
kms_key_id: "kms-key-id"
iam_role_arn: "export-role-arn"
stream: true
aws:
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
region: "us-east-1"
authentication:
username: ${{aws_secrets:secret:username}}
password: ${{aws_secrets:secret:password}}
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
index: "${getMetadata(\"table_name\")}"
index_type: custom
document_id: "${getMetadata(\"primary_key\")}"
action: "${getMetadata(\"opensearch_action\")}"
document_version: "${getMetadata(\"document_version\")}"
document_version_type: "external"
aws:
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
region: "us-east-1"
extension:
aws:
secrets:
secret:
secret_id: "rds-secret-id"
region: "us-east-1"
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
refresh_interval: PT1H
```
사전 구성된 Amazon Aurora 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
Amazon Aurora를 소스로 사용하려면 파이프라인에 대한 VPC 액세스를 구성해야 합니다. 선택한 VPC는 Amazon Aurora 소스에서 사용하는 것과 동일한 VPC여야 합니다. 그런 다음 하나 이상의 서브넷과 하나 이상의 VPC 보안 그룹을 선택합니다. 파이프라인에는 Aurora MySQL 데이터베이스에 대한 네트워크 액세스가 필요하므로 Aurora 클러스터가 파이프라인의 VPC 보안 그룹에서 데이터베이스 포트로의 인바운드 트래픽을 허용하는 VPC 보안 그룹으로 구성되어 있는지도 확인해야 합니다. 자세한 내용은 [보안 그룹을 통한 액세스 제어](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Overview.RDSSecurityGroups.html)를 참조하세요.
를 사용하여 파이프라인 AWS Management Console 을 생성하는 경우 Amazon Aurora를 소스로 사용하려면 VPC에 파이프라인도 연결해야 합니다. 이를 수행하려면 **네트워크 구성** 섹션을 찾아 **VPC에 연결** 확인란을 선택하고 제공된 기본 옵션 중 하나에서 CIDR을 선택하거나 직접 선택합니다. [RFC 1918 Best Current Practice](https://datatracker.ietf.org/doc/html/rfc1918)에 정의된 대로 프라이빗 주소 공간에서 모든 CIDR을 사용할 수 있습니다.
사용자 지정 CIDR을 제공하려면 드롭다운 메뉴에서 **기타**를 선택합니다. OpenSearch Ingestion과 Amazon Aurora 간의 IP 주소 충돌을 방지하려면 Amazon Aurora VPC CIDR이 OpenSearch Ingestion의 CIDR과 달라야 합니다.
자세한 내용은 [파이프라인에 대한 VPC 액세스 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security.html#pipeline-vpc-configure)을 참조하세요.
## 데이터 일관성
파이프라인은 Amazon Aurora 클러스터의 변경 사항을 지속적으로 폴링하거나 수신하고 OpenSearch 인덱스에서 해당 문서를 업데이트하여 데이터 일관성을 보장합니다.
OpenSearch Ingestion은 데이터 내구성을 보장하는 엔드 투 엔드 승인을 지원합니다. 파이프라인에서는 스냅샷이나 스트림을 읽을 때 병렬 처리를 위해 동적으로 분할을 생성합니다. 파이프라인에서는 OpenSearch 도메인이나 컬렉션에서 모든 레코드를 수집한 후 승인을 받으면 분할을 완료 상태로 표시합니다. OpenSearch Serverless 검색 컬렉션에 수집하려는 경우 파이프라인에서 문서 ID를 생성할 수 있습니다. OpenSearch Serverless 시계열 컬렉션에 수집하려면 파이프라인이 문서 ID를 생성하지 않으므로 파이프라인 싱크 구성`document_id: "${getMetadata(\"primary_key\")}"`에서를 생략해야 합니다.
또한 OpenSearch Ingestion 파이프라인에서는 수신 이벤트 작업을 해당하는 대량 인덱싱 작업에 매핑하여 문서를 쉽게 수집할 수 있게 합니다. 이렇게 하면 데이터 일관성이 유지되므로 Amazon Aurora의 모든 데이터 변경 사항이 OpenSearch에서 해당하는 문서 변경 사항으로 조정됩니다.
## 데이터 형식 매핑
OpenSearch Ingestion 파이프라인은 OpenSearch Service 도메인 또는 컬렉션이 사용할 수 있는 표현에 MySQL 데이터 유형을 매핑합니다. OpenSearch에 매핑 템플릿이 정의되지 않은 경우 OpenSearch는 처음 전송된 문서를 기반으로 [동적 매핑](https://opensearch.org/docs/latest/field-types/#dynamic-mapping)을 사용하여 필드 유형을 자동으로 결정합니다. 매핑 템플릿을 통해 OpenSearch에서 가장 적합한 필드 유형을 명시적으로 정의할 수도 있습니다.
아래 표에는 MySQL 데이터 유형과 해당 OpenSearch 필드 유형이 나열되어 있습니다. 명시적 매핑이 정의되지 않은 경우 *기본 OpenSearch 필드 유형* 열에 OpenSearch의 해당 필드 유형이 표시됩니다. 이 경우 OpenSearch는 동적 매핑을 사용하여 필드 유형을 자동으로 결정합니다. *권장 OpenSearch 필드 유형* 열은 매핑 템플릿에서 명시적으로 지정하도록 권장되는 해당 필드 유형입니다. 이들 필드 유형은 MySQL의 데이터 유형과 더 긴밀하게 맞춤화되며 일반적으로 OpenSearch에서 사용할 수 있는 더 나은 검색 기능을 지원할 수 있습니다.
| MySQL 데이터 형식 | 기본 OpenSearch 필드 유형 | 권장 OpenSearch 필드 유형 |
| --- | --- | --- |
| BIGINT | long | long |
| BIGINT UNSIGNED | long | unsigned long |
| BIT | long | 비트 수에 따라 byte, short, integer 또는 long입니다. |
| DECIMAL | 텍스트 | double 또는 키워드 |
| DOUBLE | 실수 | double |
| FLOAT | 실수 | 실수 |
| INT | long | 정수 |
| INT UNSIGNED | long | long |
| MEDIUMINT | long | 정수 |
| MEDIUMINT UNSIGNED | long | 정수 |
| NUMERIC | 텍스트 | double 또는 키워드 |
| SMALLINT | long | bigint |
| SMALLINT UNSIGNED | long | 정수 |
| TINYINT | long | 바이트 |
| TINYINT UNSIGNED | long | bigint |
| BINARY | 텍스트 | 이진수 |
| BLOB | 텍스트 | 이진수 |
| CHAR | 텍스트 | 텍스트 |
| ENUM | 텍스트 | 키워드 |
| LONGBLOB | 텍스트 | 이진수 |
| LONGTEXT | 텍스트 | 텍스트 |
| MEDIUMBLOB | 텍스트 | 이진수 |
| MEDIUMTEXT | 텍스트 | 텍스트 |
| SET | 텍스트 | 키워드 |
| TEXT | 텍스트 | 텍스트 |
| TINYBLOB | 텍스트 | 이진수 |
| TINYTEXT | 텍스트 | 텍스트 |
| VARBINARY | 텍스트 | 이진수 |
| VARCHAR | 텍스트 | 텍스트 |
| DATE | long(에포크 밀리초) | 날짜 |
| DATETIME | long(에포크 밀리초) | 날짜 |
| TIME | long(에포크 밀리초) | 날짜 |
| TIMESTAMP | long(에포크 밀리초) | 날짜 |
| YEAR | long(에포크 밀리초) | 날짜 |
| GEOMETRY | text(WKT 형식) | geo\$1shape |
| GEOMETRYCOLLECTION | text(WKT 형식) | geo\$1shape |
| LINESTRING | text(WKT 형식) | geo\$1shape |
| MULTILINESTRING | text(WKT 형식) | geo\$1shape |
| MULTIPOINT | text(WKT 형식) | geo\$1shape |
| MULTIPOLYGON | text(WKT 형식) | geo\$1shape |
| POINT | text(WKT 형식) | geo\$1point 또는 geo\$1shape |
| POLYGON | text(WKT 형식) | geo\$1shape |
| JSON | 텍스트 | 객체 |
OpenSearch Ingestion 파이프라인에서 DLQ(Dead Letter Queue)를 구성하는 것이 좋습니다. 이 대기열을 구성하면 OpenSearch Service에서는 동적 매핑 실패로 인해 수집할 수 없는 모든 실패한 문서를 대기열로 전송합니다.
자동 매핑이 실패하면 파이프라인 구성에서 `template_type` 및 `template_content`를 사용하여 명시적 매핑 규칙을 정의할 수 있습니다. 또는 파이프라인을 시작하기 전에 검색 도메인이나 컬렉션에서 직접 매핑 템플릿을 생성할 수도 있습니다.
## 제한 사항
Aurora MySQL용 OpenSearch Ingestion 파이프라인을 설정하는 경우 다음과 같은 제한 사항을 고려하세요.
+ 이 통합에서는 파이프라인당 하나의 MySQL 데이터베이스만 지원합니다.
+ 이 통합에서는 현재 교차 리전 데이터 수집을 지원하지 않습니다. Amazon Aurora 클러스터와 OpenSearch 도메인은 동일한 AWS 리전에 있어야 합니다.
+ 이 통합에서는 현재 교차 계정 데이터 수집을 지원하지 않습니다. Amazon Aurora 클러스터와 OpenSearch Ingestion 파이프라인은 동일한 AWS 계정에 있어야 합니다.
+ 지원되는 유일한 인증 메커니즘인 Secrets Manager를 사용한 인증이 Amazon Aurora 클러스터에 활성화되어 있는지 확인합니다.
+ 기존 파이프라인 구성은 다른 데이터베이스 및/또는 다른 테이블에서 데이터를 수집하도록 업데이트할 수 없습니다. 파이프라인의 데이터베이스 및/또는 테이블 이름을 업데이트하려면 파이프라인을 중지하고 업데이트된 구성으로 다시 시작하거나 새 파이프라인을 생성해야 합니다.
+ 데이터 정의 언어(DDL) 문은 일반적으로 지원되지 않습니다. 다음의 경우에는 데이터 일관성이 유지되지 않습니다.
+ 기본 키가 변경될 경우(추가/삭제/이름 변경)
+ 테이블이 삭제되거나 잘린 경우.
+ 열 이름 또는 데이터 형식이 변경된 경우.
+ 동기화할 MySQL 테이블에 기본 키가 정의되지 않은 경우 데이터 일관성이 보장되지 않습니다. 업데이트/삭제를 OpenSearch에 동기화하려면 OpenSearch 싱크 구성에서 사용자 지정 `document_id` 옵션을 올바르게 정의해야 합니다.
+ 계단식 삭제 작업이 있는 외래 키 참조는 지원되지 않으며, Aurora MySQL과 OpenSearch 간에 데이터 불일치가 발생할 수 있습니다.
+ 지원되는 버전: Aurora MySQL 버전 3.05.25 이상
## 권장되는 CloudWatch 경보
수집 파이프라인의 성능을 모니터링하려면 다음 CloudWatch 지표가 권장됩니다. 이러한 지표는 내보내기에서 처리된 데이터의 양, 스트림에서 처리된 이벤트의 수, 내보내기 및 스트림 이벤트 처리 오류, 대상에 쓴 문서 수를 식별하는 데 도움이 될 수 있습니다. 이러한 지표 중 하나가 지정된 시간 동안 지정된 값을 초과하면 작업을 수행하도록 CloudWatch 경보를 설정할 수 있습니다.
| 지표 | 설명 |
| --- | --- |
| pipeline-name.rds.credentialsChanged | 이 지표는 AWS 보안 암호 교체 빈도를 나타냅니다. |
| pipeline-name.rds.executorRefreshErrors | 이 지표는 AWS 보안 암호 새로 고침 실패를 나타냅니다. |
| pipeline-name.rds.exportRecordsTotal | 이 지표는 Amazon Aurora에서 내보낸 레코드 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsProcessed | 이 지표는 OpenSearch Ingestion 파이프라인에서 처리한 레코드 수를 나타냅니다. |
| pipeline-name.rds.exportRecordProcessingErrors | 이 지표는 Amazon Aurora 클러스터에서 데이터를 읽는 동안 OpenSearch Ingestion 파이프라인에서 처리한 오류 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsSuccessTotal | 이 지표는 성공적으로 처리한 내보내기 레코드의 총 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsFailedTotal | 이 지표는 처리하지 못한 내보내기 레코드의 총 수를 나타냅니다. |
| pipeline-name.rds.bytesReceived | 이 지표는 OpenSearch Ingestion 파이프라인에서 수신한 총 바이트 수를 나타냅니다. |
| pipeline-name.rds.bytesProcessed | 이 지표는 OpenSearch Ingestion 파이프라인에서 처리한 총 바이트 수를 나타냅니다. |
| pipeline-name.rds.streamRecordsSuccessTotal | 이 지표는 스트림에서 성공적으로 처리한 레코드 수를 나타냅니다. |
| pipeline-name.rds.streamRecordsFailedTotal | 이 지표는 스트림에서 처리하지 못한 총 레코드 수를 나타냅니다. |
# Aurora PostgreSQL
Amazon Aurora for Aurora PostgreSQL을 사용하여 OpenSearch Ingestion 파이프라인을 구성하려면 다음 단계를 완료합니다.
**Topics**
+ [
## Aurora PostgreSQL 사전 조건
](#aurora-PostgreSQL-prereqs)
+ [
## 1단계: 파이프라인 역할 구성
](#aurora-mysql-pipeline-role)
+ [
## 2단계: 파이프라인 생성
](#aurora-PostgreSQL-pipeline)
+ [
## 데이터 일관성
](#aurora-mysql-pipeline-consistency)
+ [
## 데이터 형식 매핑
](#aurora-PostgreSQL-pipeline-mapping)
+ [
## 제한 사항
](#aurora-PostgreSQL-pipeline-limitations)
+ [
## 권장되는 CloudWatch 경보
](#aurora-mysql-pipeline-metrics)
## Aurora PostgreSQL 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. Amazon Aurora에서 [사용자 지정 DB 클러스터 파라미터 그룹을 생성](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_GettingStartedAurora.CreatingConnecting.Aurora.html)하여 논리적 복제를 구성합니다.
```
rds.logical_replication=1
aurora.enhanced_logical_replication=1
aurora.logical_replication_backup=0
aurora.logical_replication_globaldb=0
```
1. [Aurora PostgreSQL DB 클러스터를 선택하거나 생성하고](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_GettingStartedAurora.CreatingConnecting.Aurora.html) 1단계에서 생성한 파라미터 그룹을 DB 클러스터와 연결합니다.
1. [Aurora 및 AWS Secrets Manager에서 암호 관리를 사용](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/rds-secrets-manager.html)하여 Amazon Aurora 클러스터에서 사용자 이름과 암호 인증을 설정합니다. [Secrets Manager 보안 암호를 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)하여 사용자 이름/암호 조합을 생성할 수도 있습니다.
1. 전체 초기 스냅샷 기능을 사용하는 경우 Amazon Aurora에서 Amazon S3로 데이터를 내보내기 위한 AWS KMS key 및 IAM 역할을 생성합니다.
이 IAM 역할에는 다음과 같은 권한 정책도 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ExportPolicy",
"Effect": "Allow",
"Action": [
"s3:PutObject*",
"s3:ListBucket",
"s3:GetObject*",
"s3:DeleteObject*",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::s3-bucket-used-in-pipeline",
"arn:aws:s3:::s3-bucket-used-in-pipeline/*"
]
}
]
}
```
------
이 역할에는 다음과 같은 신뢰 관계도 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "export.rds.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 선택하거나 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html#createdomains) 및 [컬렉션 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-manage.html#serverless-create)을 참조하세요.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 Amazon Aurora DB 클러스터의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
## 1단계: 파이프라인 역할 구성
Amazon Aurora 파이프라인 사전 조건을 설정한 후 [파이프라인 구성에 사용할 파이프라인 역할을 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security-overview.html#pipeline-security-sink)합니다. 또한 Amazon Aurora 소스에 대한 다음 권한을 역할에 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "allowReadingFromS3Buckets",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:DeleteObject",
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::s3_bucket",
"arn:aws:s3:::s3_bucket/*"
]
},
{
"Sid": "allowNetworkInterfacesActions",
"Effect": "Allow",
"Action": [
"ec2:AttachNetworkInterface",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DetachNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"arn:aws:ec2:*:111122223333:network-interface/*",
"arn:aws:ec2:*:111122223333:subnet/*",
"arn:aws:ec2:*:111122223333:security-group/*"
]
},
{
"Sid": "allowDescribeEC2",
"Effect": "Allow",
"Action": [
"ec2:Describe*"
],
"Resource": "*"
},
{
"Sid": "allowTagCreation",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:111122223333:network-interface/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/OSISManaged": "true"
}
}
},
{
"Sid": "AllowDescribeInstances",
"Effect": "Allow",
"Action": [
"rds:DescribeDBInstances"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:db:*"
]
},
{
"Sid": "AllowDescribeClusters",
"Effect": "Allow",
"Action": [
"rds:DescribeDBClusters"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:cluster:DB-id"
]
},
{
"Sid": "AllowSnapshots",
"Effect": "Allow",
"Action": [
"rds:DescribeDBClusterSnapshots",
"rds:CreateDBClusterSnapshot",
"rds:AddTagsToResource"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:cluster:DB-id",
"arn:aws:rds:us-east-2:111122223333:cluster-snapshot:DB-id*"
]
},
{
"Sid": "AllowExport",
"Effect": "Allow",
"Action": [
"rds:StartExportTask"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:cluster:DB-id",
"arn:aws:rds:us-east-2:111122223333:cluster-snapshot:DB-id*"
]
},
{
"Sid": "AllowDescribeExports",
"Effect": "Allow",
"Action": [
"rds:DescribeExportTasks"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": "us-east-2",
"aws:ResourceAccount": "111122223333"
}
}
},
{
"Sid": "AllowAccessToKmsForExport",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:Encrypt",
"kms:DescribeKey",
"kms:RetireGrant",
"kms:CreateGrant",
"kms:ReEncrypt*",
"kms:GenerateDataKey*"
],
"Resource": [
"arn:aws:kms:us-east-2:111122223333:key/export-key-id"
]
},
{
"Sid": "AllowPassingExportRole",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": [
"arn:aws:iam::111122223333:role/export-role"
]
},
{
"Sid": "SecretsManagerReadAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:*:111122223333:secret:*"
]
}
]
}
```
------
## 2단계: 파이프라인 생성
Aurora PostgreSQL 클러스터를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
```
version: "2"
aurora-postgres-pipeline:
source:
rds:
db_identifier: "cluster-id"
engine: aurora-postgresql
database: "database-name"
tables:
include:
- "schema1.table1"
- "schema2.table2"
s3_bucket: "bucket-name"
s3_region: "bucket-region"
s3_prefix: "prefix-name"
export:
kms_key_id: "kms-key-id"
iam_role_arn: "export-role-arn"
stream: true
aws:
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
region: "us-east-1"
authentication:
username: ${{aws_secrets:secret:username}}
password: ${{aws_secrets:secret:password}}
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
index: "${getMetadata(\"table_name\")}"
index_type: custom
document_id: "${getMetadata(\"primary_key\")}"
action: "${getMetadata(\"opensearch_action\")}"
document_version: "${getMetadata(\"document_version\")}"
document_version_type: "external"
aws:
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
region: "us-east-1"
extension:
aws:
secrets:
secret:
secret_id: "rds-secret-id"
region: "us-east-1"
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
refresh_interval: PT1H
```
**참고**
사전 구성된 Amazon Aurora 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
Amazon Aurora를 소스로 사용하려면 파이프라인에 대한 VPC 액세스를 구성해야 합니다. 선택한 VPC는 Amazon Aurora 소스에서 사용하는 것과 동일한 VPC여야 합니다. 그런 다음 하나 이상의 서브넷과 하나 이상의 VPC 보안 그룹을 선택합니다. 파이프라인에는 Aurora MySQL 데이터베이스에 대한 네트워크 액세스가 필요하므로 Aurora 클러스터가 파이프라인의 VPC 보안 그룹에서 데이터베이스 포트로의 인바운드 트래픽을 허용하는 VPC 보안 그룹으로 구성되어 있는지도 확인해야 합니다. 자세한 내용은 [보안 그룹을 통한 액세스 제어](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Overview.RDSSecurityGroups.html)를 참조하세요.
를 사용하여 파이프라인 AWS Management Console 을 생성하는 경우 Amazon Aurora를 소스로 사용하려면 VPC에 파이프라인도 연결해야 합니다. 이를 수행하려면 **네트워크 구성** 섹션을 찾아 **VPC에 연결**을 선택하고 제공된 기본 옵션 중 하나에서 CIDR을 선택하거나 자체 CIDR을 선택합니다. [RFC 1918 Best Current Practice](https://datatracker.ietf.org/doc/html/rfc1918)에 정의된 대로 프라이빗 주소 공간에서 모든 CIDR을 사용할 수 있습니다.
사용자 지정 CIDR을 제공하려면 드롭다운 메뉴에서 기타를 선택합니다. OpenSearch Ingestion과 Amazon Aurora 간의 IP 주소 충돌을 방지하려면 Amazon Aurora VPC CIDR이 OpenSearch Ingestion의 CIDR과 달라야 합니다.
자세한 내용은 [파이프라인에 대한 VPC 액세스 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security.html#pipeline-vpc-configure)을 참조하세요.
## 데이터 일관성
파이프라인은 Amazon Aurora 클러스터의 변경 사항을 지속적으로 폴링하거나 수신하고 OpenSearch 인덱스에서 해당 문서를 업데이트하여 데이터 일관성을 보장합니다.
OpenSearch Ingestion은 데이터 내구성을 보장하는 엔드 투 엔드 승인을 지원합니다. 파이프라인에서는 스냅샷이나 스트림을 읽을 때 병렬 처리를 위해 동적으로 분할을 생성합니다. 파이프라인에서는 OpenSearch 도메인이나 컬렉션에서 모든 레코드를 수집한 후 승인을 받으면 분할을 완료 상태로 표시합니다. OpenSearch Serverless 검색 컬렉션에 수집하려는 경우 파이프라인에서 문서 ID를 생성할 수 있습니다. OpenSearch Serverless 시계열 컬렉션에 수집하려면 파이프라인이 문서 ID를 생성하지 않으므로 파이프라인 싱크 구성`document_id: "${getMetadata(\"primary_key\")}"`에서를 생략해야 합니다.
또한 OpenSearch Ingestion 파이프라인에서는 수신 이벤트 작업을 해당하는 대량 인덱싱 작업에 매핑하여 문서를 쉽게 수집할 수 있게 합니다. 이렇게 하면 데이터 일관성이 유지되므로 Amazon Aurora의 모든 데이터 변경 사항이 OpenSearch에서 해당하는 문서 변경 사항으로 조정됩니다.
## 데이터 형식 매핑
OpenSearch Ingestion 파이프라인은 OpenSearch Service 도메인 또는 컬렉션이 사용할 수 있는 표현에 Aurora PostgreSQL 데이터 유형을 매핑합니다. OpenSearch에 매핑 템플릿이 정의되지 않은 경우 OpenSearch는 처음 전송된 문서를 기반으로 [동적 매핑](https://opensearch.org/docs/latest/field-types/#dynamic-mapping)을 사용하여 필드 유형을 자동으로 결정합니다. 매핑 템플릿을 통해 OpenSearch에서 가장 적합한 필드 유형을 명시적으로 정의할 수도 있습니다.
아래 표에는 Aurora PostgreSQL 데이터 유형과 해당 OpenSearch 필드 유형이 나열되어 있습니다. 명시적 매핑이 정의되지 않은 경우 *기본 OpenSearch 필드 유형* 열에 OpenSearch의 해당 필드 유형이 표시됩니다. 이 경우 OpenSearch는 동적 매핑을 사용하여 필드 유형을 자동으로 결정합니다. *권장 OpenSearch 필드 유형* 열은 매핑 템플릿에서 명시적으로 지정하는 해당 권장 필드 유형입니다. 이들 필드 유형은 Aurora PostgreSQL의 데이터 유형과 더 긴밀하게 맞춤화되며 일반적으로 OpenSearch에서 사용할 수 있는 더 나은 검색 기능을 지원할 수 있습니다.
| Aurora PostgreSQL 데이터 유형 | 기본 OpenSearch 필드 유형 | 권장 OpenSearch 필드 유형 |
| --- | --- | --- |
| smallint | long | bigint |
| 정수 | long | 정수 |
| bigint | long | long |
| decimal | 텍스트 | double 또는 키워드 |
| numeric[ (p, s) ] | 텍스트 | double 또는 키워드 |
| real | 실수 | 실수 |
| double precision | 실수 | double |
| smallserial | long | bigint |
| serial | long | 정수 |
| bigserial | long | long |
| money | 객체 | 객체 |
| character varying(n) | 텍스트 | 텍스트 |
| varchar(n) | 텍스트 | 텍스트 |
| character(n) | 텍스트 | 텍스트 |
| char(n) | 텍스트 | 텍스트 |
| bpchar(n) | 텍스트 | 텍스트 |
| bpchar | 텍스트 | 텍스트 |
| 텍스트 | 텍스트 | 텍스트 |
| enum | 텍스트 | 텍스트 |
| bytea | 텍스트 | 이진수 |
| timestamp [ (p) ](시간대 제외) | long(에포크 밀리초) | 날짜 |
| timestamp [ (p) ](시간대 포함) | long(에포크 밀리초) | 날짜 |
| 날짜 | long(에포크 밀리초) | 날짜 |
| time [ (p) ](시간대 제외) | long(에포크 밀리초) | 날짜 |
| time [ (p) ](시간대 포함) | long(에포크 밀리초) | 날짜 |
| interval [ fields ] [ (p) ] | text(ISO8601 형식) | 텍스트 |
| 부울 | 부울 | 부울 |
| point | text(WKT 형식) | geo\$1shape |
| line | text(WKT 형식) | geo\$1shape |
| lseg | text(WKT 형식) | geo\$1shape |
| box | text(WKT 형식) | geo\$1shape |
| 경로 | text(WKT 형식) | geo\$1shape |
| 다각형 | text(WKT 형식) | geo\$1shape |
| circle | 객체 | 객체 |
| cidr | 텍스트 | 텍스트 |
| inet | 텍스트 | 텍스트 |
| macaddr | 텍스트 | 텍스트 |
| macaddr8 | 텍스트 | 텍스트 |
| bit(n) | long | byte, short, integer 또는 long(비트 수에 따라 다름) |
| bit varying(n) | long | byte, short, integer 또는 long(비트 수에 따라 다름) |
| json | 객체 | 객체 |
| jsonb | 객체 | 객체 |
| jsonpath | 텍스트 | 텍스트 |
OpenSearch Ingestion 파이프라인에서 DLQ(Dead Letter Queue)를 구성하는 것이 좋습니다. 이 대기열을 구성하면 OpenSearch Service에서는 동적 매핑 실패로 인해 수집할 수 없는 모든 실패한 문서를 대기열로 전송합니다.
자동 매핑이 실패할 경우 파이프라인 구성에서 `template_type` 및 `template_content`를 사용하여 명시적 매핑 규칙을 정의할 수 있습니다. 또는 파이프라인을 시작하기 전에 검색 도메인이나 컬렉션에서 직접 매핑 템플릿을 생성할 수도 있습니다.
## 제한 사항
Aurora PostgreSQL용 OpenSearch Ingestion 파이프라인을 설정하는 경우 다음과 같은 제한 사항을 고려하세요.
+ 이 통합에서는 파이프라인당 하나의 Aurora PostgreSQL 데이터베이스만 지원합니다.
+ 이 통합에서는 현재 교차 리전 데이터 수집을 지원하지 않습니다. Amazon Aurora 클러스터와 OpenSearch 도메인은 동일한 AWS 리전에 있어야 합니다.
+ 이 통합에서는 현재 교차 계정 데이터 수집을 지원하지 않습니다. Amazon Aurora 클러스터와 OpenSearch Ingestion 파이프라인은 동일한 AWS 계정에 있어야 합니다.
+ 지원되는 유일한 인증 메커니즘인 AWS Secrets Manager를 사용한 인증이 Amazon Aurora 클러스터에 활성화되어 있는지 확인합니다.
+ 기존 파이프라인 구성은 다른 데이터베이스 및/또는 다른 테이블에서 데이터를 수집하도록 업데이트할 수 없습니다. 파이프라인의 데이터베이스 및/또는 테이블 이름을 업데이트하려면 파이프라인을 중지하고 업데이트된 구성으로 다시 시작하거나 새 파이프라인을 생성해야 합니다.
+ 데이터 정의 언어(DDL) 문은 일반적으로 지원되지 않습니다. 다음의 경우에는 데이터 일관성이 유지되지 않습니다.
+ 기본 키가 변경될 경우(추가/삭제/이름 변경)
+ 테이블이 삭제되거나 잘린 경우.
+ 열 이름 또는 데이터 형식이 변경된 경우.
+ 동기화할 Aurora PostgreSQL 테이블에 기본 키가 정의되지 않은 경우 데이터 일관성이 보장되지 않습니다. 업데이트/삭제를 OpenSearch에 동기화하려면 OpenSearch 및 싱크 구성에서 사용자 지정 `document_id` 옵션을 올바르게 정의해야 합니다.
+ 지원되는 버전: Aurora PostgreSQL 버전 16.4 이상
## 권장되는 CloudWatch 경보
수집 파이프라인의 성능을 모니터링하려면 다음 CloudWatch 지표가 권장됩니다. 이러한 지표는 내보내기에서 처리된 데이터의 양, 스트림에서 처리된 이벤트의 수, 내보내기 및 스트림 이벤트 처리 오류, 대상에 쓴 문서 수를 식별하는 데 도움이 될 수 있습니다. 이러한 지표 중 하나가 지정된 시간 동안 지정된 값을 초과하면 작업을 수행하도록 CloudWatch 경보를 설정할 수 있습니다.
| 지표 | 설명 |
| --- | --- |
| pipeline-name.rds.credentialsChanged | 이 지표는 AWS 보안 암호 교체 빈도를 나타냅니다. |
| pipeline-name.rds.executorRefreshErrors | 이 지표는 AWS 보안 암호 새로 고침 실패를 나타냅니다. |
| pipeline-name.rds.exportRecordsTotal | 이 지표는 Amazon Aurora에서 내보낸 레코드 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsProcessed | 이 지표는 OpenSearch Ingestion 파이프라인에서 처리한 레코드 수를 나타냅니다. |
| pipeline-name.rds.exportRecordProcessingErrors | 이 지표는 Amazon Aurora 클러스터에서 데이터를 읽는 동안 OpenSearch Ingestion 파이프라인에서 처리한 오류 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsSuccessTotal | 이 지표는 성공적으로 처리한 내보내기 레코드의 총 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsFailedTotal | 이 지표는 처리하지 못한 내보내기 레코드의 총 수를 나타냅니다. |
| pipeline-name.rds.bytesReceived | 이 지표는 OpenSearch Ingestion 파이프라인에서 수신한 총 바이트 수를 나타냅니다. |
| pipeline-name.rds.bytesProcessed | 이 지표는 OpenSearch Ingestion 파이프라인에서 처리한 총 바이트 수를 나타냅니다. |
| pipeline-name.rds.streamRecordsSuccessTotal | 이 지표는 스트림에서 성공적으로 처리한 레코드 수를 나타냅니다. |
| pipeline-name.rds.streamRecordsFailedTotal | 이 지표는 스트림에서 처리하지 못한 총 레코드 수를 나타냅니다. |
# Amazon DynamoDB와 함께 OpenSearch Ingestion 파이프라인 사용
[DynamoDB](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/dynamo-db/) 플러그인을 사용하여 생성, 업데이트, 삭제 등의 테이블 이벤트를 Amazon OpenSearch Service 도메인 및 Amazon OpenSearch Serverless 컬렉션으로 스트리밍할 수 있습니다. 파이프라인은 변경 데이터 캡처(CDC)를 사용하여 지연 시간이 짧은 대규모 스트리밍을 지원합니다.
전체 초기 스냅샷을 사용하거나 사용하지 않으면서 DynamoDB 데이터를 처리할 수 있습니다.
+ **전체 스냅샷 사용** - DynamoDB가 [시점 복구](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/PointInTimeRecovery.html)(PITR)를 사용하여 백업을 생성하고 Amazon S3에 업로드합니다. 그런 다음 OpenSearch Ingestion이 하나 이상의 OpenSearch 인덱스에서 스냅샷을 인덱싱합니다. 일관성을 유지하기 위해 파이프라인은 모든 DynamoDB 변경 사항을 OpenSearch와 동기화합니다. 이 옵션을 사용하려면 PITR과 [DynamoDB Streams](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.Streams)를 모두 활성화해야 합니다.
+ **스냅샷 사용 안 함** - OpenSearch Ingestion이 새 DynamoDB 이벤트만 스트리밍합니다. 이미 스냅샷이 있거나 기록 데이터 없이 실시간 스트리밍이 필요한 경우 이 옵션을 선택합니다. 이 옵션을 사용하려면 DynamoDB 스트림만 활성화해야 합니다.
자세한 내용은 *Amazon DynamoDB 개발자 가이드*의 [DynamoDB zero-ETL integration with Amazon OpenSearch Service](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/OpenSearchIngestionForDynamoDB.html)를 참조하세요.
**Topics**
+ [
## 사전 조건
](#s3-prereqs)
+ [
## 1단계: 파이프라인 역할 구성
](#ddb-pipeline-role)
+ [
## 2단계: 파이프라인 생성
](#ddb-pipeline)
+ [
## 데이터 일관성
](#ddb-pipeline-consistency)
+ [
## 데이터 형식 매핑
](#ddb-pipeline-mapping)
+ [
## 제한 사항
](#ddb-pipeline-limitations)
+ [
## DynamoDB에 대해 권장되는 CloudWatch 경보
](#ddb-pipeline-metrics)
## 사전 조건
파이프라인을 설정하려면 DynamoDB 스트림이 활성화된 DynamoDB 테이블이 있어야 합니다. 스트림은 `NEW_IMAGE` 스트림 뷰 유형을 사용해야 합니다. 하지만 `NEW_AND_OLD_IMAGES` 유형이 사용 사례에 맞는 경우 OpenSearch Ingestion 파이프라인에서는 이 스트림 뷰 유형으로도 이벤트를 스트리밍할 수 있습니다.
스냅샷을 사용하는 경우 테이블에서 특정 시점 복구도 활성화해야 합니다. 자세한 내용은 *Amazon DynamoDB 개발자 안내서*의 [테이블 생성](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html#WorkingWithTables.Basics.CreateTable), [특정 시점으로 복구 활성화](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/PointInTimeRecovery_Howitworks.html#howitworks_enabling) 및 [스트림 활성화](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html#Streams.Enabling)를 참조하세요.
## 1단계: 파이프라인 역할 구성
DynamoDB 테이블을 설정한 후 파이프라인 구성에서 사용하려는 [파이프라인 역할을 설정](pipeline-security-overview.md#pipeline-security-sink)하고 다음 DynamoDB 권한을 해당 역할에 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "allowRunExportJob",
"Effect": "Allow",
"Action": [
"dynamodb:DescribeTable",
"dynamodb:DescribeContinuousBackups",
"dynamodb:ExportTableToPointInTime"
],
"Resource": [
"arn:aws:dynamodb:us-east-1:111122223333:table/my-table"
]
},
{
"Sid": "allowCheckExportjob",
"Effect": "Allow",
"Action": [
"dynamodb:DescribeExport"
],
"Resource": [
"arn:aws:dynamodb:us-east-1:111122223333:table/my-table/export/*"
]
},
{
"Sid": "allowReadFromStream",
"Effect": "Allow",
"Action": [
"dynamodb:DescribeStream",
"dynamodb:GetRecords",
"dynamodb:GetShardIterator"
],
"Resource": [
"arn:aws:dynamodb:us-east-1:111122223333:table/my-table/stream/*"
]
},
{
"Sid": "allowReadAndWriteToS3ForExport",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:AbortMultipartUpload",
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/export-folder/*"
]
}
]
}
```
------
AWS KMS 고객 관리형 키를 사용하여 내보내기 데이터 파일을 암호화할 수도 있습니다. 내보낸 객체를 해독하려면 파이프라인의 내보내기 구성에서 키 ID에 `arn:aws:kms:region:account-id:key/my-key-id` 형식으로 `s3_sse_kms_key_id`를 지정합니다. 다음 정책에는 고객 관리형 키를 사용하는 데 필요한 권한이 포함되어 있습니다.
```
{
"Sid": "allowUseOfCustomManagedKey",
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": arn:aws:kms:region:account-id:key/my-key-id
}
```
## 2단계: 파이프라인 생성
이제 DynamoDB를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다. 이 샘플 파이프라인은 PITR 스냅샷이 있는 `table-a`에서 데이터를 수집한 다음 DynamoDB 스트림에서 이벤트를 수집합니다. `LATEST` 시작 위치는 파이프라인이 DynamoDB 스트림에서 최신 데이터를 읽어야 함을 나타냅니다.
```
version: "2"
cdc-pipeline:
source:
dynamodb:
tables:
- table_arn: "arn:aws:dynamodb:region:account-id:table/table-a"
export:
s3_bucket: "my-bucket"
s3_prefix: "export/"
stream:
start_position: "LATEST"
aws:
region: "us-east-1"
sink:
- opensearch:
hosts: ["https://search-mydomain.region.es.amazonaws.com"]
index: "${getMetadata(\"table-name\")}"
index_type: custom
normalize_index: true
document_id: "${getMetadata(\"primary_key\")}"
action: "${getMetadata(\"opensearch_action\")}"
document_version: "${getMetadata(\"document_version\")}"
document_version_type: "external"
```
사전 구성된 DynamoDB 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
## 데이터 일관성
OpenSearch Ingestion은 데이터 내구성을 보장하는 엔드 투 엔드 승인을 지원합니다. 파이프라인에서는 스냅샷이나 스트림을 읽을 때 병렬 처리를 위해 동적으로 분할을 생성합니다. 파이프라인에서는 OpenSearch 도메인이나 컬렉션에서 모든 레코드를 수집한 후 승인을 받으면 분할을 완료 상태로 표시합니다.
OpenSearch Serverless *검색* 컬렉션에 수집하려는 경우 파이프라인에서 문서 ID를 생성할 수 있습니다. OpenSearch Serverless *시계열* 컬렉션에 수집하려는 경우에는 파이프라인에서 문서 ID를 생성하지 않습니다.
또한 OpenSearch Ingestion 파이프라인에서는 수신 이벤트 작업을 해당하는 대량 인덱싱 작업에 매핑하여 문서를 쉽게 수집할 수 있게 합니다. 이렇게 하면 데이터 일관성이 유지되므로 DynamoDB의 모든 데이터 변경 사항이 OpenSearch에서 해당하는 문서 변경 사항으로 조정됩니다.
## 데이터 형식 매핑
OpenSearch Service에서는 각 수신 문서의 데이터 형식을 DynamoDB의 해당 데이터 형식에 동적으로 매핑합니다. 다음 표에서는 OpenSearch Service에서 다양한 데이터 형식을 자동으로 매핑하는 방법을 보여줍니다.
| 데이터 유형 | OpenSearch | DynamoDB |
| --- | --- | --- |
| 숫자 | OpenSearch에서는 숫자 데이터를 자동으로 매핑합니다. 숫자가 정수인 경우 OpenSearch에서는 숫자를 긴 정수 값으로 매핑합니다. 숫자가 소수인 경우 OpenSearch에서는 숫자를 부동 소수점 값으로 매핑합니다. OpenSearch에서는 처음 보낸 문서를 기반으로 다양한 속성을 동적으로 매핑합니다. DynamoDB의 동일한 속성에 정수와 분수와 같은 여러 데이터 형식이 혼합되어 있는 경우 매핑이 실패할 수 있습니다. 예를 들어 첫 번째 문서에는 정수인 속성이 있고 이후 문서에는 동일한 속성이 소수로 되어 있는 경우 OpenSearch에서 두 번째 문서를 수집하지 못합니다. 이러한 경우에는 다음과 같은 명시적 매핑 템플릿을 제공해야 합니다.
배정밀도가 필요한 경우 문자열 형식의 필드 매핑을 사용합니다. OpenSearch에는 38자리 정밀도를 지원하는 동등한 숫자 형식이 없습니다. | DynamoDB는 [숫자](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.Number)를 지원합니다. |
| 숫자 집합 | OpenSearch에서는 숫자 집합을 긴 정수 값이나 부동 소수점 값의 배열에 자동으로 매핑합니다. 스칼라 수와 마찬가지로, 매핑은 수집된 첫 번째 숫자가 정수인지 소수인지에 따라 달라집니다. 스칼라 문자열을 매핑하는 것과 같은 방식으로 숫자 집합에 대한 매핑을 제공할 수 있습니다. | DynamoDB는 [숫자 집합](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.SetTypes)을 나타내는 형식을 지원합니다. |
| 문자열 | OpenSearch에서는 문자열 값을 자동으로 텍스트에 매핑합니다. 열거된 값과 같은 일부 상황에서는 키워드 형식에 매핑할 수 있습니다. 다음 예제에서는 이름이 `PartType`인 DynamoDB 속성을 OpenSearch 키워드에 매핑하는 방법을 보여줍니다.
| DynamoDB는 [문자열](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.String)을 지원합니다. |
| 문자열 집합 | OpenSearch에서는 문자열 집합을 자동으로 문자열 배열에 매핑합니다. 스칼라 문자열을 매핑하는 것과 같은 방식으로 문자열 집합에 대한 매핑을 제공할 수 있습니다. | DynamoDB는 [문자열 집합](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.SetTypes)을 나타내는 형식을 지원합니다. |
| 바이너리 | OpenSearch에서는 바이너리 데이터를 자동으로 텍스트에 매핑합니다. OpenSearch에서 이러한 데이터를 바이너리 필드로 작성하기 위한 매핑을 제공할 수 있습니다. 다음 예제에서는 이름이 `ImageData`인 DynamoDB 속성을 OpenSearch 바이너리 필드에 매핑하는 방법을 보여줍니다.
| DynamoDB는 [이진수 형식 속성](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.Binary)을 지원합니다. |
| 이진수 집합 | OpenSearch에서는 이진수 집합을 텍스트 형식인 이진수 데이터 배열에 자동으로 매핑합니다. 스칼라 이진수를 매핑하는 것과 같은 방식으로 숫자 집합에 대한 매핑을 제공할 수 있습니다. | DynamoDB에서는 [이진수 값 집합](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.SetTypes)을 나타내는 형식을 지원합니다. |
| 부울 | OpenSearch에서는 DynamoDB 부울 형식을 OpenSearch 부울 형식으로 매핑합니다. | DynamoDB에서는 [부울 형식 속성](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.Boolean)을 지원합니다. |
| Null | OpenSearch에서는 DynamoDB null 형식의 문서를 수집할 수 있습니다. 값을 문서에 null 값으로 저장합니다. 이 형식에는 매핑이 없으며 이 필드는 인덱싱되거나 검색할 수 없습니다. 한 속성 이름을 null 형식에 사용한 후 나중에 문자열과 같은 다른 형식으로 변경하면 OpenSearch에서 null이 아닌 첫 번째 값에 대해 동적 매핑을 생성합니다. 후속 값은 여전히 DynamoDB null 값일 수 있습니다. | DynamoDB는 [null 형식 속성](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.Null)을 지원합니다. |
| 맵 | OpenSearch에서는 DynamoDB 맵 속성을 중첩 필드에 매핑합니다. 중첩 필드 내에도 동일한 매핑이 적용됩니다. 다음 예제에서는 중첩 필드의 문자열을 OpenSearch의 키워드 형식에 매핑합니다.
| DynamoDB는 [맵 형식 속성](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.Document.Map)을 지원합니다. |
| List | OpenSearch에서는 목록의 내용에 따라 DynamoDB 목록에 대해 다른 결과를 제공합니다. 목록에 모두 동일한 유형의 스칼라 형식(예: 모든 문자열 목록)이 포함된 경우 OpenSearch에서는 해당 목록을 해당 형식의 배열로 수집합니다. 이 방식은 문자열, 숫자, 부울 및 null 유형에서 작동합니다. 각 형식에 대한 제한은 해당 형식의 스칼라에 대한 제한과 동일합니다. 맵에 사용하는 것과 동일한 매핑을 사용하여 맵 목록에 대한 매핑을 제공할 수도 있습니다. 혼합 형식 목록은 제공할 수 없습니다. | DynamoDB는 [목록 형식 속성](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.Document.List)을 지원합니다. |
| Set | OpenSearch에서는 집합의 내용에 따라 DynamoDB 집합에 대해 다른 결과를 제공합니다. 집합에 모두 동일한 유형의 스칼라 형식(예: 모든 문자열 집합)이 포함된 경우 OpenSearch에서는 해당 집합을 해당 형식의 배열로 수집합니다. 이 방식은 문자열, 숫자, 부울 및 null 유형에서 작동합니다. 각 형식에 대한 제한은 해당 형식의 스칼라에 대한 제한과 동일합니다. 맵에 사용하는 것과 동일한 매핑을 사용하여 맵 집합에 대한 매핑을 제공할 수도 있습니다. 혼합 형식 집합은 제공할 수 없습니다. | DynamoDB는 [집합](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.SetTypes)을 나타내는 형식을 지원합니다. |
OpenSearch Ingestion 파이프라인에서 DLQ(Dead Letter Queue)를 구성하는 것이 좋습니다. 이 대기열을 구성하면 OpenSearch Service에서는 동적 매핑 실패로 인해 수집할 수 없는 모든 실패한 문서를 대기열로 전송합니다.
자동 매핑이 실패할 경우 파이프라인 구성에서 `template_type` 및 `template_content`를 사용하여 명시적 매핑 규칙을 정의할 수 있습니다. 또는 파이프라인을 시작하기 전에 검색 도메인이나 컬렉션에서 직접 매핑 템플릿을 생성할 수도 있습니다.
## 제한 사항
DynamoDB용 OpenSearch Ingestion 파이프라인을 설정하는 경우 다음과 같은 제한 사항을 고려하세요.
+ DynamoDB와의 OpenSearch Ingestion 통합 기능에서는 현재 교차 리전 수집을 지원하지 않습니다. DynamoDB 테이블과 OpenSearch Ingestion 파이프라인은 동일한 AWS 리전에 속해야 합니다.
+ DynamoDB 테이블과 OpenSearch Ingestion 파이프라인은 동일한 AWS 계정에 속해야 합니다.
+ OpenSearch Ingestion 파이프라인은 단일 DynamoDB 테이블만 소스로 지원합니다.
+ DynamoDB 스트림은 최대 24시간 동안만 데이터를 로그에 저장합니다. 대규모 테이블의 초기 스냅샷에서 수집하는 데 24시간 이상 걸리는 경우 일부 초기 데이터 손실이 발생합니다. 이러한 데이터 손실 문제를 완화하려면 테이블 크기를 예측하고 OpenSearch Ingestion 파이프라인의 적절한 컴퓨팅 유닛을 구성하십시오.
## DynamoDB에 대해 권장되는 CloudWatch 경보
수집 파이프라인의 성능을 모니터링하려면 다음 CloudWatch 지표가 권장됩니다. 이러한 지표는 내보내기에서 처리된 데이터의 양, 스트림에서 처리된 이벤트의 양, 내보내기 및 스트림 이벤트 처리 오류, 대상에 쓴 문서 수를 식별하는 데 도움이 될 수 있습니다. 이러한 지표 중 하나가 지정된 시간 동안 지정된 값을 초과하면 작업을 수행하도록 CloudWatch 경보를 설정할 수 있습니다.
| 지표 | 설명 |
| --- |--- |
| dynamodb-pipeline.BlockingBuffer.bufferUsage.value | 사용 중인 버퍼의 양을 나타냅니다. |
| dynamodb-pipeline.dynamodb.activeExportS3ObjectConsumers.value | 내보내기를 위해 Amazon S3 객체를 적극적으로 처리하는 총 OCU 수를 표시합니다. |
| dynamodb-pipeline.dynamodb.bytesProcessed.count | DynamoDB 소스에서 처리된 바이트 수. |
| dynamodb-pipeline.dynamodb.changeEventsProcessed.count | DynamoDB 스트림에서 처리된 변경 이벤트 수. |
| dynamodb-pipeline.dynamodb.changeEventsProcessingErrors.count | DynamoDB에서 처리된 변경 이벤트의 오류 수. |
| dynamodb-pipeline.dynamodb.exportJobFailure.count | Number of export job submission attempts that have failed. |
| dynamodb-pipeline.dynamodb.exportJobSuccess.count | Number of export jobs that have been submitted successfully. |
| dynamodb-pipeline.dynamodb.exportRecordsProcessed.count | 내보내기에서 처리된 총 레코드 수. |
| dynamodb-pipeline.dynamodb.exportRecordsTotal.count | 데이터 내보내기 볼륨을 추적하는 데 필요한 DynamoDB에서 내보낸 레코드의 총 수. |
| dynamodb-pipeline.dynamodb.exportS3ObjectsProcessed.count | Total number of export data files that have been processed successfully from Amazon S3. |
| dynamodb-pipeline.opensearch.bulkBadRequestErrors.count | Count of errors during bulk requests due to malformed request. |
| dynamodb-pipeline.opensearch.bulkRequestLatency.avg | Average latency for bulk write requests made to OpenSearch. |
| dynamodb-pipeline.opensearch.bulkRequestNotFoundErrors.count | Number of bulk requests that failed because the target data could not be found. |
| dynamodb-pipeline.opensearch.bulkRequestNumberOfRetries.count | Number of retries by OpenSearch Ingestion pipelines to write OpenSearch cluster. |
| dynamodb-pipeline.opensearch.bulkRequestSizeBytes.sum | Total size in bytes of all bulk requests made to OpenSearch. |
| dynamodb-pipeline.opensearch.documentErrors.count | Number of errors when sending documents to OpenSearch. The documents causing the errors witll be sent to DLQ. |
| dynamodb-pipeline.opensearch.documentsSuccess.count | Number of documents successfully written to an OpenSearch cluster or collection. |
| dynamodb-pipeline.opensearch.documentsSuccessFirstAttempt.count | Number of documents successfully indexed in OpenSearch on the first attempt. |
| `dynamodb-pipeline.opensearch.documentsVersionConflictErrors.count` | Count of errors due to version conflicts in documents during processing. |
| `dynamodb-pipeline.opensearch.PipelineLatency.avg` | Average latency of OpenSearch Ingestion pipeline to process the data by reading from the source to writint to the destination. |
| dynamodb-pipeline.opensearch.PipelineLatency.max | Maximum latency of OpenSearch Ingestion pipeline to process the data by reading from the source to writing the destination. |
| dynamodb-pipeline.opensearch.recordsIn.count | Count of records successfully ingested into OpenSearch. This metric is essential for tracking the volume of data being processed and stored. |
| dynamodb-pipeline.opensearch.s3.dlqS3RecordsFailed.count | Number of records that failed to write to DLQ. |
| dynamodb-pipeline.opensearch.s3.dlqS3RecordsSuccess.count | Number of records that are written to DLQ. |
| dynamodb-pipeline.opensearch.s3.dlqS3RequestLatency.count | Count of latency measurements for requests to the Amazon S3 dead-letter queue. |
| dynamodb-pipeline.opensearch.s3.dlqS3RequestLatency.sum | Total latency for all requests to the Amazon S3 dead-letter queue |
| dynamodb-pipeline.opensearch.s3.dlqS3RequestSizeBytes.sum | Total size in bytes of all requests made to the Amazon S3 dead-letter queue. |
| dynamodb-pipeline.recordsProcessed.count | Total number of records processed in the pipeline, a key metric for overal throughput. |
| dynamodb.changeEventsProcessed.count | No records are being gathered from DynamoDB streams. This could be due to no activitiy on the table, an export being in progress, or an issue accessing the DynamoDB streams. |
| `dynamodb.exportJobFailure.count` | The attempt to trigger an export to S3 failed. |
| `dynamodb-pipeline.opensearch.bulkRequestInvalidInputErrors.count` | Count of bulk request errors in OpenSearch due to invalid input, crucial for monitoring data quality and operational issues. |
| opensearch.EndToEndLatency.avg | The end to end latnecy is higher than desired for reading from DynamoDB streams. This could be due to an underscaled OpenSearch cluster or a maximum pipeline OCU capacity that is too low for the WCU throughput on the DynamoDB table. This end to end latency will be high after an export and should decrease over time as it catches up to the latest DynamoDB streams. |
# Amazon DocumentDB에서 OpenSearch Ingestion 파이프라인 사용
[DocumentDB](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/documentdb/) 플러그인을 사용하여 생성, 업데이트, 삭제 등의 문서 변경 사항을 Amazon OpenSearch Service로 스트리밍할 수 있습니다. 이 파이프라인은 가능한 경우 변경 데이터 캡처(CDC) 또는 지연 시간이 짧은 대규모 스트리밍을 위한 API 폴링을 지원합니다.
전체 초기 스냅샷을 사용하거나 사용하지 않으면서 데이터를 처리할 수 있습니다. 전체 스냅샷은 전체 Amazon DocumentDB 컬렉션을 캡처하여 Amazon S3에 업로드합니다. 그러면 이 파이프라인이 데이터를 하나 이상의 OpenSearch 인덱스로 전송합니다. 스냅샷을 수집한 후 이 파이프라인은 지속적인 변경 사항을 동기화하여 일관성을 유지하고 결국 거의 실시간에 가까운 업데이트를 포착합니다.
다른 소스의 전체 스냅샷이 이미 있거나 새 이벤트만 처리해야 하는 경우 스냅샷 없이 스트리밍할 수 있습니다. 이 경우 파이프라인은 초기 대량 로드 없이 Amazon DocumentDB 변경 스트림에서 직접 읽습니다.
스트리밍을 활성화하는 경우 Amazon DocumentDB 컬렉션에 대해 [변경 스트림을 활성화](https://docs.aws.amazon.com/documentdb/latest/developerguide/change_streams.html#change_streams-enabling)해야 합니다. 하지만 전체 로드 또는 내보내기만 수행하는 경우에는 변경 스트림이 필요하지 않습니다.
## 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. **Amazon DocumentDB 개발자 안내서의 [Create an Amazon DocumentDB cluster](https://docs.aws.amazon.com/documentdb/latest/developerguide/get-started-guide.html#cloud9-cluster)에 나온 단계를 수행하여 데이터 읽기 권한을 가진 Amazon DocumentDB 클러스터를 생성합니다. CDC 인프라를 사용하는 경우 변경 스트림을 게시하도록 Amazon DocumentDB 클러스터를 구성합니다.
1. Amazon DocumentDB 클러스터에서 TLS를 활성화합니다.
1. OpenSearch Ingestion에서 사용할 프라이빗 주소 공간의 VPC CIDR을 설정합니다.
1. 를 사용하여 Amazon DocumentDB 클러스터에 대한 인증을 설정합니다 AWS Secrets Manager. [Automatically Rotating Passwords for Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/security.managing-users.html#security.managing-users-rotating-passwords)에 나온 단계를 수행하여 스크릿 교체를 활성화합니다. 자세한 내용은 [Database Access Using Role-Based Access Control](https://docs.aws.amazon.com/documentdb/latest/developerguide/role_based_access_control.html) 및 [Security in Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/security.html)를 참조하세요.
1. 변경 스트림을 사용하여 Amazon DocumentDB 컬렉션의 데이터 변경 사항을 구독하는 경우 `change_stream_log_retention_duration` 파라미터를 사용하여 보존 기간을 최대 7일로 연장해 데이터 손실을 방지합니다. 변경 스트림 이벤트는 이벤트가 기록된 후 기본적으로 3시간 동안 저장됩니다.단, 대규모 수집에 충분한 시간이 아닙니다. 변경 스트림 보존 기간을 수정하려면 [Modifying the Change Stream Log Retention Duration](https://docs.aws.amazon.com/documentdb/latest/developerguide/change_streams.html#change_streams-modifying_log_retention)을 참조하세요.
1. OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](createupdatedomains.md#createdomains) 및 [컬렉션 생성](serverless-create.md) 섹션을 참조하세요.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 Amazon DocumentDB 클러스터의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
다음 샘플 도메인 액세스 정책은 다음 단계에서 생성하는 파이프라인 역할을 사용하여 도메인에 데이터를 쓰도록 허용합니다. 자체 ARN으로 `resource`을 업데이트해야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:role/pipeline-role"
},
"Action": [
"es:DescribeDomain",
"es:ESHttp*"
],
"Resource": [
"arn:aws:es:us-east-1:111122223333:domain/domain-name"
]
}
]
}
```
------
컬렉션 또는 도메인에 쓰기 데이터에 액세스할 수 있는 올바른 권한이 있는 IAM 역할을 생성하려면 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md)을 참조하세요.
## 1단계: 파이프라인 역할 구성
Amazon DocumentDB 파이프라인 사전 조건을 설정한 후 파이프라인 구성에서 사용하려는 [파이프라인 역할을 구성](pipeline-security-overview.md#pipeline-security-sink)하고 역할에서 다음 Amazon DocumentDB 권한을 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "allowS3ListObjectAccess",
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::s3-bucket"
],
"Condition": {
"StringLike": {
"s3:prefix": "s3-prefix/*"
}
}
},
{
"Sid": "allowReadAndWriteToS3ForExportStream",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::s3-bucket/s3-prefix/*"
]
},
{
"Sid": "SecretsManagerReadAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:111122223333:secret:secret-name"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:AttachNetworkInterface",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DetachNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"arn:aws:ec2:*:111122223333:network-interface/*",
"arn:aws:ec2:*:111122223333:subnet/*",
"arn:aws:ec2:*:111122223333:security-group/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeDhcpOptions",
"ec2:DescribeRouteTables",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:Describe*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:*:network-interface/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/OSISManaged": "true"
}
}
}
]
}
```
------
파이프라인은 이러한 권한을 사용하여 VPC에서 네트워크 인터페이스를 생성하고 삭제하므로 OpenSearch Ingestion 파이프라인을 생성하는 데 사용하는 IAM 역할에서 위의 Amazon EC2 권한을 제공해야 합니다. 파이프라인은 오직 이 네트워크 인터페이스를 통해 Amazon DocumentDB 클러스터에 액세스할 수 있습니다.
## 2단계: 파이프라인 생성
이제 Amazon DocumentDB를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다. 인덱스 이름을 채우기 위해 `getMetadata` 함수는 `documentdb_collection`을 메타데이터 키로 사용합니다. `getMetadata` 메서드 없이 다른 인덱스 이름을 사용하려면 `index: "my_index_name"` 구성을 사용할 수 있습니다.
```
version: "2"
documentdb-pipeline:
source:
documentdb:
acknowledgments: true
host: "https://docdb-cluster-id.us-east-1.docdb.amazonaws.com"
port: 27017
authentication:
username: ${aws_secrets:secret:username}
password: ${aws_secrets:secret:password}
aws:
s3_bucket: "bucket-name"
s3_region: "bucket-region"
s3_prefix: "path" #optional path for storing the temporary data
collections:
- collection: "dbname.collection"
export: true
stream: true
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
index: "${getMetadata(\"documentdb_collection\")}"
index_type: custom
document_id: "${getMetadata(\"primary_key\")}"
action: "${getMetadata(\"opensearch_action\")}"
document_version: "${getMetadata(\"document_version\")}"
document_version_type: "external"
extension:
aws:
secrets:
secret:
secret_id: "my-docdb-secret"
region: "us-east-1"
refresh_interval: PT1H
```
사전 구성된 Amazon DocumentDB 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
를 사용하여 파이프라인 AWS Management Console 을 생성하는 경우 Amazon DocumentDB를 소스로 사용하려면 VPC에 파이프라인도 연결해야 합니다. 이를 수행하려면 **소스 네트워크 옵션** 섹션을 찾아 **VPC에 연결** 확인란을 선택하고 제공된 기본 옵션 중 하나에서 CIDR을 선택합니다. [RFC 1918 Best Current Practice](https://datatracker.ietf.org/doc/html/rfc1918)에 정의된 대로 프라이빗 주소 공간에서 모든 CIDR을 사용할 수 있습니다.
사용자 지정 CIDR을 제공하려면 드롭다운 메뉴에서 **기타**를 선택합니다. OpenSearch Ingestion과 자Amazon DocumentDB 간의 IP 주소 충돌을 방지하려면 Amazon DocumentDB VPC CIDR이 OpenSearch Ingestion의 CIDR과 달라야 합니다.
자세한 내용은 [파이프라인에 대한 VPC 액세스 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security.html#pipeline-vpc-configure)을 참조하세요.
## 데이터 일관성
파이프라인은 Amazon DocumentDB 클러스터의 변경 사항을 지속적으로 폴링하거나 수신하고 OpenSearch 인덱스에서 해당 문서를 업데이트하여 데이터 일관성을 보장합니다.
OpenSearch Ingestion은 데이터 내구성을 보장하는 엔드 투 엔드 승인을 지원합니다. 파이프라인에서는 스냅샷이나 스트림을 읽을 때 병렬 처리를 위해 동적으로 분할을 생성합니다. 파이프라인에서는 OpenSearch 도메인이나 컬렉션에서 모든 레코드를 수집한 후 승인을 받으면 분할을 완료 상태로 표시합니다.
OpenSearch Serverless *검색* 컬렉션에 수집하려는 경우 파이프라인에서 문서 ID를 생성할 수 있습니다. OpenSearch Serverless *시계열* 컬렉션으로 수집하려는 경우에는 파이프라인에서 문서 ID를 생성하지 않습니다. 따라서 파이프라인 싱크 구성에서 `document_id: "${getMetadata(\"primary_key\")}"`를 생략해야 합니다.
또한 OpenSearch Ingestion 파이프라인에서는 수신 이벤트 작업을 해당하는 대량 인덱싱 작업에 매핑하여 문서를 쉽게 수집할 수 있게 합니다. 이렇게 하면 데이터 일관성이 유지되므로 Amazon DocumentDB의 모든 데이터 변경 사항이 OpenSearch에서 해당하는 문서 변경 사항으로 조정됩니다.
## 데이터 형식 매핑
OpenSearch Service에서는 각 수신 문서의 데이터 형식을 Amazon DocumentDB의 해당 데이터 형식에 동적으로 매핑합니다. 다음 표에서는 OpenSearch Service에서 다양한 데이터 형식을 자동으로 매핑하는 방법을 보여줍니다.
| 데이터 유형 | OpenSearch | Amazon DocumentDB |
| --- | --- | --- |
| Integer | OpenSearch는 Amazon DocumentDB 정수 값을 OpenSearch 정수에 자동으로 매핑합니다. OpenSearch에서는 처음 보낸 문서를 기반으로 필드를 동적으로 매핑합니다. Amazon DocumentDB에서 동일한 속성에 대해 데이터 유형을 혼합한 경우 자동 매핑이 실패할 수 있습니다. 예를 들어 첫 번째 문서에는 long인 속성이 있고 이후 문서에는 동일한 속성이 정수인 경우 OpenSearch는 두 번째 문서를 수집하지 못합니다. 이러한 경우에는 다음과 같이 보다 유연한 숫자 유형을 선택하는 명시적 매핑 템플릿을 제공해야 합니다.
| Amazon DocumentDB는 [정수](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
| Long | OpenSearch는 Amazon DocumentDB long 값을 OpenSearch long에 자동으로 매핑합니다. OpenSearch에서는 처음 보낸 문서를 기반으로 필드를 동적으로 매핑합니다. Amazon DocumentDB에서 동일한 속성에 대해 데이터 유형을 혼합한 경우 자동 매핑이 실패할 수 있습니다. 예를 들어 첫 번째 문서에는 long인 속성이 있고 이후 문서에는 동일한 속성이 정수인 경우 OpenSearch는 두 번째 문서를 수집하지 못합니다. 이러한 경우에는 다음과 같이 보다 유연한 숫자 유형을 선택하는 명시적 매핑 템플릿을 제공해야 합니다.
| Amazon DocumentDB는 [longs](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
| 문자열 | OpenSearch에서는 문자열 값을 자동으로 텍스트에 매핑합니다. 열거된 값과 같은 일부 상황에서는 키워드 형식에 매핑할 수 있습니다. 다음 예제에서는 이름이 `PartType`인 Amazon DocumentDB 속성을 OpenSearch 키워드에 매핑하는 방법을 보여줍니다.
| Amazon DocumentDB는 [문자열](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)을 지원합니다. |
| 배정밀도 실수 | OpenSearch는 Amazon DocumentDB double 값을 OpenSearch double 값에 자동으로 매핑합니다. OpenSearch에서는 처음 보낸 문서를 기반으로 필드를 동적으로 매핑합니다. Amazon DocumentDB에서 동일한 속성에 대해 데이터 유형을 혼합한 경우 자동 매핑이 실패할 수 있습니다. 예를 들어 첫 번째 문서에는 long인 속성이 있고 이후 문서에는 동일한 속성이 정수인 경우 OpenSearch는 두 번째 문서를 수집하지 못합니다. 이러한 경우에는 다음과 같이 보다 유연한 숫자 유형을 선택하는 명시적 매핑 템플릿을 제공해야 합니다.
| Amazon DocumentDB는 [doubles](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
| Date | 기본적으로 날짜는 OpenSearch의 정수에 매핑됩니다. 사용자 지정 매핑 템플릿을 정의하여 날짜를 OpenSearch 날짜에 매핑할 수 있습니다.
| Amazon DocumentDB는 [날짜](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
| 타임스탬프 | 기본적으로 타임스탬프는 OpenSearch의 정수에 매핑됩니다. 사용자 지정 매핑 템플릿을 정의하여 날짜를 OpenSearch 날짜에 매핑할 수 있습니다.
이 사용자 지정 매핑을 사용하면 double 수준의 정밀도로 필드를 쿼리하고 집계할 수 있습니다. 원래 값은 OpenSearch 문서의 `_source` 속성에서 전체 정밀도를 유지합니다. 이 매핑이 없으면 OpenSearch는 기본적으로 텍스트를 사용합니다. | Amazon DocumentDB는 [소수](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
| 정규식 | 정규식 유형은 중첩 필드를 생성합니다. 여기에는 .pattern 및 .options가 포함됩니다. | Amazon DocumentDB는 [정규식](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)을 지원합니다. |
| 이진 데이터 | OpenSearch는 Amazon DocumentDB 바이너리 데이터를 OpenSearch 텍스트에 자동으로 매핑합니다. OpenSearch에서 이러한 데이터를 바이너리 필드로 작성하기 위한 매핑을 제공할 수 있습니다. 다음 예제에서는 이름이 `imageData`인 Amazon DocumentDB 필드를 OpenSearch 바이너리 필드에 매핑하는 방법을 보여줍니다.
| Amazon DocumentDB는 [바이너리 데이터 필드](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
| ObjectId | objectId 유형의 필드는 OpenSearch 텍스트 필드에 매핑됩니다. 값은 objectId의 문자열 표현입니다. | Amazon DocumentDB는 [objectIds](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
| Null | OpenSearch는 Amazon DocumentDB null 유형의 문서를 수집할 수 있습니다. 값을 문서에 null 값으로 저장합니다. 이 형식에는 매핑이 없으며 이 필드는 인덱싱되거나 검색할 수 없습니다. 한 속성 이름을 null 형식에 사용한 후 나중에 문자열과 같은 다른 형식으로 변경하면 OpenSearch에서 null이 아닌 첫 번째 값에 대해 동적 매핑을 생성합니다. 후속 값은 여전히 Amazon DocumentDB null 값일 수 있습니다. | Amazon DocumentDB는 [null 유형 필드](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
| 정의되지 않음 | OpenSearch는 Amazon DocumentDB 정의되지 않은 유형의 문서를 수집할 수 있습니다. 값을 문서에 null 값으로 저장합니다. 이 형식에는 매핑이 없으며 이 필드는 인덱싱되거나 검색할 수 없습니다. 정의되지 않은 유형에 동일한 필드 이름을 사용한 후 문자열과 같이 다른 유형으로 변경하면 OpenSearch에서 정의되지 않은 값이 아닌 첫 번째 값에 대해 동적 매핑을 생성합니다. 후속 값은 여전히 Amazon DocumentDB 정의되지 않은 값일 수 있습니다. | Amazon DocumentDB는 [정의되지 않은 유형 필드](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
| MinKey | OpenSearch는 Amazon DocumentDB minKey 유형의 문서를 수집할 수 있습니다. 값을 문서에 null 값으로 저장합니다. 이 형식에는 매핑이 없으며 이 필드는 인덱싱되거나 검색할 수 없습니다. minKey 유형에 동일한 필드 이름을 사용한 후 문자열과 같이 다른 유형으로 변경하면 OpenSearch에서 minKey가 아닌 첫 번째 값에 대해 동적 매핑을 생성합니다. 후속 값은 여전히 Amazon DocumentDB minKey 값일 수 있습니다. | Amazon DocumentDB는 [minKey 유형 필드](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
| MaxKey | OpenSearch는 Amazon DocumentDB maxKey 유형의 문서를 수집할 수 있습니다. 값을 문서에 null 값으로 저장합니다. 이 형식에는 매핑이 없으며 이 필드는 인덱싱되거나 검색할 수 없습니다. maxKey 유형에 동일한 필드 이름을 사용한 후 문자열과 같이 다른 유형으로 변경하면 OpenSearch에서 maxKey가 아닌 첫 번째 값에 대해 동적 매핑을 생성합니다. 후속 값은 여전히 Amazon DocumentDB maxKey 값일 수 있습니다. | Amazon DocumentDB는 [maxKey 유형 필드](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)를 지원합니다. |
OpenSearch Ingestion 파이프라인에서 DLQ(Dead Letter Queue)를 구성하는 것이 좋습니다. 이 대기열을 구성하면 OpenSearch Service에서는 동적 매핑 실패로 인해 수집할 수 없는 모든 실패한 문서를 대기열로 전송합니다.
자동 매핑이 실패할 경우 파이프라인 구성에서 `template_type` 및 `template_content`를 사용하여 명시적 매핑 규칙을 정의할 수 있습니다. 또는 파이프라인을 시작하기 전에 검색 도메인이나 컬렉션에서 직접 매핑 템플릿을 생성할 수도 있습니다.
## 제한 사항
Amazon DocumentDB용 OpenSearch Ingestion 파이프라인을 설정하는 경우 다음과 같은 제한 사항을 고려합니다.
+ Amazon DocumentDB와의 OpenSearch Ingestion 통합 기능에서는 현재 교차 리전 수집을 지원하지 않습니다. Amazon DocumentDB 클러스터와 OpenSearch Ingestion 파이프라인은 동일한 AWS 리전에 있어야 합니다.
+ Amazon DocumentDB와의 OpenSearch Ingestion 통합 기능에서는 현재 교차 계정 수집을 지원하지 않습니다. Amazon DocumentDB 클러스터와 OpenSearch Ingestion 파이프라인은 동일한 AWS 계정에 있어야 합니다.
+ OpenSearch Ingestion 파이프라인은 단일 Amazon DocumentDB 테이블만 소스로 지원합니다.
+ Amazon DocumentDB와의 OpenSearch Ingestion 통합은 특별히 Amazon DocumentDB 인스턴스 기반 클러스터를 지원합니다. Amazon DocumentDB 탄력적 클러스터는 지원하지 않습니다.
+ OpenSearch Ingestion 통합은 Amazon DocumentDB 클러스터의 인증 메커니즘 AWS Secrets Manager 으로 만 지원합니다.
+ 다른 데이터베이스 또는 컬렉션에서 데이터를 수집하도록 기존 파이프라인 구성을 업데이트할 수 없습니다. 대신 새 파이프라인을 생성해야 합니다.
## 권장되는 CloudWatch 경보
최상의 성능을 위해 다음 Amazon DocumentDB 클러스터에 소스로 액세스하도록 OpenSearch Ingestion 파이프라인을 생성할 때 다음 CloudWatch 경보를 사용하는 것이 좋습니다.
| CloudWatch 경보 | 설명 |
| --- | --- |
| .doucmentdb.credentialsChanged | 이 지표는 AWS 보안 암호 교체 빈도를 나타냅니다. |
| .doucmentdb.executorRefreshErrors | 이 지표는 AWS 시크릿의 새로 고침 실패를 나타냅니다. |
| .doucmentdb.exportRecordsTotal | 이 지표는 Amazon DocumentDB에서 내보낸 레코드 수를 나타냅니다. |
| .doucmentdb.exportRecordsProcessed | 이 지표는 OpenSearch Ingestion 파이프라인에서 처리한 레코드 수를 나타냅니다. |
| .doucmentdb.exportRecordProcessingErrors | 이 지표는 Amazon DocumentDB 클러스터에서 데이터를 읽는 동안 OpenSearch Ingestion 파이프라인에서 처리한 오류 수를 나타냅니다. |
| .doucmentdb.exportRecordsSuccessTotal | 이 지표는 성공적으로 처리한 내보내기 레코드의 총 수를 나타냅니다. |
| .doucmentdb.exportRecordsFailedTotal | 이 지표는 처리하지 못한 내보내기 레코드의 총 수를 나타냅니다. |
| .doucmentdb.bytesReceived | 이 지표는 OpenSearch Ingestion 파이프라인에서 수신한 총 바이트 수를 나타냅니다. |
| .doucmentdb.bytesProcessed | 이 지표는 OpenSearch Ingestion 파이프라인에서 처리한 총 바이트 수를 나타냅니다. |
| .doucmentdb.exportPartitionQueryTotal | 이 지표는 내보내기 파티션 합계를 나타냅니다. |
| .doucmentdb.streamRecordsSuccessTotal | 이 지표는 스트림에서 성공적으로 처리한 레코드 수를 나타냅니다. |
| .doucmentdb.streamRecordsFailedTotal | 이 지표는 스트림에서 처리하지 못한 총 레코드 수를 나타냅니다. |
# Confluent Cloud Kafka에서 OpenSearch Ingestion 파이프라인 사용
OpenSearch Ingestion 파이프라인을 사용하여 Confluent Cloud Kafka 클러스터에서 Amazon OpenSearch Service 도메인 및 OpenSearch Serverless 컬렉션으로 데이터를 스트리밍할 수 있습니다. OpenSearch Ingestion은 Confluent Cloud Kafka 클러스터에서 OpenSearch Service 또는 OpenSearch Serverless가 관리하는 도메인 또는 컬렉션으로 데이터를 스트리밍하기 위한 퍼블릭 및 프라이빗 네트워크 구성을 모두 지원합니다.
## Confluent Cloud 퍼블릭 Kafka 클러스터에 대한 연결
OpenSearch Ingestion 파이프라인을 사용하여 퍼블릭 구성을 통해 자체 관리형 Confluent Cloud Kafka 클러스터에서 데이터를 마이그레이션할 수 있습니다. 즉, 도메인 DNS 이름을 공개적으로 확인할 수 있습니다. 이렇게 하려면 Confluent Cloud 퍼블릭 Kafka 클러스터를 소스로, OpenSearch Service 또는 OpenSearch Serverless를 대상으로 하는 OpenSearch Ingestion 파이프라인을 설정합니다. 이렇게 하면 자체 관리형 소스 클러스터에서 AWS관리형 대상 도메인 또는 컬렉션으로 스트리밍 데이터가 처리됩니다.
### 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. 소스 역할을 하는 Confluent Cloud Kafka 클러스터를 생성합니다. 클러스터에는 OpenSearch Service로 수집할 데이터가 포함되어 있어야 합니다.
1. 데이터를 마이그레이션할 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](createupdatedomains.md#createdomains) 및 [컬렉션 생성](serverless-create.md) 섹션을 참조하세요.
1. AWS Secrets Manager를 사용하여 Confluent Cloud Kafka 클러스터에서 인증을 설정합니다. [AWS Secrets Manager 시크릿 교체](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)의 단계를 수행하여 시크릿 교체를 활성화합니다.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 자체 관리형 클러스터의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
다음 샘플 도메인 액세스 정책은 다음 단계에서 생성하는 파이프라인 역할을 사용하여 도메인에 데이터를 쓰도록 허용합니다. 자체 ARN으로 `resource`을 업데이트해야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:role/pipeline-role"
},
"Action": [
"es:DescribeDomain",
"es:ESHttp*"
],
"Resource": [
"arn:aws:es:us-east-1:111122223333:domain/domain-name"
]
}
]
}
```
------
컬렉션 또는 도메인에 쓰기 데이터에 액세스할 수 있는 올바른 권한이 있는 IAM 역할을 생성하려면 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md)을 참조하세요.
### 1단계: 파이프라인 역할 구성
Confluent Cloud Kafka 클러스터 파이프라인 사전 조건을 설정한 후 파이프라인 구성에 사용할 [파이프라인 역할을 구성](pipeline-security-overview.md#pipeline-security-sink)하고 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션에 쓸 수 있는 권한과 Secrets Manager에서 시크릿을 읽을 수 있는 권한을 추가합니다.
네트워크 인터페이스를 관리하려면 다음 권한이 필요합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:AttachNetworkInterface",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DetachNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:network-interface/*",
"arn:aws:ec2:us-east-1:111122223333:subnet/*",
"arn:aws:ec2:us-east-1:111122223333:security-group/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeDhcpOptions",
"ec2:DescribeRouteTables",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:Describe*"
],
"Resource": "arn:aws:ec2:us-east-1:111122223333:subnet/*"
},
{
"Effect": "Allow",
"Action": [ "ec2:CreateTags" ],
"Resource": "arn:aws:ec2:us-east-1:111122223333:network-interface/*",
"Condition": {
"StringEquals": { "aws:RequestTag/OSISManaged": "true" }
}
}
]
}
```
------
다음은 AWS Secrets Manager 서비스에서 보안 암호를 읽는 데 필요한 권한입니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerReadAccess",
"Effect": "Allow",
"Action": ["secretsmanager:GetSecretValue"],
"Resource": ["arn:aws:secretsmanager:us-east-1:111122223333:secret:,secret-name"]
}
]
}
```
------
Amazon OpenSearch Service 도메인에 쓰려면 다음 권한이 필요합니다.
```
{
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::account-id:role/pipeline-role"
},
"Action": ["es:DescribeDomain", "es:ESHttp*"],
"Resource": "arn:aws:es:region:account-id:domain/domain-name/*"
}
]
}
```
### 2단계: 파이프라인 생성
이제 Confluent Cloud Kafka를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
여러 OpenSearch Service 도메인을 데이터의 대상으로 지정할 수 있습니다. 이 기능을 사용하여 조건부로 라우팅하거나 수신 데이터를 여러 OpenSearch Service 도메인으로 복제할 수 있습니다.
소스 Confluent Kafka의 데이터를 OpenSearch Serverless VPC 컬렉션으로 마이그레이션할 수도 있습니다. 파이프라인 구성 내에서 네트워크 액세스 정책을 제공해야 합니다. Confluent 스키마 레지스트리를 사용하여 Confluent 스키마를 정의할 수 있습니다.
```
version: "2"
kafka-pipeline:
source:
kafka:
encryption:
type: "ssl"
topics:
- name: "topic-name"
group_id: "group-id"
bootstrap_servers:
- "bootstrap-server.us-east-1.aws.private.confluent.cloud:9092"
authentication:
sasl:
plain:
username: ${aws_secrets:confluent-kafka-secret:username}
password: ${aws_secrets:confluent-kafka-secret:password}
schema:
type: confluent
registry_url: https://my-registry.us-east-1.aws.confluent.cloud
api_key: "${{aws_secrets:schema-secret:schema_registry_api_key}}"
api_secret: "${{aws_secrets:schema-secret:schema_registry_api_secret}}"
basic_auth_credentials_source: "USER_INFO"
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
aws:
region: "us-east-1"
aws:
secrets:
confluent-kafka-secret:
secret_id: "my-kafka-secret"
region: "us-east-1"
schema-secret:
secret_id: "my-self-managed-kafka-schema"
region: "us-east-1"
```
사전 구성된 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
### VPC에서 Confluent Cloud Kafka 클러스터에 대한 연결
OpenSearch Ingestion 파이프라인을 사용하여 VPC에서 실행되는 Confluent Cloud Kafka 클러스터에서 데이터를 마이그레이션할 수도 있습니다. 이렇게 하려면 Confluent Cloud Kafka 클러스터를 소스로, OpenSearch Service 또는 OpenSearch Serverless를 대상으로 하는 OpenSearch Ingestion 파이프라인을 설정합니다. 이렇게 하면 Confluent Cloud Kafka 소스 클러스터에서 AWS관리형 대상 도메인 또는 컬렉션으로 스트리밍 데이터를 처리합니다.
OpenSearch Ingestion은 Confluent에서 지원되는 모든 네트워크 모드에서 구성된 Confluent Cloud Kafka 클러스터를 지원합니다. OpenSearch Ingestion에서 다음 네트워크 구성 모드가 소스로 지원됩니다.
+ AWS VPC 피어링
+ AWS PrivateLink 전용 클러스터용
+ AWS PrivateLink 엔터프라이즈 클러스터용
+ AWS Transit Gateway
#### 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. OpenSearch Service로 수집하려는 데이터가 포함된 VPC 네트워크 구성을 사용하여 Confluent Cloud Kafka 클러스터를 생성합니다.
1. 데이터를 마이그레이션할 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](createupdatedomains.md#createdomains) 및 [컬렉션 생성](serverless-create.md) 섹션을 참조하세요.
1. AWS Secrets Manager를 사용하여 Confluent Cloud Kafka 클러스터에서 인증을 설정합니다. [AWS Secrets Manager 시크릿 교체](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)의 단계를 수행하여 시크릿 교체를 활성화합니다.
1. Confluent Cloud Kafka 클러스터에 대한 액세스 권한이 있는 VPC의 ID를 획득합니다. OpenSearch Ingestion에서 사용할 VPC CIDR을 선택합니다.
**참고**
를 사용하여 파이프라인 AWS Management Console 을 생성하는 경우 Confluent Cloud Kafka 클러스터를 사용하려면 OpenSearch Ingestion 파이프라인도 VPC에 연결해야 합니다. 이를 수행하려면 **네트워크 구성** 섹션을 찾아 **VPC에 연결** 확인란을 선택하고 제공된 기본 옵션 중 하나에서 CIDR을 선택하거나 직접 선택합니다. [RFC 1918 Best Current Practice](https://datatracker.ietf.org/doc/html/rfc1918)에 정의된 대로 프라이빗 주소 공간에서 모든 CIDR을 사용할 수 있습니다.
사용자 지정 CIDR을 제공하려면 드롭다운 메뉴에서 **기타**를 선택합니다. OpenSearch Ingestion과 자체 관리형 OpenSearch 간의 IP 주소 충돌을 방지하려면 자체 관리형 OpenSearch VPC CIDR이 OpenSearch Ingestion의 CIDR과 달라야 합니다.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 자체 관리형 클러스터의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
**참고**
AWS PrivateLink 를 사용하여 Confluent Cloud Kafka를 연결하는 경우 [VPC DHCP 옵션](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html)을 구성해야 합니다. *DNS 호스트 이름*과 *DNS 확인*이 활성화되어 있어야 합니다.
특히 다음 옵션 세트 값을 사용합니다.
**엔터프라이즈 클러스터:**
```
domain-name: aws.private.confluent.cloud
domain-name-servers: AmazonProvidedDNS
```
**전용 클러스터:**
```
domain-name: aws.confluent.cloud
domain-name-servers: AmazonProvidedDNS
```
이렇게 변경하면 Confluent PrivateLink 엔드포인트의 DNS 확인이 VPC 내에서 올바르게 작동합니다.
다음 샘플 도메인 액세스 정책은 다음 단계에서 생성하는 파이프라인 역할을 사용하여 도메인에 데이터를 쓰도록 허용합니다. 자체 ARN으로 `resource`을 업데이트해야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:role/pipeline-role"
},
"Action": [
"es:DescribeDomain",
"es:ESHttp*"
],
"Resource": [
"arn:aws:es:us-east-1:111122223333:domain/domain-name"
]
}
]
}
```
------
컬렉션 또는 도메인에 쓰기 데이터에 액세스할 수 있는 올바른 권한이 있는 IAM 역할을 생성하려면 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md)을 참조하세요.
#### 1단계: 파이프라인 역할 구성
파이프라인 사전 조건을 설정한 후 파이프라인 구성에서 사용하려는 [파이프라인 역할을 구성](pipeline-security-overview.md#pipeline-security-sink)하고 역할에서 다음 권한을 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerReadAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": ["arn:aws:secretsmanager:us-east-1:111122223333:secret:secret-name"]
},
{
"Effect": "Allow",
"Action": [
"ec2:AttachNetworkInterface",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DetachNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"arn:aws:ec2:*:*:network-interface/*",
"arn:aws:ec2:*:*:subnet/*",
"arn:aws:ec2:*:*:security-group/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeDhcpOptions",
"ec2:DescribeRouteTables",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:Describe*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:*:network-interface/*",
"Condition": {
"StringEquals":
{
"aws:RequestTag/OSISManaged": "true"
}
}
}
]
}
```
------
파이프라인은 이러한 권한을 사용하여 VPC에서 네트워크 인터페이스를 생성하고 삭제하므로 OpenSearch Ingestion 파이프라인을 생성하는 데 사용하는 IAM 역할에서 위의 Amazon EC2 권한을 제공해야 합니다. 파이프라인은 오직 이 네트워크 인터페이스를 통해 Kafka 클러스터에 액세스할 수 있습니다.
#### 2단계: 파이프라인 생성
이제 Kafka를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
여러 OpenSearch Service 도메인을 데이터의 대상으로 지정할 수 있습니다. 이 기능을 사용하여 조건부로 라우팅하거나 수신 데이터를 여러 OpenSearch Service 도메인으로 복제할 수 있습니다.
소스 Confluent Kafka의 데이터를 OpenSearch Serverless VPC 컬렉션으로 마이그레이션할 수도 있습니다. 파이프라인 구성 내에서 네트워크 액세스 정책을 제공해야 합니다. Confluent 스키마 레지스트리를 사용하여 Confluent 스키마를 정의할 수 있습니다.
```
version: "2"
kafka-pipeline:
source:
kafka:
encryption:
type: "ssl"
topics:
- name: "topic-name"
group_id: "group-id"
bootstrap_servers:
- "bootstrap-server.us-east-1.aws.private.confluent.cloud:9092"
authentication:
sasl:
plain:
username: ${aws_secrets:confluent-kafka-secret:username}
password: ${aws_secrets:confluent-kafka-secret:password}
schema:
type: confluent
registry_url: https://my-registry.us-east-1.aws.confluent.cloud
api_key: "${{aws_secrets:schema-secret:schema_registry_api_key}}"
api_secret: "${{aws_secrets:schema-secret:schema_registry_api_secret}}"
basic_auth_credentials_source: "USER_INFO"
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
aws:
region: "us-east-1"
index: "confluent-index"
extension:
aws:
secrets:
confluent-kafka-secret:
secret_id: "my-kafka-secret"
region: "us-east-1"
schema-secret:
secret_id: "my-self-managed-kafka-schema"
region: "us-east-2"
```
# 에서 OpenSearch Ingestion 파이프라인 사용 Amazon Managed Streaming for Apache Kafka
[Kafka 플러그인](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/kafka/)을 사용하여 [Amazon Managed Streaming for Apache Kafka](https://docs.aws.amazon.com/msk/latest/developerguide/)(Amazon MSK)에서 OpenSearch Ingestion 파이프라인으로 데이터를 수집할 수 있습니다. Amazon MSK로 Apache Kafka를 사용하여 스트리밍 데이터를 처리하는 애플리케이션을 구축하고 실행할 수 있습니다. OpenSearch Ingestion은 AWS PrivateLink 를 사용하여 Amazon MSK에 연결합니다. Amazon MSK 및 Amazon MSK Serverless 클러스터 모두에서 데이터를 수집할 수 있습니다. 두 프로세스의 유일한 차이는 파이프라인을 설정하기 전에 수행해야 하는 사전 조건 단계입니다.
**Topics**
+ [
## 프로비저닝된 Amazon MSK 사전 조건
](#msk-prereqs)
+ [
## Amazon MSK Serverless 사전 조건
](#msk-serverless-prereqs)
+ [
## 1단계: 파이프라인 역할 구성
](#msk-pipeline-role)
+ [
## 2단계: 파이프라인 생성
](#msk-pipeline)
+ [
## 3단계: (선택 사항) AWS Glue 스키마 레지스트리 사용
](#msk-glue)
+ [
## 4단계: (선택 사항) Amazon MSK 파이프라인의 권장 컴퓨팅 유닛(OCU) 구성
](#msk-ocu)
## 프로비저닝된 Amazon MSK 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. **Amazon Managed Streaming for Apache Kafka 개발자 안내서의 [클러스터 생성](https://docs.aws.amazon.com/msk/latest/developerguide/msk-create-cluster.html#create-cluster-console)에 나온 단계를 수행하여 Amazon MSK 클러스터를 생성합니다. **브로커 유형**의 경우 OpenSearch Ingestion에서 지원되지 않으므로 `t3` 유형을 제외한 옵션을 선택합니다.
1. 클러스터가 **활성** 상태가 되면 [다중 VPC 연결 켜기](https://docs.aws.amazon.com/msk/latest/developerguide/aws-access-mult-vpc.html#mvpc-cluster-owner-action-turn-on) 단계를 따르세요.
1. 클러스터와 파이프라인이 동일한 AWS 계정에 있는지 여부에 따라 [MSK 클러스터에 클러스터 정책 연결](https://docs.aws.amazon.com/msk/latest/developerguide/aws-access-mult-vpc.html#mvpc-cluster-owner-action-policy)의 단계에 따라 다음 정책 중 하나를 연결합니다. 이 정책은 OpenSearch Ingestion이 Amazon MSK 클러스터에 대한 AWS PrivateLink 연결을 생성하고 Kafka 주제에서 데이터를 읽을 수 있도록 허용합니다. 자체 ARN으로 `resource`을 업데이트해야 합니다.
클러스터와 파이프라인이 동일한 AWS 계정에 있는 경우 다음 정책이 적용됩니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "osis.amazonaws.com"
},
"Action": [
"kafka:CreateVpcConnection",
"kafka:DescribeClusterV2"
],
"Resource": "arn:aws:kafka:us-east-1:111122223333:cluster/cluster-name/cluster-id"
},
{
"Effect": "Allow",
"Principal": {
"Service": "osis-pipelines.amazonaws.com"
},
"Action": [
"kafka:CreateVpcConnection",
"kafka:GetBootstrapBrokers",
"kafka:DescribeClusterV2"
],
"Resource": "arn:aws:kafka:us-east-1:111122223333:cluster/cluster-name/cluster-id"
}
]
}
```
------
Amazon MSK 클러스터가 파이프라인 AWS 계정 과 다른에 있는 경우 대신 다음 정책을 연결합니다. 교차 계정 액세스는 프로비저닝된 Amazon MSK 클러스터에서만 가능하며 Amazon MSK Serverless 클러스터에서는 불가능합니다. 의 AWS `principal` ARN은 파이프라인 구성에 제공하는 것과 동일한 파이프라인 역할에 대한 ARN이어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "osis.amazonaws.com"
},
"Action": [
"kafka:CreateVpcConnection",
"kafka:DescribeClusterV2"
],
"Resource": "arn:aws:kafka:us-east-1:111122223333:cluster/cluster-name/cluster-id"
},
{
"Effect": "Allow",
"Principal": {
"Service": "osis-pipelines.amazonaws.com"
},
"Action": [
"kafka:CreateVpcConnection",
"kafka:GetBootstrapBrokers",
"kafka:DescribeClusterV2"
],
"Resource": "arn:aws:kafka:us-east-1:111122223333:cluster/cluster-name/cluster-id"
},
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:role/pipeline-role"
},
"Action": [
"kafka-cluster:*",
"kafka:*"
],
"Resource": [
"arn:aws:kafka:us-east-1:111122223333:cluster/cluster-name/cluster-id",
"arn:aws:kafka:us-east-1:111122223333:topic/cluster-name/cluster-id/*",
"arn:aws:kafka:us-east-1:111122223333:group/cluster-name/*"
]
}
]
}
```
------
1. [주제 생성](https://docs.aws.amazon.com/msk/latest/developerguide/create-topic.html)의 단계에 따라 Kafka 주제를 생성하세요. `BootstrapServerString`이 프라이빗 엔드포인트(단일 VPC) 부트스트랩 URL 중 하나인지 확인하세요. `--replication-factor`의 값은 Amazon MSK 클러스터의 영역 수에 따라 `2` 또는 `3`이어야 합니다. `--partitions`의 값은 최소 `10` 이상이어야 합니다.
1. [데이터 생산 및 소비](https://docs.aws.amazon.com/msk/latest/developerguide/produce-consume.html)의 단계에 따라 데이터를 생산하고 소비하세요. 다시, `BootstrapServerString`이 프라이빗 엔드포인트(단일 VPC) 부트스트랩 URL 중 하나인지 확인하세요.
## Amazon MSK Serverless 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. *Amazon Managed Streaming for Apache Kafka 개발자 안내서*의 [클러스터 생성](https://docs.aws.amazon.com/msk/latest/developerguide/create-serverless-cluster.html#)에 있는 단계에 따라 Amazon MSK Serverless를 생성합니다.
1. 클러스터가 **활성** 상태이면 [Attach a cluster policy to the MSK cluster](https://docs.aws.amazon.com/msk/latest/developerguide/aws-access-mult-vpc.html#mvpc-cluster-owner-action-policy)에 나온 단계를 수행하여 다음 정책을 연결합니다. 자체 ARN으로 `resource`을 업데이트해야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "osis.amazonaws.com"
},
"Action": [
"kafka:CreateVpcConnection",
"kafka:DescribeClusterV2"
],
"Resource": "arn:aws:kafka:us-east-1:111122223333:cluster/cluster-name/cluster-id"
},
{
"Effect": "Allow",
"Principal": {
"Service": "osis-pipelines.amazonaws.com"
},
"Action": [
"kafka:CreateVpcConnection",
"kafka:GetBootstrapBrokers",
"kafka:DescribeClusterV2"
],
"Resource": "arn:aws:kafka:us-east-1:111122223333:cluster/cluster-name/cluster-id"
}
]
}
```
------
이 정책은 OpenSearch Ingestion이 Amazon MSK Serverless 클러스터에 대한 AWS PrivateLink 연결을 생성하고 Kafka 주제에서 데이터를 읽을 수 있도록 허용합니다. 이 정책은 클러스터와 파이프라인이 동일한에 있는 경우 적용되며 AWS 계정, Amazon MSK Serverless는 교차 계정 액세스를 지원하지 않으므로 true여야 합니다.
1. [주제 생성](https://docs.aws.amazon.com/msk/latest/developerguide/msk-serverless-create-topic.html)의 단계에 따라 Kafka 주제를 생성하세요. `BootstrapServerString`이 Simple Authentication and Security Layer(SASL) IAM 부트스트랩 URL 중 하나인지 확인합니다. `--replication-factor`의 값은 Amazon MSK Serverless 클러스터의 영역 수에 따라 `2` 또는 `3`이어야 합니다. `--partitions`의 값은 최소 `10` 이상이어야 합니다.
1. [데이터 생산 및 소비](https://docs.aws.amazon.com/msk/latest/developerguide/msk-serverless-produce-consume.html)의 단계에 따라 데이터를 생산하고 소비하세요. 다시 `BootstrapServerString`이 Simple Authentication and Security Layer(SASL) IAM 부트스트랩 URL 중 하나인지 확인합니다.
## 1단계: 파이프라인 역할 구성
Amazon MSK 프로비저닝 또는 서버리스 클러스터를 설정한 후 파이프라인 구성에서 사용하려는 파이프라인 역할에 다음 Kafka 권한을 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kafka-cluster:Connect",
"kafka-cluster:AlterCluster",
"kafka-cluster:DescribeCluster",
"kafka:DescribeClusterV2",
"kafka:GetBootstrapBrokers"
],
"Resource": [
"arn:aws:kafka:us-east-1:111122223333:cluster/cluster-name/cluster-id"
]
},
{
"Effect": "Allow",
"Action": [
"kafka-cluster:*Topic*",
"kafka-cluster:ReadData"
],
"Resource": [
"arn:aws:kafka:us-east-1:111122223333:topic/cluster-name/cluster-id/topic-name"
]
},
{
"Effect": "Allow",
"Action": [
"kafka-cluster:AlterGroup",
"kafka-cluster:DescribeGroup"
],
"Resource": [
"arn:aws:kafka:us-east-1:111122223333:group/cluster-name/*"
]
}
]
}
```
------
## 2단계: 파이프라인 생성
그런 다음 Kafka를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
```
version: "2"
log-pipeline:
source:
kafka:
acknowledgements: true
topics:
- name: "topic-name"
group_id: "grouplambd-id"
aws:
msk:
arn: "arn:aws:kafka:region:account-id:cluster/cluster-name/cluster-id"
region: "us-west-2"
processor:
- grok:
match:
message:
- "%{COMMONAPACHELOG}"
- date:
destination: "@timestamp"
from_time_received: true
sink:
- opensearch:
hosts: ["https://search-domain-endpoint.us-east-1es.amazonaws.com"]
index: "index_name"
aws_region: "region"
aws_sigv4: true
```
사전 구성된 Amazon MSK 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
## 3단계: (선택 사항) AWS Glue 스키마 레지스트리 사용
Amazon MSK에서 OpenSearch Ingestion을 사용하는 경우 AWS Glue 스키마 레지스트리에서 호스팅되는 스키마에 AVRO 데이터 형식을 사용할 수 있습니다. [AWS Glue 스키마 레지스트리](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)를 사용하면 데이터 스트림 스키마를 중앙에서 검색, 제어 및 발전시킬 수 있습니다.
이 옵션을 사용하려면 파이프라인 구성에서 스키마 `type`를 활성화하세요.
```
schema:
type: "aws_glue"
```
또한 파이프라인 역할에 AWS Glue 읽기 액세스 권한을 제공해야 합니다. [AWSGlueSchemaRegistryReadonlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSGlueSchemaRegistryReadonlyAccess.html)라는 AWS 관리형 정책을 사용할 수 있습니다. 또한 레지스트리는 OpenSearch Ingestion 파이프라인과 동일한 AWS 계정 및 리전에 있어야 합니다.
## 4단계: (선택 사항) Amazon MSK 파이프라인의 권장 컴퓨팅 유닛(OCU) 구성
각 컴퓨팅 유닛에는 주제당 한 명의 소비자가 있습니다. 브로커는 특정 주제에 대해 이러한 소비자 간의 파티션을 조정합니다. 하지만 파티션 수가 소비자 수보다 많을 경우 Amazon MSK는 모든 소비자에게 여러 파티션을 호스팅합니다. OpenSearch Ingestion에는 CPU 사용량 또는 파이프라인에서 보류 중인 레코드 수에 따라 규모를 늘리거나 줄일 수 있는 auto-scaling 기능이 내장되어 있습니다.
성능을 최적화하려면 여러 컴퓨팅 유닛에 파티션을 분산하여 병렬 처리하세요. 주제에 많은 수의 파티션이 있는 경우(예: 파이프라인당 최대 OCU인 96개 초과), 1\$196개의 OCU로 파이프라인을 구성하는 것이 좋습니다. 필요에 따라 자동으로 크기가 조정되기 때문입니다. 주제의 파티션 수가 적은 경우(예: 96개 미만), 최대 컴퓨팅 유닛을 파티션 수와 동일하게 유지하세요.
파이프라인에 주제가 한 개 이상 있는 경우 파티션 수가 가장 많은 주제를 참조로 선택하여 최대 컴퓨팅 유닛을 구성하세요. 새 OCU 세트가 포함된 다른 파이프라인을 동일한 주제 및 소비자 그룹에 추가하면 처리량을 거의 선형적으로 확장할 수 있습니다.
# Amazon RDS에서 OpenSearch Ingestion 파이프라인 사용
Amazon RDS와 함께 OpenSearch Ingestion 파이프라인을 사용하여 기존 데이터를 내보내고 변경 사항(예: 생성, 업데이트 및 삭제)을 Amazon OpenSearch Service 도메인 및 컬렉션으로 스트리밍할 수 있습니다. OpenSearch Ingestion 파이프라인은 변경 데이터 캡처(CDC) 인프라를 통합하여 지연 시간을 최소화하면서 대규모로 Amazon RDS에서 데이터를 지속적으로 스트리밍할 수 있도록 합니다. RDS for MySQL 및 RDS for PostgreSQL이 지원됩니다.
Amazon RDS를 데이터 처리를 위한 소스로 사용하는 두 가지 방법(전체 초기 스냅샷 사용 또는 사용 안 함)이 있습니다. 전체 초기 스냅샷은 지정된 테이블의 스냅샷이며, 이 스냅샷은 Amazon S3로 내보내집니다. 그러면 OpenSearch Ingestion 파이프라인이 이 스냅샷을 도메인의 한 인덱스로 보내거나 분할하여 도메인의 여러 인덱스로 보냅니다. Amazon RDS와 OpenSearch의 데이터를 일관되게 유지하기 위해 파이프라인에서는 Amazon RDS 인스턴스의 테이블에 있는 모든 생성, 업데이트 및 삭제 이벤트를 하나 이상의 OpenSearch 인덱스에 저장된 문서와 동기화합니다.
전체 초기 스냅샷을 사용하는 경우 OpenSearch Ingestion 파이프라인에서는 먼저 스냅샷을 수집한 다음, Amazon RDS 변경 스트림에서 데이터를 읽기 시작합니다. 실제로 처리의 시간 차이가 거의 없기 때문에 Amazon RDS와 OpenSearch 간에 실시간에 가까운 데이터 일관성이 유지됩니다.
또한 Amazon RDS와의 OpenSearch Ingestion 통합을 사용하여 변경 데이터 캡처를 추적하고 Aurora에서 OpenSearch로의 모든 업데이트를 수집할 수 있습니다. 다른 메커니즘의 전체 스냅샷이 이미 있거나 Amazon RDS 인스턴스의 데이터에 대한 모든 변경 사항을 캡처하려는 경우 이 옵션을 선택합니다.
이 옵션을 선택하면 [Amazon RDS for MySQL 바이너리 로깅을 구성](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_LogAccess.MySQL.BinaryFormat.html)하거나 [Amazon RDS for PostgresSQL DB 인스턴스에 대한 논리적 복제를 설정](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.pglogical.setup-replication.html)해야 합니다.
**Topics**
+ [
# RDS for MySQL
](rds-mysql.md)
+ [
# RDS for PostgreSQL
](rds-PostgreSQL.md)
# RDS for MySQL
Amazon RDS for RDS for MySQL을 사용하여 OpenSearch Ingestion 파이프라인을 구성하려면 다음 단계를 완료합니다.
**Topics**
+ [
## RDS for MySQL 사전 조건
](#rds-mysql-prereqs)
+ [
## 1단계: 파이프라인 역할 구성
](#rds-mysql-pipeline-role)
+ [
## 2단계: 파이프라인 생성
](#rds-mysql-pipeline)
+ [
## 데이터 일관성
](#rds-mysql-pipeline-consistency)
+ [
## 데이터 형식 매핑
](#rds-mysql-pipeline-mapping)
+ [
## 제한 사항
](#rds-mysql-pipeline-limitations)
+ [
## 권장되는 CloudWatch 경보
](#aurora-mysql-pipeline-metrics)
## RDS for MySQL 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. Amazon RDS에서 사용자 지정 DB 파라미터 그룹을 생성하여 바이너리 로깅을 구성하고 다음 파라미터를 설정합니다.
```
binlog_format=ROW
binlog_row_image=full
binlog_row_metadata=FULL
```
또한 `binlog_row_value_options` 파라미터가 `PARTIAL_JSON`으로 설정되어 있지 않아야 합니다.
자세한 내용은 [RDS for MySQL 이진 로깅 구성](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_LogAccess.MySQL.BinaryFormat.html)을 참조하세요.
1. [RDS for MySQL DB 인스턴스를 선택하거나 생성하고](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateDBInstance.html) 이전 단계에서 생성한 파라미터 그룹을 DB 인스턴스와 연결합니다.
1. 데이터베이스에서 자동 백업이 활성화되어 있는지 확인합니다. 자세한 내용은 [자동 백업 활성화](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithAutomatedBackups.Enabling.html)를 참조하세요.
1. 예를 들어 복제가 발생하기에 충분한 시간(예: 24시간)으로 바이너리 로그 보존을 구성합니다. 자세한 내용은 *Amazon RDS 사용 설명서*의 [이진수 로그 구성 설정 및 표시](https://docs.aws.amazon.com//AmazonRDS/latest/UserGuide/mysql-stored-proc-configuring.html)를 참조하세요.
1. [Amazon RDS 및 AWS Secrets Manager에서 암호 관리를 사용](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-secrets-manager.html)하여 Amazon RDS 인스턴스에서 사용자 이름과 암호 인증을 설정합니다. [Secrets Manager 보안 암호를 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)하여 사용자 이름/암호 조합을 생성할 수도 있습니다.
1. 전체 초기 스냅샷 기능을 사용하는 경우 Amazon RDS에서 Amazon S3로 데이터를 내보내기 위한 AWS KMS key 및 IAM 역할을 생성합니다.
이 IAM 역할에는 다음과 같은 권한 정책도 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ExportPolicy",
"Effect": "Allow",
"Action": [
"s3:PutObject*",
"s3:ListBucket",
"s3:GetObject*",
"s3:DeleteObject*",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::s3-bucket-used-in-pipeline",
"arn:aws:s3:::s3-bucket-used-in-pipeline/*"
]
}
]
}
```
------
이 역할에는 다음과 같은 신뢰 관계도 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "export.rds.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 선택하거나 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html#createdomains) 및 [컬렉션 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-manage.html#serverless-create)을 참조하세요.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 Amazon RDS DB 인스턴스의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
## 1단계: 파이프라인 역할 구성
Amazon RDS 파이프라인 사전 조건을 설정한 후 [파이프라인 구성에 사용할 파이프라인 역할을 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security-overview.html#pipeline-security-sink)합니다. 또한 Amazon RDS 소스에 대한 다음 권한을 역할에 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "allowReadingFromS3Buckets",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:DeleteObject",
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::s3_bucket",
"arn:aws:s3:::s3_bucket/*"
]
},
{
"Sid": "allowNetworkInterfacesActions",
"Effect": "Allow",
"Action": [
"ec2:AttachNetworkInterface",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DetachNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"arn:aws:ec2:*:111122223333:network-interface/*",
"arn:aws:ec2:*:111122223333:subnet/*",
"arn:aws:ec2:*:111122223333:security-group/*"
]
},
{
"Sid": "allowDescribeEC2",
"Effect": "Allow",
"Action": [
"ec2:Describe*"
],
"Resource": "*"
},
{
"Sid": "allowTagCreation",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:111122223333:network-interface/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/OSISManaged": "true"
}
}
},
{
"Sid": "AllowDescribeInstances",
"Effect": "Allow",
"Action": [
"rds:DescribeDBInstances"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:db:*"
]
},
{
"Sid": "AllowSnapshots",
"Effect": "Allow",
"Action": [
"rds:DescribeDBSnapshots",
"rds:CreateDBSnapshot",
"rds:AddTagsToResource"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:db:DB-id",
"arn:aws:rds:us-east-2:111122223333:snapshot:DB-id*"
]
},
{
"Sid": "AllowExport",
"Effect": "Allow",
"Action": [
"rds:StartExportTask"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:snapshot:DB-id*"
]
},
{
"Sid": "AllowDescribeExports",
"Effect": "Allow",
"Action": [
"rds:DescribeExportTasks"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": "us-east-2",
"aws:ResourceAccount": "111122223333"
}
}
},
{
"Sid": "AllowAccessToKmsForExport",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:Encrypt",
"kms:DescribeKey",
"kms:RetireGrant",
"kms:CreateGrant",
"kms:ReEncrypt*",
"kms:GenerateDataKey*"
],
"Resource": [
"arn:aws:kms:us-east-2:111122223333:key/export-key-id"
]
},
{
"Sid": "AllowPassingExportRole",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": [
"arn:aws:iam::111122223333:role/export-role"
]
},
{
"Sid": "SecretsManagerReadAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:*:111122223333:secret:*"
]
}
]
}
```
------
## 2단계: 파이프라인 생성
다음과 유사한 OpenSearch Ingestion 파이프라인을 구성합니다. 이 파이프라인 예는 Amazon RDS 인스턴스를 소스로 지정합니다.
```
version: "2"
rds-mysql-pipeline:
source:
rds:
db_identifier: "instance-id"
engine: mysql
database: "database-name"
tables:
include:
- "table1"
- "table2"
s3_bucket: "bucket-name"
s3_region: "bucket-region"
s3_prefix: "prefix-name"
export:
kms_key_id: "kms-key-id"
iam_role_arn: "export-role-arn"
stream: true
aws:
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
region: "us-east-1"
authentication:
username: ${{aws_secrets:secret:username}}
password: ${{aws_secrets:secret:password}}
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
index: "${getMetadata(\"table_name\")}"
index_type: custom
document_id: "${getMetadata(\"primary_key\")}"
action: "${getMetadata(\"opensearch_action\")}"
document_version: "${getMetadata(\"document_version\")}"
document_version_type: "external"
aws:
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
region: "us-east-1"
extension:
aws:
secrets:
secret:
secret_id: "rds-secret-id"
region: "us-east-1"
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
refresh_interval: PT1H
```
사전 구성된 Amazon RDS 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
Amazon Aurora를 소스로 사용하려면 파이프라인에 대한 VPC 액세스를 구성해야 합니다. 선택한 VPC는 Amazon Aurora 소스에서 사용하는 것과 동일한 VPC여야 합니다. 그런 다음 하나 이상의 서브넷과 하나 이상의 VPC 보안 그룹을 선택합니다. 파이프라인에는 Aurora MySQL 데이터베이스에 대한 네트워크 액세스가 필요하므로 Aurora 클러스터가 파이프라인의 VPC 보안 그룹에서 데이터베이스 포트로의 인바운드 트래픽을 허용하는 VPC 보안 그룹으로 구성되어 있는지도 확인해야 합니다. 자세한 내용은 [보안 그룹을 통한 액세스 제어](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Overview.RDSSecurityGroups.html)를 참조하세요.
를 사용하여 파이프라인 AWS Management Console 을 생성하는 경우 Amazon Aurora를 소스로 사용하려면 VPC에 파이프라인도 연결해야 합니다. 이를 수행하려면 **네트워크 구성** 섹션을 찾아 **VPC에 연결**을 선택하고 제공된 기본 옵션 중 하나에서 CIDR을 선택하거나 자체 CIDR을 선택합니다. [RFC 1918 Best Current Practice](https://datatracker.ietf.org/doc/html/rfc1918)에 정의된 대로 프라이빗 주소 공간에서 모든 CIDR을 사용할 수 있습니다.
사용자 지정 CIDR을 제공하려면 드롭다운 메뉴에서 **기타**를 선택합니다. OpenSearch Ingestion과 Amazon RDS 간의 IP 주소 충돌을 방지하려면 Amazon RDS VPC CIDR이 OpenSearch Ingestion의 CIDR과 달라야 합니다.
자세한 내용은 [파이프라인에 대한 VPC 액세스 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security.html#pipeline-vpc-configure)을 참조하세요.
## 데이터 일관성
파이프라인은 Amazon RDS 인스턴스의 변경 사항을 지속적으로 폴링하거나 수신하고 OpenSearch 인덱스에서 해당 문서를 업데이트하여 데이터 일관성을 보장합니다.
OpenSearch Ingestion은 데이터 내구성을 보장하는 엔드 투 엔드 승인을 지원합니다. 파이프라인에서는 스냅샷이나 스트림을 읽을 때 병렬 처리를 위해 동적으로 분할을 생성합니다. 파이프라인에서는 OpenSearch 도메인이나 컬렉션에서 모든 레코드를 수집한 후 승인을 받으면 분할을 완료 상태로 표시합니다. OpenSearch Serverless 검색 컬렉션에 수집하려는 경우 파이프라인에서 문서 ID를 생성할 수 있습니다. OpenSearch Serverless 시계열 컬렉션에 수집하려면 파이프라인이 문서 ID를 생성하지 않으므로 파이프라인 싱크 구성`document_id: "${getMetadata(\"primary_key\")}"`에서를 생략해야 합니다.
또한 OpenSearch Ingestion 파이프라인에서는 수신 이벤트 작업을 해당하는 대량 인덱싱 작업에 매핑하여 문서를 쉽게 수집할 수 있게 합니다. 이렇게 하면 데이터 일관성이 유지되므로 Amazon RDS의 모든 데이터 변경 사항이 OpenSearch에서 해당하는 문서 변경 사항으로 조정됩니다.
## 데이터 형식 매핑
OpenSearch Ingestion 파이프라인은 OpenSearch Service 도메인 또는 컬렉션이 사용할 수 있는 표현에 MySQL 데이터 유형을 매핑합니다. OpenSearch에 매핑 템플릿이 정의되지 않은 경우 OpenSearch는 처음 전송된 문서를 기반으로 [동적 매핑](https://docs.opensearch.org/latest/field-types/#dynamic-mapping)을 사용하여 필드 유형을 자동으로 결정합니다. 매핑 템플릿을 통해 OpenSearch에서 가장 적합한 필드 유형을 명시적으로 정의할 수도 있습니다.
아래 표에는 MySQL 데이터 유형과 해당 OpenSearch 필드 유형이 나열되어 있습니다. 명시적 매핑이 정의되지 않은 경우 *기본 OpenSearch 필드 유형* 열에 OpenSearch의 해당 필드 유형이 표시됩니다. 이 경우 OpenSearch는 동적 매핑을 사용하여 필드 유형을 자동으로 결정합니다. *권장 OpenSearch 필드 유형* 열은 매핑 템플릿에서 명시적으로 지정하도록 권장되는 해당 필드 유형입니다. 이들 필드 유형은 MySQL의 데이터 유형과 더 긴밀하게 맞춤화되며 일반적으로 OpenSearch에서 사용할 수 있는 더 나은 검색 기능을 지원할 수 있습니다.
| MySQL 데이터 형식 | 기본 OpenSearch 필드 유형 | 권장 OpenSearch 필드 유형 |
| --- | --- | --- |
| BIGINT | long | long |
| BIGINT UNSIGNED | long | unsigned long |
| BIT | long | 비트 수에 따라 byte, short, integer 또는 long입니다. |
| DECIMAL | 텍스트 | double 또는 키워드 |
| DOUBLE | 실수 | double |
| FLOAT | 실수 | 실수 |
| INT | long | 정수 |
| INT UNSIGNED | long | long |
| MEDIUMINT | long | 정수 |
| MEDIUMINT UNSIGNED | long | 정수 |
| NUMERIC | 텍스트 | double 또는 키워드 |
| SMALLINT | long | bigint |
| SMALLINT UNSIGNED | long | 정수 |
| TINYINT | long | 바이트 |
| TINYINT UNSIGNED | long | bigint |
| BINARY | 텍스트 | 이진수 |
| BLOB | 텍스트 | 이진수 |
| CHAR | 텍스트 | 텍스트 |
| ENUM | 텍스트 | 키워드 |
| LONGBLOB | 텍스트 | 이진수 |
| LONGTEXT | 텍스트 | 텍스트 |
| MEDIUMBLOB | 텍스트 | 이진수 |
| MEDIUMTEXT | 텍스트 | 텍스트 |
| SET | 텍스트 | 키워드 |
| TEXT | 텍스트 | 텍스트 |
| TINYBLOB | 텍스트 | 이진수 |
| TINYTEXT | 텍스트 | 텍스트 |
| VARBINARY | 텍스트 | 이진수 |
| VARCHAR | 텍스트 | 텍스트 |
| DATE | long(에포크 밀리초) | 날짜 |
| DATETIME | long(에포크 밀리초) | 날짜 |
| TIME | long(에포크 밀리초) | 날짜 |
| TIMESTAMP | long(에포크 밀리초) | 날짜 |
| YEAR | long(에포크 밀리초) | 날짜 |
| GEOMETRY | text(WKT 형식) | geo\$1shape |
| GEOMETRYCOLLECTION | text(WKT 형식) | geo\$1shape |
| LINESTRING | text(WKT 형식) | geo\$1shape |
| MULTILINESTRING | text(WKT 형식) | geo\$1shape |
| MULTIPOINT | text(WKT 형식) | geo\$1shape |
| MULTIPOLYGON | text(WKT 형식) | geo\$1shape |
| POINT | text(WKT 형식) | geo\$1point 또는 geo\$1shape |
| POLYGON | text(WKT 형식) | geo\$1shape |
| JSON | 텍스트 | 객체 |
OpenSearch Ingestion 파이프라인에서 DLQ(Dead Letter Queue)를 구성하는 것이 좋습니다. 이 대기열을 구성하면 OpenSearch Service에서는 동적 매핑 실패로 인해 수집할 수 없는 모든 실패한 문서를 대기열로 전송합니다.
자동 매핑이 실패하면 파이프라인 구성에서 `template_type` 및 `template_content`를 사용하여 명시적 매핑 규칙을 정의할 수 있습니다. 또는 파이프라인을 시작하기 전에 검색 도메인이나 컬렉션에서 직접 매핑 템플릿을 생성할 수도 있습니다.
## 제한 사항
RDS for MySQL용 OpenSearch Ingestion 파이프라인을 설정하는 경우 다음과 같은 제한 사항을 고려하세요.
+ 이 통합에서는 파이프라인당 하나의 MySQL 데이터베이스만 지원합니다.
+ 이 통합에서는 현재 교차 리전 데이터 수집을 지원하지 않습니다. Amazon RDS 인스턴스와 OpenSearch 도메인은 동일한 AWS 리전에 있어야 합니다.
+ 이 통합에서는 현재 교차 계정 데이터 수집을 지원하지 않습니다. Amazon RDS 인스턴스와 OpenSearch Ingestion 파이프라인은 동일한 AWS 계정에 있어야 합니다.
+ 지원되는 유일한 인증 메커니즘인 Secrets Manager를 사용한 인증이 Amazon RDS 인스턴스에 활성화되어 있는지 확인합니다.
+ 기존 파이프라인 구성은 다른 데이터베이스 및/또는 다른 테이블에서 데이터를 수집하도록 업데이트할 수 없습니다. 파이프라인의 데이터베이스 및/또는 테이블 이름을 업데이트하려면 새 파이프라인을 생성해야 합니다.
+ 데이터 정의 언어(DDL) 문은 일반적으로 지원되지 않습니다. 다음의 경우에는 데이터 일관성이 유지되지 않습니다.
+ 기본 키가 변경될 경우(추가/삭제/이름 변경)
+ 테이블이 삭제되거나 잘린 경우.
+ 열 이름 또는 데이터 형식이 변경된 경우.
+ 동기화할 MySQL 테이블에 기본 키가 정의되지 않은 경우 데이터 일관성이 보장되지 않습니다. 업데이트/삭제를 OpenSearch에 동기화하려면 OpenSearch 싱크 구성에서 사용자 지정 `document_id` 옵션을 올바르게 정의해야 합니다.
+ 계단식 삭제 작업이 있는 외래 키 참조는 지원되지 않으며, RDS for MySQL과 OpenSearch 간에 데이터 불일치가 발생할 수 있습니다.
+ Amazon RDS 다중 가용 영역 DB 클러스터는 지원되지 않습니다.
+ 지원되는 버전: MySQL 버전 8.0 이상
## 권장되는 CloudWatch 경보
수집 파이프라인의 성능을 모니터링하려면 다음 CloudWatch 지표가 권장됩니다. 이러한 지표는 내보내기에서 처리된 데이터의 양, 스트림에서 처리된 이벤트의 수, 내보내기 및 스트림 이벤트 처리 오류, 대상에 쓴 문서 수를 식별하는 데 도움이 될 수 있습니다. 이러한 지표 중 하나가 지정된 시간 동안 지정된 값을 초과하면 작업을 수행하도록 CloudWatch 경보를 설정할 수 있습니다.
| 지표 | 설명 |
| --- | --- |
| pipeline-name.rds.credentialsChanged | 이 지표는 AWS 보안 암호 교체 빈도를 나타냅니다. |
| pipeline-name.rds.executorRefreshErrors | 이 지표는 AWS 보안 암호 새로 고침 실패를 나타냅니다. |
| pipeline-name.rds.exportRecordsTotal | 이 지표는 Amazon Aurora에서 내보낸 레코드 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsProcessed | 이 지표는 OpenSearch Ingestion 파이프라인에서 처리한 레코드 수를 나타냅니다. |
| pipeline-name.rds.exportRecordProcessingErrors | 이 지표는 Amazon Aurora 클러스터에서 데이터를 읽는 동안 OpenSearch Ingestion 파이프라인에서 처리한 오류 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsSuccessTotal | 이 지표는 성공적으로 처리한 내보내기 레코드의 총 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsFailedTotal | 이 지표는 처리하지 못한 내보내기 레코드의 총 수를 나타냅니다. |
| pipeline-name.rds.bytesReceived | 이 지표는 OpenSearch Ingestion 파이프라인에서 수신한 총 바이트 수를 나타냅니다. |
| pipeline-name.rds.bytesProcessed | 이 지표는 OpenSearch Ingestion 파이프라인에서 처리한 총 바이트 수를 나타냅니다. |
| pipeline-name.rds.streamRecordsSuccessTotal | 이 지표는 스트림에서 성공적으로 처리한 레코드 수를 나타냅니다. |
| pipeline-name.rds.streamRecordsFailedTotal | 이 지표는 스트림에서 처리하지 못한 총 레코드 수를 나타냅니다. |
# RDS for PostgreSQL
Amazon RDS for RDS for PostgreSQL을 사용하여 OpenSearch Ingestion 파이프라인을 구성하려면 다음 단계를 완료합니다.
**Topics**
+ [
## RDS for PostgreSQL 사전 조건
](#rds-PostgreSQL-prereqs)
+ [
## 1단계: 파이프라인 역할 구성
](#rds-mysql-pipeline-role)
+ [
## 2단계: 파이프라인 생성
](#rds-PostgreSQL-pipeline)
+ [
## 데이터 일관성
](#rds-mysql-pipeline-consistency)
+ [
## 데이터 형식 매핑
](#rds-PostgreSQL-pipeline-mapping)
+ [
## 제한 사항
](#rds-PostgreSQL-pipeline-limitations)
+ [
## 권장되는 CloudWatch 경보
](#aurora-mysql-pipeline-metrics)
## RDS for PostgreSQL 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. Amazon RDS에서 [사용자 지정 DB 파라미터 그룹을 생성](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/zero-etl.setting-up.html#zero-etl.parameters)하여 논리적 복제를 구성합니다.
```
rds.logical_replication=1
```
자세한 내용은 [Amazon RDS for PostgreSQL에 대한 논리적 복제 수행](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/PostgreSQL.Concepts.General.FeatureSupport.LogicalReplication.html)을 참조하세요.
1. [RDS for PostgreSQL DB 인스턴스를 선택하거나 생성하고](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_GettingStarted.CreatingConnecting.PostgreSQL.html) 1단계에서 생성한 파라미터 그룹을 DB 인스턴스와 연결합니다.
1. [Aurora 및 AWS Secrets Manager에서 암호 관리를 사용](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/rds-secrets-manager.html)하여 Amazon RDS 인스턴스에서 사용자 이름과 암호 인증을 설정합니다. [Secrets Manager 보안 암호를 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)하여 사용자 이름/암호 조합을 생성할 수도 있습니다.
1. 전체 초기 스냅샷 기능을 사용하는 경우 Amazon RDS에서 Amazon S3로 데이터를 내보내기 위한 AWS KMS key 및 IAM 역할을 생성합니다.
이 IAM 역할에는 다음과 같은 권한 정책도 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ExportPolicy",
"Effect": "Allow",
"Action": [
"s3:PutObject*",
"s3:ListBucket",
"s3:GetObject*",
"s3:DeleteObject*",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::s3-bucket-used-in-pipeline",
"arn:aws:s3:::s3-bucket-used-in-pipeline/*"
]
}
]
}
```
------
이 역할에는 다음과 같은 신뢰 관계도 있어야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "export.rds.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 선택하거나 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html#createdomains) 및 [컬렉션 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-manage.html#serverless-create)을 참조하세요.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 Amazon RDS DB 인스턴스의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
## 1단계: 파이프라인 역할 구성
Amazon RDS 파이프라인 사전 조건을 설정한 후 [파이프라인 구성에 사용할 파이프라인 역할을 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security-overview.html#pipeline-security-sink)합니다. 또한 Amazon RDS 소스에 대한 다음 권한을 역할에 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "allowReadingFromS3Buckets",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:DeleteObject",
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::s3_bucket",
"arn:aws:s3:::s3_bucket/*"
]
},
{
"Sid": "allowNetworkInterfacesActions",
"Effect": "Allow",
"Action": [
"ec2:AttachNetworkInterface",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DetachNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"arn:aws:ec2:*:111122223333:network-interface/*",
"arn:aws:ec2:*:111122223333:subnet/*",
"arn:aws:ec2:*:111122223333:security-group/*"
]
},
{
"Sid": "allowDescribeEC2",
"Effect": "Allow",
"Action": [
"ec2:Describe*"
],
"Resource": "*"
},
{
"Sid": "allowTagCreation",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:111122223333:network-interface/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/OSISManaged": "true"
}
}
},
{
"Sid": "AllowDescribeInstances",
"Effect": "Allow",
"Action": [
"rds:DescribeDBInstances"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:db:*"
]
},
{
"Sid": "AllowSnapshots",
"Effect": "Allow",
"Action": [
"rds:DescribeDBSnapshots",
"rds:CreateDBSnapshot",
"rds:AddTagsToResource"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:db:DB-id",
"arn:aws:rds:us-east-2:111122223333:snapshot:DB-id*"
]
},
{
"Sid": "AllowExport",
"Effect": "Allow",
"Action": [
"rds:StartExportTask"
],
"Resource": [
"arn:aws:rds:us-east-2:111122223333:snapshot:DB-id*"
]
},
{
"Sid": "AllowDescribeExports",
"Effect": "Allow",
"Action": [
"rds:DescribeExportTasks"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": "us-east-2",
"aws:ResourceAccount": "111122223333"
}
}
},
{
"Sid": "AllowAccessToKmsForExport",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:Encrypt",
"kms:DescribeKey",
"kms:RetireGrant",
"kms:CreateGrant",
"kms:ReEncrypt*",
"kms:GenerateDataKey*"
],
"Resource": [
"arn:aws:kms:us-east-2:111122223333:key/export-key-id"
]
},
{
"Sid": "AllowPassingExportRole",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": [
"arn:aws:iam::111122223333:role/export-role"
]
},
{
"Sid": "SecretsManagerReadAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:*:111122223333:secret:*"
]
}
]
}
```
------
## 2단계: 파이프라인 생성
RDS for PostgreSQL 인스턴스를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
```
version: "2"
rds-postgres-pipeline:
source:
rds:
db_identifier: "instance-id"
engine: postgresql
database: "database-name"
tables:
include:
- "schema1.table1"
- "schema2.table2"
s3_bucket: "bucket-name"
s3_region: "bucket-region"
s3_prefix: "prefix-name"
export:
kms_key_id: "kms-key-id"
iam_role_arn: "export-role-arn"
stream: true
aws:
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
region: "us-east-1"
authentication:
username: ${{aws_secrets:secret:username}}
password: ${{aws_secrets:secret:password}}
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
index: "${getMetadata(\"table_name\")}"
index_type: custom
document_id: "${getMetadata(\"primary_key\")}"
action: "${getMetadata(\"opensearch_action\")}"
document_version: "${getMetadata(\"document_version\")}"
document_version_type: "external"
aws:
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
region: "us-east-1"
extension:
aws:
secrets:
secret:
secret_id: "rds-secret-id"
region: "us-east-1"
sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
refresh_interval: PT1H
```
**참고**
사전 구성된 Amazon RDS 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
Amazon Aurora를 소스로 사용하려면 파이프라인에 대한 VPC 액세스를 구성해야 합니다. 선택한 VPC는 Amazon Aurora 소스에서 사용하는 것과 동일한 VPC여야 합니다. 그런 다음 하나 이상의 서브넷과 하나 이상의 VPC 보안 그룹을 선택합니다. 파이프라인에는 Aurora MySQL 데이터베이스에 대한 네트워크 액세스가 필요하므로 Aurora 클러스터가 파이프라인의 VPC 보안 그룹에서 데이터베이스 포트로의 인바운드 트래픽을 허용하는 VPC 보안 그룹으로 구성되어 있는지도 확인해야 합니다. 자세한 내용은 [보안 그룹을 통한 액세스 제어](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Overview.RDSSecurityGroups.html)를 참조하세요.
를 사용하여 파이프라인 AWS Management Console 을 생성하는 경우 Amazon Aurora를 소스로 사용하려면 VPC에 파이프라인도 연결해야 합니다. 이를 수행하려면 **네트워크 구성** 섹션을 찾아 **VPC에 연결**을 선택하고 제공된 기본 옵션 중 하나에서 CIDR을 선택하거나 자체 CIDR을 선택합니다. [RFC 1918 Best Current Practice](https://datatracker.ietf.org/doc/html/rfc1918)에 정의된 대로 프라이빗 주소 공간에서 모든 CIDR을 사용할 수 있습니다.
사용자 지정 CIDR을 제공하려면 드롭다운 메뉴에서 **기타**를 선택합니다. OpenSearch Ingestion과 Amazon RDS 간의 IP 주소 충돌을 방지하려면 Amazon Aurora VPC CIDR이 OpenSearch Ingestion의 CIDR과 달라야 합니다.
자세한 내용은 [파이프라인에 대한 VPC 액세스 구성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security.html#pipeline-vpc-configure)을 참조하세요.
## 데이터 일관성
파이프라인은 Amazon RDS 인스턴스의 변경 사항을 지속적으로 폴링하거나 수신하고 OpenSearch 인덱스에서 해당 문서를 업데이트하여 데이터 일관성을 보장합니다.
OpenSearch Ingestion은 데이터 내구성을 보장하는 엔드 투 엔드 승인을 지원합니다. 파이프라인에서는 스냅샷이나 스트림을 읽을 때 병렬 처리를 위해 동적으로 분할을 생성합니다. 파이프라인에서는 OpenSearch 도메인이나 컬렉션에서 모든 레코드를 수집한 후 승인을 받으면 분할을 완료 상태로 표시합니다. OpenSearch Serverless 검색 컬렉션에 수집하려는 경우 파이프라인에서 문서 ID를 생성할 수 있습니다. OpenSearch Serverless 시계열 컬렉션에 수집하려면 파이프라인이 문서 ID를 생성하지 않으므로 파이프라인 싱크 구성`document_id: "${getMetadata(\"primary_key\")}"`에서를 생략해야 합니다.
또한 OpenSearch Ingestion 파이프라인에서는 수신 이벤트 작업을 해당하는 대량 인덱싱 작업에 매핑하여 문서를 쉽게 수집할 수 있게 합니다. 이렇게 하면 데이터 일관성이 유지되므로 Amazon RDS의 모든 데이터 변경 사항이 OpenSearch에서 해당하는 문서 변경 사항으로 조정됩니다.
## 데이터 형식 매핑
OpenSearch Ingestion 파이프라인은 OpenSearch Service 도메인 또는 컬렉션이 사용할 수 있는 표현에 PostgreSQL 데이터 유형을 매핑합니다. OpenSearch에 매핑 템플릿이 정의되지 않은 경우 OpenSearch는 처음 전송된 문서를 기반으로 [동적 매핑](https://docs.opensearch.org/latest/field-types/#dynamic-mapping)을 사용하여 필드 유형을 자동으로 결정합니다. 매핑 템플릿을 통해 OpenSearch에서 가장 적합한 필드 유형을 명시적으로 정의할 수도 있습니다.
아래 표에는 RDS for PostgreSQL 데이터 유형과 해당 OpenSearch 필드 유형이 나열되어 있습니다. 명시적 매핑이 정의되지 않은 경우 *기본 OpenSearch 필드 유형* 열에 OpenSearch의 해당 필드 유형이 표시됩니다. 이 경우 OpenSearch는 동적 매핑을 사용하여 필드 유형을 자동으로 결정합니다. *권장 OpenSearch 필드 유형* 열은 매핑 템플릿에서 명시적으로 지정하는 해당 권장 필드 유형입니다. 이들 필드 유형은 RDS for PostgreSQL의 데이터 유형과 더 긴밀하게 맞춤화되며 일반적으로 OpenSearch에서 사용할 수 있는 더 나은 검색 기능을 지원할 수 있습니다.
| RDS for PostgreSQL 데이터 유형 | 기본 OpenSearch 필드 유형 | 권장 OpenSearch 필드 유형 |
| --- | --- | --- |
| smallint | long | bigint |
| 정수 | long | 정수 |
| bigint | long | long |
| decimal | 텍스트 | double 또는 키워드 |
| numeric[ (p, s) ] | 텍스트 | double 또는 키워드 |
| real | 실수 | 실수 |
| double precision | 실수 | double |
| smallserial | long | bigint |
| serial | long | 정수 |
| bigserial | long | long |
| money | 객체 | 객체 |
| character varying(n) | 텍스트 | 텍스트 |
| varchar(n) | 텍스트 | 텍스트 |
| character(n) | 텍스트 | 텍스트 |
| char(n) | 텍스트 | 텍스트 |
| bpchar(n) | 텍스트 | 텍스트 |
| bpchar | 텍스트 | 텍스트 |
| 텍스트 | 텍스트 | 텍스트 |
| enum | 텍스트 | 텍스트 |
| bytea | 텍스트 | 이진수 |
| timestamp [ (p) ](시간대 제외) | long(에포크 밀리초) | 날짜 |
| timestamp [ (p) ](시간대 포함) | long(에포크 밀리초) | 날짜 |
| 날짜 | long(에포크 밀리초) | 날짜 |
| time [ (p) ](시간대 제외) | long(에포크 밀리초) | 날짜 |
| time [ (p) ](시간대 포함) | long(에포크 밀리초) | 날짜 |
| interval [ fields ] [ (p) ] | text(ISO8601 형식) | 텍스트 |
| 부울 | 부울 | 부울 |
| point | text(WKT 형식) | geo\$1shape |
| line | text(WKT 형식) | geo\$1shape |
| lseg | text(WKT 형식) | geo\$1shape |
| box | text(WKT 형식) | geo\$1shape |
| 경로 | text(WKT 형식) | geo\$1shape |
| 다각형 | text(WKT 형식) | geo\$1shape |
| circle | 객체 | 객체 |
| cidr | 텍스트 | 텍스트 |
| inet | 텍스트 | 텍스트 |
| macaddr | 텍스트 | 텍스트 |
| macaddr8 | 텍스트 | 텍스트 |
| bit(n) | long | byte, short, integer 또는 long(비트 수에 따라 다름) |
| bit varying(n) | long | byte, short, integer 또는 long(비트 수에 따라 다름) |
| json | 객체 | 객체 |
| jsonb | 객체 | 객체 |
| jsonpath | 텍스트 | 텍스트 |
OpenSearch Ingestion 파이프라인에서 DLQ(Dead Letter Queue)를 구성하는 것이 좋습니다. 이 대기열을 구성하면 OpenSearch Service에서는 동적 매핑 실패로 인해 수집할 수 없는 모든 실패한 문서를 대기열로 전송합니다.
자동 매핑이 실패할 경우 파이프라인 구성에서 `template_type` 및 `template_content`를 사용하여 명시적 매핑 규칙을 정의할 수 있습니다. 또는 파이프라인을 시작하기 전에 검색 도메인이나 컬렉션에서 직접 매핑 템플릿을 생성할 수도 있습니다.
## 제한 사항
RDS for PostgreSQL용 OpenSearch Ingestion 파이프라인을 설정하는 경우 다음과 같은 제한 사항을 고려하세요.
+ 이 통합에서는 파이프라인당 하나의 PostgreSQL 데이터베이스만 지원합니다.
+ 이 통합에서는 현재 교차 리전 데이터 수집을 지원하지 않습니다. Amazon RDS 인스턴스와 OpenSearch 도메인은 동일한 AWS 리전에 있어야 합니다.
+ 이 통합에서는 현재 교차 계정 데이터 수집을 지원하지 않습니다. Amazon RDS 인스턴스와 OpenSearch Ingestion 파이프라인은 동일한 AWS 계정에 있어야 합니다.
+ 지원되는 유일한 인증 메커니즘 AWS Secrets Manager인를 사용하여 Amazon RDS 인스턴스에 인증이 활성화되어 있는지 확인합니다.
+ 기존 파이프라인 구성은 다른 데이터베이스 및/또는 다른 테이블에서 데이터를 수집하도록 업데이트할 수 없습니다. 파이프라인의 데이터베이스 및/또는 테이블 이름을 업데이트하려면 파이프라인을 중지하고 업데이트된 구성으로 다시 시작하거나 새 파이프라인을 생성해야 합니다.
+ 데이터 정의 언어(DDL) 문은 일반적으로 지원되지 않습니다. 다음의 경우에는 데이터 일관성이 유지되지 않습니다.
+ 기본 키가 변경될 경우(추가/삭제/이름 변경)
+ 테이블이 삭제되거나 잘린 경우.
+ 열 이름 또는 데이터 형식이 변경된 경우.
+ 동기화할 PostgreSQL 테이블에 기본 키가 정의되지 않은 경우 데이터 일관성이 보장되지 않습니다. 업데이트/삭제를 OpenSearch에 동기화하려면 OpenSearch 및 싱크 구성에서 사용자 지정 `document_id` 옵션을 올바르게 정의해야 합니다.
+ RDS 다중 AZ DB 클러스터는 지원되지 않습니다.
+ 지원되는 버전: PostgreSQL 16 이상
## 권장되는 CloudWatch 경보
수집 파이프라인의 성능을 모니터링하려면 다음 CloudWatch 지표가 권장됩니다. 이러한 지표는 내보내기에서 처리된 데이터의 양, 스트림에서 처리된 이벤트의 수, 내보내기 및 스트림 이벤트 처리 오류, 대상에 쓴 문서 수를 식별하는 데 도움이 될 수 있습니다. 이러한 지표 중 하나가 지정된 시간 동안 지정된 값을 초과하면 작업을 수행하도록 CloudWatch 경보를 설정할 수 있습니다.
| 지표 | 설명 |
| --- | --- |
| pipeline-name.rds.credentialsChanged | 이 지표는 AWS 보안 암호 교체 빈도를 나타냅니다. |
| pipeline-name.rds.executorRefreshErrors | 이 지표는 AWS 보안 암호 새로 고침 실패를 나타냅니다. |
| pipeline-name.rds.exportRecordsTotal | 이 지표는 Amazon Aurora에서 내보낸 레코드 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsProcessed | 이 지표는 OpenSearch Ingestion 파이프라인에서 처리한 레코드 수를 나타냅니다. |
| pipeline-name.rds.exportRecordProcessingErrors | 이 지표는 Amazon Aurora 클러스터에서 데이터를 읽는 동안 OpenSearch Ingestion 파이프라인에서 처리한 오류 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsSuccessTotal | 이 지표는 성공적으로 처리한 내보내기 레코드의 총 수를 나타냅니다. |
| pipeline-name.rds.exportRecordsFailedTotal | 이 지표는 처리하지 못한 내보내기 레코드의 총 수를 나타냅니다. |
| pipeline-name.rds.bytesReceived | 이 지표는 OpenSearch Ingestion 파이프라인에서 수신한 총 바이트 수를 나타냅니다. |
| pipeline-name.rds.bytesProcessed | 이 지표는 OpenSearch Ingestion 파이프라인에서 처리한 총 바이트 수를 나타냅니다. |
| pipeline-name.rds.streamRecordsSuccessTotal | 이 지표는 스트림에서 성공적으로 처리한 레코드 수를 나타냅니다. |
| pipeline-name.rds.streamRecordsFailedTotal | 이 지표는 스트림에서 처리하지 못한 총 레코드 수를 나타냅니다. |
# Amazon S3와 함께 OpenSearch Ingestion 파이프라인 사용
OpenSearch Ingestion 기능을 사용하면 Amazon S3를 원본 또는 대상으로 사용할 수 있습니다. Amazon S3를 소스로 사용하는 경우 OpenSearch Ingestion 파이프라인으로 데이터를 전송합니다. Amazon S3를 대상으로 사용하는 경우 OpenSearch Ingestion 파이프라인의 데이터를 하나 이상의 S3 버킷에 기록합니다.
**Topics**
+ [
## 소스로서의 Amazon S3
](#s3-source)
+ [
## 대상으로서의 Amazon S3
](#s3-destination)
+ [
## 소스 역할을 하는 Amazon S3 교차 계정
](#fdsf)
## 소스로서의 Amazon S3
Amazon S3를 데이터 처리 원본으로 사용할 수 있는 두 가지 방법, 즉 *S3-SQS 처리*와 *예약 스캔*이 있습니다.
S3에 파일을 기록한 후 파일을 거의 실시간으로 스캔해야 하는 경우 S3-SQS 처리를 사용하세요. 객체가 버킷 내에 저장되거나 수정될 때마다 이벤트를 발생시키도록 Amazon S3 버킷을 구성할 수 있습니다. 일회성 또는 반복되는 예약 스캔을 사용하여 S3 버킷의 데이터를 일괄 처리하세요.
**Topics**
+ [
### 사전 조건
](#s3-prereqs)
+ [
### 1단계: 파이프라인 역할 구성
](#s3-pipeline-role)
+ [
### 2단계: 파이프라인 생성
](#s3-pipeline)
### 사전 조건
예약 스캔 또는 S3-SQS 처리 모두에 대해 Amazon S3를 OpenSearch Ingestion 파이프라인의 소스로 사용하려면 먼저 [S3 버킷을 생성](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)하세요.
**참고**
OpenSearch Ingestion 파이프라인에서 소스로 사용되는 S3 버킷이 다른에 AWS 계정있는 경우 버킷에 대한 교차 계정 읽기 권한도 활성화해야 합니다. 이렇게 하면 파이프라인이 데이터를 읽고 처리할 수 있습니다. 교차 계정 권한을 활성화하려면 *Amazon S3 사용 설명서*의 [계정 간 버킷 권한 부여하는 버킷 소유자](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-walkthroughs-managing-access-example2.html)를 참조하세요.
S3 버킷이 여러 계정에 있는 경우 `bucket_owners` 맵을 사용합니다. 예제는 OpenSearch 설명서의 [Cross-account S3 access](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/s3/#cross-account-s3-access)를 참조하세요.
S3-SQS 처리를 설정하려면 다음 단계도 수행해야 합니다.
1. [Amazon SQS 대기열을 생성합니다](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/step-create-queue.html).
1. SQS 대기열을 대상으로 하는 S3 버킷에서 [이벤트 알림을 활성화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enable-event-notifications.html)합니다.
### 1단계: 파이프라인 역할 구성
데이터를 파이프라인으로 *푸시*하는 다른 소스 플러그인과 달리 [S3 소스 플러그인](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/s3/)은 파이프라인이 소스에서 데이터를 *가져오는* 읽기 기반 아키텍처를 사용합니다.
따라서 S3에서 파이프라인을 읽으려면 S3 버킷과 Amazon SQS 대기열 모두에 액세스할 수 있는 파이프라인의 S3 소스 구성 내에서 역할을 지정해야 합니다. 파이프라인은 대기열에서 데이터를 읽기 위해 이 역할을 맡습니다.
**참고**
S3 소스 구성 내에서 지정하는 역할은 [파이프라인 역할]()이어야 합니다. 따라서 파이프라인 역할에는 두 개의 개별 권한 정책이 포함되어야 합니다. 하나는 싱크에 쓰는 정책이고 다른 하나는 S3 소스에서 가져오기 위한 것입니다. 모든 파이프라인 구성 요소에서 `sts_role_arn`을 동일하게 사용해야 합니다.
다음 샘플 정책은 S3를 소스로 사용하는 데 필요한 권한을 보여줍니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action":[
"s3:ListBucket",
"s3:GetBucketLocation",
"s3:GetObject"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
},
{
"Effect":"Allow",
"Action":"s3:ListAllMyBuckets",
"Resource":"arn:aws:s3:::*"
},
{
"Effect": "Allow",
"Action": [
"sqs:DeleteMessage",
"sqs:ReceiveMessage",
"sqs:ChangeMessageVisibility"
],
"Resource": "arn:aws:sqs:us-east-1:111122223333:MyS3EventSqsQueue"
}
]
}
```
------
S3 소스 플러그인 구성 내 `sts_role_arn` 옵션에 지정하는 IAM 역할에 다음 권한을 연결해야 합니다.
```
version: "2"
source:
s3:
...
aws:
...
processor:
...
sink:
- opensearch:
...
```
### 2단계: 파이프라인 생성
권한을 설정한 후 Amazon S3 사용 사례에 따라 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
#### S3-SQS 처리
S3-SQS 처리를 설정하려면 S3를 소스로 지정하도록 파이프라인을 구성하고 Amazon SQS 알림을 설정하세요.
```
version: "2"
s3-pipeline:
source:
s3:
notification_type: "sqs"
codec:
newline: null
sqs:
queue_url: "https://sqs.us-east-1amazonaws.com/account-id/ingestion-queue"
compression: "none"
aws:
region: "region"
processor:
- grok:
match:
message:
- "%{COMMONAPACHELOG}"
- date:
destination: "@timestamp"
from_time_received: true
sink:
- opensearch:
hosts: ["https://search-domain-endpoint.us-east-1es.amazonaws.com"]
index: "index-name"
aws:
region: "region"
```
Amazon S3에서 작은 파일을 처리하는 동안 CPU 사용률이 낮게 나타나면 `workers` 옵션 값을 수정하여 처리량을 늘리는 방법을 고려합니다. 자세한 내용은 [S3 plugin configuration options](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/s3/#configuration)를 참조하세요.
#### 예약 스캔
예약 스캔을 설정하려면 모든 S3 버킷에 적용되는 스캔 수준 또는 버킷 수준의 일정으로 파이프라인을 구성하세요. 버킷 수준 일정 또는 스캔 간격 구성은 항상 스캔 수준 구성을 덮어씁니다.
예약 스캔은 데이터 마이그레이션에 적합한 *1회성 스캔* 또는 일괄 처리에 적합한 *반복 스캔*으로 구성할 수 있습니다.
Amazon S3에서 읽을 파이프라인을 구성하려면 사전 구성된 Amazon S3 블루프린트를 사용합니다. 일정 요구 사항에 맞게 파이프라인 구성의 `scan` 일부를 편집할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
**1회성 스캔**
1회성 예약 스캔은 한 번 실행됩니다. 파이프라인 구성에서 `start_time` 및 `end_time`을 사용하여 버킷의 객체를 스캔할 시기를 지정할 수 있습니다. 또는 버킷의 객체를 스캔하려는 현재 시간을 기준으로 시간 간격을 지정하는 데 `range`을 사용할 수 있습니다.
예를 들어 최근 4시간 동안 생성된 모든 파일을 `PT4H` 스캔하도록 범위를 설정합니다. 한 번 스캔을 두 번 실행하도록 구성하려면 파이프라인을 중지하고 다시 시작해야 합니다. 범위를 구성하지 않은 경우 시작 시간 및 종료 시간도 업데이트해야 합니다.
다음 구성은 모든 버킷과 해당 버킷의 모든 객체를 한 번 스캔하도록 설정합니다.
```
version: "2"
log-pipeline:
source:
s3:
codec:
csv:
compression: "none"
aws:
region: "region"
acknowledgments: true
scan:
buckets:
- bucket:
name: my-bucket
filter:
include_prefix:
- Objects1/
exclude_suffix:
- .jpeg
- .png
- bucket:
name: my-bucket-2
key_prefix:
include:
- Objects2/
exclude_suffix:
- .jpeg
- .png
delete_s3_objects_on_read: false
processor:
- date:
destination: "@timestamp"
from_time_received: true
sink:
- opensearch:
hosts: ["https://search-domain-endpoint.us-east-1es.amazonaws.com"]
index: "index-name"
aws:
region: "region"
dlq:
s3:
bucket: "dlq-bucket"
region: "us-east-1"
```
다음 구성은 지정된 기간 동안 모든 버킷에 대한 1회성 스캔을 설정합니다. 즉, S3는 생성 시간이 이 기간에 해당하는 객체만 처리합니다.
```
scan:
start_time: 2023-01-21T18:00:00.000Z
end_time: 2023-04-21T18:00:00.000Z
buckets:
- bucket:
name: my-bucket-1
filter:
include:
- Objects1/
exclude_suffix:
- .jpeg
- .png
- bucket:
name: my-bucket-2
filter:
include:
- Objects2/
exclude_suffix:
- .jpeg
- .png
```
다음 구성은 스캔 수준과 버킷 수준 모두에서 1회성 스캔을 설정합니다. 버킷 수준의 시작 및 종료 시간은 스캔 수준의 시작 및 종료 시간보다 우선합니다.
```
scan:
start_time: 2023-01-21T18:00:00.000Z
end_time: 2023-04-21T18:00:00.000Z
buckets:
- bucket:
start_time: 2023-01-21T18:00:00.000Z
end_time: 2023-04-21T18:00:00.000Z
name: my-bucket-1
filter:
include:
- Objects1/
exclude_suffix:
- .jpeg
- .png
- bucket:
start_time: 2023-01-21T18:00:00.000Z
end_time: 2023-04-21T18:00:00.000Z
name: my-bucket-2
filter:
include:
- Objects2/
exclude_suffix:
- .jpeg
- .png
```
파이프라인을 중지하면 중지 전에 파이프라인에서 스캔한 객체에 대한 기존 참조가 제거됩니다. 단일 스캔 파이프라인이 중지되면 이미 스캔되었어도 시작된 이후 모든 객체를 다시 스캔합니다. 단일 스캔 파이프라인을 중지해야 하는 경우 파이프라인을 다시 시작하기 전에 기간을 변경하는 것이 좋습니다.
시작 시간 및 종료 시간별로 객체를 필터링해야 하는 경우 파이프라인을 중지하고 시작하는 것이 유일한 옵션입니다. 시작 시간 및 종료 시간을 기준으로 필터링할 필요가 없는 경우 이름을 기준으로 객체를 필터링할 수 있습니다. 이름을 기준으로 필터링하는 경우 파이프라인을 중지하고 시작할 필요가 없습니다. 이렇게 하려면 `include_prefix` 및 `exclude_suffix`를 사용합니다.
**반복 스캔**
반복 예약 스캔은 지정된 S3 버킷의 스캔을 정기적으로 예약된 간격으로 실행합니다. 개별 버킷 수준 구성은 지원되지 않으므로 스캔 수준에서만 이러한 간격을 구성할 수 있습니다.
파이프라인 구성에서는 `interval`이 반복 스캔 빈도를 지정하며 30초에서 365일 사이일 수 있습니다. 파이프라인을 생성할 때 항상 첫 번째 스캔이 발생합니다. `count`는 스캔 인스턴스 총 수를 정의합니다.
다음 구성은 스캔 사이에 12시간의 지연을 두고 반복 스캔을 설정합니다.
```
scan:
scheduling:
interval: PT12H
count: 4
buckets:
- bucket:
name: my-bucket-1
filter:
include:
- Objects1/
exclude_suffix:
- .jpeg
- .png
- bucket:
name: my-bucket-2
filter:
include:
- Objects2/
exclude_suffix:
- .jpeg
- .png
```
## 대상으로서의 Amazon S3
OpenSearch Ingestion 파이프라인의 데이터를 S3 버킷에 쓰려면 사전 구성된 S3 블루프린트를 사용하여 [S3 싱크](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/s3/)가 있는 파이프라인을 생성합니다. 이 파이프라인은 선택적 데이터를 OpenSearch 싱크로 라우팅하고 동시에 S3에 보관할 모든 데이터를 전송합니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
S3 싱크를 생성할 때 다양한 [싱크 코덱](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/s3/#codec) 중에서 원하는 형식을 지정할 수 있습니다. 예를 들어 데이터를 열 형식으로 쓰려면 Parquet 또는 Avro 코덱을 선택하세요. 행 기반 형식을 선호하는 경우 JSON 또는 NDJSON을 선택하세요. 지정된 스키마로 S3에 데이터를 쓰려면 [Avro 형식](https://avro.apache.org/docs/current/specification/#schema-declaration)을 사용하여 싱크 코덱 내에 인라인 스키마를 정의할 수도 있습니다.
다음 예제에서는 S3 싱크에 인라인 스키마를 정의합니다.
```
- s3:
codec:
parquet:
schema: >
{
"type" : "record",
"namespace" : "org.vpcFlowLog.examples",
"name" : "VpcFlowLog",
"fields" : [
{ "name" : "version", "type" : "string"},
{ "name" : "srcport", "type": "int"},
{ "name" : "dstport", "type": "int"},
{ "name" : "start", "type": "int"},
{ "name" : "end", "type": "int"},
{ "name" : "protocol", "type": "int"},
{ "name" : "packets", "type": "int"},
{ "name" : "bytes", "type": "int"},
{ "name" : "action", "type": "string"},
{ "name" : "logStatus", "type" : "string"}
]
}
```
이 스키마를 정의할 때는 파이프라인이 싱크에 전달하는 다양한 유형의 이벤트에 존재할 수 있는 모든 키의 상위 세트를 지정하세요.
예를 들어 이벤트에 키가 누락될 가능성이 있는 경우 스키마에 해당 키를 `null` 값과 함께 추가하세요. Null 값 선언을 사용하면 스키마가 비균일 데이터를 처리할 수 있습니다(일부 이벤트에는 이러한 키가 있고 다른 이벤트에는 이러한 키가 없는 경우). 수신 이벤트에 이러한 키가 있는 경우 해당 값이 싱크에 기록됩니다.
이 스키마 정의는 정의된 키만 싱크로 전송하도록 허용하고 수신 이벤트에서 정의되지 않은 키를 삭제하는 필터 역할을 합니다.
싱크에서 `include_keys` 및 `exclude_keys`를 사용하여 다른 싱크로 라우팅되는 데이터를 필터링할 수도 있습니다. 이 두 필터는 상호 배타적이므로 스키마에서 한 번에 하나만 사용할 수 있습니다. 또한 사용자 정의 스키마 내에서는 이러한 스키마를 사용할 수 없습니다.
이러한 필터를 사용하여 파이프라인을 생성하려면 사전 구성된 싱크 필터 블루프린트를 사용합니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
## 소스 역할을 하는 Amazon S3 교차 계정
OpenSearch Ingestion 파이프라인이 다른 계정의 S3 버킷에 소스로 액세스할 수 있도록 Amazon S3가 있는 여러 계정에서 액세스 권한을 부여할 수 있습니다. 교차 계정 액세스를 활성화하려면 **Amazon S3 사용 설명서의 [교차 계정 버킷 권한을 부여하는 버킷 소유자](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-walkthroughs-managing-access-example2.html)를 참조하세요. 액세스 권한을 부여한 후 파이프라인 역할에 필요한 권한이 있는지 확인합니다.
그런 다음, `bucket_owners`를 사용하여 파이프라인을 생성해 소스로 Amazon S3 버킷에 대한 교차 계정 액세스를 활성화할 수 있습니다.
```
s3-pipeline:
source:
s3:
notification_type: "sqs"
codec:
csv:
delimiter: ","
quote_character: "\""
detect_header: True
sqs:
queue_url: "https://sqs.ap-northeast-1.amazonaws.com/401447383613/test-s3-queue"
bucket_owners:
my-bucket-01: 123456789012
my-bucket-02: 999999999999
compression: "gzip"
```
# Amazon Security Lake와 함께 OpenSearch Ingestion 파이프라인 사용
[S3 소스 플러그인](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/s3/)을 사용하여 [Amazon Security Lake](https://docs.aws.amazon.com/security-lake/latest/userguide/what-is-security-lake.html)의 데이터를 OpenSearch Ingestion 파이프라인으로 수집할 수 있습니다. Security Lake는 AWS 환경, 온프레미스 환경 및 SaaS 공급자의 보안 데이터를 특별히 구축된 데이터 레이크로 자동으로 중앙 집중화합니다. Security Lake의 데이터를 OpenSearch Ingestion 파이프라인으로 복제하는 구독을 생성하여 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션에 데이터를 쓸 수 있습니다.
Security Lake에서 읽을 파이프라인을 구성하려면 사전 구성된 Security Lake 블루프린트를 사용합니다. 청사진에는 Security Lake에서 Open Cybersecurity Schema Framewor(OCSF) 파켓 파일을 수집하기 위한 기본 구성이 포함되어 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
**Topics**
+ [
# 소스로서의 Amazon Security Lake와 함께 OpenSearch Ingestion 파이프라인 사용
](configure-client-source-security-lake.md)
+ [
# 싱크로서의 Amazon Security Lake와 함께 OpenSearch Ingestion 파이프라인 사용
](configure-client-sink-security-lake.md)
# 소스로서의 Amazon Security Lake와 함께 OpenSearch Ingestion 파이프라인 사용
OpenSearch Ingestion 파이프라인 내에서 Amazon S3 소스 플러그인을 사용하여 Amazon Security Lake의 데이터를 수집할 수 있습니다. Security Lake는 AWS 환경, 온프레미스 시스템 및 SaaS 제공업체의 보안 데이터를 특별히 구축된 데이터 레이크로 자동 중앙 집중화합니다.
Amazon Security Lake에는 파이프라인 내에 다음 메타데이터 속성이 있습니다.
+ `bucket_name`: 보안 데이터를 저장하기 위해 Security Lake가 생성한 Amazon S3 버킷의 이름입니다.
+ `path_prefix`: Security Lake IAM 역할 정책에 정의된 사용자 지정 소스 이름입니다.
+ `region`: Security Lake S3 버킷이 AWS 리전 위치한 입니다.
+ `accountID`: Security Lake가 활성화된 AWS 계정 ID입니다.
+ `sts_role_arn`: Security Lake와 함께 사용하기 위한 IAM 역할의 ARN입니다.
## 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
+ [Security Lake를 활성화합니다](https://docs.aws.amazon.com/security-lake/latest/userguide/getting-started.html#enable-service).
+ Security Lake에서 [구독자를 생성](https://docs.aws.amazon.com/security-lake/latest/userguide/subscriber-data-access.html#create-subscriber-data-access)하세요.
+ 파이프라인에 수집하려는 소스를 선택하세요.
+ **구독자 자격 증명**에 파이프라인을 생성하려는 AWS 계정 의 ID를 추가합니다. 외부 ID의 경우 `OpenSearchIngestion-{accountid}`을 지정하세요.
+ **데이터 액세스 메서드**로는 **S3**를 선택합니다.
+ **알림 세부 정보**를 보려면 **SQS 대기열**을 선택합니다.
구독자를 생성하면 Security Lake는 자동으로 두 개의 인라인 권한 정책을 생성합니다. 하나는 S3용이고 다른 하나는 SQS용입니다. 정책 형식은 `AmazonSecurityLake-amzn-s3-demo-bucket-S3` 및 `AmazonSecurityLake-AWS Demo-SQS`입니다. 파이프라인이 구독자 소스에 액세스할 수 있게 하려면 필요한 권한을 파이프라인 역할에 연결해야 합니다.
## 파이프라인 역할 구성
Security Lake에서 자동으로 생성한 두 정책의 필수 권한만 결합하는 새 권한 정책을 IAM에 생성하세요. 다음 예제 정책은 OpenSearch Ingestion 파이프라인이 여러 Security Lake 소스의 데이터를 읽는 데 필요한 최소 권한을 보여줍니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"s3:GetObject"
],
"Resource":[
"arn:aws:s3:::aws-security-data-lake-us-east-1-abcde/aws/LAMBDA_EXECUTION/1.0/*",
"arn:aws:s3:::aws-security-data-lake-us-east-1-abcde/aws/S3_DATA/1.0/*",
"arn:aws:s3:::aws-security-data-lake-us-east-1-abcde/aws/VPC_FLOW/1.0/*",
"arn:aws:s3:::aws-security-data-lake-us-east-1-abcde/aws/ROUTE53/1.0/*",
"arn:aws:s3:::aws-security-data-lake-us-east-1-abcde/aws/SH_FINDINGS/1.0/*"
]
},
{
"Effect":"Allow",
"Action":[
"sqs:ReceiveMessage",
"sqs:DeleteMessage"
],
"Resource":[
"arn:aws:sqs:us-east-1:111122223333:AmazonSecurityLake-abcde-Main-Queue"
]
}
]
}
```
------
**중요**
Security Lake는 파이프라인 역할 정책을 대신 관리하지 않습니다. Security Lake 구독에서 소스를 추가하거나 제거하는 경우 정책을 수동으로 업데이트해야 합니다. Security Lake는 각 로그 소스에 대해 파티션을 생성하므로 파이프라인 역할에서 권한을 수동으로 추가하거나 제거해야 합니다.
`sqs`에서 S3 소스 플러그인 구성 내 `sts_role_arn` 옵션에 지정하는 IAM 역할에 다음 권한을 연결해야 합니다.
```
version: "2"
source:
s3:
...
sqs:
queue_url: "https://sqs.us-east-1amazonaws.com/account-id/AmazonSecurityLake-amzn-s3-demo-bucket-Main-Queue"
aws:
...
processor:
...
sink:
- opensearch:
...
```
## 파이프라인 생성
파이프라인 역할에 권한을 추가한 후 사전 구성된 Security Lake 블루프린트를 사용하여 파이프라인을 생성합니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
`s3` 소스 구성 내에서 읽을 Amazon SQS 대기열 URL인 `queue_url` 옵션을 지정해야 합니다. URL 형식을 지정하려면 구독자 구성에서 **구독 엔드포인트**를 찾아 `arn:aws:`를 `https://`로 변경하세요. 예를 들어 `https://sqs.us-east-1amazonaws.com/account-id/AmazonSecurityLake-AWS Demo-Main-Queue`입니다.
S3 소스 구성 내에서 지정하는 `sts_role_arn`은 파이프라인 역할의 ARN이어야 합니다.
# 싱크로서의 Amazon Security Lake와 함께 OpenSearch Ingestion 파이프라인 사용
OpenSearch Ingestion의 Amazon S3 싱크 플러그인을 사용하여 지원되는 소스에서 Amazon Security Lake로 데이터를 전송합니다. Security Lake는, AWS온프레미스 환경 및 SaaS 공급자로부터 보안 데이터를 수집하여 전용 데이터 레이크에 저장합니다.
Security Lake에 로그 데이터를 쓰도록 파이프라인을 구성하려면 사전 구성된 **방화벽 트래픽 로그** 블루프린트를 사용합니다. 이 블루프린트에는 Amazon S3 버킷에 저장된 원시 보안 로그 또는 기타 데이터를 검색하고, 레코드를 처리하고, 정규화하기 위한 기본 구성이 포함되어 있습니다. 그런 다음 Open Cybersecurity Schema Framework(OCSF)에 데이터를 매핑하고 변환된 OCSF 준수 데이터를 Security Lake로 전송합니다.
파이프라인에는 다음 메타데이터 속성이 있습니다.
+ `bucket_name`: 보안 데이터를 저장하기 위해 Security Lake가 생성한 Amazon S3 버킷의 이름입니다.
+ `path_prefix`: Security Lake IAM 역할 정책에 정의된 사용자 지정 소스 이름입니다.
+ `region`: Security Lake S3 버킷이 AWS 리전 위치한 입니다.
+ `accountID`: Security Lake가 활성화된 AWS 계정 ID입니다.
+ `sts_role_arn`: Security Lake와 함께 사용하기 위한 IAM 역할의 ARN입니다.
## 사전 조건
Security Lake로 데이터를 전송하는 파이프라인을 생성하기 전에 다음 단계를 수행합니다.
+ **Amazon Security Lake 활성화 및 구성**: 다양한 소스의 보안 데이터를 중앙 집중화하도록 Amazon Security Lake를 설정합니다. 지침은 [콘솔을 사용하여 Security Lake 활성화](https://docs.aws.amazon.com/security-lake/latest/userguide/get-started-console.html)를 참조하세요.
소스를 선택할 때 **특정 AWS 소스 수집**을 선택하고 수집할 로그 및 이벤트 소스를 하나 이상 선택합니다.
+ **권한 설정**: Security Lake에 데이터를 쓰는 데 필요한 권한으로 파이프라인 역할을 구성합니다. 자세한 내용은 [파이프라인 역할](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security-overview.html#pipeline-security-sink)을 참조하세요.
### 파이프라인 생성
사전 구성된 Security Lake 블루프린트를 사용하여 파이프라인을 생성합니다. 자세한 내용은 [블루프린트를 사용하여 파이프라인 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-blueprint.html)을 참조하세요.
# Fluent Bit와 함께 OpenSearch Ingestion 파이프라인 사용
이 샘플 [Fluent Bit 구성 파일](https://docs.fluentbit.io/manual/pipeline/outputs/http)은 Fluent Bit의 로그 데이터를 OpenSearch Ingestion 파이프라인으로 보냅니다. 로그 데이터 수집에 대한 자세한 내용은 Data Prepper 설명서의 [로그 분석](https://github.com/opensearch-project/data-prepper/blob/main/docs/log_analytics.md)을 참조하세요.
다음 사항에 유의하세요.
+ `host` 값은 파이프라인 엔드포인트여야 합니다. 예를 들어 `pipeline-endpoint.us-east-1osis.amazonaws.com`입니다.
+ `aws_service` 값은 `osis`여야 합니다.
+ `aws_role_arn` 값은 클라이언트가 서명 버전 4 인증에 수임하고 사용할 AWS IAM 역할의 ARN입니다.
```
[INPUT]
name tail
refresh_interval 5
path /var/log/test.log
read_from_head true
[OUTPUT]
Name http
Match *
Host pipeline-endpoint.us-east-1osis.amazonaws.com
Port 443
URI /log/ingest
Format json
aws_auth true
aws_region region
aws_service osis
aws_role_arn arn:aws:iam::account-id:role/ingestion-role
Log_Level trace
tls On
```
그런 다음 HTTP를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
```
version: "2"
unaggregated-log-pipeline:
source:
http:
path: "/log/ingest"
processor:
- grok:
match:
log:
- "%{TIMESTAMP_ISO8601:timestamp} %{NOTSPACE:network_node} %{NOTSPACE:network_host} %{IPORHOST:source_ip}:%{NUMBER:source_port:int} -> %{IPORHOST:destination_ip}:%{NUMBER:destination_port:int} %{GREEDYDATA:details}"
- grok:
match:
details:
- "'%{NOTSPACE:http_method} %{NOTSPACE:http_uri}' %{NOTSPACE:protocol}"
- "TLS%{NOTSPACE:tls_version} %{GREEDYDATA:encryption}"
- "%{NUMBER:status_code:int} %{NUMBER:response_size:int}"
- delete_entries:
with_keys: ["details", "log"]
sink:
- opensearch:
hosts: ["https://search-domain-endpoint.us-east-1es.amazonaws.com"]
index: "index_name"
index_type: custom
bulk_size: 20
aws:
region: "region"
```
# Fluent Bit에서 OpenSearch Ingestion 파이프라인 사용
Fluentd는 Fluent Bit와 같은 다양한 언어 및 하위 프로젝트용 SDK를 제공하는 오픈 소스 데이터 컬렉션 에코시스템입니다. 이 샘플 [Fluentd 구성 파일](https://docs.fluentd.org/output/http#example-configuration)은 Fluentd의 로그 데이터를 OpenSearch Ingestion 파이프라인으로 전송합니다. 로그 데이터 수집에 대한 자세한 내용은 Data Prepper 설명서의 [로그 분석](https://github.com/opensearch-project/data-prepper/blob/main/docs/log_analytics.md)을 참조하세요.
다음 사항에 유의하세요.
+ `endpoint` 값은 파이프라인 엔드포인트여야 합니다. 예를 들어 `pipeline-endpoint.us-east-1osis.amazonaws.com/apache-log-pipeline/logs`입니다.
+ `aws_service` 값은 `osis`여야 합니다.
+ `aws_role_arn` 값은 클라이언트가 서명 버전 4 인증에 수임하고 사용할 AWS IAM 역할의 ARN입니다.
```
@type tail
path logs/sample.log
path_key log
tag apache
@type none
@type record_transformer
log ${record["message"]}
@type record_transformer
remove_keys message
@type http
endpoint pipeline-endpoint.us-east-1osis.amazonaws.com/apache-log-pipeline/logs
json_array true
method aws_sigv4
aws_service osis
aws_region region
aws_role_arn arn:aws:iam::account-id:role/ingestion-role
@type json
flush_interval 1s
```
그런 다음 HTTP를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
```
version: "2"
apache-log-pipeline:
source:
http:
path: "/${pipelineName}/logs"
processor:
- grok:
match:
log:
- "%{TIMESTAMP_ISO8601:timestamp} %{NOTSPACE:network_node} %{NOTSPACE:network_host} %{IPORHOST:source_ip}:%{NUMBER:source_port:int} -> %{IPORHOST:destination_ip}:%{NUMBER:destination_port:int} %{GREEDYDATA:details}"
sink:
- opensearch:
hosts: ["https://search-domain-endpoint.us-east-1es.amazonaws.com"]
index: "index_name"
aws_region: "region"
aws_sigv4: true
```
# 기계 학습 오프라인 배치 추론과 함께 OpenSearch Ingestion 파이프라인 사용
Amazon OpenSearch Ingestion(OSI) 파이프라인은 낮은 비용으로 대량의 데이터를 효율적으로 보강할 수 있도록 기계 학습(ML) 오프라인 배치 추론 처리를 지원합니다. 비동기적으로 처리할 수 있는 대규모 데이터세트가 있을 때마다 오프라인 배치 추론을 사용합니다. 오프라인 배치 추론은 Amazon Bedrock 및 SageMaker 모델과 함께 작동합니다. 이 기능은 OpenSearch Service 2.17\$1 도메인을 사용하는 OpenSearch Ingestion을 AWS 리전 지원하는 모든에서 사용할 수 있습니다.
**참고**
실시간 추론 처리의 경우 [서드파티 플랫폼에 대한 Amazon OpenSearch Service ML 커넥터](ml-external-connector.md)를 사용합니다.
오프라인 배치 추론 처리는 ML Commons라는 OpenSearch의 기능을 활용합니다. *ML Commons*는 전송 및 REST API 호출을 통해 ML 알고리즘을 제공합니다. 이러한 직접적 호출은 각 ML 요청에 적합한 노드와 리소스를 선택하고 ML 작업을 모니터링하여 가동 시간을 보장합니다. 이를 통해 ML Commons는 기존 오픈 소스 ML 알고리즘을 활용하고 새로운 ML 기능을 개발하는 데 필요한 노력을 줄일 수 있습니다. ML Commons에 대한 자세한 내용은 OpenSearch.org 설명서의 [Machine learning](https://docs.opensearch.org/latest/ml-commons-plugin/)을 참조하세요.
## 작동 방식
[기계 학습 추론 프로세서를 파이프라인에 추가](https://docs.opensearch.org/latest/ingest-pipelines/processors/ml-inference/)하여 OpenSearch Ingestion에서 오프라인 배치 추론 파이프라인을 생성할 수 있습니다. 이 프로세서를 사용하면 파이프라인을 SageMaker와 같은 AI 서비스에 연결하여 배치 추론 작업을 실행할 수 있습니다. 대상 도메인에서 실행되는 AI 커넥터([batch\$1predict](https://docs.opensearch.org/latest/ml-commons-plugin/api/model-apis/batch-predict/) 지원 포함)를 통해 원하는 AI 서비스에 연결하도록 프로세서를 구성할 수 있습니다.
OpenSearch Ingestion은 ML Commons와 함께 `ml_inference` 프로세서를 사용하여 오프라인 배치 추론 작업을 생성합니다. 그런 다음 ML Commons는 [batch\$1predict](https://docs.opensearch.org/latest/ml-commons-plugin/api/model-apis/batch-predict/) API를 사용합니다. 이 API는 Amazon Bedrock, Amazon SageMaker, Cohere 및 OpenAI의 외부 모델 서버에 배포된 모델을 사용하여 오프라인 비동기 모드로 대규모 데이터세트에 대한 추론을 수행합니다. 다음 다이어그램은 여러 구성 요소를 오케스트레이션하여 이 프로세스를 처음부터 끝까지 수행하는 OpenSearch Ingestion 파이프라인을 보여줍니다.
![\[배치 AI 추론 처리의 3 파이프라인 아키텍처.\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/images/ml_processor.png)
파이프라인 구성 요소는 다음과 같이 작동합니다.
**파이프라인 1(데이터 준비 및 변환)\$1:**
+ 소스: OpenSearch Ingestion에서 지원하는 외부 소스에서 스캔한 데이터.
+ 데이터 프로세서: 원시 데이터는 통합 AI 서비스에서 배치 추론을 위해 처리되고 올바른 형식으로 변환됩니다.
+ S3(싱크): 처리된 데이터는 통합 AI 서비스에서 배치 추론 작업을 실행하기 위한 입력으로 사용할 준비가 된 Amazon S3 버킷에 스테이징됩니다.
**파이프라인 2(트리거 ML batch\$1inference):**
+ 소스: 파이프라인 1의 출력으로 생성된 새 파일의 자동 S3 이벤트 감지.
+ Ml\$1inference 프로세서: 비동기 배치 작업을 통해 ML 추론을 생성하는 프로세서. 대상 도메인에서 실행 중인 구성된 AI 커넥터를 통해 AI 서비스에 연결합니다.
+ 작업 ID: 각 배치 작업은 추적 및 관리를 위해 ml-commons의 작업 ID와 연결됩니다.
+ OpenSearch ML Commons: 실시간 신경망 검색을 위해 모델을 호스팅하고, 원격 AI 서버에 대한 커넥터를 관리하고, 배치 추론 및 작업 관리를 위한 API를 제공하는 ML Commons.
+ AI 서비스: OpenSearch ML Commons는 Amazon Bedrock 및 Amazon SageMaker와 같은 AI 서비스와 상호 작용하여 데이터에 대한 배치 추론을 수행함으로써 예측 또는 인사이트를 생성합니다. 결과는 별도의 S3 파일에 비동기적으로 저장됩니다.
**파이프라인 3(대량 수집):**
+ S3(소스): 배치 작업의 결과는 이 파이프라인의 소스인 S3에 저장됩니다.
+ 데이터 변환 프로세서: 수집 전에 배치 추론 출력에 추가 처리 및 변환이 적용됩니다. 이는 OpenSearch 인덱스에서 데이터가 올바르게 매핑되도록 보장합니다.
+ OpenSearch 인덱스(싱크): 처리된 결과는 스토리지, 검색 및 추가 분석을 위해 OpenSearch에 인덱싱됩니다.
**참고**
\$1파이프라인 1에서 설명하는 프로세스는 선택 사항입니다. 원하는 경우 해당 프로세스를 건너뛰고 S3 싱크에 준비된 데이터를 업로드하여 배치 작업을 생성할 수도 있습니다.
## ml\$1inference 프로세서 정보
OpenSearch Ingestion은 배치 처리를 위해 S3 스캔 소스와 ML 추론 프로세서 간의 특수한 통합을 사용합니다. S3 스캔은 메타데이터 전용 모드에서 작동하여 실제 파일 콘텐츠를 읽지 않고도 S3 파일 정보를 효율적으로 수집합니다. `ml_inference` 프로세서는 S3 파일 URL을 사용하여 배치 처리를 위해 ML Commons와 조율합니다. 이러한 설계는 스캔 단계에서 불필요한 데이터 전송을 최소화하여 배치 추론 워크플로를 최적화합니다. `ml_inference` 프로세서는 사용자가 파라미터를 사용하여 정의합니다. 다음 예를 참고하세요
```
processor:
- ml_inference:
# The endpoint URL of your OpenSearch domain
host: "https://AWS test-offlinebatch-123456789abcdefg.us-west-2.es.amazonaws.com"
# Type of inference operation:
# - batch_predict: for batch processing
# - predict: for real-time inference
action_type: "batch_predict"
# Remote ML model service provider (Amazon Bedrock or SageMaker)
service_name: "bedrock"
# Unique identifier for the ML model
model_id: "AWS TestModelID123456789abcde"
# S3 path where batch inference results will be stored
output_path: "s3://amzn-s3-demo-bucket/"
# Supports ISO_8601 notation strings like PT20.345S or PT15M
# These settings control how long to keep your inputs in the processor for retry on throttling errors
retry_time_window: "PT9M"
# AWS configuration settings
aws:
# AWS 리전 where the Lambda function is deployed
region: "us-west-2"
# IAM role ARN for Lambda function execution
sts_role_arn: "arn:aws::iam::account_id:role/Admin"
# Dead-letter queue settings for storing errors
dlq:
s3:
region: us-west-2
bucket: batch-inference-dlq
key_path_prefix: bedrock-dlq
sts_role_arn: arn:aws:iam::account_id:role/OSI-invoke-ml
# Conditional expression that determines when to trigger the processor
# In this case, only process when bucket matches "amzn-s3-demo-bucket"
ml_when: /bucket == "amzn-s3-demo-bucket"
```
### ml\$1inference 프로세서를 사용한 수집 성능 개선
OpenSearch Ingestion `ml_inference` 프로세서는 ML 지원 검색의 데이터 수집 성능을 크게 높입니다. 이 프로세서는 시맨틱 검색, 멀티모달 검색, 문서 보강, 쿼리 이해 등 기계 학습 모델 생성 데이터가 필요한 사용 사례에 적합합니다. 시맨틱 검색에서 이 프로세서는 대용량 고차원 벡터의 생성 및 수집을 10배까지 가속화할 수 있습니다.
이 프로세서의 오프라인 배치 추론 기능은 실시간 모델 호출에 비해 고유한 이점을 제공합니다. 실시간 처리에는 용량 제한이 있는 라이브 모델 서버가 필요하지만 배치 추론은 온디맨드로 컴퓨팅 리소스를 동적으로 확장하고 데이터를 병렬로 처리합니다. 예를 들어 OpenSearch Ingestion 파이프라인이 10억 개의 소스 데이터 요청을 수신하면 ML 배치 추론 입력을 위해 100개의 S3 파일을 생성합니다. 그런 다음 `ml_inference` 프로세서는 100개의 `ml.m4.xlarge` Amazon Elastic Compute Cloud(Amazon EC2) 인스턴스를 사용하여 SageMaker 배치 작업을 시작하고, 14시간 내에 10억 개의 요청을 벡터화하여 실시간 모드에서는 거의 불가능한 작업을 완료합니다.
## 시맨틱 검색에 대한 데이터 요청을 수집하도록 ml\$1inference 프로세서 구성
다음 절차에서는 텍스트 임베딩 모델을 사용하여 의미 체계 검색을 위한 10억 개의 데이터 요청을 수집하도록 OpenSearch Ingestion `ml_inference` 프로세서를 설정하고 구성하는 프로세스를 안내합니다.
**Topics**
+ [
### 1단계: OpenSearch에서 커넥터 생성 및 모델 등록
](#configure-clients-ml-commons-configuring-create-connectors)
+ [
### 2단계: ML 오프라인 배치 추론을 위한 OpenSearch Ingestion 파이프라인 생성
](#configure-clients-ml-commons-configuring-pipeline)
+ [
### 3단계: 수집을 위한 데이터 준비
](#configure-clients-ml-commons-configuring-data)
+ [
### 4단계: 배치 추론 작업 모니터링
](#configure-clients-ml-commons-configuring-monitor)
+ [
### 5단계: 검색 실행
](#configure-clients-ml-commons-configuring-semantic-search)
### 1단계: OpenSearch에서 커넥터 생성 및 모델 등록
다음 절차에서는 ML Commons [batch\$1inference\$1sagemaker\$1connector\$1blueprint](https://github.com/opensearch-project/ml-commons/blob/main/docs/remote_inference_blueprints/batch_inference_sagemaker_connector_blueprint.md)를 사용하여 Amazon SageMaker에서 커넥터와 모델을 생성합니다. OpenSearch CloudFormation 통합 템플릿을 사용하려면이 섹션 [(대안 절차) 1단계: CloudFormation 통합 템플릿을 사용하여 커넥터 및 모델 생성](#configure-clients-ml-commons-configuring-create-connectors-alternative)뒷부분의 섹션을 참조하세요.
**OpenSearch에서 커넥터를 생성하고 모델을 등록하려면**
1. 배치 변환을 위해 SageMaker에서 Deep Java Library(DJL) ML 모델을 생성합니다. 다른 DJL 모델을 보려면 GitHub의 [semantic\$1search\$1with\$1CFN\$1template\$1for\$1Sagemaker](https://github.com/opensearch-project/ml-commons/blob/main/docs/tutorials/aws/semantic_search_with_CFN_template_for_Sagemaker.md)를 참조하세요.
```
POST https://api.sagemaker.us-east-1.amazonaws.com/CreateModel
{
"ExecutionRoleArn": "arn:aws:iam::123456789012:role/aos_ml_invoke_sagemaker",
"ModelName": "DJL-Text-Embedding-Model-imageforjsonlines",
"PrimaryContainer": {
"Environment": {
"SERVING_LOAD_MODELS" : "djl://ai.djl.huggingface.pytorch/sentence-transformers/all-MiniLM-L6-v2"
},
"Image": "763104351884.dkr.ecr.us-east-1.amazonaws.com/djl-inference:0.29.0-cpu-full"
}
}
```
1. `actions` 필드에 `batch_predict`를 새 `action` 유형으로 사용하여 커넥터를 생성합니다.
```
POST /_plugins/_ml/connectors/_create
{
"name": "DJL Sagemaker Connector: all-MiniLM-L6-v2",
"version": "1",
"description": "The connector to sagemaker embedding model all-MiniLM-L6-v2",
"protocol": "aws_sigv4",
"credential": {
"roleArn": "arn:aws:iam::111122223333:role/SageMakerRole"
},
"parameters": {
"region": "us-east-1",
"service_name": "sagemaker",
"DataProcessing": {
"InputFilter": "$.text",
"JoinSource": "Input",
"OutputFilter": "$"
},
"MaxConcurrentTransforms": 100,
"ModelName": "DJL-Text-Embedding-Model-imageforjsonlines",
"TransformInput": {
"ContentType": "application/json",
"DataSource": {
"S3DataSource": {
"S3DataType": "S3Prefix",
"S3Uri": "s3://offlinebatch/msmarcotests/"
}
},
"SplitType": "Line"
},
"TransformJobName": "djl-batch-transform-1-billion",
"TransformOutput": {
"AssembleWith": "Line",
"Accept": "application/json",
"S3OutputPath": "s3://offlinebatch/msmarcotestsoutputs/"
},
"TransformResources": {
"InstanceCount": 100,
"InstanceType": "ml.m4.xlarge"
},
"BatchStrategy": "SingleRecord"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"headers": {
"content-type": "application/json"
},
"url": "https://runtime.sagemaker.us-east-1.amazonaws.com/endpoints/OpenSearch-sagemaker-060124023703/invocations",
"request_body": "${parameters.input}",
"pre_process_function": "connector.pre_process.default.embedding",
"post_process_function": "connector.post_process.default.embedding"
},
{
"action_type": "batch_predict",
"method": "POST",
"headers": {
"content-type": "application/json"
},
"url": "https://api.sagemaker.us-east-1.amazonaws.com/CreateTransformJob",
"request_body": """{ "BatchStrategy": "${parameters.BatchStrategy}", "ModelName": "${parameters.ModelName}", "DataProcessing" : ${parameters.DataProcessing}, "MaxConcurrentTransforms": ${parameters.MaxConcurrentTransforms}, "TransformInput": ${parameters.TransformInput}, "TransformJobName" : "${parameters.TransformJobName}", "TransformOutput" : ${parameters.TransformOutput}, "TransformResources" : ${parameters.TransformResources}}"""
},
{
"action_type": "batch_predict_status",
"method": "GET",
"headers": {
"content-type": "application/json"
},
"url": "https://api.sagemaker.us-east-1.amazonaws.com/DescribeTransformJob",
"request_body": """{ "TransformJobName" : "${parameters.TransformJobName}"}"""
},
{
"action_type": "cancel_batch_predict",
"method": "POST",
"headers": {
"content-type": "application/json"
},
"url": "https://api.sagemaker.us-east-1.amazonaws.com/StopTransformJob",
"request_body": """{ "TransformJobName" : "${parameters.TransformJobName}"}"""
}
]
}
```
1. 반환된 커넥터 ID를 사용하여 SageMaker 모델을 등록합니다.
```
POST /_plugins/_ml/models/_register
{
"name": "SageMaker model for batch",
"function_name": "remote",
"description": "test model",
"connector_id": "example123456789-abcde"
}
```
1. `batch_predict` 작업 유형으로 모델을 간접적으로 호출합니다.
```
POST /_plugins/_ml/models/teHr3JABBiEvs-eod7sn/_batch_predict
{
"parameters": {
"TransformJobName": "SM-offline-batch-transform"
}
}
```
응답에는 배치 작업에 대한 작업 ID가 포함됩니다.
```
{
"task_id": "exampleIDabdcefd_1234567",
"status": "CREATED"
}
```
1. 작업 ID를 사용하여 작업 가져오기 API를 직접적으로 호출하여 배치 작업 상태를 확인합니다.
```
GET /_plugins/_ml/tasks/exampleIDabdcefd_1234567
```
응답에는 작업 상태가 포함됩니다.
```
{
"model_id": "nyWbv5EB_tT1A82ZCu-e",
"task_type": "BATCH_PREDICTION",
"function_name": "REMOTE",
"state": "RUNNING",
"input_type": "REMOTE",
"worker_node": [
"WDZnIMcbTrGtnR4Lq9jPDw"
],
"create_time": 1725496527958,
"last_update_time": 1725496527958,
"is_async": false,
"remote_job": {
"TransformResources": {
"InstanceCount": 1,
"InstanceType": "ml.c5.xlarge"
},
"ModelName": "DJL-Text-Embedding-Model-imageforjsonlines",
"TransformOutput": {
"Accept": "application/json",
"AssembleWith": "Line",
"KmsKeyId": "",
"S3OutputPath": "s3://offlinebatch/output"
},
"CreationTime": 1725496531.935,
"TransformInput": {
"CompressionType": "None",
"ContentType": "application/json",
"DataSource": {
"S3DataSource": {
"S3DataType": "S3Prefix",
"S3Uri": "s3://offlinebatch/sagemaker_djl_batch_input.json"
}
},
"SplitType": "Line"
},
"TransformJobArn": "arn:aws:sagemaker:us-east-1:111122223333:transform-job/SM-offline-batch-transform15",
"TransformJobStatus": "InProgress",
"BatchStrategy": "SingleRecord",
"TransformJobName": "SM-offline-batch-transform15",
"DataProcessing": {
"InputFilter": "$.content",
"JoinSource": "Input",
"OutputFilter": "$"
}
}
}
```
#### (대안 절차) 1단계: CloudFormation 통합 템플릿을 사용하여 커넥터 및 모델 생성
원하는 경우 AWS CloudFormation 를 사용하여 ML 추론에 필요한 모든 Amazon SageMaker 커넥터 및 모델을 자동으로 생성할 수 있습니다. 이 방식은 Amazon OpenSearch Service 콘솔에서 사용할 수 있는 사전 구성된 템플릿을 사용하므로 설정이 간소화됩니다. 자세한 내용은 [CloudFormation 를 사용하여 의미 체계 검색을 위한 원격 추론 설정](cfn-template.md) 단원을 참조하십시오.
**필요한 모든 SageMaker 커넥터 및 모델을 생성하는 CloudFormation 스택을 배포하려면**
1. Amazon OpenSearch Service 콘솔을 엽니다.
1. 탐색 창에서 **통합**을 선택합니다.
1. 검색 필드에 **SageMaker**를 입력한 다음 **Amazon SageMaker를 통한 텍스트 임베딩 모델과의 통합**을 선택합니다.
1. **도메인 구성**을 선택한 다음 **VPC 도메인 구성** 또는 **퍼블릭 도메인 구성**을 선택합니다.
1. 템플릿 필드에 정보를 입력합니다. **오프라인 배치 추론 활성화**에서 **true**를 선택하여 오프라인 배치 처리를 위한 리소스를 프로비저닝합니다.
1. **생성을** 선택하여 CloudFormation 스택을 생성합니다.
1. 스택이 생성된 후 CloudFormation 콘솔에서 **출력** 탭을 열고 **connector\$1id**와 **model\$1id**를 찾습니다. 나중에 파이프라인을 구성할 때 이들 값이 필요합니다.
### 2단계: ML 오프라인 배치 추론을 위한 OpenSearch Ingestion 파이프라인 생성
다음 샘플을 사용하여 ML 오프라인 배치 추론을 위한 OpenSearch Ingestion 파이프라인을 생성합니다. OpenSearch Ingestion용 파이프라인 생성에 대한 자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인 생성](creating-pipeline.md) 섹션을 참조하세요.
**시작하기 전에**
다음 샘플에서는 `sts_role_arn` 파라미터의 IAM 역할 ARN을 지정합니다. 다음 절차에 따라 이 역할이 OpenSearch의 ml-commons에 액세스할 수 있는 백엔드 역할에 매핑되었는지 확인합니다.
1. OpenSearch Service 도메인에 대한 OpenSearch 대시보드 플러그인으로 이동합니다. OpenSearch Service 콘솔의 도메인 Dashboards에서 Dashboards 엔드포인트를 찾을 수 있습니다.
1. 주 메뉴에서 **보안**, **역할**을 선택하고 **ml\$1full\$1access** 역할을 선택합니다.
1. **매핑된 사용자(Mapped users)**, **매핑 관리(Manage mapping)**를 차례로 선택합니다.
1. **백엔드 역할**에 도메인 호출 권한이 필요한 Lambda 역할의 ARN을 입력합니다. 예: arn:aws:iam::*111122223333*:role/*lambda-role*
1. **Map**(맵)을 선택하고 **Mapped users**(매핑된 사용자)에 사용자 또는 역할이 나타나는지 확인합니다.
**ML 오프라인 배치 추론을 위한 OpenSearch Ingestion 파이프라인을 생성하는 샘플**
```
version: '2'
extension:
osis_configuration_metadata:
builder_type: visual
sagemaker-batch-job-pipeline:
source:
s3:
acknowledgments: true
delete_s3_objects_on_read: false
scan:
buckets:
- bucket:
name: name
data_selection: metadata_only
filter:
include_prefix:
- sagemaker/sagemaker_djl_batch_input
exclude_suffix:
- .manifest
- bucket:
name: name
data_selection: data_only
filter:
include_prefix:
- sagemaker/output/
scheduling:
interval: PT6M
aws:
region: name
default_bucket_owner: account_ID
codec:
ndjson:
include_empty_objects: false
compression: none
workers: '1'
processor:
- ml_inference:
host: "https://search-AWStest-offlinebatch-123456789abcdef.us-west-2.es.amazonaws.com"
aws_sigv4: true
action_type: "batch_predict"
service_name: "sagemaker"
model_id: "model_ID"
output_path: "s3://AWStest-offlinebatch/sagemaker/output"
aws:
region: "us-west-2"
sts_role_arn: "arn:aws:iam::account_ID:role/Admin"
ml_when: /bucket == "AWStest-offlinebatch"
dlq:
s3:
region: us-west-2
bucket: batch-inference-dlq
key_path_prefix: bedrock-dlq
sts_role_arn: arn:aws:iam::account_ID:role/OSI-invoke-ml
- copy_values:
entries:
- from_key: /text
to_key: chapter
- from_key: /SageMakerOutput
to_key: chapter_embedding
- delete_entries:
with_keys:
- text
- SageMakerOutput
sink:
- opensearch:
hosts: ["https://search-AWStest-offlinebatch-123456789abcdef.us-west-2.es.amazonaws.com"]
aws:
serverless: false
region: us-west-2
routes:
- ml-ingest-route
index_type: custom
index: test-nlp-index
routes:
- ml-ingest-route: /chapter != null and /title != null
```
### 3단계: 수집을 위한 데이터 준비
ML 오프라인 배치 추론 처리를 위해 데이터를 준비하려면 자체 도구 또는 프로세스를 사용하여 직접 데이터를 준비하거나 [OpenSearch Data Prepper](https://docs.opensearch.org/latest/data-prepper/getting-started/)를 사용합니다. 파이프라인을 사용하여 데이터 소스의 데이터를 사용하거나, 기계 학습 데이터세트를 생성하여 데이터가 올바른 형식으로 구성되어 있는지 확인합니다.
다음 예에서는 자연어 처리 작업에 대한 실제 사용자 쿼리 모음이 포함된 [MS MARCO](https://microsoft.github.io/msmarco/Datasets.html) 데이터세트를 사용합니다. 이 데이터세트는 JSONL 형식으로 구성되어 있습니다. 여기서 각 줄은 ML 임베딩 모델로 전송된 요청을 나타냅니다.
```
{"_id": "1185869", "text": ")what was the immediate impact of the Paris Peace Treaties of 1947?", "metadata": {"world war 2"}}
{"_id": "1185868", "text": "_________ justice is designed to repair the harm to victim, the community and the offender caused by the offender criminal act. question 19 options:", "metadata": {"law"}}
{"_id": "597651", "text": "what is amber", "metadata": {"nothing"}}
{"_id": "403613", "text": "is autoimmune hepatitis a bile acid synthesis disorder", "metadata": {"self immune"}}
...
```
MS MARCO 데이터세트를 사용하여 테스트하기 위해, 각각 1,000만 개의 요청이 포함된 100개의 파일에 분산된 10억 개의 입력 요청을 구성하는 시나리오를 가정해 보겠습니다. 이 파일은 접두사 s3://offlinebatch/sagemaker/sagemaker\$1djl\$1batch\$1input/과 함께 Amazon S3에 저장됩니다. OpenSearch Ingestion 파이프라인은 이러한 100개의 파일을 동시에 스캔하고, 병렬 처리를 위해 100개의 작업자로 SageMaker 배치 작업을 시작하여 10억 개의 문서를 OpenSearch로 효율적으로 벡터화하고 수집합니다.
프로덕션 환경에서는 OpenSearch Ingestion 파이프라인을 사용하여 배치 추론 입력을 위한 S3 파일을 생성할 수 있습니다. 이 파이프라인은 다양한 [데이터 소스](https://docs.opensearch.org/latest/data-prepper/pipelines/configuration/sources/sources/)를 지원하며 일정에 따라 작동하여 소스 데이터를 S3 파일로 지속적으로 변환합니다. 그런 다음 예약된 오프라인 배치 작업을 통해 AI 서버에서 이러한 파일을 자동으로 처리하여 지속적인 데이터 처리와 수집을 보장합니다.
### 4단계: 배치 추론 작업 모니터링
SageMaker 콘솔 또는 AWS CLI를 사용하여 배치 추론 작업을 모니터링할 수 있습니다. 작업 가져오기 API를 사용하여 배치 작업을 모니터링할 수도 있습니다.
```
GET /_plugins/_ml/tasks/_search
{
"query": {
"bool": {
"filter": [
{
"term": {
"state": "RUNNING"
}
}
]
}
},
"_source": ["model_id", "state", "task_type", "create_time", "last_update_time"]
}
```
이 API는 활성 배치 작업 목록을 반환합니다.
```
{
"took": 2,
"timed_out": false,
"_shards": {
"total": 5,
"successful": 5,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 3,
"relation": "eq"
},
"max_score": 0.0,
"hits": [
{
"_index": ".plugins-ml-task",
"_id": "nyWbv5EB_tT1A82ZCu-e",
"_score": 0.0,
"_source": {
"model_id": "nyWbv5EB_tT1A82ZCu-e",
"state": "RUNNING",
"task_type": "BATCH_PREDICTION",
"create_time": 1725496527958,
"last_update_time": 1725496527958
}
},
{
"_index": ".plugins-ml-task",
"_id": "miKbv5EB_tT1A82ZCu-f",
"_score": 0.0,
"_source": {
"model_id": "miKbv5EB_tT1A82ZCu-f",
"state": "RUNNING",
"task_type": "BATCH_PREDICTION",
"create_time": 1725496528123,
"last_update_time": 1725496528123
}
},
{
"_index": ".plugins-ml-task",
"_id": "kiLbv5EB_tT1A82ZCu-g",
"_score": 0.0,
"_source": {
"model_id": "kiLbv5EB_tT1A82ZCu-g",
"state": "RUNNING",
"task_type": "BATCH_PREDICTION",
"create_time": 1725496529456,
"last_update_time": 1725496529456
}
}
]
}
}
```
### 5단계: 검색 실행
배치 추론 작업을 모니터링하고 완료를 확인한 후 시맨틱, 하이브리드, 대화형(RAG 사용), 신경망 희소, 멀티모달 등 다양한 유형의 AI 검색을 실행할 수 있습니다. OpenSearch Service에서 지원하는 AI 검색에 대한 자세한 내용은 [AI 검색](https://docs.opensearch.org/latest/vector-search/ai-search/index/)을 참조하세요.
원시 벡터를 검색하려면 `knn` 쿼리 유형을 사용하고, `vector` 배열을 입력으로 제공하고, 반환된 결과의 `k` 수를 지정합니다.
```
GET /my-raw-vector-index/_search
{
"query": {
"knn": {
"my_vector": {
"vector": [0.1, 0.2, 0.3],
"k": 2
}
}
}
}
```
AI 기반 검색을 실행하려면 `neural` 쿼리 유형을 사용합니다. `query_text` 입력, OpenSearch Ingestion 파이프라인에서 구성한 임베딩 모델의 `model_id`, 반환된 결과의 `k` 수를 지정합니다. 검색 결과에서 임베딩을 제외하려면 `_source.excludes` 파라미터에 임베딩 필드의 이름을 지정합니다.
```
GET /my-ai-search-index/_search
{
"_source": {
"excludes": [
"output_embedding"
]
},
"query": {
"neural": {
"output_embedding": {
"query_text": "What is AI search?",
"model_id": "mBGzipQB2gmRjlv_dOoB",
"k": 2
}
}
}
}
```
# OpenTelemetry Collector와 함께 OpenSearch Ingestion 파이프라인 사용
[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)를 사용하여 로그, 추적 및 지표를 OpenSearch Ingestion 파이프라인으로 수집할 수 있습니다. 단일 파이프라인을 사용하여 모든 로그, 추적 및 지표를 도메인 또는 컬렉션의 다른 인덱스에 수집할 수 있습니다. 파이프라인을 사용하여 로그, 추적 또는 지표만 개별적으로 수집할 수도 있습니다.
**Topics**
+ [
## 사전 조건
](#otel-prereqs)
+ [
## 1단계: 파이프라인 역할 구성
](#otel-pipeline-role)
+ [
## 2단계: 파이프라인 생성
](#create-otel-pipeline)
+ [
## 교차 계정 연결
](#x-account-connectivity)
+ [
## 제한 사항
](#otel-limitations)
+ [
## OpenTelemetry 소스에 권장되는 CloudWatch 경보
](#otel-pipeline-metrics)
## 사전 조건
[OpenTelemetry 구성 파일을](https://opentelemetry.io/docs/collector/configuration/) 설정하는 동안 수집을 수행하려면 다음을 구성해야 합니다.
+ 수집 역할에는 파이프라인과 상호 작용할 수 있는 `osis:Ingest` 권한이 필요합니다. 자세한 내용은 [수집 역할을 참조하세요](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security-overview.html#pipeline-security-same-account).
+ 엔드포인트 값에는 파이프라인 엔드포인트가 포함되어야 합니다. 예: `https://pipeline-endpoint.us-east-1.osis.amazonaws.com.`
+ 서비스 값은 여야 합니다`osis`.
+ OTLP/HTTP Exporter의 압축 옵션은 파이프라인에서 선택한 소스의 압축 옵션과 일치해야 합니다.
```
extensions:
sigv4auth:
region: "region"
service: "osis"
exporters:
otlphttp:
logs_endpoint: "https://pipeline-endpoint.us-east-1.osis.amazonaws.com/v1/logs"
metrics_endpoint: "https://pipeline-endpoint.us-east-1.osis.amazonaws.com/v1/metrics"
traces_endpoint: "https://pipeline-endpoint.us-east-1.osis.amazonaws.com/v1/traces"
auth:
authenticator: sigv4auth
compression: none
service:
extensions: [sigv4auth]
pipelines:
traces:
receivers: [jaeger]
exporters: [otlphttp]
```
## 1단계: 파이프라인 역할 구성
OpenTelemetry 수집기 구성을 설정한 후 [ 파이프라인 구성에 사용할 파이프라인 역할을 설정합니다](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security-overview.html#pipeline-security-sink). 파이프라인 역할에 OTLP 소스에 필요한 특정 권한은 없으며 파이프라인에 OpenSearch 도메인 또는 컬렉션에 대한 액세스 권한을 부여할 수 있는 권한만 있습니다.
## 2단계: 파이프라인 생성
그런 다음 OTLP를 소스로 지정하는 다음과 같이 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다. OpenTelemetry 로그, 지표 및 추적을 개별 소스로 구성할 수도 있습니다.
OTLP 소스 파이프라인 구성:
```
version: 2
otlp-pipeline:
source:
otlp:
logs_path: /otlp-pipeline/v1/logs
traces_path: /otlp-pipeline/v1/traces
metrics_path: /otlp-pipeline/v1/metrics
sink:
- opensearch:
hosts: ["https://search-mydomain.region.es.amazonaws.com"]
index: "ss4o_metrics-otel-%{yyyy.MM.dd}"
index_type: custom
aws:
region: "region"
```
OpenTelemetry Logs 파이프라인 구성:
```
version: 2
otel-logs-pipeline:
source:
otel_logs_source:
path: /otel-logs-pipeline/v1/logs
sink:
- opensearch:
hosts: ["https://search-mydomain.region.es.amazonaws.com"]
index: "ss4o_metrics-otel-%{yyyy.MM.dd}"
index_type: custom
aws:
region: "region"
```
OpenTelemetry 지표 파이프라인 구성:
```
version: 2
otel-metrics-pipeline:
source:
otel_metrics_source:
path: /otel-metrics-pipeline/v1/metrics
sink:
- opensearch:
hosts: ["https://search-mydomain.region.es.amazonaws.com"]
index: "ss4o_metrics-otel-%{yyyy.MM.dd}"
index_type: custom
aws:
region: "region"
```
OpenTelemetry Traces 파이프라인 구성:
```
version: 2
otel-trace-pipeline:
source:
otel_trace_source:
path: /otel-traces-pipeline/v1/traces
sink:
- opensearch:
hosts: ["https://search-mydomain.region.es.amazonaws.com"]
index: "ss4o_metrics-otel-%{yyyy.MM.dd}"
index_type: custom
aws:
region: "region"
```
사전 구성된 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
## 교차 계정 연결
OpenTelemetry 소스가 있는 OpenSearch Ingestion 파이프라인에는 교차 계정 수집 기능이 있습니다. OpenTelemetry Amazon OpenSearch Ingestion을 사용하면 Virtual Private Cloud(VPC) AWS 계정 에서 별도의 VPC의 파이프라인 엔드포인트로 파이프라인을 공유할 수 있습니다. 자세한 내용은 [교차 계정 수집을 위한 OpenSearch Ingestion 파이프라인 구성](cross-account-pipelines.md) 단원을 참조하십시오.
## 제한 사항
OpenSearch Ingestion 파이프라인은 20mb를 초과하는 요청을 수신할 수 없습니다. 이 값은 `max_request_length` 옵션에서 사용자가 구성합니다. 이 옵션은 기본적으로 10mb입니다.
## OpenTelemetry 소스에 권장되는 CloudWatch 경보
수집 파이프라인의 성능을 모니터링하려면 다음 CloudWatch 지표가 권장됩니다. 이러한 지표는 내보내기에서 처리된 데이터의 양, 스트림에서 처리된 이벤트의 양, 내보내기 및 스트림 이벤트 처리 오류, 대상에 쓴 문서 수를 식별하는 데 도움이 될 수 있습니다. 이러한 지표 중 하나가 지정된 시간 동안 지정된 값을 초과하면 작업을 수행하도록 CloudWatch 경보를 설정할 수 있습니다.
OTLP 소스에 대한 CloudWatch 지표는 형식으로 지정됩니다`{pipeline-name}.otlp.{logs | traces | metrics}.{metric-name}`. 예를 들어 `otel-pipeline.otlp.metrics.requestTimeouts.count`입니다.
개별 OpenTelemetry 소스를 사용하는 경우 지표는 형식으로 지정됩니다`{pipeline-name}.{source-name}.{metric-name}`. 예를 들어 `trace-pipeline.otel_trace_source.requestTimeouts.count`입니다.
세 OpenTelemetry 데이터 형식은 모두 동일한 지표를 가지지만 간결하게 설명하면 지표는 OTLP 소스 로그 형식 데이터에 대한 아래 표에만 나열됩니다.
| 지표 | 설명 |
| --- |--- |
| otel-pipeline.BlockingBuffer.bufferUsage.value | 사용 중인 버퍼의 양을 나타냅니다. |
| otel-pipeline.otlp.logs.requestTimeouts.count | 시간 초과된 요청 수입니다. |
| otel-pipeline.otlp.logs.requestsReceived.count | OpenTelemetry Collector에서 수신한 요청 수입니다. |
| otel-pipeline.otlp.logs.badRequests.count | OpenTelemetry Collector에서 수신한 잘못된 형식의 요청 수입니다. |
| otel-pipeline.otlp.logs.requestsTooLarge.count | OpenTelemetry Collector에서 수신한 최대 20mb보다 큰 요청 수입니다. |
| otel-pipeline.otlp.logs.internalServerError.count | The number of HTTP 500 errors received from the OpenTelemetry Collector. |
| otel-pipeline.opensearch.bulkBadRequestErrors.count | Count of errors during bulk requests due to malformed request. |
| otel-pipeline.opensearch.bulkRequestLatency.avg | Average latency for bulk write requests made to OpenSearch. |
| otel-pipeline.opensearch.bulkRequestNotFoundErrors.count | Number of bulk requests that failed because the target data could not be found. |
| otel-pipeline.opensearch.bulkRequestNumberOfRetries.count | Number of retries by OpenSearch Ingestion pipelines to write OpenSearch cluster. |
| otel-pipeline.opensearch.bulkRequestSizeBytes.sum | Total size in bytes of all bulk requests made to OpenSearch. |
| otel-pipeline.opensearch.documentErrors.count | Number of errors when sending documents to OpenSearch. The documents causing the errors witll be sent to DLQ. |
| otel-pipeline.opensearch.documentsSuccess.count | Number of documents successfully written to an OpenSearch cluster or collection. |
| otel-pipeline.opensearch.documentsSuccessFirstAttempt.count | Number of documents successfully indexed in OpenSearch on the first attempt. |
| `otel-pipeline.opensearch.documentsVersionConflictErrors.count` | Count of errors due to version conflicts in documents during processing. |
| `otel-pipeline.opensearch.PipelineLatency.avg` | Average latency of OpenSearch Ingestion pipeline to process the data by reading from the source to writing to the destination. |
| otel-pipeline.opensearch.PipelineLatency.max | Maximum latency of OpenSearch Ingestion pipeline to process the data by reading from the source to writing the destination. |
| otel-pipeline.opensearch.recordsIn.count | Count of records successfully ingested into OpenSearch. This metric is essential for tracking the volume of data being processed and stored. |
| otel-pipeline.opensearch.s3.dlqS3RecordsFailed.count | Number of records that failed to write to DLQ. |
| otel-pipeline.opensearch.s3.dlqS3RecordsSuccess.count | Number of records that are written to DLQ. |
| otel-pipeline.opensearch.s3.dlqS3RequestLatency.count | Count of latency measurements for requests to the Amazon S3 dead-letter queue. |
| otel-pipeline.opensearch.s3.dlqS3RequestLatency.sum | Total latency for all requests to the Amazon S3 dead-letter queue |
| otel-pipeline.opensearch.s3.dlqS3RequestSizeBytes.sum | Total size in bytes of all requests made to the Amazon S3 dead-letter queue. |
| otel-pipeline.recordsProcessed.count | Total number of records processed in the pipeline, a key metric for overal throughput. |
| `otel-pipeline.opensearch.bulkRequestInvalidInputErrors.count` | Count of bulk request errors in OpenSearch due to invalid input, crucial for monitoring data quality and operational issues. |
# Amazon Managed Service for Prometheus에서 OpenSearch Ingestion 파이프라인 사용
Amazon Managed Service for Prometheus를 OpenSearch Ingestion 파이프라인의 대상으로 사용하여 지표를 시계열 형식으로 저장할 수 있습니다. Prometheus 싱크를 사용하면 파이프라인의 OpenTelemetry 지표 또는 기타 시계열 데이터를 모니터링, 알림 및 분석을 위해 Amazon Managed Service for Prometheus 워크스페이스로 전송할 수 있습니다.
`prometheus` 싱크 플러그인을 사용하면 OpenSearch Ingestion 파이프라인이 Prometheus 원격 쓰기 프로토콜을 사용하여 Amazon Managed Service for Prometheus 워크스페이스에 지표 데이터를 쓸 수 있습니다. 이 통합을 통해 다음을 수행할 수 있습니다.
+ Amazon Managed Service for Prometheus에 시계열 지표 데이터 저장
+ Amazon Managed Service for Prometheus 및 Amazon Managed Grafana를 사용하여 지표 모니터링 및 알림
+ 지표를 여러 대상으로 동시에 라우팅(예: OpenSearch 및 Amazon Managed Service for Prometheus)
+ 외부 에이전트의 OpenTelemetry 지표를 처리하거나 파이프라인 내에서 지표를 생성합니다.
**Topics**
+ [
## 사전 조건
](#prometheus-prereqs)
+ [
## 1단계: 파이프라인 역할 구성
](#prometheus-pipeline-role)
+ [
## 2단계: 파이프라인 생성
](#prometheus-pipeline)
+ [
## 모니터링 및 문제 해결
](#prometheus-monitoring)
+ [
## 제한 사항
](#prometheus-limitations)
+ [
## 모범 사례
](#prometheus-best-practices)
## 사전 조건
Prometheus 싱크를 구성하기 전에 다음이 있는지 확인합니다.
+ **Amazon Managed Service for Prometheus 워크**스페이스: OpenSearch Ingestion 파이프라인 AWS 리전 과 동일한 AWS 계정 및에 워크스페이스를 생성합니다. 지침은 *Amazon Managed Service for Prometheus 사용 설명서*의 [워크스페이스 생성을](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-onboard-create-workspace.html) 참조하세요.
+ **IAM 권한**: Amazon Managed Service for Prometheus에 쓸 수 있는 권한이 있는 IAM 역할을 구성합니다. 자세한 내용은 [1단계: 파이프라인 역할 구성](#prometheus-pipeline-role) 단원을 참조하십시오.
**참고**
Amazon Managed Service for Prometheus 워크스페이스는 AWS 서비스 관리형 AWS KMS 키를 사용해야 합니다. 고객 관리형 AWS KMS 키는 현재 OpenSearch Ingestion 파이프라인의 Amazon Managed Service for Prometheus 싱크에서 지원되지 않습니다.
## 1단계: 파이프라인 역할 구성
Prometheus 싱크는 인증에 대한 [파이프라인 역할의](pipeline-security-overview.md#pipeline-security-sink) IAM 권한을 자동으로 상속하므로 싱크 설정에서 추가 역할 구성(예: `sts_role_arn`)이 필요하지 않습니다.
다음 샘플 정책은 Amazon Managed Service for Prometheus를 싱크로 사용하는 데 필요한 권한을 보여줍니다.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AMPRemoteWrite",
"Effect": "Allow",
"Action": [
"aps:RemoteWrite"
],
"Resource": "arn:aws:aps:region:account-id:workspace/workspace-id"
}
]
}
```
다음과 같이 자리 표시자를 바꿉니다.
+ `region`: ( AWS 리전 예: `us-east-1`)
+ `account-id`: ID AWS 계정
+ `workspace-id`: Amazon Managed Service for Prometheus 워크스페이스 ID
파이프라인 역할에 이러한 권한을 연결해야 합니다.
파이프라인 역할에 OpenSearch Ingestion이 이를 수임할 수 있는 신뢰 관계가 있는지 확인합니다.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "osis-pipelines.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
## 2단계: 파이프라인 생성
권한을 설정한 후 Amazon Managed Service for Prometheus를 싱크로 사용하도록 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
### 기본 구성
다음 예제에서는 최소 Prometheus 싱크 구성을 보여줍니다.
```
version: "2"
sink:
- prometheus:
url: "https://aps-workspaces.region.amazonaws.com/workspaces/workspace-id/api/v1/remote_write"
aws:
region: "region"
```
`prometheus` 싱크 구성 내에서 Amazon Managed Service for Prometheus 원격 쓰기 엔드포인트인 `url` 옵션을 지정해야 합니다. URL의 형식을 지정하려면 Amazon Managed Service for Prometheus 콘솔에서 워크스페이스 ID를 찾고 다음과 같이 URL을 구성합니다`https://aps-workspaces.region.amazonaws.com/workspaces/workspace-id/api/v1/remote_write`.
### 구성 옵션
다음 옵션을 사용하여 Prometheus 싱크에 대한 일괄 처리 및 플러시 동작을 구성합니다.
**Prometheus 싱크 구성 옵션**
| 옵션 | 필수 | Type | 설명 |
| --- | --- | --- | --- |
| max\$1events | 아니요 | Integer | Prometheus로 플러시하기 전에 누적할 최대 이벤트 수입니다. 기본값은 1000입니다. |
| max\$1request\$1size | 아니요 | 바이트 수 | 플러시 전 요청 페이로드의 최대 크기입니다. 기본값은 1mb입니다. |
| flush\$1interval | 아니요 | 지속 시간 | 이벤트를 플러시하기 전에 대기하는 최대 시간입니다. 기본값은 10s입니다. 허용되는 최대 값은 입니다60s. |
### 파이프라인 예제
**예제 1: Amazon Managed Service for Prometheus에 대한 OpenTelemetry 지표**
이 파이프라인은 외부 에이전트로부터 OpenTelemetry 지표를 수신하여 Amazon Managed Service for Prometheus에 기록합니다.
```
version: "2"
source:
otel_metrics_source:
path: "/v1/metrics"
output_format: otel
sink:
- prometheus:
url: "https://aps-workspaces.us-east-1.amazonaws.com/workspaces/ws-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/api/v1/remote_write"
aws:
region: "us-east-1"
```
**예제 2: 듀얼 싱크 - OpenSearch 및 Amazon Managed Service for Prometheus**
이 파이프라인은 OpenSearch와 Amazon Managed Service for Prometheus 모두에 지표를 라우팅합니다.
```
version: "2"
source:
otel_metrics_source:
path: "/v1/metrics"
output_format: otel
sink:
- opensearch:
hosts:
- "https://search-domain-endpoint.us-east-1.es.amazonaws.com"
index: "metrics-%{yyyy.MM.dd}"
aws:
region: "us-east-1"
sts_role_arn: "arn:aws:iam::123456789012:role/OSI-Pipeline-Role"
- prometheus:
url: "https://aps-workspaces.us-east-1.amazonaws.com/workspaces/ws-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/api/v1/remote_write"
aws:
region: "us-east-1"
```
**예제 3: 필터링이 포함된 지표**
이 파이프라인은 Amazon Managed Service for Prometheus로 전송하기 전에 지표를 필터링합니다.
```
version: "2"
source:
otel_metrics_source:
path: "/v1/metrics"
output_format: otel
processor:
- drop_events:
drop_when: '/name != "http.server.duration" and /name != "http.client.duration"'
sink:
- prometheus:
url: "https://aps-workspaces.us-east-1.amazonaws.com/workspaces/ws-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/api/v1/remote_write"
aws:
region: "us-east-1"
```
사전 구성된 Amazon Managed Service for Prometheus 블루프린트를 사용하여 이러한 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
### Amazon Managed Service for Prometheus 싱크를 사용하여 파이프라인 생성
#### AWS 콘솔 사용
1. OpenSearch Service 콘솔로 이동합니다.
1. **수집**에서 **파이프라인**을 선택합니다.
1. [**파이프라인 생성**]을 선택합니다.
1. **블루프린트를 사용하여 빌드**를 선택하고 **Amazon Prometheus 블루프린트에 대한 OpenTelemetry 지표**를 선택합니다.
1. 파이프라인을 구성합니다.
+ Amazon Managed Service for Prometheus 워크스페이스 ID 입력
+ 파이프라인 역할 ARN 지정
+ 필요에 따라 소스 및 프로세서 설정 구성
1. 파이프라인을 검토하고 생성합니다.
#### AWS CLI 사용
원하는 구성으로 파이프라인 구성 파일(예: `amp-pipeline.yaml`)을 생성한 다음 다음을 실행합니다.
```
aws osis create-pipeline \
--pipeline-name my-amp-pipeline \
--min-units 2 \
--max-units 4 \
--pipeline-configuration-body file://amp-pipeline.yaml
```
#### 사용 AWS CloudFormation
```
Resources:
MyAMPPipeline:
Type: AWS::OSIS::Pipeline
Properties:
PipelineName: my-amp-pipeline
MinUnits: 2
MaxUnits: 4
PipelineConfigurationBody: |
version: "2"
source:
otel_metrics_source:
path: "/v1/metrics"
output_format: otel
sink:
- prometheus:
url: "https://aps-workspaces.us-east-1.amazonaws.com/workspaces/ws-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/api/v1/remote_write"
aws:
region: "us-east-1"
```
## 모니터링 및 문제 해결
### CloudWatch 지표
CloudWatch 지표를 사용하여 파이프라인의 성능을 모니터링합니다.
+ `DocumentsWritten`: Amazon Managed Service for Prometheus에 성공적으로 기록된 지표 수
+ `DocumentsWriteFailed`: 쓰기에 실패한 지표 수
+ `RequestLatency`: 원격 쓰기 요청의 지연 시간
### 일반적인 문제
**문제**: 파이프라인이 Amazon Managed Service for Prometheus에 쓰지 못함
**솔루션:**
+ URL의 워크스페이스 ID 및 리전이 올바른지 확인
+ 파이프라인 역할에 `aps:RemoteWrite` 권한이 있는지 확인합니다.
+ 워크스페이스가 서비스 관리형 AWS KMS 키를 사용하는지 확인
+ 파이프라인과 워크스페이스가 동일한지 확인 AWS 계정
**문제**: 인증 오류
**솔루션:**
+ 신뢰 관계가이 파이프라인 역할을 수임`osis-pipelines.amazonaws.com`하도록 허용하는지 확인
+ 파이프라인 역할에 필요한 `aps:RemoteWrite` 권한이 있는지 확인합니다.
**문제**: 높은 지연 시간 또는 제한
**솔루션:**
+ 파이프라인 용량 단위 증가
+ 프로세서에서 일괄 처리 구현
+ Amazon Managed Service for Prometheus 서비스 할당량 검토
## 제한 사항
Amazon Managed Service for Prometheus용 OpenSearch Ingestion 파이프라인을 설정할 때 다음 제한 사항을 고려하세요.
+ Amazon Managed Service for Prometheus 워크스페이스는 서비스 관리형 AWS KMS 키를 사용해야 AWS 합니다. 고객 관리형 AWS KMS 키는 현재 지원되지 않습니다.
+ 파이프라인과 Amazon Managed Service for Prometheus 워크스페이스는 동일한에 있어야 합니다 AWS 계정.
## 모범 사례
+ **동일한 IAM 역할 사용**: Prometheus 싱크는 파이프라인 역할을 자동으로 사용합니다. 다른 싱크를 사용하는 경우 `sts_role_arn`가 파이프라인 역할과 동일한지 확인합니다.
+ **지표 모니터링**: 실패한 쓰기 및 긴 지연 시간에 대한 CloudWatch 경보 설정
+ **필터링 구현**: Amazon Managed Service for Prometheus로 전송하기 전에 프로세서를 사용하여 불필요한 지표 필터링
+ **적절한 크기 용량**: 최소 용량으로 시작하고 지표 볼륨에 따라 확장
+ **블루프린트 사용**: 일반적인 사용 사례에 대해 사전 구성된 블루프린트 활용
# Kafka에서 OpenSearch Ingestion 파이프라인 사용
[Kafka](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/kafka/) 플러그인을 사용하여 자체 관리형 Kafka 클러스터의 데이터를 Amazon OpenSearch Service 도메인 및 OpenSearch Serverless 컬렉션으로 스트리밍할 수 있습니다. OpenSearch Ingestion은 퍼블릭 또는 프라이빗(VPC) 네트워킹으로 구성된 Kafka 클러스터의 연결을 지원합니다. 이 주제에서는 상호 TLS(mTLS), SASL/SCRAM 또는 IAM과 같은 네트워크 설정 및 인증 방법 구성을 비롯하여, 수집 파이프라인을 설정하기 위한 사전 조건과 단계를 간략하게 설명합니다.
## 퍼블릭 Kafka 클러스터에서 데이터 마이그레이션
OpenSearch Ingestion 파이프라인을 사용하여 자체 관리형 퍼블릭 Kafka 클러스터에서 데이터를 마이그레이션할 수 있습니다. 즉, 도메인 DNS 이름을 공개적으로 확인할 수 있습니다. 이렇게 하려면 자체 관리형 Kafka를 소스로, OpenSearch Service 또는 OpenSearch Serverless를 대상으로 하는 OpenSearch Ingestion 파이프라인을 설정합니다. 이렇게 하면 자체 관리형 소스 클러스터에서 AWS관리형 대상 도메인 또는 컬렉션으로 스트리밍 데이터가 처리됩니다.
### 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. 퍼블릭 네트워크 구성을 사용하여 자체 관리형 Kafka 클러스터를 생성합니다. 클러스터에는 OpenSearch Service로 수집할 데이터가 포함되어 있어야 합니다.
1. 데이터를 마이그레이션할 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](createupdatedomains.md#createdomains) 및 [컬렉션 생성](serverless-create.md) 섹션을 참조하세요.
1. 를 사용하여 자체 관리형 클러스터에 인증을 설정합니다 AWS Secrets Manager. [AWS Secrets Manager 시크릿 교체](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)의 단계를 수행하여 시크릿 교체를 활성화합니다.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 자체 관리형 클러스터의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
다음 샘플 도메인 액세스 정책은 다음 단계에서 생성하는 파이프라인 역할을 사용하여 도메인에 데이터를 쓰도록 허용합니다. 자체 ARN으로 `resource`을 업데이트해야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:role/pipeline-role"
},
"Action": [
"es:DescribeDomain",
"es:ESHttp*"
],
"Resource": [
"arn:aws:es:us-east-1:111122223333:domain/domain-name"
]
}
]
}
```
------
컬렉션 또는 도메인에 쓰기 데이터에 액세스할 수 있는 올바른 권한이 있는 IAM 역할을 생성하려면 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md)을 참조하세요.
### 1단계: 파이프라인 역할 구성
Kafka 파이프라인 사전 조건을 설정한 후 파이프라인 구성에 사용할 [파이프라인 역할을 구성](pipeline-security-overview.md#pipeline-security-sink)하고 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션에 쓸 수 있는 권한과 Secrets Manager에서 시크릿을 읽을 수 있는 권한을 추가합니다.
### 2단계: 파이프라인 생성
이제 Kafka를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
여러 OpenSearch Service 도메인을 데이터의 대상으로 지정할 수 있습니다. 이 기능을 사용하여 조건부로 라우팅하거나 수신 데이터를 여러 OpenSearch Service 도메인으로 복제할 수 있습니다.
소스 Confluent Kafka의 데이터를 OpenSearch Serverless VPC 컬렉션으로 마이그레이션할 수도 있습니다. 파이프라인 구성 내에서 네트워크 액세스 정책을 제공해야 합니다. Confluent 스키마 레지스트리를 사용하여 Confluent 스키마를 정의할 수 있습니다.
```
version: "2"
kafka-pipeline:
source:
kafka:
encryption:
type: "ssl"
topics:
- name: "topic-name"
group_id: "group-id"
bootstrap_servers:
- "bootstrap-server.us-east-1.aws.private.confluent.cloud:9092"
authentication:
sasl:
plain:
username: ${aws_secrets:confluent-kafka-secret:username}
password: ${aws_secrets:confluent-kafka-secret:password}
schema:
type: confluent
registry_url: https://my-registry.us-east-1.aws.confluent.cloud
api_key: "${{aws_secrets:schema-secret:schema_registry_api_key}}"
api_secret: "${{aws_secrets:schema-secret:schema_registry_api_secret}}"
basic_auth_credentials_source: "USER_INFO"
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
aws:
region: "us-east-1"
index: "confluent-index"
extension:
aws:
secrets:
confluent-kafka-secret:
secret_id: "my-kafka-secret"
region: "us-east-1"
schema-secret:
secret_id: "my-self-managed-kafka-schema"
region: "us-east-1"
```
사전 구성된 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
### VPC의 Kafka 클러스터에서 데이터 마이그레이션
OpenSearch Ingestion 파이프라인을 사용하여 VPC에서 실행되는 자체 관리형 Kafka 클러스터에서 데이터를 마이그레이션할 수도 있습니다. 이렇게 하려면 자체 관리형 Kafka를 소스로, OpenSearch Service 또는 OpenSearch Serverless를 대상으로 하는 OpenSearch Ingestion 파이프라인을 설정합니다. 이렇게 하면 자체 관리형 소스 클러스터에서 AWS관리형 대상 도메인 또는 컬렉션으로 스트리밍 데이터가 처리됩니다.
#### 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. OpenSearch Service로 수집하려는 데이터가 포함된 VPC 네트워크 구성을 사용하여 자체 관리형 Kafka 클러스터를 생성합니다.
1. 데이터를 마이그레이션할 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html#createdomains) 및 [컬렉션 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-manage.html#serverless-create)을 참조하세요.
1. 를 사용하여 자체 관리형 클러스터에 인증을 설정합니다 AWS Secrets Manager. [AWS Secrets Manager 시크릿 교체](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)의 단계를 수행하여 시크릿 교체를 활성화합니다.
1. 자체 관리형 Kafka에 대한 액세스 권한을 보유한 VPC의 ID를 가져옵니다. OpenSearch Ingestion에서 사용할 VPC CIDR을 선택합니다.
**참고**
를 사용하여 파이프라인 AWS Management Console 을 생성하는 경우 자체 관리형 Kafka를 사용하려면 OpenSearch Ingestion 파이프라인도 VPC에 연결해야 합니다. 이를 수행하려면 **네트워크 구성** 섹션을 찾아 **VPC에 연결** 확인란을 선택하고 제공된 기본 옵션 중 하나에서 CIDR을 선택하거나 직접 선택합니다. [RFC 1918 Best Current Practice](https://datatracker.ietf.org/doc/html/rfc1918)에 정의된 대로 프라이빗 주소 공간에서 모든 CIDR을 사용할 수 있습니다.
사용자 지정 CIDR을 제공하려면 드롭다운 메뉴에서 **기타**를 선택합니다. OpenSearch Ingestion과 자체 관리형 OpenSearch 간의 IP 주소 충돌을 방지하려면 자체 관리형 OpenSearch VPC CIDR이 OpenSearch Ingestion의 CIDR과 달라야 합니다.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 자체 관리형 클러스터의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
다음 샘플 도메인 액세스 정책은 다음 단계에서 생성하는 파이프라인 역할을 사용하여 도메인에 데이터를 쓰도록 허용합니다. 자체 ARN으로 `resource`을 업데이트해야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:role/pipeline-role"
},
"Action": [
"es:DescribeDomain",
"es:ESHttp*"
],
"Resource": [
"arn:aws:es:us-east-1:111122223333:domain/domain-name"
]
}
]
}
```
------
컬렉션 또는 도메인에 쓰기 데이터에 액세스할 수 있는 올바른 권한이 있는 IAM 역할을 생성하려면 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md)을 참조하세요.
#### 1단계: 파이프라인 역할 구성
파이프라인 사전 조건을 설정한 후 파이프라인 구성에서 사용하려는 [파이프라인 역할을 구성](pipeline-security-overview.md#pipeline-security-sink)하고 역할에서 다음 권한을 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerReadAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": ["arn:aws:secretsmanager:us-east-1:111122223333:secret:secret-name"]
},
{
"Effect": "Allow",
"Action": [
"ec2:AttachNetworkInterface",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DetachNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"arn:aws:ec2:*:*:network-interface/*",
"arn:aws:ec2:*:*:subnet/*",
"arn:aws:ec2:*:*:security-group/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeDhcpOptions",
"ec2:DescribeRouteTables",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:Describe*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:*:network-interface/*",
"Condition": {
"StringEquals":
{
"aws:RequestTag/OSISManaged": "true"
}
}
}
]
}
```
------
파이프라인은 이러한 권한을 사용하여 VPC에서 네트워크 인터페이스를 생성하고 삭제하므로 OpenSearch Ingestion 파이프라인을 생성하는 데 사용하는 IAM 역할에서 위의 Amazon EC2 권한을 제공해야 합니다. 파이프라인은 오직 이 네트워크 인터페이스를 통해 Kafka 클러스터에 액세스할 수 있습니다.
#### 2단계: 파이프라인 생성
이제 Kafka를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
여러 OpenSearch Service 도메인을 데이터의 대상으로 지정할 수 있습니다. 이 기능을 사용하여 조건부로 라우팅하거나 수신 데이터를 여러 OpenSearch Service 도메인으로 복제할 수 있습니다.
소스 Confluent Kafka의 데이터를 OpenSearch Serverless VPC 컬렉션으로 마이그레이션할 수도 있습니다. 파이프라인 구성 내에서 네트워크 액세스 정책을 제공해야 합니다. Confluent 스키마 레지스트리를 사용하여 Confluent 스키마를 정의할 수 있습니다.
```
version: "2"
kafka-pipeline:
source:
kafka:
encryption:
type: "ssl"
topics:
- name: "topic-name"
group_id: "group-id"
bootstrap_servers:
- "bootstrap-server.us-east-1.aws.private.confluent.cloud:9092"
authentication:
sasl:
plain:
username: ${aws_secrets:confluent-kafka-secret:username}
password: ${aws_secrets:confluent-kafka-secret:password}
schema:
type: confluent
registry_url: https://my-registry.us-east-1.aws.confluent.cloud
api_key: "${{aws_secrets:schema-secret:schema_registry_api_key}}"
api_secret: "${{aws_secrets:schema-secret:schema_registry_api_secret}}"
basic_auth_credentials_source: "USER_INFO"
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
aws:
region: "us-east-1"
index: "confluent-index"
extension:
aws:
secrets:
confluent-kafka-secret:
secret_id: "my-kafka-secret"
region: "us-east-1"
schema-secret:
secret_id: "my-self-managed-kafka-schema"
region: "us-east-1"
```
사전 구성된 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
# Amazon OpenSearch Ingestion을 사용하여 자체 관리 OpenSearch 클러스터에서 데이터 마이그레이션
자체 관리형 Amazon OpenSearch 또는 Elasticsearch에서 OpenSearch Ingestion 파이프라인을 사용하여 Amazon OpenSearch Service 도메인 또는 OpenSearch Serverless VPC 컬렉션으로 데이터를 마이그레이션할 수 있습니다. OpenSearch Ingestion은 자체 관리형 OpenSearch 및 Elasticsearch에서 데이터를 마이그레이션하기 위해 퍼블릭 및 프라이빗 네트워크 구성을 모두 지원합니다.
## 퍼블릭 OpenSearch 클러스터에서 마이그레이션
OpenSearch Ingestion 파이프라인을 사용하여 퍼블릭 구성을 통해 자체 관리형 OpenSearch 또는 Elasticsearch 클러스터에서 데이터를 마이그레이션할 수 있습니다. 즉, 도메인 DNS 이름을 공개적으로 확인할 수 있습니다. 이렇게 하려면 자체 관리형 OpenSearch 또는 Elasticsearch를 소스로, OpenSearch Service 또는 OpenSearch Serverless를 대상으로 하는 OpenSearch Ingestion 파이프라인을 설정합니다. 이렇게 하면 자체 관리형 소스 클러스터에서 AWS관리형 대상 도메인 또는 컬렉션으로 데이터를 효과적으로 마이그레이션할 수 있습니다.
### 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. 퍼블릭 DNS 이름을 마이그레이션하고 구성하려는 데이터가 포함된 자체 관리형 OpenSearch 또는 Elastisearch 클러스터를 생성합니다. 지침은 OpenSearch 설명서의 [클러스터 생성](https://opensearch.org/docs/latest/tuning-your-cluster/)을 참조하세요.
1. 데이터를 마이그레이션할 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](createupdatedomains.md#createdomains) 및 [컬렉션 생성](serverless-create.md) 섹션을 참조하세요.
1. 를 사용하여 자체 관리형 클러스터에 인증을 설정합니다 AWS Secrets Manager. [AWS Secrets Manager 시크릿 교체](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)의 단계를 수행하여 시크릿 교체를 활성화합니다.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 자체 관리형 클러스터의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
다음 샘플 도메인 액세스 정책은 다음 단계에서 생성하는 파이프라인 역할을 사용하여 도메인에 데이터를 쓰도록 허용합니다. 자체 ARN으로 `resource`을 업데이트해야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:role/pipeline-role"
},
"Action": [
"es:DescribeDomain",
"es:ESHttp*"
],
"Resource": [
"arn:aws:es:us-east-1:111122223333:domain/domain-name"
]
}
]
}
```
------
컬렉션 또는 도메인에 쓰기 데이터에 액세스할 수 있는 올바른 권한이 있는 IAM 역할을 생성하려면 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md)을 참조하세요.
### 1단계: 파이프라인 역할 구성
OpenSearch 파이프라인 사전 조건을 설정한 후 파이프라인 구성에 사용할 [파이프라인 역할을 구성](pipeline-security-overview.md#pipeline-security-sink)하고 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션에 쓸 수 있는 권한과 Secrets Manager에서 시크릿을 읽을 수 있는 권한을 추가합니다.
### 2단계: 파이프라인 생성
이제 OpenSearch를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
여러 OpenSearch Service 도메인을 데이터의 대상으로 지정할 수 있습니다. 이 기능을 사용하여 조건부로 라우팅하거나 수신 데이터를 여러 OpenSearch Service 도메인으로 복제할 수 있습니다.
소스 OpenSearch 또는 Elasticsearch 클러스터의 데이터를 OpenSearch Serverless VPC 컬렉션으로 마이그레이션할 수도 있습니다. 파이프라인 구성 내에서 네트워크 액세스 정책을 제공해야 합니다.
```
version: "2"
opensearch-migration-pipeline:
source:
opensearch:
acknowledgments: true
host: [ "https://my-self-managed-cluster-name:9200" ]
indices:
include:
- index_name_regex: "include-.*"
exclude:
- index_name_regex: '\..*'
authentication:
username: ${aws_secrets:secret:username}
password: ${aws_secrets:secret:password}
scheduling:
interval: "PT2H"
index_read_count: 3
start_time: "2023-06-02T22:01:30.00Z"
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
aws:
region: "us-east-1"
#Uncomment the following lines if your destination is an OpenSearch Serverless collection
#serverless: true
# serverless_options:
# network_policy_name: "network-policy-name"
index: "${getMetadata(\"opensearch-index\")}"
document_id: "${getMetadata(\"opensearch-document_id\")}"
enable_request_compression: true
dlq:
s3:
bucket: "bucket-name"
key_path_prefix: "apache-log-pipeline/logs/dlq"
region: "us-east-1"
extension:
aws:
secrets:
secret:
secret_id: "my-opensearch-secret"
region: "us-east-1"
refresh_interval: PT1H
```
사전 구성된 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
## VPC의 OpenSearch 클러스터에서 데이터 마이그레이션
OpenSearch Ingestion 파이프라인을 사용하여 VPC에서 실행되는 자체 관리형 OpenSearch 또는 Elasticsearch 클러스터에서 데이터를 마이그레이션할 수도 있습니다. 이렇게 하려면 자체 관리형 OpenSearch 또는 Elasticsearch를 소스로, OpenSearch Service 또는 OpenSearch Serverless를 대상으로 하는 OpenSearch Ingestion 파이프라인을 설정합니다. 이렇게 하면 자체 관리형 소스 클러스터에서 AWS관리형 대상 도메인 또는 컬렉션으로 데이터를 효과적으로 마이그레이션할 수 있습니다.
### 사전 조건
OpenSearch Ingestion 파이프라인을 생성하기 전에 다음 단계를 수행하세요.
1. 마이그레이션하려는 데이터가 포함된 VPC 네트워크 구성을 사용하여 자체 관리형 OpenSearch 또는 Elastisearch 클러스터를 생성합니다.
1. 데이터를 마이그레이션할 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 생성합니다. 자세한 내용은 [OpenSearch Service 도메인 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html#createdomains) 및 [컬렉션 생성](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-manage.html#serverless-create)을 참조하세요.
1. 를 사용하여 자체 관리형 클러스터에 인증을 설정합니다 AWS Secrets Manager. [AWS Secrets Manager 시크릿 교체](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)의 단계를 수행하여 시크릿 교체를 활성화합니다.
1. 자체 관리형 OpenSearch 또는 Elasticsearch에 대한 액세스 권한을 보유한 VPC의 ID를 가져옵니다. OpenSearch Ingestion에서 사용할 VPC CIDR을 선택합니다.
**참고**
를 사용하여 파이프라인 AWS Management Console 을 생성하는 경우 자체 관리형 OpenSearch 또는 Elasticsearch를 사용하려면 OpenSearch Ingestion 파이프라인도 VPC에 연결해야 합니다. 이를 수행하려면 **소스 네트워크 옵션** 섹션을 찾아 **VPC에 연결** 확인란을 선택하고 제공된 기본 옵션 중 하나에서 CIDR을 선택합니다. [RFC 1918 Best Current Practice](https://datatracker.ietf.org/doc/html/rfc1918)에 정의된 대로 프라이빗 주소 공간에서 모든 CIDR을 사용할 수 있습니다.
사용자 지정 CIDR을 제공하려면 드롭다운 메뉴에서 **기타**를 선택합니다. OpenSearch Ingestion과 자체 관리형 OpenSearch 간의 IP 주소 충돌을 방지하려면 자체 관리형 OpenSearch VPC CIDR이 OpenSearch Ingestion의 CIDR과 달라야 합니다.
1. [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 도메인에 연결하거나 [데이터 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)을 컬렉션에 연결합니다. 이러한 액세스 정책을 통해 OpenSearch Ingestion은 자체 관리형 클러스터의 데이터를 도메인 또는 컬렉션에 쓸 수 있습니다.
다음 샘플 도메인 액세스 정책은 다음 단계에서 생성하는 파이프라인 역할을 사용하여 도메인에 데이터를 쓰도록 허용합니다. 자체 ARN으로 `resource`을 업데이트해야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:role/pipeline-role"
},
"Action": [
"es:DescribeDomain",
"es:ESHttp*"
],
"Resource": [
"arn:aws:es:us-east-1:111122223333:domain/example.com"
]
}
]
}
```
------
컬렉션 또는 도메인에 쓰기 데이터에 액세스할 수 있는 올바른 권한이 있는 IAM 역할을 생성하려면 [Amazon OpenSearch Ingestion 내 역할 및 사용자 설정](pipeline-security-overview.md)을 참조하세요.
### 1단계: 파이프라인 역할 구성
파이프라인 사전 조건을 설정한 후 파이프라인 구성에서 사용하려는 [파이프라인 역할을 구성](pipeline-security-overview.md#pipeline-security-sink)하고 역할에서 다음 권한을 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerReadAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": ["arn:aws:secretsmanager:us-east-1:111122223333:secret:secret-name"]
},
{
"Effect": "Allow",
"Action": [
"ec2:AttachNetworkInterface",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DetachNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"arn:aws:ec2:*:*:network-interface/*",
"arn:aws:ec2:*:*:subnet/*",
"arn:aws:ec2:*:*:security-group/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeDhcpOptions",
"ec2:DescribeRouteTables",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:Describe*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:*:network-interface/*",
"Condition": {
"StringEquals":
{
"aws:RequestTag/OSISManaged": "true"
}
}
}
]
}
```
------
파이프라인은 이러한 권한을 사용하여 VPC에서 네트워크 인터페이스를 생성하고 삭제하므로 OpenSearch Ingestion 파이프라인을 생성하는 데 사용하는 IAM 역할에서 위의 Amazon EC2 권한을 제공해야 합니다. 파이프라인은 오직 이 네트워크 인터페이스를 통해 OpenSearch 클러스터에 액세스할 수 있습니다.
### 2단계: 파이프라인 생성
이제 OpenSearch를 소스로 지정하는 다음과 같은 OpenSearch Ingestion 파이프라인을 구성할 수 있습니다.
여러 OpenSearch Service 도메인을 데이터의 대상으로 지정할 수 있습니다. 이 기능을 사용하여 조건부로 라우팅하거나 수신 데이터를 여러 OpenSearch Service 도메인으로 복제할 수 있습니다.
소스 OpenSearch 또는 Elasticsearch 클러스터의 데이터를 OpenSearch Serverless VPC 컬렉션으로 마이그레이션할 수도 있습니다. 파이프라인 구성 내에서 네트워크 액세스 정책을 제공해야 합니다.
```
version: "2"
opensearch-migration-pipeline:
source:
opensearch:
acknowledgments: true
host: [ "https://my-self-managed-cluster-name:9200" ]
indices:
include:
- index_name_regex: "include-.*"
exclude:
- index_name_regex: '\..*'
authentication:
username: ${aws_secrets:secret:username}
password: ${aws_secrets:secret:password}
scheduling:
interval: "PT2H"
index_read_count: 3
start_time: "2023-06-02T22:01:30.00Z"
sink:
- opensearch:
hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"]
aws:
region: "us-east-1"
#Uncomment the following lines if your destination is an OpenSearch Serverless collection
#serverless: true
# serverless_options:
# network_policy_name: "network-policy-name"
index: "${getMetadata(\"opensearch-index\")}"
document_id: "${getMetadata(\"opensearch-document_id\")}"
enable_request_compression: true
dlq:
s3:
bucket: "bucket-name"
key_path_prefix: "apache-log-pipeline/logs/dlq"
region: "us-east-1"
extension:
aws:
secrets:
secret:
secret_id: "my-opensearch-secret"
region: "us-east-1"
refresh_interval: PT1H
```
사전 구성된 블루프린트를 사용하여 이 파이프라인을 생성할 수 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
# Amazon Kinesis Data Streams와 함께 OpenSearch Ingestion 파이프라인 사용
Amazon Kinesis Data Streams와 함께 OpenSearch Ingestion 파이프라인을 사용하여 여러 스트림의 스트림 레코드 데이터를 Amazon OpenSearch Service 도메인 및 컬렉션으로 수집합니다. OpenSearch Ingestion 파이프라인은 스트리밍 수집 인프라를 통합하여 Kinesis에서 스트림 레코드를 짧은 지연 시간으로, 대규모로, 지속적으로 수집할 수 있도록 지원합니다.
**Topics**
+ [
## 소스로서의 Amazon Kinesis Data Streams
](#confluent-cloud-kinesis)
+ [
## 소스로서의 Amazon Kinesis Data Streams 교차 계정
](#kinesis-cross-account-source)
## 소스로서의 Amazon Kinesis Data Streams
다음 절차에서는 Amazon Kinesis Data Streams를 데이터 소스로 사용하는 OpenSearch Ingestion 파이프라인을 설정하는 방법을 알아봅니다. 이 섹션에서는 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 생성하고, 파이프라인 역할을 구성하고, 파이프라인을 생성하는 단계를 안내하는 등 필요한 사전 조건을 다룹니다.
### 사전 조건
파이프라인을 설정하려면 활성 Kinesis Data Streams가 하나 이상 필요합니다. 이 스트림은 레코드를 수신하거나 다른 소스에서 레코드를 수신할 준비가 되어 있어야 합니다. 자세한 내용은 [OpenSearch Ingestion 개요](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/osis-getting-started-tutorials.html)를 참조하세요.
**파이프라인을 설정하려면**
1.
**OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션 생성**
도메인 또는 컬렉션을 생성하려면 [OpenSearch Ingestion 시작하기](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/osis-getting-started-tutorials.html)를 참조하세요.
컬렉션 또는 도메인에 쓰기 데이터에 액세스할 수 있는 올바른 권한이 있는 IAM 역할을 생성하려면 [리소스 기반 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)을 참조하세요.
1.
**권한을 사용하여 파이프라인 역할 구성**
[파이프라인 구성에 사용할 파이프라인 역할을 설정](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security-overview.html#pipeline-security-sink)하고 다음 권한을 추가합니다. *자리 표시자*를 자신의 정보로 바꿉니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "allowReadFromStream",
"Effect": "Allow",
"Action": [
"kinesis:DescribeStream",
"kinesis:DescribeStreamConsumer",
"kinesis:DescribeStreamSummary",
"kinesis:GetRecords",
"kinesis:GetShardIterator",
"kinesis:ListShards",
"kinesis:ListStreams",
"kinesis:ListStreamConsumers",
"kinesis:RegisterStreamConsumer",
"kinesis:SubscribeToShard"
],
"Resource": [
"arn:aws:kinesis:us-east-1:111122223333:stream/stream-name"
]
}
]
}
```
------
스트림에서 서버 측 암호화가 활성화된 경우 다음 AWS KMS 정책은 레코드를 복호화하도록 허용합니다. *자리 표시자*를 자신의 정보로 바꿉니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "allowDecryptionOfCustomManagedKey",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/key-id"
}
]
}
```
------
파이프라인이 도메인에 데이터를 쓰려면 도메인에 **sts\$1role\$1arn** 파이프라인 역할이 도메인에 액세스할 수 있도록 허용하는 [도메인 수준 액세스 정책](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)이 있어야 합니다.
다음은 이전 단계에서 생성한 파이프라인 역할(`pipeline-role`)을 사용하여 `ingestion-domain` 도메인에 데이터를 쓰도록 허용하는 도메인 액세스 정책의 예입니다. *자리 표시자*를 자신의 정보로 바꿉니다.
```
{
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::your-account-id:role/pipeline-role"
},
"Action": ["es:DescribeDomain", "es:ESHttp*"],
"Resource": "arn:aws:es:AWS 리전:account-id:domain/domain-name/*"
}
]
}
```
1.
**파이프라인 생성**
**Kinesis-data-streams**를 원본으로 지정하는 OpenSearch Ingestion 파이프라인을 구성합니다. OpenSearch Ingestion 콘솔에서 이러한 파이프라인을 생성하는 데 사용 가능한 준비된 블루프린트를 찾을 수 있습니다. (선택 사항)를 사용하여 파이프라인을 생성하려면 "**`AWS-KinesisDataStreamsPipeline`**"라는 블루프린트를 사용할 AWS CLI수 있습니다. *자리 표시자*를 자신의 정보로 바꿉니다.
```
version: "2"
kinesis-pipeline:
source:
kinesis_data_streams:
acknowledgments: true
codec:
# Based on whether kinesis records are aggregated or not, you could choose json, newline or ndjson codec for processing the records.
# JSON codec supports parsing nested CloudWatch Events into individual log entries that will be written as documents into OpenSearch.
# json:
# key_name: "logEvents"
# These keys contain the metadata sent by CloudWatch Subscription Filters
# in addition to the individual log events:
# include_keys: [ 'owner', 'logGroup', 'logStream' ]
newline:
streams:
- stream_name: "stream name"
# Enable this if ingestion should start from the start of the stream.
# initial_position: "EARLIEST"
# checkpoint_interval: "PT5M"
# Compression will always be gzip for CloudWatch, but will vary for other sources:
# compression: "gzip"
- stream_name: "stream name"
# Enable this if ingestion should start from the start of the stream.
# initial_position: "EARLIEST"
# checkpoint_interval: "PT5M"
# Compression will always be gzip for CloudWatch, but will vary for other sources:
# compression: "gzip"
# buffer_timeout: "1s"
# records_to_accumulate: 100
# Change the consumer strategy to "polling". Default consumer strategy will use enhanced "fan-out" supported by KDS.
# consumer_strategy: "polling"
# if consumer strategy is set to "polling", enable the polling config below.
# polling:
# max_polling_records: 100
# idle_time_between_reads: "250ms"
aws:
# Provide the Role ARN with access to Amazon Kinesis Data Streams. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::111122223333:role/Example-Role"
# Provide the AWS 리전 of the Data Stream.
region: "us-east-1"
sink:
- opensearch:
# Provide an Amazon OpenSearch Serverless domain endpoint
hosts: [ "https://search-mydomain-1a2a3a4a5a6a7a8a9a0a9a8a7a.us-east-1.es.amazonaws.com" ]
index: "index_${getMetadata(\"stream_name\")}"
# Ensure adding unique document id as a combination of the metadata attributes available.
document_id: "${getMetadata(\"partition_key\")}_${getMetadata(\"sequence_number\")}_${getMetadata(\"sub_sequence_number\")}"
aws:
# Provide a Role ARN with access to the domain. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::111122223333:role/Example-Role"
# Provide the AWS 리전 of the domain.
region: "us-east-1"
# Enable the 'serverless' flag if the sink is an Amazon OpenSearch Serverless collection
serverless: false
# serverless_options:
# Specify a name here to create or update network policy for the serverless collection
# network_policy_name: "network-policy-name"
# Enable the 'distribution_version' setting if the OpenSearch Serverless domain is of version Elasticsearch 6.x
# distribution_version: "es6"
# Enable and switch the 'enable_request_compression' flag if the default compression setting is changed in the domain. See https://docs.aws.amazon.com/opensearch-service/latest/developerguide/gzip.html
# enable_request_compression: true/false
# Optional: Enable the S3 DLQ to capture any failed requests in an S3 bucket. Delete this entire block if you don't want a DLQ.
dlq:
s3:
# Provide an S3 bucket
bucket: "your-dlq-bucket-name"
# Provide a key path prefix for the failed requests
# key_path_prefix: "kinesis-pipeline/logs/dlq"
# Provide the region of the bucket.
region: "us-east-1"
# Provide a Role ARN with access to the bucket. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::111122223333:role/Example-Role"
```
**구성 옵션**
Kinesis 구성 옵션은 *OpenSearch* 설명서의 [구성 옵션](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/kinesis/#configuration-options)을 참조하세요.
**사용 가능한 메타데이터 속성**
+ **stream\$1name** - 레코드가 수집된 Kinesis Data Streams의 이름
+ **partition\$1key** - 수집 중인 Kinesis Data Streams 레코드의 파티션 키
+ **sequence\$1number** – 수집 중인 Kinesis Data Streams 레코드의 시퀀스 번호
+ **sub\$1sequence\$1number** – 수집 중인 Kinesis Data Streams 레코드의 하위 시퀀스 번호
1.
**(선택 사항) Kinesis Data Streams 파이프라인의 권장 컴퓨팅 유닛(OCU) 구성**
둘 이상의 스트림에서 스트림 레코드를 수집하도록 OpenSearch Kinesis Data Streams 소스 파이프라인을 구성할 수도 있습니다. 수집 속도를 높이려면 추가된 새 스트림당 컴퓨팅 유닛을 추가하는 것이 좋습니다.
### 데이터 일관성
OpenSearch Ingestion은 데이터 내구성을 보장하는 엔드 투 엔드 승인을 지원합니다. 파이프라인은 Kinesis에서 스트림 레코드를 읽을 때 스트림과 연결된 샤드를 기반으로 스트림 레코드를 읽는 작업을 동적으로 분산합니다. 파이프라인은 OpenSearch 도메인이나 컬렉션에서 모든 레코드를 수집한 후 승인을 받으면 스트림을 자동으로 체크포인트합니다. 이렇게 하면 스트림 레코드의 중복 처리가 방지됩니다.
스트림 이름을 기반으로 인덱스를 생성하려면 OpenSearch 싱크 섹션의 인덱스를 **"index\$1\$1\$1getMetadata(\$1"stream\$1name\$1")\$1"**로 정의합니다.
## 소스로서의 Amazon Kinesis Data Streams 교차 계정
OpenSearch Ingestion 파이프라인이 소스로서 다른 계정의 Kinesis Data Streams에 액세스할 수 있도록 Amazon Kinesis Data Streams가 있는 여러 계정에서 액세스 권한을 부여할 수 있습니다. 교차 계정 액세스를 활성화하려면 다음 단계를 수행합니다.
**교차 계정 액세스 구성**
1.
**Kinesis 스트림이 있는 계정에서 리소스 정책 설정**
*자리 표시자*를 자신의 정보로 바꿉니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "StreamReadStatementID",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/Pipeline-Role"
},
"Action": [
"kinesis:DescribeStreamSummary",
"kinesis:GetRecords",
"kinesis:GetShardIterator",
"kinesis:ListShards"
],
"Resource": "arn:aws:kinesis:us-east-1:444455556666:stream/stream-name"
},
{
"Sid": "StreamEFOReadStatementID",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/Pipeline-Role"
},
"Action": [
"kinesis:DescribeStreamSummary",
"kinesis:ListShards"
],
"Resource": "arn:aws:kinesis:us-east-1:444455556666:stream/stream-name/consumer/consumer-name"
}
]
}
```
------
1.
**(선택 사항) 소비자 및 소비자 리소스 정책 설정**
이는 선택적 단계이며 스트림 레코드 읽기에 향상된 팬아웃 소비자 전략을 사용할 계획인 경우에만 필요합니다. 자세한 내용은 [전용 처리량으로 향상된 팬아웃 소비자 개발](https://docs.aws.amazon.com/streams/latest/dev/enhanced-consumers.html)을 참조하세요.
1.
**소비자 설정**
기존 소비자를 재사용하려는 경우 이 단계를 건너뛸 수 있습니다. 자세한 내용은 *Amazon Kinesis Data Streams API 참조*에서 [RegisterStreamConsumer](https://docs.aws.amazon.com/dms/latest/APIReference/API_RegisterStreamConsumer.html)를 참조하세요.
다음 CLI 명령 예에서는 *자리 표시자 값*을 자신의 정보로 바꿉니다.
**Example CLI 명령 예제:**
```
aws kinesis register-stream-consumer \
--stream-arn "arn:aws:kinesis:AWS 리전:account-id:stream/stream-name" \
--consumer-name consumer-name
```
1.
**소비자 리소스 정책 설정**
다음 문에서는 *자리 표시자 값*을 자신의 정보로 바꿉니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ConsumerEFOReadStatementID",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/Pipeline-Role"
},
"Action": [
"kinesis:DescribeStreamConsumer",
"kinesis:SubscribeToShard"
],
"Resource": "arn:aws:kinesis:us-east-1:444455556666:stream/stream-1/consumer/consumer-name"
}
]
}
```
------
1.
**파이프라인 구성**
교차 계정 수집의 경우 각 스트림에 대해 `kinesis_data_streams`에 다음 속성을 추가합니다.
+ `stream_arn` - 스트림이 있는 계정에 속한 스트림의 ARN
+ `consumer_arn` - 선택적 속성으로, 기본 향상된 팬아웃 소비자 전략을 선택한 경우 지정해야 합니다. 이 필드에는 실제 소비자 ARN을 지정합니다. *자리 표시자*를 자신의 정보로 바꿉니다.
```
version: "2"
kinesis-pipeline:
source:
kinesis_data_streams:
acknowledgments: true
codec:
newline:
streams:
- stream_arn: "arn:aws:kinesis:region:stream-account-id:stream/stream-name"
consumer_arn: "consumer arn"
# Enable this if ingestion should start from the start of the stream.
# initial_position: "EARLIEST"
# checkpoint_interval: "PT5M"
- stream_arn: "arn:aws:kinesis:region:stream-account-id:stream/stream-name"
consumer_arn: "consumer arn"
# initial_position: "EARLIEST"
# buffer_timeout: "1s"
# records_to_accumulate: 100
# Enable the consumer strategy to "polling". Default consumer strategy will use enhanced "fan-out" supported by KDS.
# consumer_strategy: "polling"
# if consumer strategy is set to "polling", enable the polling config below.
# polling:
# max_polling_records: 100
# idle_time_between_reads: "250ms"
aws:
# Provide the Role ARN with access to Kinesis. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::111122223333:role/Example-Role"
# Provide the AWS 리전 of the domain.
region: "us-east-1"
sink:
- opensearch:
# Provide an OpenSearch Serverless domain endpoint
hosts: [ "https://search-mydomain-1a2a3a4a5a6a7a8a9a0a9a8a7a.us-east-1.es.amazonaws.com" ]
index: "index_${getMetadata(\"stream_name\")}"
# Mapping for documentid based on partition key, shard sequence number and subsequence number metadata attributes
document_id: "${getMetadata(\"partition_key\")}_${getMetadata(\"sequence_number\")}_${getMetadata(\"sub_sequence_number\")}"
aws:
# Provide a Role ARN with access to the domain. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::111122223333:role/Example-Role"
# Provide the AWS 리전 of the domain.
region: "us-east-1"
# Enable the 'serverless' flag if the sink is an OpenSearch Serverless collection
serverless: false
# serverless_options:
# Specify a name here to create or update network policy for the serverless collection
# network_policy_name: network-policy-name
# Enable the 'distribution_version' setting if the OpenSearch Serverless domain is of version Elasticsearch 6.x
# distribution_version: "es6"
# Enable and switch the 'enable_request_compression' flag if the default compression setting is changed in the domain. See https://docs.aws.amazon.com/opensearch-service/latest/developerguide/gzip.html
# enable_request_compression: true/false
# Optional: Enable the S3 DLQ to capture any failed requests in an S3 bucket. Delete this entire block if you don't want a DLQ.
dlq:
s3:
# Provide an Amazon S3 bucket
bucket: "your-dlq-bucket-name"
# Provide a key path prefix for the failed requests
# key_path_prefix: "alb-access-log-pipeline/logs/dlq"
# Provide the AWS 리전 of the bucket.
region: "us-east-1"
# Provide a Role ARN with access to the bucket. This role should have a trust relationship with osis-pipelines.amazonaws.com
sts_role_arn: "arn:aws:iam::111122223333:role/Example-Role"
```
1.
**OSI 파이프라인 역할 Kinesis Data Streams**
1.
**IAM 정책**
다음 정책을 파이프라인 역할에 추가합니다. *자리 표시자*를 자신의 정보로 바꿉니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesis:DescribeStreamConsumer",
"kinesis:SubscribeToShard"
],
"Resource": [
"arn:aws:kinesis:us-east-1:111122223333:stream/my-stream"
]
},
{
"Sid": "allowReadFromStream",
"Effect": "Allow",
"Action": [
"kinesis:DescribeStream",
"kinesis:DescribeStreamSummary",
"kinesis:GetRecords",
"kinesis:GetShardIterator",
"kinesis:ListShards",
"kinesis:ListStreams",
"kinesis:ListStreamConsumers",
"kinesis:RegisterStreamConsumer"
],
"Resource": [
"arn:aws:kinesis:us-east-1:111122223333:stream/my-stream"
]
}
]
}
```
------
1.
**신뢰 정책**
스트림 계정에서 데이터를 수집하려면 파이프라인 수집 역할과 스트림 계정 간에 신뢰 관계를 설정해야 합니다. 파이프라인 역할에 다음을 추가합니다. *자리 표시자*를 자신의 정보로 바꿉니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
},
"Action": "sts:AssumeRole"
}]
}
```
------
## 다음 단계
데이터를 파이프라인으로 내보낸 후 파이프라인의 싱크로 구성된 OpenSearch Service 도메인에서 [데이터를 쿼리](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/searching.html)할 수 있습니다. 다음 리소스는 시작하는 데 도움이 됩니다.
+ [Amazon OpenSearch Service의 Observability](observability.md)
+ [트레이스 검색](observability-analyze-traces.md)
+ [Amazon OpenSearch Service의 Observability](observability.md)
# 에서 OpenSearch Ingestion 파이프라인 사용 AWS Lambda
[AWS Lambda 프로세서](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/aws-lambda/)에서 사용자 지정 코드를 사용하여 OpenSearch Ingestion에서 지원하는 모든 소스 또는 대상의 데이터를 보강합니다. Lambda 프로세서를 사용하면 자체 데이터 변환 또는 보강을 적용한 다음 처리된 이벤트를 파이프라인에 반환하여 추가 처리를 수행할 수 있습니다. 이 프로세서를 사용하면 사용자 지정 데이터 처리를 활성화하고 파이프라인을 통과하기 전에 데이터가 조작되는 방식을 완벽하게 제어할 수 있습니다.
**참고**
Lambda 프로세서에서 처리하는 단일 이벤트의 페이로드 크기 제한은 5MB입니다. 또한 Lambda 프로세서는 JSON 배열 형식의 응답만 지원합니다.
## 사전 조건
Lambda 프로세서를 사용하여 파이프라인을 생성하기 전에 다음 리소스를 생성합니다.
+ 소스 데이터를 보강하고 변환하는 AWS Lambda 함수입니다. 지침은 [첫 번째 Lambda 함수 생성](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html)을 참조하세요.
+ 파이프라인 싱크가 될 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션입니다. 자세한 내용은 [OpenSearch Service 도메인 생성](createupdatedomains.md#createdomains) 및 [컬렉션 생성](serverless-create.md) 섹션을 참조하세요.
+ 도메인 또는 컬렉션 싱크에 쓸 권한이 포함된 파이프라인 역할입니다. 자세한 내용은 [파이프라인 역할](pipeline-security-overview.md#pipeline-security-sink) 단원을 참조하십시오.
파이프라인 역할에는 파이프라인 구성에 지정된 Lambda 함수를 호출할 수 있는 연결된 권한 정책도 필요합니다. 예제:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "allowinvokeFunction",
"Effect": "Allow",
"Action": [
"lambda:invokeFunction",
"lambda:InvokeAsync",
"lambda:ListFunctions"
],
"Resource": "arn:aws:lambda:us-east-1:111122223333:function:function-name"
}
]
}
```
------
## 파이프라인 생성
를 프로세서 AWS Lambda 로 사용하려면 OpenSearch Ingestion 파이프라인을 구성하고를 프로세서`aws_lambda`로 지정합니다. **AWS Lambda 사용자 지정 보강** 블루프린트를 사용하여 파이프라인을 생성할 수도 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
다음 예제 파이프라인은 HTTP 소스에서 데이터를 수신하고, 날짜 프로세서와 AWS Lambda 프로세서를 사용하여 데이터를 보강하고, 처리된 데이터를 OpenSearch 도메인에 수집합니다.
```
version: "2"
lambda-processor-pipeline:
source:
http:
path: "/${pipelineName}/logs"
processor:
- date:
destination: "@timestamp"
from_time_received: true
- aws_lambda:
function_name: "my-lambda-function"
tags_on_failure: ["lambda_failure"]
batch:
key_name: "events"
aws:
region: region
sink:
- opensearch:
hosts: [ "https://search-mydomain.us-east-1es.amazonaws.com" ]
index: "table-index"
aws:
region: "region"
serverless: false
```
다음 예제 AWS Lambda 함수는 제공된 이벤트 배열의 각 요소에 새 키-값 페어(`"transformed": "true"`)를 추가하여 수신 데이터를 변환한 다음 수정된 버전을 다시 보냅니다.
```
import json
def lambda_handler(event, context):
input_array = event.get('events', [])
output = []
for input in input_array:
input["transformed"] = "true";
output.append(input)
return output
```
## 배칭
파이프라인은 배치 이벤트를 Lambda 프로세서로 전송하고 배치 크기를 동적으로 조정하여 5MB 한도 미만으로 유지되도록 합니다.
다음은 파이프라인 배치의 예입니다.
```
batch:
key_name: "events"
input_arrary = event.get('events', [])
```
**참고**
파이프라인을 생성할 때 Lambda 프로세서 구성의 `key_name` 옵션이 Lambda 핸들러의 이벤트 키와 일치하는지 확인합니다.
## 조건부 필터링
조건부 필터링을 사용하면 AWS Lambda 프로세서가 이벤트 데이터의 특정 조건을 기반으로 Lambda 함수를 호출하는 시기를 제어할 수 있습니다. 이는 다른 이벤트를 무시하면서 특정 유형의 이벤트를 선택적으로 처리하려는 경우에 특히 유용합니다.
다음 구성 예에서는 조건부 필터링을 사용합니다.
```
processors:
- aws_lambda:
function_name: "my-lambda-function"
aws:
region: "region"
lambda_when: "/sourceIp == 10.10.10.10"
```
# Amazon OpenSearch Ingestion을 사용하여 도메인과 컬렉션 간 데이터 마이그레이션
OpenSearch Ingestion 파이프라인을 사용하여 Amazon OpenSearch Service 도메인 또는 OpenSearch Serverless VPC 컬렉션 간에 데이터를 마이그레이션할 수 있습니다. 이를 수행하려면 한 도메인 또는 컬렉션을 소스로 구성하고 다른 도메인 또는 컬렉션을 싱크로 구성하는 파이프라인을 설정합니다. 그러면 한 도메인 또는 컬렉션에서 다른 도메인이나 컬렉션으로 데이터가 효과적으로 마이그레이션됩니다.
데이터를 마이그레이션하려면 다음 리소스가 있어야 합니다.
+ 소스 OpenSearch Service 도메인 또는 소스 OpenSearch Serverless VPC 컬렉션. 이 도메인 또는 컬렉션에 마이그레이션하려는 데이터가 포함되어 있습니다. 도메인을 사용하는 경우 OpenSearch 1.0 이상 또는 Elasticsearch 7.4 이상이 실행되고 있어야 합니다. 도메인에는 파이프라인 역할에 적절한 권한을 부여하는 액세스 정책도 있어야 합니다.
+ 데이터를 마이그레이션하려는 별도의 도메인 또는 VPC 컬렉션. 이 도메인 또는 컬렉션은 파이프라인 *싱크*로 작동합니다.
+ OpenSearch Ingestion이 컬렉션이나 도메인에서 읽고 쓸 때 사용하는 파이프라인 역할. 파이프라인 구성에 이 역할의 Amazon 리소스 이름(ARN)을 포함합니다. 자세한 정보는 다음 자료를 참조하세요.
+ [도메인에 대한 Amazon OpenSearch Ingestion 파이프라인 액세스 권한 부여](pipeline-domain-access.md)
+ [컬렉션에 대한 액세스 권한을 Amazon OpenSearch Ingestion 파이프라인에 부여](pipeline-collection-access.md)
**Topics**
+ [
## 제한 사항
](#Limitations-domain-collection)
+ [
## OpenSearch Service를 소스로 사용
](#opensearch-source)
+ [
## 여러 OpenSearch Service 도메인 싱크 지정
](#multiple-domains)
+ [
## OpenSearch Serverless VPC 컬렉션으로 데이터 마이그레이션
](#pipeline-collection)
## 제한 사항
OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션을 싱크로 지정할 때 다음과 같은 제한 사항이 적용됩니다.
+ 파이프라인은 둘 이상의 VPC 도메인에 쓸 수 없습니다.
+ VPC 액세스를 사용하는 OpenSearch Serverless 컬렉션 사이에서만 데이터를 마이그레이션할 수 있습니다. 퍼블릭 컬렉션은 지원되지 않습니다.
+ 단일 파이프라인 구성에서 VPC와 퍼블릭 도메인의 조합을 지정할 수 없습니다.
+ 단일 파이프라인 구성 내에서 최대 20개의 비파이프라인 싱크를 보유할 수 있습니다.
+ 단일 파이프라인 구성에서 최대 3개의 싱크를 지정할 수 AWS 리전 있습니다.
+ 싱크가 여러 개 있는 파이프라인에서 싱크가 너무 오랫동안 중단된 상태이거나 수신 데이터를 처리할 수 있는 충분한 용량이 프로비저닝되지 않은 경우 시간이 지남에 따라 처리 속도가 저하될 수 있습니다.
## OpenSearch Service를 소스로 사용
소스로 지정하는 도메인 또는 컬렉션이 데이터가 마이그레이션되는 *소스* 위치입니다.
### IAM에서 파이프라인 역할 생성
OpenSearch Ingestion 파이프라인을 생성하려면 먼저 도메인 또는 컬렉션 사이에서 읽기 및 쓰기 액세스 권한을 부여하도록 파이프라인 역할을 생성해야 합니다. 이렇게 하려면 다음 단계를 수행하세요.
1. IAM에서 새 권한 정책을 생성하여 파이프라인 역할에 연결합니다. 소스에서 읽고 싱크에 쓸 수 있는 권한을 허용해야 합니다. OpenSearch Service 도메인의 IAM 파이프라인 권한 설정에 대한 자세한 내용은 [도메인에 대한 Amazon OpenSearch Ingestion 파이프라인 액세스 권한 부여](pipeline-domain-access.md) 및 [컬렉션에 대한 액세스 권한을 Amazon OpenSearch Ingestion 파이프라인에 부여](pipeline-collection-access.md) 섹션을 참조하세요.
1. 소스에서 읽을 수 있도록 파이프라인 역할에 다음 권한을 지정합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"es:ESHttpGet",
"Resource":[
"arn:aws:es:us-east-1:111122223333:domain/domain-name/",
"arn:aws:es:us-east-1:111122223333:domain/domain-name/_cat/indices",
"arn:aws:es:us-east-1:111122223333:domain/domain-name/_search",
"arn:aws:es:us-east-1:111122223333:domain/domain-name/_search/scroll",
"arn:aws:es:us-east-1:111122223333:domain/domain-name/*/_search"
]
},
{
"Effect":"Allow",
"Action":"es:ESHttpPost",
"Resource":[
"arn:aws:es:us-east-1:111122223333:domain/domain-name/*/_search/point_in_time",
"arn:aws:es:us-east-1:111122223333:domain/domain-name/*/_search/scroll"
]
},
{
"Effect":"Allow",
"Action":"es:ESHttpDelete",
"Resource":[
"arn:aws:es:us-east-1:111122223333:domain/domain-name/_search/point_in_time",
"arn:aws:es:us-east-1:111122223333:domain/domain-name/_search/scroll"
]
}
]
}
```
------
### 파이프라인 생성
정책을 파이프라인 역할에 연결한 후 **AWSOpenSearchDataMigrationPipeline** 마이그레이션 블루프린트를 사용하여 파이프라인을 생성합니다. 이 블루프린트에는 OpenSearch Service 도메인 또는 컬렉션 사이에서 데이터를 마이그레이션하기 위한 기본 구성이 포함되어 있습니다. 자세한 내용은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하십시오.
**참고**
OpenSearch Ingestion에서는 소스 도메인 버전과 배포를 사용하여 마이그레이션에 사용할 메커니즘을 결정합니다. 일부 버전은 `point_in_time` 옵션을 지원합니다. OpenSearch Serverless는 `point_in_time` 또는 `scroll`을 지원하지 않으므로 `search_after` 옵션을 사용합니다.
마이그레이션 프로세스 중에 새 인덱스가 생성되거나, 마이그레이션이 진행되는 동안 문서가 업데이트될 수 있습니다. 이 때문에 새 데이터나 업데이트된 데이터를 찾기 위해 도메인 인덱스 데이터의 단일 스캔이나 다중 스캔을 수행해야 할 수 있습니다.
파이프라인 구성에서 `index_read_count` 및 `interval`을 구성하여 스캔 실행 횟수를 지정합니다. 다음 예제에서는 다중 스캔을 수행하는 방법을 보여줍니다.
```
scheduling:
interval: "PT2H"
index_read_count: 3
start_time: "2023-06-02T22:01:30.00Z"
```
OpenSearch Ingestion은 다음 구성을 사용하여 데이터를 동일한 인덱스에 쓰고 동일한 문서 ID를 유지하도록 합니다.
```
index: "${getMetadata(\"opensearch-index\")}"
document_id: "${getMetadata(\"opensearch-document_id\")}"
```
## 여러 OpenSearch Service 도메인 싱크 지정
여러 퍼블릭 OpenSearch Service 도메인을 데이터의 대상으로 지정할 수 있습니다. 이 기능을 사용하여 조건부 라우팅을 수행하거나 수신 데이터를 여러 OpenSearch Service 도메인으로 복제할 수 있습니다. 최대 10개의 서로 다른 퍼블릭 OpenSearch Service 도메인을 싱크로 지정할 수 있습니다.
다음 예제에서는 수신 데이터를 조건에 따라 서로 다른 OpenSearch Service 도메인으로 라우팅합니다.
```
...
route:
- 2xx_status: "/response >= 200 and /response < 300"
- 5xx_status: "/response >= 500 and /response < 600"
sink:
- opensearch:
hosts: [ "https://search-response-2xx.region.es.amazonaws.com" ]
aws:
region: "us-east-1"
index: "response-2xx"
routes:
- 2xx_status
- opensearch:
hosts: [ "https://search-response-5xx.region.es.amazonaws.com" ]
aws:
region: "us-east-1"
index: "response-5xx"
routes:
- 5xx_status
```
## OpenSearch Serverless VPC 컬렉션으로 데이터 마이그레이션
OpenSearch Ingestion을 사용하여 Amazon OpenSearch Service 도메인 또는 OpenSearch Serverless VPC 컬렉션에서 VPC 컬렉션 싱크에서 데이터를 마이그레이션할 수 있습니다. 파이프라인 구성 내에서 네트워크 액세스 정책을 제공해야 합니다. OpenSearch Serverless VPC 컬렉션으로 데이터를 수집하는 방법에 대한 자세한 내용은 [튜토리얼: Amazon OpenSearch Ingestion을 사용하여 컬렉션에 데이터 수집](osis-serverless-get-started.md) 섹션을 참조하세요.
**VPC 컬렉션으로 데이터를 마이그레이션하는 방법**
1. OpenSearch Serverless 컬렉션을 생성합니다. 지침은 [튜토리얼: Amazon OpenSearch Ingestion을 사용하여 컬렉션에 데이터 수집](osis-serverless-get-started.md) 섹션을 참조하세요.
1. 컬렉션 엔드포인트와 대시보드 엔드포인트 모두에 VPC 액세스 권한을 지정하는 컬렉션에 대한 네트워크 정책을 생성합니다. 지침은 [Amazon OpenSearch Serverless에 대한 네트워크 액세스](serverless-network.md) 섹션을 참조하세요.
1. 아직 없는 경우 파이프라인 역할을 생성합니다. 지침은 [파이프라인 역할](pipeline-security-overview.md#pipeline-security-sink) 섹션을 참조하세요.
1. 파이프라인을 생성합니다. 지침은 [블루프린트 작업](pipeline-blueprint.md) 단원을 참조하세요.
# AWS SDKs를 사용하여 Amazon OpenSearch Ingestion과 상호 작용
이 섹션에는 AWS SDKs를 사용하여 Amazon OpenSearch Ingestion과 상호 작용하는 방법의 예가 포함되어 있습니다. 코드 예제는 도메인과 파이프라인을 생성한 다음 파이프라인으로 데이터를 수집하는 방법을 보여줍니다.
**Topics**
+ [
## Python
](#osis-sdk-python)
## Python
다음 샘플 스크립트는 [AWS SDK for Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/osis.html)를 사용하여 IAM 파이프라인 역할, 데이터를 쓸 도메인, 데이터를 수집하는 파이프라인을 생성합니다. 그런 다음 `[requests](https://pypi.org/project/requests/)` HTTP 라이브러리를 사용하여 샘플 로그 파일을 파이프라인으로 수집합니다.
필요한 종속성을 설치하려면 다음 명령을 실행합니다.
```
pip install boto3
pip install botocore
pip install requests
pip install requests-auth-aws-sigv4
```
스크립트 내에서 `account-id`의 모든 인스턴스를 AWS 계정 ID로 바꿉니다.
```
import boto3
import botocore
from botocore.config import Config
import requests
from requests_auth_aws_sigv4 import AWSSigV4
import time
# Build the client using the default credential configuration.
# You can use the CLI and run 'aws configure' to set access key, secret
# key, and default region.
opensearch = boto3.client('opensearch', config=my_config)
iam = boto3.client('iam', config=my_config)
osis = boto3.client('osis', config=my_config)
domainName = 'test-domain' # The name of the domain
pipelineName = 'test-pipeline' # The name of the pipeline
def createPipelineRole(iam, domainName):
"""Creates the pipeline role"""
response = iam.create_policy(
PolicyName='pipeline-policy',
PolicyDocument=f'{{\"Version\":\"2012-10-17\",\"Statement\":[{{\"Effect\":\"Allow\",\"Action\":\"es:DescribeDomain\",\"Resource\":\"arn:aws:es:us-east-1:account-id:domain\/{domainName}\"}},{{\"Effect\":\"Allow\",\"Action\":\"es:ESHttp*\",\"Resource\":\"arn:aws:es:us-east-1:account-id:domain\/{domainName}\/*\"}}]}}'
)
policyarn = response['Policy']['Arn']
response = iam.create_role(
RoleName='PipelineRole',
AssumeRolePolicyDocument='{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"osis-pipelines.amazonaws.com\"},\"Action\":\"sts:AssumeRole\"}]}'
)
rolename=response['Role']['RoleName']
response = iam.attach_role_policy(
RoleName=rolename,
PolicyArn=policyarn
)
print('Creating pipeline role...')
time.sleep(10)
print('Role created: ' + rolename)
def createDomain(opensearch, domainName):
"""Creates a domain to ingest data into"""
response = opensearch.create_domain(
DomainName=domainName,
EngineVersion='OpenSearch_2.3',
ClusterConfig={
'InstanceType': 't2.small.search',
'InstanceCount': 5,
'DedicatedMasterEnabled': True,
'DedicatedMasterType': 't2.small.search',
'DedicatedMasterCount': 3
},
# Many instance types require EBS storage.
EBSOptions={
'EBSEnabled': True,
'VolumeType': 'gp2',
'VolumeSize': 10
},
AccessPolicies=f'{{\"Version\":\"2012-10-17\",\"Statement\":[{{\"Effect\":\"Allow\",\"Principal\":{{\"AWS\":\"arn:aws:iam::account-id:role\/PipelineRole\"}},\"Action\":\"es:*\",\"Resource\":\"arn:aws:es:us-east-1:account-id:domain\/{domainName}\/*\"}}]}}',
NodeToNodeEncryptionOptions={
'Enabled': True
}
)
return(response)
def waitForDomainProcessing(opensearch, domainName):
"""Waits for the domain to be active"""
try:
response = opensearch.describe_domain(
DomainName=domainName
)
# Every 30 seconds, check whether the domain is processing.
while 'Endpoint' not in response['DomainStatus']:
print('Creating domain...')
time.sleep(60)
response = opensearch.describe_domain(
DomainName=domainName)
# Once we exit the loop, the domain is ready for ingestion.
endpoint = response['DomainStatus']['Endpoint']
print('Domain endpoint ready to receive data: ' + endpoint)
createPipeline(osis, endpoint)
except botocore.exceptions.ClientError as error:
if error.response['Error']['Code'] == 'ResourceNotFoundException':
print('Domain not found.')
else:
raise error
def createPipeline(osis, endpoint):
"""Creates a pipeline using the domain and pipeline role"""
try:
definition = f'version: \"2\"\nlog-pipeline:\n source:\n http:\n path: \"/${{pipelineName}}/logs\"\n processor:\n - date:\n from_time_received: true\n destination: \"@timestamp\"\n sink:\n - opensearch:\n hosts: [ \"https://{endpoint}\" ]\n index: \"application_logs\"\n aws:\n region: \"us-east-1\"'
response = osis.create_pipeline(
PipelineName=pipelineName,
MinUnits=4,
MaxUnits=9,
PipelineConfigurationBody=definition,
PipelineRoleArn="arn:aws:iam::account-id:role/PipelineRole"
)
response = osis.get_pipeline(
PipelineName=pipelineName
)
# Every 30 seconds, check whether the pipeline is active.
while response['Pipeline']['Status'] == 'CREATING':
print('Creating pipeline...')
time.sleep(30)
response = osis.get_pipeline(
PipelineName=pipelineName)
# Once we exit the loop, the pipeline is ready for ingestion.
ingestionEndpoint = response['Pipeline']['IngestEndpointUrls'][0]
print('Pipeline ready to ingest data at endpoint: ' + ingestionEndpoint)
ingestData(ingestionEndpoint)
except botocore.exceptions.ClientError as error:
if error.response['Error']['Code'] == 'ResourceAlreadyExistsException':
print('Pipeline already exists.')
response = osis.get_pipeline(
PipelineName=pipelineName
)
ingestionEndpoint = response['Pipeline']['IngestEndpointUrls'][0]
ingestData(ingestionEndpoint)
else:
raise error
def ingestData(ingestionEndpoint):
"""Ingests a sample log file into the pipeline"""
endpoint = 'https://' + ingestionEndpoint
r = requests.request('POST', f'{endpoint}/log-pipeline/logs',
data='[{"time":"2014-08-11T11:40:13+00:00","remote_addr":"122.226.223.69","status":"404","request":"GET http://www.k2proxy.com//hello.html HTTP/1.1","http_user_agent":"Mozilla/4.0 (compatible; WOW64; SLCC2;)"}]',
auth=AWSSigV4('osis'))
print('Ingesting sample log file into pipeline')
print('Response: ' + r.text)
def main():
createPipelineRole(iam, domainName)
createDomain(opensearch, domainName)
waitForDomainProcessing(opensearch, domainName)
if __name__ == "__main__":
main()
```
# Amazon OpenSearch Ingestion의 보안
의 클라우드 보안 AWS 이 최우선 순위입니다. AWS 고객은 보안에 가장 민감한 조직의 요구 사항을 충족하도록 구축된 데이터 센터 및 네트워크 아키텍처의 이점을 누릴 수 있습니다.
보안은 AWS 와 사용자 간의 공동 책임입니다. [공동 책임 모델](https://aws.amazon.com/compliance/shared-responsibility-model/)은 이를 클라우드*의* 보안과 클라우드 *내* 보안으로 설명합니다.
+ **클라우드 보안 **- AWS 는 클라우드에서 AWS AWS 서비스를 실행하는 인프라를 보호할 책임이 있습니다. AWS 또한는 안전하게 사용할 수 있는 서비스를 제공합니다. 서드 파티 감사원은 정기적으로 [AWS 규정 준수 프로그램](https://aws.amazon.com/compliance/programs/)의 일환으로 보안 효과를 테스트하고 검증합니다.
+ **클라우드의 보안** - 사용자의 책임은 사용하는 AWS 서비스에 따라 결정됩니다. 또한 귀하는 귀사의 데이터 민감도, 귀사의 요구 사항, 관련 법률 및 규정을 비롯한 기타 요소에 대해서도 책임이 있습니다.
이 설명서는 OpenSearch Ingestion 사용 시 공동 책임 모델을 적용하는 방법을 이해하는 데 도움이 됩니다. 다음 주제에서는 보안 및 규정 준수 목적에 맞게 OpenSearch Ingestion을 구성하는 방법을 보여줍니다. 또한 OpenSearch Ingestion 리소스를 모니터링하고 보호하는 데 도움이 되는 다른 AWS 서비스를 사용하는 방법을 알아봅니다.
**Topics**
+ [
# Amazon OpenSearch Ingestion 파이프라인에 대한 VPC 액세스 구성
](pipeline-security.md)
+ [
# 교차 계정 수집을 위한 OpenSearch Ingestion 파이프라인 구성
](cross-account-pipelines.md)
+ [
# Amazon OpenSearch Ingestion에 대한 자격 증명 및 액세스 관리자
](security-iam-ingestion.md)
+ [
# 를 사용하여 Amazon OpenSearch Ingestion API 호출 로깅 AWS CloudTrail
](osis-logging-using-cloudtrail.md)
+ [
# Amazon OpenSearch Ingestion 및 인터페이스 엔드포인트 API(AWS PrivateLink)
](osis-access-apis-using-privatelink.md)
# Amazon OpenSearch Ingestion 파이프라인에 대한 VPC 액세스 구성
인터페이스 VPC 엔드포인트를 사용하여 Amazon OpenSearch Ingestion 파이프라인에 액세스할 수 있습니다. VPC는 전용 가상 네트워크입니다 AWS 계정. AWS 클라우드의 다른 가상 네트워크와 논리적으로 격리되어 있습니다. VPC 엔드포인트를 통해 파이프라인에 액세스하면 인터넷 게이트웨이, NAT 디바이스 또는 VPN을 연결하지 않아도 VPC 내부에서 OpenSearch Ingestion과 다른 서비스 간에 보안 통신이 가능합니다. 모든 트래픽은 AWS 클라우드 내에서 안전하게 유지됩니다.
OpenSearch Ingestion은 AWS PrivateLink에서 지원하는 *인터페이스 엔드포인트*를 생성하여 이 프라이빗 연결을 설정합니다. 파이프라인 생성 중에 지정한 각 서브넷에서 엔드포인트 네트워크 인터페이스를 생성합니다. 이는 OpenSearch Ingestion 파이프라인으로 향하는 트래픽의 진입점 역할을 하는 요청자 관리형 네트워크 인터페이스입니다. 인터페이스 엔드포인트를 직접 생성하고 관리하도록 선택할 수도 있습니다.
VPC를 사용하면 공용 인터넷을 통하지 않고 VPC의 경계 내에서 OpenSearch Ingestion 파이프라인을 통해 데이터 흐름을 적용할 수 있습니다. VPC 내에 있지 않은 파이프라인은 공용 엔드포인트와 인터넷을 통해 데이터를 보내고 받습니다.
VPC 액세스 권한이 있는 파이프라인은 퍼블릭 또는 VPC OpenSearch Service 도메인과 퍼블릭 또는 VPC OpenSearch Serverless 컬렉션에 쓸 수 있습니다.
**Topics**
+ [
## 고려 사항
](#pipeline-vpc-considerations)
+ [
## 제한 사항
](#pipeline-vpc-limitations)
+ [
## 사전 조건
](#pipeline-vpc-prereqs)
+ [
## 파이프라인에 대한 VPC 액세스 구성
](#pipeline-vpc-configure)
+ [
## 자체 관리형 VPC 엔드포인트
](#pipeline-vpc-self-managed)
+ [
## VPC 액세스를 위한 서비스 연결 역할
](#pipeline-vpc-slr)
## 고려 사항
파이프라인에 대한 VPC 액세스를 구성할 때 다음 사항을 고려하세요.
+ 파이프라인은 싱크와 동일한 VPC에 있지 않아도 됩니다. 또한 두 VPC 간에 연결을 설정할 필요도 없습니다. OpenSearch Ingestion이 이들을 연결해 줍니다.
+ 파이프라인에는 하나의 VPC만 지정할 수 있습니다.
+ 퍼블릭 파이프라인과 달리 VPC 파이프라인은 쓰기 대상 도메인 또는 컬렉션 싱크와 동일한 AWS 리전 에 있어야 합니다. 교차 리전을 작성하기 위해 파이프라인에 대한 S3 소스를 구성할 수 있습니다.
+ 파이프라인을 사용자의 VPC의 서브넷 1개, 2개 또는 3개에 배포하도록 선택할 수 있습니다. 서브넷은 통합 OpenSearch Compute Units(OCU)가 배포된 동일한 가용 영역에 분산되어 있습니다.
+ 하나의 서브넷에만 파이프라인을 배포하고 가용 영역이 다운되면 데이터를 수집할 수 없습니다. 고가용성을 보장하려면 2개 또는 3개의 서브넷으로 파이프라인을 구성하는 것이 좋습니다.
+ 보안 그룹 지정은 선택 사항입니다. 보안 그룹을 제공하지 않는 경우 OpenSearch Ingestion은 VPC에서 지정된 기본 보안 그룹을 사용합니다.
## 제한 사항
VPC 내 파이프라인에는 다음과 같은 제한 사항이 있습니다.
+ 파이프라인 네트워크 구성을 생성한 후에는 해당 구성을 변경할 수 없습니다. VPC 내에서 파이프라인을 시작하는 경우 나중에 퍼블릭 엔드포인트로 변경할 수 없으며 그 반대의 경우도 마찬가지입니다.
+ 인터페이스 VPC 엔드포인트 또는 퍼블릭 엔드포인트에서 파이프라인을 시작할 수도 있지만 두 방법을 동시에 사용할 수는 없습니다. 파이프라인을 만들 때 한 가지를 선택해야 합니다.
+ VPC 액세스 권한이 있는 파이프라인을 프로비저닝한 후 다른 VPC로 이동할 수 없지만 해당 서브넷과 보안 그룹 설정은 변경할 수 있습니다.
+ 파이프라인이 VPC 액세스를 사용하는 도메인 또는 컬렉션 싱크에 쓰는 경우, 파이프라인이 생성된 후에는 나중에 돌아가서 싱크(VPC 또는 퍼블릭)를 변경할 수 없습니다. 파이프라인을 삭제하고 새 싱크로 재생성해야 합니다. 여전히 퍼블릭 싱크에서 VPC 액세스를 사용하는 싱크로 전환할 수 있습니다.
+ VPC 파이프라인에 [계정 간 수집 액세스](configure-client.md#configure-client-cross-account)를 제공할 수 없습니다.
## 사전 조건
VPC 액세스 권한이 있는 파이프라인을 프로비저닝하려면 먼저 다음을 수행해야 합니다.
+ **VPC 생성**
VPC를 생성하려면 Amazon VPC 콘솔, AWS CLI 또는 AWS SDKs. 자세한 내용은 *Amazon VPC 사용 설명서*의 [VPC 작업](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html)을 참조하세요. VPC가 이미 있는 경우에는 이 단계를 건너뛸 수 있습니다.
+ **IP 주소 예약 **
OpenSearch Ingestion은 파이프라인 생성 중에 지정한 각 서브넷에 *탄력적 네트워크 인터페이스*를 배치합니다. 각 네트워크 인터페이스에는 IP 주소가 연결됩니다. 서브넷당 네트워크 인터페이스용 IP 주소 하나를 예약해야 합니다.
## 파이프라인에 대한 VPC 액세스 구성
OpenSearch Service 콘솔 내에서 또는 AWS CLI를 사용한 파이프라인에 대한 VPC 액세스 기능을 활성화할 수 있습니다.
### 콘솔
[파이프라인 생성](creating-pipeline.md#create-pipeline) 중에 VPC 액세스를 구성합니다. **소스 네트워크 옵션**에서 **VPC 액세스**를 선택하고 다음 설정을 구성합니다.
| 설정 | 설명 |
| --- | --- |
| 엔드포인트 관리 | VPC 엔드포인트를 직접 생성할지 아니면 OpenSearch Ingestion에서 자동으로 생성할지 선택합니다. |
| VPC | 사용하려는 Virtual Private Cloud(VPC)를 선택합니다. VPC와 파이프라인의 AWS 리전(은)는 동일해야 합니다. |
| 서브넷 | 서브넷을 하나 이상 선택합니다. OpenSearch Service가 서브넷에 VPC 엔드포인트와 탄력적 네트워크 인터페이스를 배치합니다. |
| 보안 그룹 | 필요한 애플리케이션이 파이프라인에 의해 노출된 포트(80 또는 443) 및 프로토콜(HTTP 또는 HTTPS)에서 OpenSearch Ingestion 파이프라인에 도달하도록 허용하는 VPC 보안 그룹을 하나 이상 선택합니다. |
| VPC 연결 옵션 | 소스에 Amazon DocumentDB, 자체 관리형 OpenSearch, Confluent Kafka 등의 VPC 간 통신이 필요한 경, OpenSearch Ingestion은 이들 소스에 연결하기 위해, 지정된 서브넷에 탄력적 네트워크 인터페이스(ENI)를 생성합니다. OpenSearch Ingestion은 각 가용 영역의 ENI를 사용하여 지정된 소스에 도달합니다. **VPC에 연결** 옵션은 OpenSearch Ingestion 데이터 플레인 VPC를 지정된 VPC에 연결합니다. 관리형 VPC에 대한 CIDR 예약을 선택하여 네트워크 인터페이스를 배포합니다. |
### CLI
를 사용하여 VPC 액세스를 구성하려면 `--vpc-options` 파라미터를 AWS CLI지정합니다.
```
aws osis create-pipeline \
--pipeline-name vpc-pipeline \
--min-units 4 \
--max-units 10 \
--vpc-options SecurityGroupIds={sg-12345678,sg-9012345},SubnetIds=subnet-1212234567834asdf \
--pipeline-configuration-body "file://pipeline-config.yaml"
```
## 자체 관리형 VPC 엔드포인트
파이프라인을 생성할 때 엔드포인트 관리를 사용하여 자체 관리형 엔드포인트 또는 서비스 관리형 엔드포인트가 있는 파이프라인을 생성할 수 있습니다. 엔드포인트 관리는 선택 사항이며, 기본적으로 OpenSearch Ingestion에서 관리하는 엔드포인트로 설정됩니다.
에서 자체 관리형 VPC 엔드포인트가 있는 파이프라인을 생성하려면 OpenSearch Service 콘솔을 사용하여 파이프라인 생성을 AWS Management Console참조하세요. [ OpenSearch ](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/creating-pipeline.html#create-pipeline-console) 에서 자체 관리형 VPC 엔드포인트가 있는 파이프라인을 생성하려면 [create-pipeline](https://docs.aws.amazon.com/cli/latest/reference/osis/create-pipeline.html) 명령에서 `--vpc-options` 파라미터를 사용할 AWS CLI수 있습니다.
```
--vpc-options SubnetIds=subnet-abcdef01234567890,VpcEndpointManagement=CUSTOMER
```
엔드포인트 서비스를 지정할 때 파이프라인에 대해 엔드포인트를 직접 생성할 수 있습니다. 엔드포인트 서비스를 찾으려면 다음과 유사한 응답을 반환하는 [get-pipeline](https://docs.aws.amazon.com/cli/latest/reference/osis/get-pipeline.html) 명령을 사용합니다.
```
"vpcEndpointService" : "com.amazonaws.osis.us-east-1.pipeline-id-1234567890abcdef1234567890",
"vpcEndpoints" : [
{
"vpcId" : "vpc-1234567890abcdef0",
"vpcOptions" : {
"subnetIds" : [ "subnet-abcdef01234567890", "subnet-021345abcdef6789" ],
"vpcEndpointManagement" : "CUSTOMER"
}
}
```
응답`vpcEndpointService`의를 사용하여 AWS Management Console 또는를 사용하여 VPC 엔드포인트를 생성합니다 AWS CLI.
자체 관리형 VPC 엔드포인트를 사용하는 경우 VPC에서 DNS 속성 `enableDnsSupport` 및 `enableDnsHostnames`를 활성화해야 합니다. [중지 후 다시 시작](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline--stop-start.html)하는 자체 관리형 엔드포인트를 포함하는 파이프라인가 있으면 계정에서 VPC 엔드포인트를 다시 생성해야 합니다.
## VPC 액세스를 위한 서비스 연결 역할
[서비스 연결 역할](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role)은 서비스가 사용자를 대신하여 리소스를 생성하고 관리할 수 있도록 서비스에 권한을 위임하는 고유한 유형의 IAM 역할입니다. 서비스 관리형 VPC 엔드포인트를 선택하는 경우 OpenSearch Ingestion에서 VPC에 액세스하고, 파이프라인 엔드포인트를 생성하며, VPC의 서브넷에 네트워크 인터페이스를 배치하려면 **AWSServiceRoleForAmazonOpenSearchIngestionService**라고 하는 서비스 연결 역할이 필요합니다.
자체 관리형 VPC 엔드포인트를 선택하는 경우 OpenSearch Ingestion에는 **AWSServiceRoleForOpensearchIngestionSelfManagedVpce**라고 하는 서비스 연결 역할이 필요합니다. 이 역할, 해당 권한 및 삭제 방법에 대한 자세한 내용은 [서비스 연결 역할을 사용하여 OpenSearch Ingestion 파이프라인 생성](slr-osis.md) 섹션을 참조하세요.
수집 파이프라인을 생성할 때 OpenSearch Ingestion이 자동으로 역할을 생성합니다. 이 자동 생성이 성공하려면 계정에서 첫 번째 파이프라인을 생성하는 사용자에게 `iam:CreateServiceLinkedRole` 작업에 대한 권한이 있어야 합니다. 자세히 알아보려면 *IAM 사용 설명서*의 [서비스 연결 역할 권한](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions)을 참조하세요. 역할을 생성한 후 AWS Identity and Access Management (IAM) 콘솔에서 역할을 볼 수 있습니다.
# 교차 계정 수집을 위한 OpenSearch Ingestion 파이프라인 구성
HTTP 및 OTel과 같은 푸시 기반 소스의 경우 Amazon OpenSearch Ingestion을 사용하면 Virtual Private Cloud(VPC) AWS 계정 에서 별도의 VPC의 파이프라인 엔드포인트로 파이프라인을 공유할 수 있습니다. 조직 내 다른 팀과 분석을 공유하는 팀은 로그 분석 공유와 같은 보다 간소화된 수단을 위해 이 기능을 사용합니다.
이 섹션에서는 다음 용어를 사용합니다.
+ **파이프라인 소유자** - OpenSearch Ingestion 파이프라인을 소유하고 관리하는 계정입니다. 하나의 계정만 파이프라인을 소유할 수 있습니다.
+ **계정 연결** - 공유 파이프라인에 연결하고 사용하는 계정입니다. 여러 계정을 동일한 파이프라인에 연결할 수 있습니다.
OpenSearch Ingestion 파이프라인을 공유하도록 VPCs를 구성하려면 여기에 설명된 대로 다음 작업을 AWS 계정완료합니다.
+ (파이프라인 소유자) [연결 계정에 파이프라인에 대한 액세스 권한 부여](#cross-account-pipelines-setting-up-grant-access)
+ (연결 계정) [각 연결 VPC에 대한 파이프라인 엔드포인트 연결 생성](#cross-account-pipelines-setting-up-create-pipeline-endpoints)
## 시작하기 전 준비 사항
OpenSearch Ingestion 파이프라인을 공유하도록 VPCs를 구성하기 전에 다음 작업을 AWS 계정완료합니다.
****
| Task | 세부 정보 |
| --- | --- |
| 하나 이상의 OpenSearch Ingestion 파이프라인 생성 | 최소 OpenSearch 컴퓨팅 유닛(OSU)을 2 이상으로 설정합니다. 자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인 생성](creating-pipeline.md) 단원을 참조하십시오. 파이프라인을 업데이트는 방법에 대한 자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인 업데이트](update-pipeline.md) 섹션을 참조하세요. |
| OpenSearch Ingestion을 위한 하나 이상의 VPC 생성 | 교차 계정 파이프라인 공유를 활성화하려면 파이프라인 및 파이프라인 엔드포인트와 관련한 모든 VPC를 다음 DNS 값으로 구성해야 합니다.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/opensearch-service/latest/developerguide/cross-account-pipelines.html) 자세한 내용은 *Amazon VPC 사용 설명서*의 [VPC에 대한 DNS 속성](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html)을 참조하세요. |
## 연결 계정에 파이프라인에 대한 액세스 권한 부여
이 섹션의 절차에서는 OpenSearch Service 콘솔 및를 사용하여 리소스 정책을 생성하여 교차 계정 파이프라인 액세스를 AWS CLI 설정하는 방법을 설명합니다. *리소스 정책*을 사용하면 파이프라인 소유자가 파이프라인에 액세스 가능한 다른 계정을 지정할 수 있습니다. 파이프라인이 생성되면 파이프라인이 존재하는 한 또는 정책이 삭제될 때까지 파이프라인 정책이 존재합니다.
**참고**
리소스 정책은 [IAM 권한](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/creating-pipeline.html#create-pipeline-permissions)을 사용한 표준 OpenSearch Ingestion 권한 부여를 대체하지 않습니다. 리소스 정책은 교차 계정 파이프라인 액세스를 활성화하기 위한 추가 권한 부여 메커니즘입니다.
**Topics**
+ [
### 연결 계정에 파이프라인에 대한 액세스 권한 부여(콘솔)
](#cross-account-pipelines-setting-up-grant-access-console)
+ [
### 연결 계정에 파이프라인에 대한 액세스 권한 부여(CLI)
](#cross-account-pipelines-setting-up-grant-access-cli)
### 연결 계정에 파이프라인에 대한 액세스 권한 부여(콘솔)
다음 절차에 따라 Amazon OpenSearch Service 콘솔을 사용하여 연결 계정에 파이프라인에 대한 액세스 권한을 부여합니다.
**파이프라인 엔드포인트 연결을 생성하려면**
1. Amazon OpenSearch Service 콘솔의 탐색 창에서 **수집**을 확장한 다음 **파이프라인**을 선택합니다.
1. **파이프라인** 섹션에서 연결 계정에 대한 액세스 권한을 부여하려는 파이프라인의 이름을 선택합니다.
1. **VPC 엔드포인트** 탭을 선택합니다.
1. **권한 있는 보안 주체** 섹션에서 **계정 권한 부여**를 선택합니다.
1. **AWS 계정 ID** 필드에 12자리 숫자 계정 ID를 입력한 다음 **권한 부여**를 선택합니다.
### 연결 계정에 파이프라인에 대한 액세스 권한 부여(CLI)
다음 절차에 따라 AWS CLI를 사용하여 연결 계정에 파이프라인에 대한 액세스 권한을 부여합니다.
**연결 계정에 파이프라인에 대한 액세스 권한을 부여하려면**
1. 최신 버전의 AWS CLI (버전 2.0)로 업데이트합니다. 자세한 내용은 [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)를 참조하세요.
1. 계정과 공유하려는 파이프라인에서 CLI AWS 리전 를 엽니다.
1. 다음 명령을 실행하여 파이프라인에 대한 리소스 정책을 생성합니다. 이 정책은 파이프라인에 대한 `osis:CreatePipelineEndpoint` 권한을 부여합니다. 이 정책에는 허용할 AWS 계정 ID를 나열할 수 있는 파라미터가 포함되어 있습니다.
**참고**
다음 명령에서는 12자리 계정 ID만 제공하여 짧은 형태의 계정 ID를 사용해야 합니다. ARN을 사용하면 작동하지 않습니다. 또한 다음과 같이 `Resource`의 CLI 파라미터에 파이프라인의 Amazon 리소스 이름(ARN)을 제공하고 `resource-arn` 아래의 정책 JSON에 제공해야 합니다.
```
aws --region region osis put-resource-policy \
--resource-arn arn:aws:osis:region:pipeline-owner-account-ID:pipeline/pipeline-name
--policy 'IAM-policy'
```
*IAM 정책*에 다음과 같은 정책 사용
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowAccess",
"Effect": "Allow",
"Principal": {
"AWS": [
"111122223333",
"444455556666"
]
},
"Action":
"osis:CreatePipelineEndpoint",
"Resource": "arn:aws:osis:us-east-1:123456789012:pipeline/pipeline-name"
}
]
}
```
------
## 각 연결 VPC에 대한 파이프라인 엔드포인트 연결 생성
파이프라인 소유자가 이전 절차를 사용하여 VPC의 파이프라인에 대한 액세스 권한을 부여한 후, 연결 계정의 사용자가 VPC에 파이프라인 엔드포인트를 생성합니다. 이 섹션에는 OpenSearch Service 콘솔 및 AWS CLI를 사용하여 엔드포인트를 생성하는 절차가 포함되어 있습니다. 엔드포인트를 생성할 때 OpenSearch Ingestion은 다음 작업을 수행합니다.
+ 아직 존재하지 않는 경우 계정에 [AWSServiceRoleForAmazonOpenSearchIngestionService](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/slr-osis.html) 서비스 연결 역할을 생성합니다. 이 역할은 연결 계정의 사용자에게 [CreatePipelineEndpoint](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_CreatePipelineEndpoint.html) API 작업을 직접적으로 호출할 수 있는 권한을 부여합니다.
+ 파이프라인 엔드포인트를 생성합니다.
+ 파이프라인 소유자 VPC의 공유 파이프라인에서 데이터를 수집하도록 파이프라인 엔드포인트를 구성합니다.
**Topics**
+ [
### 파이프라인 엔드포인트 연결 생성(콘솔)
](#cross-account-pipelines-setting-up-create-pipeline-endpoints-console)
+ [
### 파이프라인 엔드포인트 연결 생성(CLI)
](#cross-account-pipelines-setting-up-create-pipeline-endpoints-cli)
### 파이프라인 엔드포인트 연결 생성(콘솔)
다음 절차에 따라 OpenSearch Service 콘솔을 사용하여 파이프라인 엔드포인트를 생성합니다.
**파이프라인 엔드포인트 연결을 생성하려면**
1. Amazon OpenSearch Service 콘솔의 탐색 창에서 **수집**을 확장한 다음 **VPC 엔드포인트**를 선택합니다.
1. **VPC 엔드포인트** 페이지에서 **생성**을 선택합니다.
1. **파이프라인 위치**에서 옵션을 선택합니다. **현재 계정**을 선택할 경우 목록에서 파이프라인을 선택합니다. **교차 계정**을 선택할 경우 필드에 파이프라인 ARN을 지정합니다. 파이프라인 소유자는 [연결 계정에 파이프라인에 대한 액세스 권한 부여](#cross-account-pipelines-setting-up-grant-access)의 설명과 같이 파이프라인에 대한 액세스 권한을 부여해야 합니다.
1. **VPC 설정** 섹션의 **VPC** 목록에서 VPC를 선택합니다.
1. **서브넷**에서 서브넷을 선택합니다.
1. **보안 그룹**에서 그룹을 선택합니다.
1. **엔드포인트 생성**을 선택합니다.
생성한 엔드포인트의 상태가 `ACTIVE`로 전환될 때까지 기다립니다. 파이프라인이 `ACTIVE` 상태가 되면 `ingestEndpointUrl`(이)라는 새 필드가 표시됩니다. 이 엔드포인트를 사용하여 파이프라인에 액세스하고 FluentBit와 같은 클라이언트를 사용하여 데이터를 수집합니다. FluentBit를 사용하여 데이터를 수집하는 데 대한 자세한 내용은 [Fluent Bit와 함께 OpenSearch Ingestion 파이프라인 사용](configure-client-fluentbit.md) 섹션을 참조하세요.
**참고**
`ingestEndpointUrl`은 모든 연결 계정에 대해 동일한 URL입니다.
### 파이프라인 엔드포인트 연결 생성(CLI)
다음 절차에 따라 AWS CLI를 사용하여 파이프라인 엔드포인트 연결을 크레이트합니다.
**파이프라인 엔드포인트 연결을 생성하려면**
1. 아직 업데이트하지 않았다면의 최신 버전 AWS CLI (버전 2.0)으로 업데이트합니다. 자세한 내용은 [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)를 참조하세요.
1. 공유 파이프라인을 AWS 리전 사용하여의 연결 계정에서 CLI를 엽니다.
1. 다음 명령을 실행해 파이프라인 엔드포인트를 생성합니다.
**참고**
계정 VPC를 연결하려면 하나 이상의 서브넷과 하나의 보안 그룹을 제공해야 합니다. 보안 그룹에는 포트 443이 포함되어야 하며, 계정 VPC 연결 시 클라이언트를 지원해야 합니다.
```
aws osis --region region create-pipeline-endpoint \
--pipeline-arn arn:aws:osis:region:connecting-account-ID:pipeline/shared-pipeline-name
--vpc-options SecurityGroupIds={sg-security-group-ID-1,sg-security-group-ID-2},SubnetIds=subnet-subnet-ID
```
1. 다음 명령을 실행하여 이전 명령에서 지정된 리전의 엔드포인트를 나열합니다.
```
aws osis --region region list-pipeline-endpoints
```
생성한 엔드포인트의 상태가 `ACTIVE`로 전환될 때까지 기다립니다. 파이프라인이 `ACTIVE` 상태가 되면 `ingestEndpointUrl`(이)라는 새 필드가 표시됩니다. 이 엔드포인트를 사용하여 파이프라인에 액세스하고 FluentBit와 같은 클라이언트를 사용하여 데이터를 수집합니다. FluentBit를 사용하여 데이터를 수집하는 데 대한 자세한 내용은 [Fluent Bit와 함께 OpenSearch Ingestion 파이프라인 사용](configure-client-fluentbit.md) 섹션을 참조하세요.
**참고**
`ingestEndpointUrl`은 모든 연결 계정에 대해 동일한 URL입니다.
## 파이프라인 엔드포인트 제거
공유 파이프라인에 대한 액세스를 더 이상 제공하지 않으려는 경우, 다음 방법 중 하나를 사용하여 파이프라인 엔드포인트를 제거할 수 있습니다.
+ 파이프라인 엔드포인트(연결 계정)를 삭제합니다.
+ 파이프라인 엔드포인트(파이프라인 소유자)를 취소합니다.
다음 절차에 따라 연결 계정에서 파이프라인 엔드포인트를 삭제합니다.
**파이프라인 엔드포인트를 삭제하려면(연결 계정)**
1. 공유 파이프라인을 AWS 리전 사용하여의 연결 계정에서 CLI를 엽니다.
1. 다음 명령을 실행하여 리전의 파이프라인 엔드포인트를 나열합니다.
```
aws osis --region region list-pipeline-endpoints
```
삭제할 파이프라인 ID를 기록해 둡니다.
1. 다음 명령을 실행하여 파이프라인 엔드포인트를 제거합니다.
```
aws osis --region region delete-pipeline-endpoint \
--endpoint-id 'ID'
```
공유 파이프라인의 파이프라인 소유자가 다음 절차에 따라 파이프라인 엔드포인트를 취소합니다.
**파이프라인 엔드포인트를 취소하려면(파이프라인 소유자)**
1. 공유 파이프라인을 AWS 리전 사용하여의 연결 계정에서 CLI를 엽니다.
1. 다음 명령을 실행하여 리전의 파이프라인 엔드포인트 연결을 나열합니다.
```
aws osis --region region list-pipeline-endpoint-connections
```
삭제할 파이프라인 ID를 기록해 둡니다.
1. 다음 명령을 실행하여 파이프라인 엔드포인트를 제거합니다.
```
aws osis --region region revoke-pipeline-endpoint-connections \
--pipeline-arn pipeline-arn --endpoint-ids ID
```
이 명령은 엔드포인트 ID를 하나만 지정할 수 있도록 지원합니다.
# Amazon OpenSearch Ingestion에 대한 자격 증명 및 액세스 관리자
AWS Identity and Access Management (IAM)는 관리자가 AWS 리소스에 대한 액세스를 안전하게 제어하는 데 도움이 AWS 서비스 되는 입니다. IAM 관리자는 어떤 사용자가 OpenSearch Ingestion 리소스를 사용할 수 있는 *인증*(로그인) 및 *권한*(권한 있음)을 받을 수 있는지 제어합니다. IAM은 추가 비용 없이 사용할 수 AWS 서비스 있는 입니다.
**Topics**
+ [
## OpenSearch Ingestion에 대한 자격 증명 기반 정책
](#security-iam-ingestion-id-based-policies)
+ [
## OpenSearch Ingestion의 정책 작업
](#security-iam-ingestion-id-based-policies-actions)
+ [
## OpenSearch Ingestion의 정책 리소스
](#security-iam-ingestion-id-based-policies-resources)
+ [
## Amazon OpenSearch Ingestion의 정책 조건 키
](#security_iam_ingestion-conditionkeys)
+ [
## OpenSearch Ingestion을 통한 ABAC
](#security_iam_ingestion-with-iam-tags)
+ [
## OpenSearch Ingestion에서 임시 보안 인증 정보 사용
](#security_iam_ingestion-tempcreds)
+ [
## OpenSearch Ingestion에 대한 서비스 연결 역할
](#security_iam_ingestion-slr)
+ [
## OpenSearch Ingestion에 대한 자격 증명 기반 정책의 예
](#security_iam_ingestion_id-based-policy-examples)
## OpenSearch Ingestion에 대한 자격 증명 기반 정책
**ID 기반 정책 지원:** 예
ID 기반 정책은 IAM 사용자, 사용자 그룹 또는 역할과 같은 ID에 연결할 수 있는 JSON 권한 정책 문서입니다. 이러한 정책은 사용자 및 역할이 어떤 리소스와 어떤 조건에서 어떤 작업을 수행할 수 있는지를 제어합니다. 자격 증명 기반 정책을 생성하는 방법을 알아보려면 *IAM 사용 설명서*에서 [고객 관리형 정책으로 사용자 지정 IAM 권한 정의](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)를 참조하세요.
IAM ID 기반 정책을 사용하면 허용되거나 거부되는 작업과 리소스뿐 아니라 작업이 허용되거나 거부되는 조건을 지정할 수 있습니다. JSON 정책에서 사용할 수 있는 모든 요소에 대해 알아보려면 *IAM 사용 설명서*의 [IAM JSON 정책 요소 참조](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html)를 참조하세요.
### OpenSearch Ingestion에 대한 자격 증명 기반 정책의 예
OpenSearch Ingestion 자격 증명 기반 정책의 예를 보려면 [OpenSearch Ingestion에 대한 자격 증명 기반 정책의 예](#security_iam_ingestion_id-based-policy-examples)을(를) 참조하세요.
## OpenSearch Ingestion의 정책 작업
**정책 작업 지원:** 예
JSON 정책의 `Action`요소는 정책에서 액세스를 허용하거나 거부하는 데 사용할 수 있는 작업을 설명합니다. 정책 작업은 일반적으로 연결된 AWS API 작업과 이름이 동일합니다. 일치하는 API 작업이 없는 권한 *전용 작업* 같은 몇 가지 예외도 있습니다. 정책에서 여러 작업이 필요한 몇 가지 작업도 있습니다. 이러한 추가 작업을 일컬어 *종속 작업*이라고 합니다.
연결된 작업을 수행할 수 있는 권한을 부여하기 위한 정책에 작업을 포함하세요.
OpenSearch Ingestion의 정책 작업은 작업 앞에 다음 접두사를 사용합니다.
```
osis
```
단일 문에서 여러 작업을 지정하려면 쉼표로 구분합니다.
```
"Action": [
"osis:action1",
"osis:action2"
]
```
와일드카드 문자(\$1)를 사용하여 여러 작업을 지정할 수 있습니다. 예를 들어, `List`라는 단어로 시작하는 모든 작업을 지정하려면 다음 작업을 포함합니다.
```
"Action": "osis:List*"
```
OpenSearch Ingestion 자격 증명 기반 정책의 예를 보려면 [OpenSearch Serverless에 대한 자격 증명 기반 정책 예시](security-iam-serverless.md#security_iam_id-based-policy-examples)을(를) 참조하세요.
## OpenSearch Ingestion의 정책 리소스
**정책 리소스 지원:** 예
관리자는 AWS JSON 정책을 사용하여 누가 무엇에 액세스할 수 있는지 지정할 수 있습니다. 즉, 어떤 **보안 주체**가 어떤 **리소스**와 어떤 **조건**에서 **작업**을 수행할 수 있는지를 지정할 수 있습니다.
`Resource` JSON 정책 요소는 작업이 적용되는 하나 이상의 객체를 지정합니다. 모범 사례에 따라 [Amazon 리소스 이름(ARN)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html)을 사용하여 리소스를 지정합니다. 리소스 수준 권한을 지원하지 않는 작업의 경우, 와일드카드(\$1)를 사용하여 해당 문이 모든 리소스에 적용됨을 나타냅니다.
```
"Resource": "*"
```
## Amazon OpenSearch Ingestion의 정책 조건 키
**서비스별 정책 조건 키 지원:** 아니요
관리자는 AWS JSON 정책을 사용하여 누가 무엇에 액세스할 수 있는지 지정할 수 있습니다. 즉, 어떤 **보안 주체**가 어떤 **리소스**와 어떤 **조건**에서 **작업**을 수행할 수 있는지를 지정할 수 있습니다.
`Condition` 요소는 정의된 기준에 따라 문이 실행되는 시기를 지정합니다. 같음(equals) 또는 미만(less than)과 같은 [조건 연산자](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html)를 사용하여 정책의 조건을 요청의 값과 일치시키는 조건식을 생성할 수 있습니다. 모든 AWS 전역 조건 키를 보려면 *IAM 사용 설명서*의 [AWS 전역 조건 컨텍스트 키를](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) 참조하세요.
OpenSearch Ingestion 조건 키 목록을 보려면 **서비스 승인 참조의 [Amazon OpenSearch Ingestion에 대한 조건 키](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonopensearchingestion.html#amazonopensearchingestion-policy-keys)를 참조하세요. 조건 키를 사용할 수 있는 작업과 리소스에 대해 알아보려면 [Amazon OpenSearch Ingestion에서 정의한 작업](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonopensearchingestion.html#amazonopensearchingestion-actions-as-permissions)을 참조하세요.
## OpenSearch Ingestion을 통한 ABAC
**ABAC 지원(정책의 태그):** 예
속성 기반 액세스 제어(ABAC)는 태그라고 불리는 속성을 기반으로 권한을 정의하는 권한 부여 전략입니다. IAM 엔터티 및 AWS 리소스에 태그를 연결한 다음 보안 주체의 태그가 리소스의 태그와 일치할 때 작업을 허용하는 ABAC 정책을 설계할 수 있습니다.
태그에 근거하여 액세스를 제어하려면 `aws:ResourceTag/key-name`, `aws:RequestTag/key-name`또는 `aws:TagKeys`조건 키를 사용하여 정책의 [조건 요소](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html)에 태그 정보를 제공합니다.
서비스가 모든 리소스 유형에 대해 세 가지 조건 키를 모두 지원하는 경우, 값은 서비스에 대해 **예**입니다. 서비스가 일부 리소스 유형에 대해서만 세 가지 조건 키를 모두 지원하는 경우, 값은 **부분적**입니다.
ABAC에 대한 자세한 내용은 *IAM 사용 설명서*의 [ABAC 권한 부여를 통한 권한 정의](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html)를 참조하세요. ABAC 설정 단계가 포함된 자습서를 보려면 *IAM 사용 설명서*의 [속성 기반 액세스 제어(ABAC) 사용](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html)을 참조하세요.
OpenSearch Ingestion 리소스 태그 지정에 대한 자세한 내용은 [Amazon OpenSearch Ingestion 파이프라인 태그 지정](tag-pipeline.md) 섹션을 참조하세요.
## OpenSearch Ingestion에서 임시 보안 인증 정보 사용
**임시 자격 증명 지원:** 예
임시 자격 증명은 AWS 리소스에 대한 단기 액세스를 제공하며 페더레이션 또는 전환 역할을 사용할 때 자동으로 생성됩니다. 장기 액세스 키를 사용하는 대신 임시 자격 증명을 동적으로 생성하는 것이 AWS 좋습니다. 자세한 내용은 *IAM 사용 설명서*의 [IAM의 임시 보안 자격 증명](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) 및 [IAM으로 작업하는AWS 서비스](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) 섹션을 참조하세요.
## OpenSearch Ingestion에 대한 서비스 연결 역할
**서비스 연결 역할 지원:** 예
서비스 연결 역할은에 연결된 서비스 역할의 한 유형입니다 AWS 서비스. 서비스는 사용자를 대신하여 작업을 수행하기 위해 역할을 수임할 수 있습니다. 서비스 연결 역할은에 나타나 AWS 계정 며 서비스가 소유합니다. IAM 관리자는 서비스 연결 역할의 권한을 볼 수 있지만 편집은 할 수 없습니다.
OpenSearch Ingestion은 `AWSServiceRoleForAmazonOpenSearchIngestionService`라는 서비스 연결 역할을 사용합니다. `AWSServiceRoleForOpensearchIngestionSelfManagedVpce`라는 서비스 연결 역할은 자체 관리형 VPC 엔드포인트가 있는 파이프라인에서도 사용할 수 있습니다. OpenSearch Ingestion 서비스 연결 역할 생성 및 관리에 대한 자세한 내용은 [서비스 연결 역할을 사용하여 OpenSearch Ingestion 파이프라인 생성](slr-osis.md) 섹션을 참조하세요.
## OpenSearch Ingestion에 대한 자격 증명 기반 정책의 예
기본적으로 사용자 및 역할에는 OpenSearch Ingestion 리소스를 생성하거나 수정할 수 있는 권한이 없습니다. 사용자에게 사용자가 필요한 리소스에서 작업을 수행할 권한을 부여하려면 IAM 관리자가 IAM 정책을 생성하면 됩니다.
이러한 예제 JSON 정책 문서를 사용하여 IAM ID 기반 정책을 생성하는 방법을 알아보려면 *IAM 사용 설명서*의 [IAM 정책 생성(콘솔)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html)을 참조하세요.
각 리소스 유형에 대한 ARN의 형식을 포함하여 Amazon OpenSearch Ingestion에서 정의한 작업 및 리소스 유형에 대한 자세한 내용은 **서비스 승인 참조의 [Amazon OpenSearch Ingestion에 대한 작업, 리소스 및 조건 키](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonopensearchingestion.html)를 참조하세요.
**Topics**
+ [
### 정책 모범 사례
](#security_iam_ingestion-policy-best-practices)
+ [
### 콘솔에서 OpenSearch Ingestion 사용
](#security_iam_ingestion_id-based-policy-examples-console)
+ [
### OpenSearch Ingestion 파이프라인 관리
](#security_iam_id-based-policy-examples-pipeline-admin)
+ [
### OpenSearch Ingestion 파이프라인으로 데이터 수집
](#security_iam_id-based-policy-examples-ingest-data)
### 정책 모범 사례
자격 증명 기반 정책은 매우 강력합니다. 이 정책은 계정에서 사용자가 OpenSearch Ingestion 리소스를 생성, 액세스 또는 삭제할 수 있는지 여부를 결정합니다. 이 작업으로 인해 AWS 계정에 비용이 발생할 수 있습니다. ID 기반 정책을 생성하거나 편집할 때는 다음 지침과 권장 사항을 따르세요.
ID 기반 정책에 따라 계정에서 사용자가 OpenSearch Ingestion 리소스를 생성, 액세스 또는 삭제할 수 있는지 여부가 결정됩니다. 이 작업으로 인해 AWS 계정에 비용이 발생할 수 있습니다. ID 기반 정책을 생성하거나 편집할 때는 다음 지침과 권장 사항을 따르세요.
+ ** AWS 관리형 정책을 시작하고 최소 권한으로 전환 -** 사용자 및 워크로드에 권한 부여를 시작하려면 많은 일반적인 사용 사례에 대한 권한을 부여하는 *AWS 관리형 정책을* 사용합니다. 에서 사용할 수 있습니다 AWS 계정. 사용 사례에 맞는 AWS 고객 관리형 정책을 정의하여 권한을 추가로 줄이는 것이 좋습니다. 자세한 내용은 *IAM 사용 설명서*의 [AWS 관리형 정책](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) 또는 [AWS 직무에 대한 관리형 정책](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html)을 참조하세요.
+ **최소 권한 적용** – IAM 정책을 사용하여 권한을 설정하는 경우, 작업을 수행하는 데 필요한 권한만 부여합니다. 이렇게 하려면 *최소 권한*으로 알려진 특정 조건에서 특정 리소스에 대해 수행할 수 있는 작업을 정의합니다. IAM을 사용하여 권한을 적용하는 방법에 대한 자세한 정보는 *IAM 사용 설명서*에 있는 [IAM의 정책 및 권한](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html)을 참조하세요.
+ **IAM 정책의 조건을 사용하여 액세스 추가 제한** – 정책에 조건을 추가하여 작업 및 리소스에 대한 액세스를 제한할 수 있습니다. 예를 들어, SSL을 사용하여 모든 요청을 전송해야 한다고 지정하는 정책 조건을 작성할 수 있습니다. AWS 서비스와 같은 특정를 통해 사용되는 경우 조건을 사용하여 서비스 작업에 대한 액세스 권한을 부여할 수도 있습니다 CloudFormation. 자세한 내용은 *IAM 사용 설명서*의 [IAM JSON 정책 요소: 조건](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html)을 참조하세요.
+ **IAM Access Analyzer를 통해 IAM 정책을 확인하여 안전하고 기능적인 권한 보장** - IAM Access Analyzer에서는 IAM 정책 언어(JSON)와 모범 사례가 정책에서 준수되도록 새로운 및 기존 정책을 확인합니다. IAM Access Analyzer는 100개 이상의 정책 확인 항목과 실행 가능한 추천을 제공하여 안전하고 기능적인 정책을 작성하도록 돕습니다. 자세한 내용은 *IAM 사용 설명서*의 [IAM Access Analyzer에서 정책 검증](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-policy-validation.html)을 참조하세요.
+ **다중 인증(MFA) 필요 -**에서 IAM 사용자 또는 루트 사용자가 필요한 시나리오가 있는 경우 추가 보안을 위해 MFA를 AWS 계정켭니다. API 작업을 직접적으로 호출할 때 MFA가 필요하면 정책에 MFA 조건을 추가합니다. 자세한 내용은 *IAM 사용 설명서*의 [MFA를 통한 보안 API 액세스](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_configure-api-require.html)를 참조하세요.
IAM의 모범 사례에 대한 자세한 내용은 *IAM 사용 설명서*의 [IAM의 보안 모범 사례](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)를 참조하세요.
### 콘솔에서 OpenSearch Ingestion 사용
OpenSearch Service 콘솔 내에서 OpenSearch Ingestion에 액세스하려면 최소한의 권한 집합이 있어야 합니다. 이러한 권한은 AWS 계정의 OpenSearch Ingestion 리소스에 대한 세부 정보를 나열하고 볼 수 있도록 허용해야 합니다. 최소 필수 권한보다 더 제한적인 ID 기반 정책을 생성하면 콘솔이 해당 정책이 있는 개체(예: IAM 역할)에 대해 의도한 대로 작동하지 않습니다.
AWS CLI 또는 AWS API만 호출하는 사용자에게 최소 콘솔 권한을 허용할 필요는 없습니다. 그 대신 수행하려는 API 작업과 일치하는 작업에만 액세스할 수 있도록 합니다.
다음 정책은 사용자가 OpenSearch Service 콘솔 내에서 OpenSearch Ingestion에 액세스할 수 있도록 허용합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Resource": "*",
"Effect": "Allow",
"Action": [
"osis:ListPipelines",
"osis:GetPipeline",
"osis:ListPipelineBlueprints",
"osis:GetPipelineBlueprint",
"osis:GetPipelineChangeProgress"
]
}
]
}
```
------
또는의 모든 OpenSearch Ingestion 리소스에 대한 읽기 전용 액세스 권한을 부여하는 [AmazonOpenSearchIngestionReadOnlyAccess](ac-managed.md#AmazonOpenSearchIngestionReadOnlyAccess) AWS 관리형 정책을 사용할 수 있습니다 AWS 계정.
### OpenSearch Ingestion 파이프라인 관리
이 정책은 사용자가 Amazon OpenSearch Ingestion 파이프라인을 관리할 수 있도록 하는 파이프라인 관리자’ 정책의 예시입니다. 사용자는 파이프라인을 생성, 확인 및 삭제할 수 있습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Resource": "arn:aws:osis:us-east-1:111122223333:pipeline/*",
"Action": [
"osis:CreatePipeline",
"osis:DeletePipeline",
"osis:UpdatePipeline",
"osis:ValidatePipeline",
"osis:StartPipeline",
"osis:StopPipeline"
],
"Effect": "Allow"
},
{
"Resource": "*",
"Action": [
"osis:ListPipelines",
"osis:GetPipeline",
"osis:ListPipelineBlueprints",
"osis:GetPipelineBlueprint",
"osis:GetPipelineChangeProgress"
],
"Effect": "Allow"
}
]
}
```
------
### OpenSearch Ingestion 파이프라인으로 데이터 수집
이 예시 정책을 통해 사용자 또는 기타 엔티티는 계정의 Amazon OpenSearch Ingestion 파이프라인으로 데이터를 수집할 수 있습니다. 사용자는 파이프라인을 수정할 수 없습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Resource": "arn:aws:osis:us-east-1:123456789012:pipeline/*",
"Action": [
"osis:Ingest"
],
"Effect": "Allow"
}
]
}
```
------
# 를 사용하여 Amazon OpenSearch Ingestion API 호출 로깅 AWS CloudTrail
Amazon OpenSearch Ingestion은 OpenSearch Ingestion에서 사용자 AWS CloudTrail, 역할 또는 서비스가 수행한 작업에 대한 레코드를 제공하는 AWS 서비스와 통합됩니다.
CloudTrail은 OpenSearch Ingestion에 대한 모든 API 직접 호출을 이벤트로 캡처합니다. 캡처된 호출에는 OpenSearch Service 콘솔의 OpenSearch Ingestion 섹션에서의 호출과 OpenSearch Ingestion API 작업에 대한 코드 호출이 포함됩니다.
추적을 생성하면 OpenSearch Ingestion 에 대한 이벤트를 포함한 CloudTrail 이벤트를 지속해서 Amazon S3 버킷에 배포할 수 있습니다. 추적을 구성하지 않은 경우에도 **이벤트 기록**에서 CloudTrail 콘솔의 최신 이벤트를 볼 수 있습니다.
CloudTrail에서 수집한 정보를 사용하여 OpenSearch Ingestion 에 수행된 요청, 요청이 수행된 IP 주소, 요청을 수행한 사람, 요청이 수행된 시간 및 추가 세부 정보를 확인할 수 있습니다.
CloudTrail에 대한 자세한 내용은 [AWS CloudTrail 사용 설명서](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html)를 참조하세요.
## CloudTrail의 OpenSearch Ingestion 정보
CloudTrail은 계정을 생성할 AWS 계정 때에서 활성화됩니다. OpenSearch Ingestion에서 활동이 발생하면 해당 활동이 **이벤트 기록**의 다른 AWS 서비스 이벤트와 함께 CloudTrail 이벤트에 기록됩니다. AWS 계정에서 최신 이벤트를 확인, 검색 및 다운로드할 수 있습니다. 자세한 내용은 [CloudTrail 이벤트 기록을 사용하여 이벤트 보기](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html)를 참조하세요.
OpenSearch Ingestion에 대한 이벤트를 AWS 계정포함하여에 이벤트를 지속적으로 기록하려면 추적을 생성합니다. CloudTrail은 *추적*을 사용하여 Amazon S3 버킷으로 로그 파일을 전송할 수 있습니다. 콘솔에서 트레일을 생성하면 기본적으로 모든 AWS 리전에 트레일이 적용됩니다.
추적은 AWS 파티션의 모든 리전에서 이벤트를 로깅하고 지정한 Amazon S3 버킷으로 로그 파일을 전송합니다. 또한 CloudTrail 로그에서 수집된 이벤트 데이터를 추가로 분석하고 조치를 취하도록 다른 AWS 서비스를 구성할 수 있습니다. 자세한 내용은 다음 자료를 참조하세요.
+ [추적 생성 개요](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail 지원 서비스 및 통합](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html)
+ [CloudTrail에 대한 Amazon SNS 알림 구성](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html)
+ [여러 리전에서 CloudTrail 로그 파일 받기](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) 및 [여러 계정에서 CloudTrail 로그 파일 받기](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
모든 OpenSearch Ingestion 작업은 CloudTrail에 의해 기록되며 [OpenSearch Serverless API 참조](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_Operations_Amazon_OpenSearch_Ingestion.html)에 문서화됩니다. 예를 들어 `CreateCollection`, `ListCollections` 및 `DeleteCollection` 작업을 직접적으로 호출하면 CloudTrail 로그 파일에 항목이 생성됩니다.
모든 이벤트 또는 로그 항목에는 요청을 생성했던 사용자에 관한 정보가 포함됩니다. 자격 증명 정보를 이용하면 다음을 판단하는 데 도움이 됩니다.
+ 요청이 루트 또는 AWS Identity and Access Management (IAM) 사용자 자격 증명으로 이루어졌는지 여부입니다.
+ 역할 또는 페더레이션 사용자의 임시 자격 증명을 사용하여 요청이 생성되었는지 여부.
+ 요청이 다른 AWS 서비스에서 이루어졌는지 여부입니다.
자세한 내용은 [CloudTrail userIdentity 요소](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)를 참조하세요.
## OpenSearch Ingestion 로그 파일 항목 이해
추적이란 지정한 Amazon S3 버킷에 이벤트를 로그 파일로 입력할 수 있게 하는 구성입니다. CloudTrail 로그 파일에는 하나 이상의 로그 항목이 포함될 수 있습니다.
이벤트는 모든 소스로부터 단일 요청을 나타냅니다. 요청된 작업, 모든 파라미터, 작업 날짜와 시간, 요청 파라미터 등에 대한 정보가 들어 있습니다. CloudTrail 로그 파일은 퍼블릭 API 직접 호출의 주문 스택 트레이스가 아니므로 특정 순서로 표시되지 않습니다.
다음은 `DeletePipeline` 작업을 보여주는 CloudTrail 로그 항목이 나타낸 예시입니다.
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn":"arn:aws:iam::123456789012:user/test-user",
"accountId": "123456789012",
"accessKeyId": "access-key",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws:iam::123456789012:role/Admin",
"accountId": "123456789012",
"userName": "Admin"
},
"webIdFederationData": {},
"attributes": {
"creationDate": "2023-04-21T16:48:33Z",
"mfaAuthenticated": "false"
}
}
},
"eventTime": "2023-04-21T16:49:22Z",
"eventSource": "osis.amazonaws.com",
"eventName": "UpdatePipeline",
"awsRegion": "us-west-2",
"sourceIPAddress": "123.456.789.012",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36",
"requestParameters": {
"pipelineName": "my-pipeline",
"pipelineConfigurationBody": "version: \"2\"\nlog-pipeline:\n source:\n http:\n path: \"/test/logs\"\n processor:\n - grok:\n match:\n log: [ '%{COMMONAPACHELOG}' ]\n - date:\n from_time_received: true\n destination: \"@timestamp\"\n sink:\n - opensearch:\n hosts: [ \"https://search-b5zd22mwxhggheqpj5ftslgyle.us-west-2.es.amazonaws.com\" ]\n index: \"apache_logs2\"\n aws_sts_role_arn: \"arn:aws:iam::709387180454:role/canary-bootstrap-OsisRole-J1BARLD26QKN\"\n aws_region: \"us-west-2\"\n aws_sigv4: true\n"
},
"responseElements": {
"pipeline": {
"pipelineName": "my-pipeline",sourceIPAddress
"pipelineArn": "arn:aws:osis:us-west-2:123456789012:pipeline/my-pipeline",
"minUnits": 1,
"maxUnits": 1,
"status": "UPDATING",
"statusReason": {
"description": "An update was triggered for the pipeline. It is still available to ingest data."
},
"pipelineConfigurationBody": "version: \"2\"\nlog-pipeline:\n source:\n http:\n path: \"/test/logs\"\n processor:\n - grok:\n match:\n log: [ '%{COMMONAPACHELOG}' ]\n - date:\n from_time_received: true\n destination: \"@timestamp\"\n sink:\n - opensearch:\n hosts: [ \"https://search-b5zd22mwxhggheqpj5ftslgyle.us-west-2.es.amazonaws.com\" ]\n index: \"apache_logs2\"\n aws_sts_role_arn: \"arn:aws:iam::709387180454:role/canary-bootstrap-OsisRole-J1BARLD26QKN\"\n aws_region: \"us-west-2\"\n aws_sigv4: true\n",
"createdAt": "Mar 29, 2023 1:03:44 PM",
"lastUpdatedAt": "Apr 21, 2023 9:49:21 AM",
"ingestEndpointUrls": [
"my-pipeline-tu33ldsgdltgv7x7tjqiudvf7m.us-west-2.osis.amazonaws.com"
]
}
},
"requestID": "12345678-1234-1234-1234-987654321098",
"eventID": "12345678-1234-1234-1234-987654321098",
"readOnly": false,
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "709387180454",
"eventCategory": "Management",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"clientProvidedHostHeader": "osis.us-west-2.amazonaws.com"
},
"sessionCredentialFromConsole": "true"
}
```
# Amazon OpenSearch Ingestion 및 인터페이스 엔드포인트 API(AWS PrivateLink)
*인터페이스* VPC 엔드포인트를 생성하여 VPC와 OpenSearch Ingestion API 엔드포인트 간에 프라이빗 연결을 설정할 수 있습니다. 인터페이스 엔드포인트는 로 구동됩니다[AWS PrivateLink](https://aws.amazon.com/privatelink)
AWS PrivateLink 를 사용하면 인터넷 게이트웨이, NAT 디바이스, VPN 연결 또는 Direct Connect 연결 없이 OpenSearch Ingestion API 작업에 비공개로 액세스할 수 있습니다. VPC의 리소스는 파이프라인을 생성, 수정 또는 삭제하기 위해 OpenSearch Ingestion API 엔드포인트와 통신하는 데 퍼블릭 IP 주소가 필요하지 않습니다. VPC와 OpenSearch Ingestion 간의 트래픽은 Amazon 네트워크를 벗어나지 않습니다.
**참고**
이 주제에서는 VPC 내에서 파이프라인을 관리(생성, 업데이트, 삭제)할 수 있는 OpenSearch Ingestion *API*에 액세스하기 위한 VPC 엔드포인트를 다룹니다. 이는 VPC 내의 소스에서 파이프라인으로 데이터가 수집되는 방식을 제어하는 파이프라인 *자체에 대한* VPC 액세스를 구성하는 것과 다릅니다. 파이프라인에 대한 VPC 액세스 구성에 대한 자세한 내용은 섹션을 참조하세요[Amazon OpenSearch Ingestion 파이프라인에 대한 VPC 액세스 구성](pipeline-security.md).
각 인터페이스 엔드포인트는 서브넷에서 하나 이상의 탄력적 네트워크 인터페이스로 표현됩니다. 탄력적 네트워크 인터페이스에 대한 자세한 내용은 *Amazon EC2 사용 설명서*의 [탄력적 네트워크 인터페이스](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)를 참조하세요.
VPC 엔드포인트에 대한 자세한 내용은 *Amazon* [VPC 사용 설명서의 인터페이스 VPC 엔드포인트(AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html)를 참조하세요. OpenSearch Ingestion API 작업에 대한 자세한 내용은 [OpenSearch Ingestion API 참조](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_Operations_Amazon_OpenSearch_Ingestion.html)를 참조하세요.
## VPC 엔드포인트에 대한 고려 사항
OpenSearch Ingestion API 엔드포인트에 대한 인터페이스 VPC 엔드포인트를 설정하기 전에 *Amazon VPC 사용 설명서*의 [인터페이스 엔드포인트 속성 및 제한](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#vpce-interface-limitations) 사항을 검토해야 합니다.
OpenSearch Ingestion 리소스 관리와 관련된 모든 OpenSearch Ingestion API 작업은를 사용하여 VPC에서 사용할 수 있습니다 AWS PrivateLink.
VPC 엔드포인트 정책은 OpenSearch Ingestion API 엔드포인트에 대해 지원됩니다. 기본적으로 엔드포인트를 통해 OpenSearch Ingestion API 작업에 대한 전체 액세스가 허용됩니다. 자세한 내용은 *Amazon VPC 사용 설명서*의 [VPC 엔드포인트를 통해 서비스에 대한 액세스 제어](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html)를 참조하세요.
## 가용성
OpenSearch Ingestion API는 현재 모든 OpenSearch Ingestion 리전에서 VPC 엔드포인트를 지원합니다.
현재 FIPS 엔드포인트는 지원되지 않습니다.
## OpenSearch Ingestion API에 대한 인터페이스 VPC 엔드포인트 생성
Amazon VPC 콘솔 또는 AWS Command Line Interface ()를 사용하여 OpenSearch Ingestion API에 대한 VPC 엔드포인트를 생성할 수 있습니다AWS CLI. 자세한 내용은 *Amazon VPC 사용 설명서*의 [인터페이스 엔드포인트 생성](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint)을 참조하세요.
서비스 이름를 사용하여 OpenSearch Ingestion API용 VPC 엔드포인트를 생성합니다`com.amazonaws.region.osis`.
엔드포인트에 대해 프라이빗 DNS를 활성화하는 경우 AWS 리전의 기본 DNS 이름을 사용하여 VPC 엔드포인트를 사용하여 OpenSearch Ingestion에 API 요청을 할 수 있습니다. 예: `osis.us-east-1.amazonaws.com`.
자세한 내용은 *Amazon VPC 사용 설명서*의 [인터페이스 엔드포인트를 통해 서비스 액세스](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#access-service-though-endpoint)를 참조하세요.
## OpenSearch Ingestion API에 대한 VPC 엔드포인트 정책 생성
OpenSearch Ingestion API에 대한 액세스를 제어하는 엔드포인트 정책을 VPC 엔드포인트에 연결할 수 있습니다. 이 정책은 다음 정보를 지정합니다.
+ 작업을 수행할 수 있는 위탁자.
+ 수행할 수 있는 작업.
+ 작업을 수행할 수 있는 리소스.
자세한 내용은 *Amazon VPC 사용 설명서*의 [VPC 엔드포인트를 통해 서비스에 대한 액세스 제어](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html)를 참조하세요.
**예: OpenSearch Ingestion API 작업에 대한 VPC 엔드포인트 정책**
다음은 OpenSearch Ingestion API에 대한 엔드포인트 정책의 예입니다. 엔드포인트에 연결되면이 정책은 모든 리소스의 모든 보안 주체에 대해 나열된 OpenSearch Ingestion API 작업에 대한 액세스 권한을 부여합니다.
```
{
"Statement":[
{
"Principal":"*",
"Effect":"Allow",
"Action":[
"osis:CreatePipeline",
"osis:UpdatePipeline",
"osis:DeletePipeline"
],
"Resource":"*"
}
]
}
```
**예: 지정된 AWS 계정의 모든 액세스를 거부하는 VPC 엔드포인트 정책**
다음 VPC 엔드포인트 정책은 엔드포인트를 사용하여 리소스에 대한 `123456789012` 모든 액세스를 AWS 거부합니다. 이 정책은 다른 계정의 모든 작업을 허용합니다.
```
{
"Statement": [
{
"Action": "*",
"Effect": "Allow",
"Resource": "*",
"Principal": "*"
},
{
"Action": "*",
"Effect": "Deny",
"Resource": "*",
"Principal": { "AWS": [ "123456789012" ] }
}
]
}
```
# Amazon OpenSearch Ingestion 파이프라인 태그 지정
태그를 사용하면 Amazon OpenSearch Service 도메인에 임의 정보를 할당할 수 있으므로 해당 정보를 분류하고 필터링할 수 있습니다. *태그*는 사용자가 할당하거나가 AWS 리소스에 AWS 할당하는 메타데이터 레이블입니다. 각 태그는 *키*와 *값*으로 구성됩니다. 사용자가 할당하는 태그에 대해 키와 값을 정의합니다. 예를 들어 키를 `stage`로 정의하고 리소스 하나의 값을 `test`로 정의할 수 있습니다.
태그는 다음을 지원합니다.
+ AWS 리소스를 식별하고 구성합니다. 많은 AWS 서비스가 태그 지정을 지원하므로 다른 서비스의 리소스에 동일한 태그를 할당하여 리소스가 관련이 있음을 나타낼 수 있습니다. 예를 들어 Amazon OpenSearch Service 도메인에 할당하는 것과 동일한 태그를 OpenSearch Serverless 컬렉션에 할당할 수 있습니다.
+ AWS 비용을 추적합니다. AWS 결제 및 비용 관리 대시보드에서 이러한 태그를 활성화합니다.는 태그를 AWS 사용하여 비용을 분류하고 월별 비용 할당 보고서를 제공합니다. 자세한 내용은 [AWS Billing 사용 설명서](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/)의 [비용 할당 태그 사용](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html)을 참조하세요.
+ 속성 기반 액세스 제어를 사용하여 파이프라인에 대한 액세스를 제한합니다. 예제 정책과 자세한 내용은 IAM 사용 설명서의 [태그 키를 기반으로 액세스 제어](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys) 섹션을 참조하세요.
에서는 파이프라인이 기본 리소스입니다. OpenSearch Service 콘솔, AWS CLI, OpenSearch Ingestion APIs 또는 AWS SDKs를 사용하여 파이프라인에서 태그를 추가, 관리 및 제거할 수 있습니다.
**Topics**
+ [
## 필요한 권한
](#pipeline-tag-permissions)
+ [
## 태그 작업(콘솔)
](#tag-pipeline-console)
+ [
## 태그 작업(AWS CLI)
](#tag-pipeline-cli)
## 필요한 권한
OpenSearch Ingestion은 파이프라인에 태그를 지정하는 데 다음 AWS Identity and Access Management Access Analyzer (IAM) 권한을 사용합니다.
+ `osis:TagResource`
+ `osis:ListTagsForResource`
+ `osis:UntagResource`
각 권한에 대한 자세한 내용은 *서비스 권한 부여 참조*에서 [OpenSearch Ingestion에 대한 작업, 리소스 및 조건 키](https://docs.aws.amazon.com/service-authorization/latest/reference/list_opensearchingestionservice.html)에 대한 액션, 리소스 및 조건 키를 참조하세요.
## 태그 작업(콘솔)
콘솔은 도메인에 태그를 지정하는 가장 간단한 방법입니다.
****태그를 만들려면****
1. [https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) Amazon OpenSearch Service 콘솔에 로그인합니다. 파이프라인 페이지에 표시됩니다.
1. 태그를 추가할 파이프라인을 선택한 다음 **태그** 탭으로 이동합니다.
1. [**관리(Manage)**], [**새 태그 추가(Add new tag)**]를 선택합니다.
1. 태그 키와 선택 값을 입력합니다.
1. **저장**을 선택합니다.
태그를 삭제하려면 동일한 단계를 따르고 [**태그 관리(Manage tags)**] 페이지에서 [**제거(Remove)**]를 선택합니다.
콘솔을 사용한 태그 작업에 대한 자세한 내용은 *AWS 관리 콘솔 시작 안내서*에서 [Tag Editor](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/tag-editor.html)를 참조하세요.
## 태그 작업(AWS CLI)
를 사용하여 파이프라인에 태그를 지정하려면 `TagResource` 요청을 AWS CLI보냅니다.
```
aws osis tag-resource
--arn arn:aws:osis:us-east-1:123456789012:pipeline/my-pipeline
--tags Key=service,Value=osis Key=source,Value=otel
```
`UntagResource` 명령을 사용하여 파이프라인에서 태그를 제거합니다.
```
aws osis untag-resource
--arn arn:aws:osis:us-east-1:123456789012:pipeline/my-pipeline
--tag-keys service
```
`ListTagsForResource` 명령을 사용하여 파이프라인의 기존 태그를 확인합니다.
```
aws osis list-tags-for-resource
--arn arn:aws:osis:us-east-1:123456789012:pipeline/my-pipeline
```
# Amazon CloudWatch를 사용한 Amazon OpenSearch Ingestion로깅 및 모니터링
Amazon OpenSearch Ingestion은 지표 및 로그를 Amazon CloudWatch에 게시합니다.
**Topics**
+ [
# 파이프라인 모니터링
](monitoring-pipeline-logs.md)
+ [
# 파이프라인 지표 모니터링
](monitoring-pipeline-metrics.md)
# 파이프라인 모니터링
Amazon OpenSearch Ingestion 파이프라인에 대한 로깅을 활성화하여 파이프라인 작업 및 수집 활동 중에 발생하는 오류 및 경고 메시지를 노출할 수 있습니다. OpenSearch Ingestion은 모든 로그를 *Amazon CloudWatch Logs*에 게시합니다. CloudWatch Logs는 로그 파일의 정보를 모니터링하고 특정 임계값에 도달하면 사용자에게 알릴 수 있습니다. 또한 매우 내구성이 뛰어난 스토리지에 로그 데이터를 저장할 수 있습니다. 자세한 내용은 [Amazon CloudWatch Logs 사용자 안내서](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/)를 참조하세요.
OpenSearch Ingestion의 로그에는 요청 처리 실패, 소스에서 싱크로의 인증 오류 및 문제 해결에 도움이 될 수 있는 기타 경고가 표시될 수 있습니다. 해당 로그의 경우 OpenSearch Ingestion은 `INFO`, `WARN`, `ERROR`, `FATAL`의 로그 수준을 사용합니다. 모든 파이프라인에 대해 로그 게시를 활성화하는 것이 좋습니다.
## 필요한 권한
OpenSearch Ingestion에서 CloudWatch Logs로 로그를 전송하도록 하려면 특정 IAM 권한을 가진 사용자로 로그인해야 합니다.
로그 전송 리소스를 생성하고 업데이트하려면 다음과 같은 CloudWatch Logs 권한이 필요합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Resource": "*",
"Action": [
"logs:CreateLogDelivery",
"logs:PutResourcePolicy",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:DescribeResourcePolicies",
"logs:GetLogDelivery",
"logs:ListLogDeliveries"
]
}
]
}
```
------
## 로그 게시 활성화
기존 파이프라인에서 또는 파이프라인을 생성하는 동안 로그 게시를 활성화할 수 있습니다. 파이프라인 생성 중에 로그 게시를 활성화하는 단계는 [파이프라인 생성](creating-pipeline.md#create-pipeline)(을)를 참조하세요.
### 콘솔
**기존 파이프라인에서 로그 게시를 활성화하려면**
1. [https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) Amazon OpenSearch Service 콘솔에 로그인합니다. 파이프라인 페이지에 표시됩니다.
1. 로그를 활성화하려는 파이프라인을 열고 **작업**, **로그 게시 옵션 편집**을 선택합니다.
1. **CloudWatch Logs에 게시**를 활성화합니다.
1. 새로운 로그 그룹을 생성하거나 기존 그룹을 선택합니다. 이름을 `/aws/vendedlogs/OpenSearchIngestion/pipeline-name/audit-logs`와 같은 경로 형식으로 지정하는 것이 좋습니다. 이 형식을 사용하면 `/aws/vendedlogs/OpenSearchIngestion`과 같은 특정 경로에 있는 모든 로그 그룹에 권한을 부여하는 CloudWatch 액세스 정책을 더 쉽게 적용할 수 있습니다.
**중요**
로그 그룹 이름에 접두사 `vendedlogs`를 포함해야 합니다. 그렇지 않으면 생성이 실패합니다.
1. **저장**을 선택합니다.
### CLI
를 사용하여 로그 게시를 활성화하려면 다음 요청을 AWS CLI보냅니다.
```
aws osis update-pipeline \
--pipeline-name my-pipeline \
--log-publishing-options IsLoggingEnabled=true,CloudWatchLogDestination={LogGroup="/aws/vendedlogs/OpenSearchIngestion/pipeline-name"}
```
# 파이프라인 지표 모니터링
원시 데이터를 수집하여 읽기 가능하며 실시간에 가까운 지표로 처리하는 Amazon CloudWatch를 통해 를 Amazon OpenSearch Ingestion 모니터링할 수 있습니다. 이러한 통계는 15개월간 보관되므로 기록 정보에 액세스하고 웹 애플리케이션 또는 서비스가 어떻게 실행되고 있는지 전체적으로 더 잘 파악할 수 있습니다. 특정 임곗값을 주시하다가 해당 임곗값이 충족될 때 알림을 전송하거나 조치를 취하도록 경보를 설정할 수도 있습니다. 자세한 내용은 [Amazon CloudWatch 사용 설명서](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)를 참조하세요.
OpenSearch Ingestion 콘솔에는 CloudWatch의 원시 데이터를 기초로 하는 일련의 차트가 각 파이프라인의 **성능** 탭에 표시됩니다.
OpenSearch Ingestion은 대부분의 [지원되는 플러그인](pipeline-config-reference.md#ingestion-plugins)의 지표를 보고합니다. 특정 플러그인에 아래의 자체 표가 없다면 플러그인별 지표를 보고하지 않는다는 뜻입니다. 이러한 지표는 `AWS/OSIS` 네임스페이스에 게시됩니다.
**Topics**
+ [
## 공통 지표
](#common-metrics)
+ [
## 버퍼 지표
](#buffer-metrics)
+ [
## 서명 V4 지표
](#sigv4-metrics)
+ [
## 경계가 있는 차단 버퍼 지표
](#blockingbuffer-metrics)
+ [
## Otel 추적 소스 지표
](#oteltrace-metrics)
+ [
## Otel 지표 소스 지표
](#otelmetrics-metrics)
+ [
## Http 지표
](#http-metrics)
+ [
## S3 ta 지표
](#s3-metrics)
+ [
## 집계 지표
](#aggregate-metrics)
+ [
## 날짜 지표
](#date-metrics)
+ [
## Lambda 지표
](#lambda-metrics)
+ [
## Grok 지표
](#grok-metrics)
+ [
## Otel 추적 원시 지표
](#oteltrace-raw-metrics)
+ [
## Otel 추적 그룹 지표
](#oteltracegroup-metrics)
+ [
## 서비스 맵 스테이트풀 메트릭
](#servicemapstateful-metrics)
+ [
## OpenSearch 지표
](#opensearch-metrics)
+ [
## 시스템 및 측정 지표
](#systemmetering-metrics)
## 공통 지표
다음 지표는 모든 프로세서와 싱크에 공통입니다.
각 지표 앞에는 <*sub\$1pipeline\$1name*><*plugin*><*metric\$1name*> 형식으로 하위 파이프라인 이름과 플러그인 이름이 접두사로 붙습니다. 예를 들어, `my-pipeline`이라는 하위 파이프라인의 `recordsIn.count` 지표 전체 이름과 [날짜](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/date/) 프로세서는 `my-pipeline.date.recordsIn.count`과 같습니다.
| 지표 접미사 | 설명 |
| --- | --- |
| recordsIn.count | 파이프라인 구성 요소로의 레코드 수신. 이 지표는 프로세서와 싱크에 적용됩니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| recordsOut.count | 파이프라인 구성 요소로의 레코드 송신. 이 지표는 프로세서와 소스에 적용됩니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| timeElapsed.count | 파이프라인 구성 요소 실행 중에 기록된 데이터 포인트 수입니다. 이 지표는 프로세서와 싱크에 적용됩니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| timeElapsed.sum | 파이프라인 구성 요소를 실행하는 동안 경과된 총 시간입니다. 이 지표는 프로세서와 싱크에 적용(밀리초)됩니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| timeElapsed.max | 파이프라인 구성 요소를 실행하는 동안 경과된 최대 시간입니다. 이 지표는 프로세서와 싱크에 적용(밀리초)됩니다. **관련 통계**: 최대 **차원**: `PipelineName` |
## 버퍼 지표
다음 지표는 OpenSearch Ingestion이 모든 파이프라인에 대해 자동으로 구성하는 기본 [경계가 있는 차단](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/buffers/bounded-blocking/) 버퍼에 적용됩니다.
각 지표 앞에는 <*sub\$1pipeline\$1name*><*plugin*><*metric\$1name*> 형식으로 하위 파이프라인 이름과 버퍼 이름이 접두사로 붙습니다. 예를 들어, `my-pipeline`이라는 하위 파이프라인의 `recordsWritten.count` 지표 전체 이름이 `my-pipeline.BlockingBuffer.recordsWritten.count`(와)과 같습니다.
| 지표 접미사 | 설명 |
| --- | --- |
| recordsWritten.count | 버퍼에 기록된 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| recordsRead.count | 버퍼에서 읽은 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| recordsInFlight.value | 버퍼에서 읽은 미확인된 레코드 수입니다. **관련 통계**: Average **차원**: `PipelineName` |
| recordsInBuffer.value | 현재 버퍼에 있는 레코드 수입니다. **관련 통계**: Average **차원**: `PipelineName` |
| recordsProcessed.count | 버퍼에서 읽고 파이프라인에서 처리한 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| recordsWriteFailed.count | 파이프라인이 싱크에 기록하지 못한 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| writeTimeElapsed.count | 버퍼에 쓰는 동안 기록된 데이터 포인트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| writeTimeElapsed.sum | 버퍼에 쓰는 동안 경과된 총 시간(밀리초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| writeTimeElapsed.max | 버퍼에 쓰는 동안 경과된 최대 시간(밀리초)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| writeTimeouts.count | 버퍼에 대한 쓰기 타임아웃 횟수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| readTimeElapsed.count | 버퍼에 쓰는 동안 기록된 데이터 포인트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| readTimeElapsed.sum | 버퍼에서 읽는 동안 경과된 총 시간(밀리초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| readTimeElapsed.max | 버퍼에서 읽는 동안 경과된 최대 시간(밀리초)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| checkpointTimeElapsed.count | 체크포인트를 수행하는 동안 기록된 데이터 포인트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| checkpointTimeElapsed.sum | 체크포인트를 수행하는 동안 경과된 총 시간(밀리초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| checkpointTimeElapsed.max | 체크포인트를 수행하는 동안 경과된 최대 시간(밀리초)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
## 서명 V4 지표
다음 지표는 파이프라인의 수집 엔드포인트에 적용되며 소스 플러그인(`http`, `otel_trace`, `otel_metrics`)과 연결됩니다. OpenSearch Ingestion에 대한 모든 요청은 [서명 버전 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)로 서명되어야 합니다. 이러한 지표를 통해 파이프라인에 연결할 때 권한 부여 문제를 식별하거나 성공적으로 인증되고 있는지 확인할 수 있습니다.
각 지표 앞에는 하위 파이프라인 이름 및 `osis_sigv4_auth`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.osis_sigv4_auth.httpAuthSuccess.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| httpAuthSuccess.count | 파이프라인에 대한 성공적인 서명 V4 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| httpAuthFailure.count | 파이프라인에 대한 실패한 서명 V4 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| httpAuthServerError.count | 서버 오류를 반환한 파이프라인에 대한 서명 V4 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
## 경계가 있는 차단 버퍼 지표
다음 지표는 [경계가 있는 차단 ](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/buffers/bounded-blocking/) 버퍼에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `BlockingBuffer`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.BlockingBuffer.bufferUsage.value`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| bufferUsage.value | 버퍼에 있는 레코드 수를 기준으로 한 `buffer_size`의 사용률입니다. `buffer_size`는 버퍼에 기록된 최대 레코드 수와 확인되지 않은 기내 레코드를 나타냅니다. **관련 통계**: Average **차원**: `PipelineName` |
## Otel 추적 소스 지표
다음 지표는 [oTel 추적 ](https://docs.opensearch.org/latest/data-prepper/pipelines/configuration/sources/otel-trace-source/) 소스에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `otel_trace_source`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.otel_trace_source.requestTimeouts.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| requestTimeouts.count | 시간을 초과한 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestsReceived.count | 플러그인에서 수신된 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| successRequests.count | 메시지 브로커가 성공적으로 처리한 구독 요청 수. **관련 통계**: 합계 **차원**: `PipelineName` |
| badRequests.count | 플러그인에서 처리한 잘못된 형식의 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestsTooLarge.count | 콘텐츠의 스팬 수가 버퍼 용량보다 큰 요청의 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| internalServerError.count | 사용자 지정 예외 유형을 사용하여 플러그인에서 처리한 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestProcessDuration.count | 플러그인의 요청을 처리하는 동안 기록된 데이터 포인트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestProcessDuration.sum | 플러그인에서 처리한 요청의 총 지연 시간(밀리초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestProcessDuration.max | 플러그인에서 처리한 요청의 최대 지연 시간(밀리초)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| payloadSize.count | 수신 요청의 페이로드 크기 분포 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| payloadSize.sum | 수신 요청의 페이로드 크기 분포의 총 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| payloadSize.max | 수신 요청의 페이로드 크기 분포의 최대 수(바이트)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
## Otel 지표 소스 지표
다음 지표는 [oTel 지표 ](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-metrics-source/) 소스에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `otel_metrics_source`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.otel_metrics_source.requestTimeouts.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| requestTimeouts.count | 시간 초과된 플러그인에 대한 총 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestsReceived.count | 플러그인에서 수신된 요청 총 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| successRequests.count | 플러그인이 성공적으로 처리한 요청 수(응답 상태 코드 200개)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestProcessDuration.count | 플러그인에서 처리한 요청의 지연 시간 수(초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestProcessDuration.sum | 플러그인에서 처리한 요청의 총 지연 시간(밀리초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestProcessDuration.max | 플러그인에서 처리한 요청의 최대 지연 시간(밀리초)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| payloadSize.count | 수신 요청의 페이로드 크기 분포 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| payloadSize.sum | 수신 요청의 페이로드 크기 분포의 총 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| payloadSize.max | 수신 요청의 페이로드 크기 분포의 최대 수(바이트)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
## Http 지표
다음 지표는 [HTTP](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/http-source/) 소스에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `http`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.http.requestsReceived.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| requestsReceived.count | `/log/ingest` 엔드포인트에서 수신된 바이트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestsRejected.count | 플러그인이 거부한 요청 수(응답 상태 코드 429개)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| successRequests.count | 플러그인이 성공적으로 처리한 요청 수(응답 상태 코드 200개)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| badRequests.count | 플러그인에서 처리한 콘텐츠 유형이나 형식이 잘못된 요청 수(응답 상태 코드 400개)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestTimeouts.count | HTTP 소스 서버에서 제한 시간이 초과된 요청 수(415 응답 상태 코드)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestsTooLarge.count | 콘텐츠의 이벤트 수가 버퍼 용량보다 큰 요청의 수(413 응답 상태 코드)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| internalServerError.count | 사용자 지정 예외 유형을 사용하여 플러그인에서 처리한 요청 수(500 응답 상태 코드)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestProcessDuration.count | 플러그인에서 처리한 요청의 지연 시간 수(초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestProcessDuration.sum | 플러그인에서 처리한 요청의 총 지연 시간(밀리초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestProcessDuration.max | 플러그인에서 처리한 요청의 최대 지연 시간(밀리초)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| payloadSize.count | 수신 요청의 페이로드 크기 분포 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| payloadSize.sum | 수신 요청의 페이로드 크기 분포의 총 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| payloadSize.max | 수신 요청의 페이로드 크기 분포의 최대 수(바이트)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
## S3 ta 지표
다음 지표는 [S3](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/s3/) 소스에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `s3`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.s3.s3ObjectsFailed.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| s3ObjectsFailed.count | 플러그인이 읽지 못한 S3 객체의 총 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectsNotFound.count | S3에서 `Not Found` 오류가 발생하여 플러그인이 읽지 못한 S3 객체의 수입니다. 이러한 지표도 `s3ObjectsFailed` 지표에 포함됩니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectsAccessDenied.count | S3에서 `Access Denied` 또는 `Forbidden` 오류가 발생하여 플러그인이 읽지 못한 S3 객체의 수입니다. 이러한 지표도 `s3ObjectsFailed` 지표에 포함됩니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectReadTimeElapsed.count | 플러그인이 S3 객체에 대한 GET 요청을 수행하고, 객체를 구문 분석하고, 버퍼에 이벤트를 쓰는 데 걸리는 시간입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectReadTimeElapsed.sum | 플러그인이 S3 객체에 대한 GET 요청을 수행하고, 객체를 구문 분석하고, 버퍼에 이벤트를 쓰는 데 걸리는 시간입니다(밀리초). **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectReadTimeElapsed.max | 플러그인이 S3 객체에 대한 GET 요청을 수행하고, 객체를 구문 분석하고, 버퍼에 이벤트를 쓰는 데 걸리는 최대 시간입니다(밀리초). **관련 통계**: 최대 **차원**: `PipelineName` |
| s3ObjectSizeBytes.count | S3 객체 크기의 분포 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectSizeBytes.sum | S3 객체 크기의 분포 총 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectSizeBytes.max | S3 객체 크기의 최대 분포 수(바이트)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| s3ObjectProcessedBytes.count | 플러그인에서 처리한 S3 객체의 배포 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectProcessedBytes.sum | 플러그인에서 처리한 S3 객체의 총 배포 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectProcessedBytes.max | 플러그인에서 처리한 S3 객체의 최대 배포 수(바이트)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| s3ObjectsEvents.count | 플러그인이 수신한 S3 이벤트의 배포 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectsEvents.sum | 플러그인이 수신한 S3 이벤트의 총 배포입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3ObjectsEvents.max | 플러그인이 수신한 S3 이벤트의 최대 배포입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| sqsMessageDelay.count | S3가 객체 생성에 필요한 이벤트 시간을 기록하여 객체가 완전히 구문 분석된 시점까지 기록하는 동안 기록된 데이터 포인트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| sqsMessageDelay.sum | S3가 객체 생성을 위한 이벤트 시간을 기록하는 시점부터 완전히 구문 분석된 시점까지의 총 시간(밀리초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| sqsMessageDelay.max | S3가 객체 생성을 위한 이벤트 시간을 기록하는 시점부터 완전히 구문 분석된 시점까지의 최대 시간(밀리초)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| s3ObjectsSucceeded.count | 플러그인이 성공적으로 읽은 S3 객체 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| sqsMessagesReceived.count | 플러그인이 대기열에서 수신한 Amazon SQS 메시지 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| sqsMessagesDeleted.count | 플러그인이 대기열에서 삭제한 Amazon SQS 메시지 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| sqsMessagesFailed.count | 플러그인이 구문 분석하지 못한 Amazon SQS 메시지 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
## 집계 지표
다음 지표는 [집계](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/aggregate/) 프로세서에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `aggregate`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.aggregate.actionHandleEventsOut.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| actionHandleEventsOut.count | 구성된 작업에 대한 `handleEvent` 호출에서 반환된 이벤트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| actionHandleEventsDropped.count | 구성된 작업에 대한 `handleEvent` 호출에서 반환된 이벤트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| actionHandleEventsProcessingErrors.count | 오류가 발생한 구성된 작업에 대해 `handleEvent`로 걸려온 호출 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| actionConcludeGroupEventsOut.count | 구성된 작업에 대한 `concludeGroup` 호출에서 반환된 이벤트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| actionConcludeGroupEventsDropped.count | 구성된 작업에 대한 `condludeGroup` 호출에서 반환되지 않은 이벤트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| actionConcludeGroupEventsProcessingErrors.count | 오류가 발생한 구성된 작업에 대해 `concludeGroup`로 걸려온 호출 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| currentAggregateGroups.value | 현재 그룹 수입니다. 이 게이지는 그룹이 종료되면 감소하고 이벤트에서 새 그룹이 생성되기 시작하면 증가합니다. **관련 통계**: Average **차원**: `PipelineName` |
## 날짜 지표
다음 지표는 [날짜](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/date/) 프로세서에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `date`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.date.dateProcessingMatchSuccess.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| dateProcessingMatchSuccess.count | `match` 구성 옵션에 지정된 패턴 중 최소 하나 이상과 일치하는 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| dateProcessingMatchFailure.count | `match` 구성 옵션에 지정된 패턴 중 어떤 것과도 일치하지 않는 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
## Lambda 지표
다음 지표는 [AWS Lambda](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/aws-lambda/) 프로세서에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `lambda`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.lambda.recordsSuccessfullySentToLambda.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| recordsSuccessfullySentToLambda.count | Lambda 함수에서 성공적으로 처리된 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| recordsFailedToSendToLambda.count | Lambda 함수로 전송하지 못한 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| lambdaFunctionLatency.avg`lambdaFunctionLatency.max` | Lambda 함수 호출의 지연 시간입니다. **관련 통계**: 평균 및 최대 **차원**: `PipelineName` |
| numberOfRequestsSucceeded.count | 성공적인 Lambda 간접 호출 요청의 총 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| numberOfRequestsFailed.count | 실패한 Lambda 간접 호출 요청의 총 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| requestPayloadSize.avg | Lambda로 전송된 요청 페이로드의 크기입니다. **관련 통계**: Average **차원**: `PipelineName` |
| responsePayloadSize.avg | Lambda에서 수신한 응답 페이로드의 크기입니다. **관련 통계**: Average **차원**: `PipelineName` |
## Grok 지표
다음 지표는 [Grok](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/processors/grok/) 프로세서에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `grok`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.grok.grokProcessingMatch.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| grokProcessingMatch.count | `match` 구성 옵션에 최소 하나 이상의 패턴이 검색된 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| grokProcessingMismatch.count | `match` 구성 옵션에 지정된 패턴 중 어떤 것과도 일치하지 않는 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| grokProcessingErrors.count | 레코드 처리 오류 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| grokProcessingTimeouts.count | 매칭 중에 제한 시간이 초과된 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| grokProcessingTime.count | 개별 레코드가 `match` 구성 옵션의 패턴과 일치하는 동안 기록된 데이터 포인트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| grokProcessingTime.sum | 각 개별 레코드가 `match` 구성 옵션의 패턴과 일치시키는 데 걸리는 총 시간(밀리초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| grokProcessingTime.max | 각 개별 레코드가 `match` 구성 옵션의 패턴과 일치시키는 데 걸리는 최대 시간(밀리초)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
## Otel 추적 원시 지표
다음 지표는 [OTel 추적 원시](https://docs.opensearch.org/latest/data-prepper/pipelines/configuration/processors/otel-traces/) 프로세서에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `otel_trace_raw`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.otel_trace_raw.traceGroupCacheCount.value`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| traceGroupCacheCount.value | 추적 그룹 캐시의 추적 그룹 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| spanSetCount.value | 스팬 세트 컬렉션의 스팬 세트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
## Otel 추적 그룹 지표
다음 지표는 [OTel 추적 그룹](https://github.com/opensearch-project/data-prepper/tree/main/data-prepper-plugins/otel-trace-group-processor) 프로세서에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `otel_trace_group`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.otel_trace_group.recordsInMissingTraceGroup.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| recordsInMissingTraceGroup.count | 추적 그룹 필드가 누락된 수신 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| recordsOutFixedTraceGroup.count | 추적 그룹 필드가 성공적으로 채워진 수신 레코드의 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| recordsOutMissingTraceGroup.count | 추적 그룹 필드가 누락된 송신 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
## 서비스 맵 스테이트풀 메트릭
다음 지표는 [Service-Map 상태 저장](https://docs.opensearch.org/latest/data-prepper/common-use-cases/trace-analytics/) 프로세서에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `service-map-stateful`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.service-map-stateful.spansDbSize.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| spansDbSize.value | 현재 및 이전 지속 기간에 대한 MapDB 내 스팬의 메모리 바이트 크기입니다. **관련 통계**: Average **차원**: `PipelineName` |
| traceGroupDbSize.value | 현재 및 이전 지속 기간에 대한 MapDB 내 추적 그룹의 메모리 바이트 크기입니다. **관련 통계**: Average **차원**: `PipelineName` |
| spansDbCount.value | 현재 및 이전 지속 기간에 대한 MapDB 내 스팬의 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| traceGroupDbCount.value | 현재 및 이전 지속 기간에 대한 MapDB의 추적 그룹 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| relationshipCount.value | 현재 및 이전 지속 기간 동안 저장된 관계 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
## OpenSearch 지표
다음 지표는 [OpenSearch](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/opensearch/) 싱크에 적용됩니다. 각 지표 앞에는 하위 파이프라인 이름 및 `opensearch`(이)가 붙습니다. 예를 들어 `sub_pipeline_name.opensearch.bulkRequestErrors.count`입니다.
| 지표 접미사 | 설명 |
| --- | --- |
| bulkRequestErrors.count | 대량 요청을 보내는 동안 발생한 총 오류 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| documentsSuccess.count | 대량 요청을 통해 OpenSearch Service에 성공적으로 전송된 문서 수(재시도 포함)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| documentsSuccessFirstAttempt.count | 첫 시도에 대량 요청을 통해 OpenSearch Service에 성공적으로 전송된 문서 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| documentErrors.count | 대량 요청으로 전송하지 못한 문서 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestFailed.count | 실패한 대량 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestNumberOfRetries.count | 대량 복원 요청의 수. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkBadRequestErrors.count | 대량 요청을 보내는 동안 발생한 `Bad Request` 오류 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestNotAllowedErrors.count | 대량 요청을 보내는 동안 발생한 `Request Not Allowed` 오류 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestInvalidInputErrors.count | 대량 요청을 보내는 동안 발생한 `Invalid Input` 오류 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestNotFoundErrors.count | 대량 요청을 보내는 동안 발생한 `Request Not Found` 오류 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestTimeoutErrors.count | 대량 요청을 보내는 동안 발생한 `Request Timeout` 오류 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestServerErrors.count | 대량 요청을 보내는 동안 발생한 `Server Error` 오류 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestSizeBytes.count | 대량 요청의 페이로드 크기 분포 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestSizeBytes.sum | 대량 요청의 페이로드 크기 분포 총 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestSizeBytes.max | 대량 요청의 페이로드 크기 분포 최대 수(바이트)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| bulkRequestLatency.count | 재시도를 포함하여 요청이 플러그인으로 전송되는 동안 기록된 데이터 포인트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestLatency.sum | 재시도를 포함하여 플러그인으로 전송된 요청의 총 지연 시간(밀리초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| bulkRequestLatency.max | 재시도를 포함하여 플러그인으로 전송된 요청의 최대 지연 시간(밀리초)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| s3.dlqS3RecordsSuccess.count | S3 DLQ(Dead Letter Queue)로 성공적으로 전송된 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3.dlqS3RecordsFailed.count | S3 DLQ(Dead Letter Queue)로 전송되지 못한 레코드 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3.dlqS3RequestSuccess.count | S3 DLQ(Dead Letter Queue)에 성공한 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3.dlqS3RequestFailed.count | S3 DLQ(Dead Letter Queue)에 실패한 요청 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3.dlqS3RequestLatency.count | 재시도를 포함하여 요청이 S3 DLQ(Dead Letter Queue)로 전송되는 동안 기록된 데이터 포인트 수입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3.dlqS3RequestLatency.sum | 재시도를 포함하여 S3 DLQ(Dead Letter Queue)로 전송된 요청의 총 지연 시간(밀리초)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3.dlqS3RequestLatency.max | 재시도를 포함하여 S3 DLQ(Dead Letter Queue)로 전송된 요청의 최대 지연 시간(밀리초)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
| s3.dlqS3RequestSizeBytes.count | S3 DLQ(Dead Letter Queue)에 대한 요청의 페이로드 크기 분포 수(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3.dlqS3RequestSizeBytes.sum | S3 DLQ(Dead Letter Queue)에 대한 요청의 총 페이로드 크기의 총 분포(바이트)입니다. **관련 통계**: 합계 **차원**: `PipelineName` |
| s3.dlqS3RequestSizeBytes.max | S3 DLQ(Dead Letter Queue)에 대한 요청의 최대 페이로드 크기 분포(바이트)입니다. **관련 통계**: 최대 **차원**: `PipelineName` |
## 시스템 및 측정 지표
다음 지표는 전체 OpenSearch Ingestion 시스템에 적용됩니다. 이러한 지표 앞에는 아무 것도 붙지 않습니다.
| 지표 | 설명 |
| --- | --- |
| system.cpu.usage.value | 모든 데이터 노드의 사용 가능한 CPU 사용률입니다. **관련 통계**: Average **차원**: `PipelineName`, `area`, `id` |
| system.cpu.count.value | 모든 데이터 노드의 총 CPU 사용량입니다. **관련 통계**: Average **차원**: `PipelineName`, `area`, `id` |
| jvm.memory.max.value | 메모리 관리에 사용할 수 있는 최대 메모리 용량(바이트)입니다. **관련 통계**: Average **차원**: `PipelineName`, `area`, `id` |
| jvm.memory.used.value | 사용된 총 메모리 용량(바이트). **관련 통계**: Average **차원**: `PipelineName`, `area`, `id`signa |
| jvm.memory.committed.value | Java 가상 머신(JVM)에서 사용하기 위해 커밋된 메모리의 용량(바이트)입니다. **관련 통계**: Average **차원**: `PipelineName`, `area`, `id` |
| computeUnits | 파이프라인에서 사용 중인 Ingestion OpenSearch Compute Units (Ingestion OCUs)의 수입니다. **관련 통계**: Maximum, Sum, Average **차원**: `PipelineName` |
# Amazon OpenSearch Ingestion의 모범 사례
이 주제는 Amazon OpenSearch Ingestion 파이프라인 생성 및 관리에 대한 모범 사례를 제공하며, 많은 사용 사례에 적용되는 일반 지침을 포함하고 있습니다. 각 워크로드는 고유한 특성을 가지고 있으므로 모든 사용 사례에 적합한 일반적인 권장 사항은 없습니다.
**Topics**
+ [
## 일반 모범 사례
](#osis-best-practices-general)
+ [
## 권장되는 CloudWatch 경보
](#osis-cloudwatch-alarms)
## 일반 모범 사례
파이프라인 생성 및 관리에는 다음과 같은 일반적인 모범 사례가 적용됩니다.
+ 고가용성을 보장하려면 2개 또는 3개의 서브넷으로 VPC 파이프라인을 구성합니다. 하나의 서브넷에만 파이프라인을 배포하고 가용 영역이 다운되면 데이터를 수집할 수 없습니다.
+ 각 파이프라인 내에서 하위 파이프라인 수를 5개 이하로 제한하는 것이 좋습니다.
+ S3 소스 플러그인을 사용하는 경우 최적의 성능을 위해 균일한 크기의 S3 파일을 사용하세요.
+ S3 소스 플러그인을 사용하는 경우 최적의 성능을 위해 S3 버킷에서 파일 크기 0.25GB마다 가시성 제한 시간을 30초씩 추가하세요.
+ 실패한 이벤트를 오프로드하고 분석에 액세스할 수 있도록 파이프라인 구성에 [DLQ(Dead Letter Queue)](https://opensearch.org/docs/latest/data-prepper/pipelines/dlq/)를 포함시키세요. 잘못된 매핑이나 기타 문제로 인해 싱크에서 데이터가 거부되는 경우 문제를 해결하고 수정하기 위해 데이터를 DLQ로 라우팅할 수 있습니다.
+ 파이프라인에서 집계 프로세서를 사용하는 경우 파이프라인의 성능을 최적화하려면 `“local_mode: true”` 플래그를 사용하는 것이 좋습니다.
## 권장되는 CloudWatch 경보
CloudWatch 경보는 CloudWatch 지표가 일정 시간 동안 지정된 값을 초과하면 조치를 수행합니다. 예를 들어 클러스터 상태가 AWS 1분 이상 `red` 지속되면 이메일을 보낼 수 있습니다. 이 단원에는 Amazon OpenSearch Ingestion에 권장되는 몇 가지 경보와 이에 대응하는 방법이 포함되어 있습니다.
경보 구성에 대한 자세한 내용은 *Amazon CloudWatch 사용 설명서*의 [Amazon CloudWatch 경보 생성](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)을 참조하세요.
| 경보 | 문제 |
| --- | --- |
| `computeUnits` 최대값은 15분, 연속 횟수 3번 동안 구성된 `maxUnits` 값임 | 파이프라인이 최대 용량에 도달했으며 maxUnits 업데이트가 필요할 수 있습니다. 파이프라인의 최대 용량을 늘리세요. |
| `opensearch.documentErrors.count` 합계는 1분, 연속 횟수 1번 동안 = `{sub_pipeline_name}.opensearch.recordsIn.count`임 | 파이프라인이 OpenSearch 싱크에 쓸 수 없습니다. 파이프라인 권한을 확인하고 도메인이나 컬렉션이 정상인지 확인하세요. DLQ(Dead Letter Queue)에 실패한 이벤트가 있는지 확인할 수도 있습니다 (구성된 경우). |
| `bulkRequestLatency.max` 최대값은 1분, 연속 횟수 1번 동안 >= *x*임 | 파이프라인이 OpenSearch 싱크로 데이터를 전송하는 데 지연이 많이 발생합니다. 이는 싱크 크기가 너무 작거나 샤딩 전략이 잘못되어 싱크가 뒤처지고 있기 때문일 수 있습니다. 지연 시간이 오래 지속되면 파이프라인 성능에 영향을 줄 수 있으며 클라이언트의 역압으로 이어질 수 있습니다. |
| `httpAuthFailure.count` 합계는 1분, 연속 횟수 1번 동안 >= 1임 | 수집 요청은 인증되지 않습니다. 모든 클라이언트에 서명 버전 4 인증이 올바르게 활성화되어 있는지 확인하세요. |
| `system.cpu.usage.value` 평균값은 15분, 연속 횟수 3번 동안 >= 80%임 | 지속적으로 CPU 사용률이 높아지면 문제가 될 수 있습니다. 파이프라인의 최대 용량을 늘리는 것이 좋습니다. |
| `bufferUsage.value` 평균값은 15분, 연속 횟수 3번 동안 >= 80%임 | 지속적으로 높은 버퍼 사용량은 문제가 될 수 있습니다. 파이프라인의 최대 용량을 늘리는 것이 좋습니다. |
### 고려할 만한 기타 경보
정기적으로 사용하는 Amazon OpenSearch Ingestion 기능에 따라 다음 경보 구성을 고려하세요.
| 경보 | 문제 |
| --- | --- |
| `dynamodb.exportJobFailure.count` 합계가 1 | Amazon S3로 내보내기를 트리거하는 시도가 실패했습니다. |
| `opensearch.EndtoEndLatency.avg` 평균값은 15분, 연속 횟수 4번 동안 > X임 | EndtoEndLatency는 DynamoDB 스트림에서 읽을 때 필요한 값보다 높습니다. 이는 OpenSearch 클러스터의 규모가 작거나 최대 파이프라인 OCU 용량이 DynamoDB 테이블의 WCU 처리량에 비해 너무 낮기 때문일 수 있습니다. EndtoEndLatency는 내보내기 후에는 더 높지만 시간이 지나면 최근 DynamoDB 스트림을 따라잡기 때문에 감소할 것입니다. |
| `dynamodb.changeEventsProcessed.count` 합계는 X분 동안 == 0임 | DynamoDB 스트림에서 수집되는 레코드가 없습니다. 테이블에 활동이 없거나 DynamoDB 스트림 액세스에 문제가 있을 수 있습니다. |
| `opensearch.s3.dlqS3RecordsSuccess.count` 합계는 1분, 연속 횟수 1번 동안 >= `opensearch.documentSuccess.count`합계임 | OpenSearch 싱크보다 많은 수의 레코드가 DLQ로 전송되고 있습니다. OpenSearch 싱크 플러그인 지표를 검토하여 근본 원인을 조사하고 결정하세요. |
| `grok.grokProcessingTimeouts.count` 합계는 = 1분, 연속 횟수 5번 동안 recordsIn.count 합계임 | Grok 프로세서가 패턴 매칭을 시도하는 동안 모든 데이터의 타임아웃이 발생했습니다. 이로 인해 성능이 저하되고 파이프라인 속도가 느려질 수 있습니다. 패턴을 조정하여 타임아웃을 줄이는 것을 고려해 보세요. |
| `grok.grokProcessingErrors.count` 합계는 1분, 연속 횟수 1번 동안 >= 1임 | Grok 프로세서가 파이프라인의 데이터와 패턴을 일치시키지 못해 오류가 발생했습니다. 데이터와 Grok 플러그인 구성을 검토하여 패턴 매칭이 예상되는지 확인하세요. |
| `grok.grokProcessingMismatch.count` 합계는 = 1분, 연속 횟수 5번 동안 recordsIn.count 합계임 | Grok 프로세서가 파이프라인의 데이터와 패턴을 일치시키지 못했습니다. 데이터와 Grok 플러그인 구성을 검토하여 패턴 매칭이 예상되는지 확인하세요. |
| `date.dateProcessingMatchFailure.count` 합계는 = 1분, 연속 횟수 5번 동안 recordsIn.count 합계임 | 날짜 프로세서가 파이프라인의 데이터에 어떤 패턴도 일치시킬 수 없습니다. 데이터와 날짜 플러그인 구성을 검토하여 패턴 매칭이 예상되는지 확인하세요. |
| `s3.s3ObjectsFailed.count` 합계는 1분, 연속 횟수 1번 동안 >= 1임 | 이 문제는 S3 객체가 없거나 파이프라인에 충분한 권한이 없기 때문에 발생합니다. s3ObjectsNotFound.count 및 s3ObjectsAccessDenied.count 지표를 검토하여 근본 원인을 파악하세요. S3 객체가 존재하는지 확인하거나 권한을 업데이트하세요. |
| `s3.sqsMessagesFailed.count` 합계는 1분, 연속 횟수 1번 동안 >= 1임 | S3 플러그인이 Amazon SQS 메시지를 처리하지 못했습니다. SQS 대기열에서 DLQ를 활성화한 경우 실패한 메시지를 검토하세요. 파이프라인이 처리하려는 잘못된 데이터를 대기열에 수신하고 있을 수 있습니다. |
| `http.badRequests.count` 합계는 1분, 연속 횟수 3번 동안 >= 1임 | 클라이언트가 잘못된 요청을 보내고 있습니다. 모든 클라이언트가 적절한 페이로드를 보내고 있는지 확인하세요. |
| `http.requestsTooLarge.count` 합계는 1분, 연속 횟수 1번 동안 >= 1임 | HTTP 소스 플러그인의 요청에 너무 많은 데이터가 포함되어 있어 버퍼 용량을 초과합니다. 클라이언트의 배치 크기를 조정하세요. |
| `http.internalServerError.count` 합계는 1분, 연속 횟수 1번 동안 >= 0임 | HTTP 소스 플러그인이 이벤트를 수신하는 데 문제가 있습니다. |
| `http.requestTimeouts.count` 합계는 1분, 연속 횟수 1번 동안 >= 0임 | 소스 타임아웃은 파이프라인이 제대로 프로비저닝되지 않았기 때문일 수 있습니다. 추가 워크로드를 처리하기 위해 파이프라인 maxUnits(을)를 늘리는 것을 고려해 보세요. |
| `otel_trace.badRequests.count` 합계는 1분, 연속 횟수 1번 동안 >= 1임 | 클라이언트가 잘못된 요청을 보내고 있습니다. 모든 클라이언트가 적절한 페이로드를 보내고 있는지 확인하세요. |
| `otel_trace.requestsTooLarge.count` 합계는 1분, 연속 횟수 1번 동안 >= 1임 | Otel Trace 소스 플러그인의 요청에 너무 많은 데이터가 포함되어 있어 버퍼 용량을 초과합니다. 클라이언트의 배치 크기를 조정하세요. |
| `otel_trace.internalServerError.count` 합계는 1분, 연속 횟수 1번 동안 >= 0임 | Otel Trace 소스 플러그인이 이벤트를 수신하는 데 문제가 있습니다. |
| `otel_trace.requestTimeouts.count` 합계는 1분, 연속 횟수 1번 동안 >= 0임 | 소스 타임아웃은 파이프라인이 제대로 프로비저닝되지 않았기 때문일 수 있습니다. 추가 워크로드를 처리하기 위해 파이프라인 maxUnits(을)를 늘리는 것을 고려해 보세요. |
| `otel_metrics.requestTimeouts.count` 합계는 1분, 연속 횟수 1번 동안 >= 0임 | 소스 타임아웃은 파이프라인이 제대로 프로비저닝되지 않았기 때문일 수 있습니다. 추가 워크로드를 처리하기 위해 파이프라인 maxUnits(을)를 늘리는 것을 고려해 보세요. |