본문 바로가기
WIKI 기술 지식 베이스

OpenSearch source

원문 보기 위키 갱신

출처: 문서

본문

OpenSearch 소스

opensearch 소스 플러그인은 OpenSearch 클러스터, 레거시 Elasticsearch 클러스터, Amazon OpenSearch Service 도메인 또는 Amazon OpenSearch Serverless 컬렉션에서 인덱스를 읽는 데 사용해요.

이 플러그인은 OpenSearch 2.x와 Elasticsearch 7.x를 지원해요.

사용 방법

최소 필수 설정으로 opensearch 소스를 사용하려면 다음 구성을 pipeline.yaml 파일에 추가하세요:

opensearch-source-pipeline:
 source:
  opensearch:
    hosts: [ "https://localhost:9200" ]
    username: "username"
    password: "password"
 ...

indices, scheduling, search_options, connection을 포함한 모든 구성 설정으로 opensearch 소스를 사용하려면 다음 예제를 pipeline.yaml 파일에 추가하세요:

opensearch-source-pipeline:
  source:
    opensearch:
      hosts: [ "https://localhost:9200" ]
      username: "username"
      password: "password"
      indices:
        include:
          - index_name_regex: "test-index-.*"
        exclude:
          - index_name_regex: "\..*"
      scheduling:
        interval: "PT1H"
        index_read_count: 2
        start_time: "2023-06-02T22:01:30.00Z"
      search_options:
        search_context_type: "none"
        batch_size: 1000
      connection:
        insecure: false
        cert: "/path/to/cert.crt"
  ...

Amazon OpenSearch Service

다음 예제에서처럼 도메인에 대한 액세스 권한이 있는 sts_role_arn을 전달하면 Amazon OpenSearch Service 도메인을 대상으로 opensearch 소스를 구성할 수 있어요:

opensearch-source-pipeline:
  source:
    opensearch:
      hosts: [ "https://search-my-domain-soopywaovobopgs8ywurr3utsu.us-east-1.es.amazonaws.com" ]
      aws:
        region: "us-east-1"
        sts_role_arn: "arn:aws:iam::123456789012:role/my-domain-role"
  ...

Amazon OpenSearch Serverless

다음 예제에서처럼 serverless 옵션을 true로 설정하면 Amazon OpenSearch Serverless에 맞게 opensearch 소스를 구성할 수 있어요:

    - opensearch:
        hosts: [ 'https://1234567890abcdefghijkl.us-west-2.aoss.amazonaws.com' ]
        aws:
          sts_role_arn: 'arn:aws:iam::123456789012:role/my-domain-role'
          region: 'us-west-2'
          serverless: true

메타데이터 사용

opensource 소스가 문서로부터 OpenSearch Data Prepper 이벤트를 만들 때, 문서 인덱스는 opensearch-index를 키로 해서 EventMetadata에 저장되고, document_id는 opensearch-document_id를 키로 해서 EventMetadata에 저장돼요. 문서 버전은 메타데이터에 opensearch_document_version으로 저장돼요.

파이프라인 구성에서 필요에 따라 이 메타데이터를 참조할 수 있어요. 예를 들어 opensearch 싱크처럼 문서 업데이트를 지원하는 싱크에서 중복을 방지하려고 opensearch-document_id를 사용할 수 있어요. 조건부 라우팅에 원본 문서 메타데이터를 활용할 수도 있어요.

다음 파이프라인 구성 예제는 이벤트를 opensearch 싱크로 보내면서, 중복 문서가 생기지 않도록 소스 클러스터의 인덱스, document_id, document_version을 대상 클러스터에서 그대로 사용해요:

opensearch-migration-pipeline:
  source:
    opensearch:
      hosts: [ "https://source-cluster:9200" ]
      username: "username"
      password: "password"
  sink:
    - opensearch:
        hosts: [ "https://sink-cluster:9200" ]
        username: "username"
        password: "password"
        document_version_type: external
        document_version: "${getMetadata(\"opensearch_document_version\")}"
        document_id: "${getMetadata(\"opensearch-document_id\")}"
        index: "${getMetadata(\"opensearch-index\"}"

구성 옵션

다음 표는 opensearch 소스에서 구성할 수 있는 옵션을 설명해요.

옵션 필수 여부 타입 설명
hosts 예 List 쓰기를 수행할 OpenSearch 호스트의 목록이에요. 예: ["https://localhost:9200", "https://remote-cluster:9200"]
username 아니요 String HTTP 기본 인증에 사용할 사용자 이름이에요. Data Prepper 2.5부터는 AWS secrets 참조를 적용하면 런타임에 이 설정을 새로 고칠 수 있어요.
password 아니요 String HTTP 기본 인증에 사용할 비밀번호예요. Data Prepper 2.5부터는 AWS secrets 참조를 적용하면 런타임에 이 설정을 새로 고칠 수 있어요.
disable_authentication 아니요 Boolean 인증을 비활성화할지 여부예요. 기본값은 false예요.
aws 아니요 Object AWS 구성이에요. 자세한 내용은 aws를 참조하세요.
acknowledgments 아니요 Boolean true이면 OpenSearch 싱크가 이벤트를 수신할 때 opensearch 소스가 엔드 투 엔드 승인을 받을 수 있어요. 기본값은 false예요.
connection 아니요 Object 연결 구성이에요. 자세한 내용은 연결을 참조하세요.
indices 아니요 Object 처리할 인덱스를 필터링하는 구성이에요. 기본값은 시스템 인덱스를 포함한 모든 인덱스예요. 자세한 내용은 인덱스를 참조하세요.
scheduling 아니요 Object 스케줄링 구성이에요. 자세한 내용은 스케줄링을 참조하세요.
search_options 아니요 Object 소스가 수행하는 검색 옵션 목록이에요. 자세한 내용은 검색 옵션을 참조하세요.
serverless 아니요 Boolean OpenSearch 백엔드가 Amazon OpenSearch Serverless인지 여부를 결정해요. opensearch 소스의 대상이 Amazon OpenSearch Serverless 컬렉션이면 이 값을 true로 설정하세요. 기본값은 false예요.
serverless_options 아니요 Object opensearch 소스의 백엔드가 Amazon OpenSearch Serverless로 설정된 경우에 사용할 수 있는 네트워크 구성 옵션이에요. 자세한 내용은 Serverless 옵션을 참조하세요.

Serverless 옵션

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

옵션 필수 여부 타입 설명
network_policy_name 예 String 생성할 네트워크 정책의 이름이에요.
collection_name 예 String 구성할 Amazon OpenSearch Serverless 컬렉션의 이름이에요.
vpce_id 예 String 소스가 연결할 가상 프라이빗 클라우드(VPC) 엔드포인트예요.

스케줄링

scheduling 구성을 사용하면 index_read_count와 재계산 시간 간격인 interval을 기준으로 소스에서 인덱스를 어떻게 재처리할지 설정할 수 있어요.

예를 들어 index_read_count를 3으로, interval을 1h로 설정하면 모든 인덱스가 1시간 간격으로 3번 재처리돼요. 기본적으로 인덱스는 한 번만 처리돼요.

scheduling 구성 아래에서 다음 옵션을 사용하세요.

옵션 필수 여부 타입 설명
index_read_count 아니요 Integer 각 인덱스가 처리될 횟수예요. 기본값은 1이에요.
interval 아니요 String 재처리 사이의 시간 간격을 결정하는 간격이에요. "PT20.345S"나 "PT15M" 같은 ISO 8601 표기 문자열과, 초("60s") 및 밀리초("1500ms")용 간단한 표기 문자열을 지원해요. 기본값은 8h예요.
start_time 아니요 String 처리가 시작되어야 하는 시간이에요. 소스는 이 시간이 될 때까지 처리를 시작하지 않아요. 문자열은 2007-12-03T10:15:30.00Z 같은 ISO 8601 형식이어야 해요. 기본 옵션은 즉시 처리를 시작해요.

indices

다음 옵션은 regex 패턴을 사용해 소스 클러스터에서 어떤 인덱스를 처리할지 opensearch 소스가 판단하는 데 도움이 돼요. 인덱스는 include 설정 아래의 index_name_regex 패턴 중 하나와 일치하고, exclude 설정 아래의 어떤 패턴과도 일치하지 않을 때만 처리돼요.

옵션 필수 여부 타입 설명
include 아니요 Array of objects 처리할 인덱스를 지정하는 인덱스 구성 패턴 목록이에요.
exclude 아니요 Array of Objects 처리하지 않을 인덱스를 지정하는 인덱스 구성 패턴 목록이에요. 예를 들어 index_name_regex 패턴을 \..*로 지정하면 시스템 인덱스를 제외할 수 있어요.

include 및 exclude 옵션 아래에서 다음 설정을 사용해 인덱스의 regex 패턴을 지정하세요.

옵션 필수 여부 타입 설명
index_name_regex 예 Regex string 인덱스를 매칭할 때 사용할 regex 패턴이에요.

search_options

search_options 구성 아래에서 다음 설정을 사용하세요.

옵션 필수 여부 타입 설명
batch_size 아니요 Integer OpenSearch에서 페이지네이션하면서 읽을 문서 수예요. 기본값은 1000이에요.
search_context_type 아니요 Enum 인덱스에 사용할 검색/페이지네이션 유형을 재정의하는 옵션이에요. point_in_time), scroll, none 중 하나를 지정할 수 있어요. none 옵션은 search_after 파라미터를 사용해요. 자세한 내용은 기본 검색 동작을 참조하세요.

기본 검색 동작

기본적으로 opensearch 소스는 클러스터의 버전과 배포판을 사용해 어떤 search_context_type을 사용할지 결정해요. Point in Time을 지원하는 클러스터와 도메인에서는 소스가 point_in_time을 사용해요. 클러스터가 Point in Time 검색을 지원하지 않으면 scroll search로 자동 전환해요.

Amazon OpenSearch Serverless 컬렉션의 경우 기본 동작은 search_after를 사용하는 거예요. 다만 point_in_time을 사용할 것을 권장해요.

연결

connection 구성 아래에서 다음 설정을 사용하세요.

옵션 필수 여부 타입 설명
cert 아니요 String 클러스터가 OpenSearch Security 플러그인을 사용할 때의 보안 인증서 경로예요. 예를 들어 "config/root-ca.pem"이에요.
insecure 아니요 Boolean SSL 인증서를 검증할지 여부예요. true로 설정하면 인증 기관(CA) 인증서 검증이 비활성화되고 안전하지 않은 HTTP 요청이 전송돼요. 기본값은 false예요.

AWS

aws 서비스 인증을 설정할 때 다음 옵션을 사용하세요.

옵션 필수 여부 타입 설명
region 아니요 String 자격 증명에 사용할 AWS Region이에요. 기본값은 Region을 결정하는 표준 SDK 동작이에요.
sts_role_arn 아니요 String Amazon OpenSearch Service 및 Amazon OpenSearch Serverless에 대한 요청에서 수임해야 하는 AWS Security Token Service(AWS STS) 역할이에요. 기본값은 null이며, 이 경우 자격 증명에 대한 표준 SDK 동작이 사용돼요.
serverless 아니요 Boolean Amazon OpenSearch Serverless 컬렉션에서 처리할 때는 true로 설정해야 해요. 기본값은 false예요.

메트릭

opensearch 소스에는 다음 메트릭이 포함돼요.

카운터

  • documentsProcessed: opensearch 소스 플러그인이 처리한 문서의 총 개수를 측정해요.
  • indicesProcessed: opensearch 소스 플러그인이 처리한 인덱스의 총 개수를 측정해요.
  • processingErrors: opensearch 소스 플러그인에서 발생한 인덱스 처리 오류의 총 개수를 측정해요.
  • credentialsChanged: opensearch 소스가 기본 자격 증명(사용자 이름/비밀번호)을 새로 고치는 횟수를 측정해요.
  • clientRefreshErrors: opensearch 소스가 기본 자격 증명을 새로 고치면서 새 클라이언트를 생성할 때 발생한 오류 횟수를 측정해요.

타이머

  • indexProcessingTime: opensearch 소스 플러그인의 인덱스 처리 지연 시간을 초 단위로 측정해요.

분포 요약

  • bytesReceived: opensearch 소스 플러그인이 수신한 들어오는 문서의 크기 분포를 바이트 단위로 측정해요.
  • bytesProcessed: opensearch 소스 플러그인이 성공적으로 처리한 들어오는 문서의 크기 분포를 바이트 단위로 측정해요.

OpenSearch 클러스터 보안

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

source:
  opensearch:
    username: "admin"
    password: "admin"
  ...

Amazon OpenSearch Service 도메인 보안

opensearch 소스 플러그인은 보안에 AWS Identity and Access Management(IAM)를 사용하는 Amazon OpenSearch Service 도메인에서 데이터를 가져올 수 있어요. 이 플러그인은 기본 Amazon OpenSearch Service 자격 증명 체인을 사용해요. 자격 증명을 설정하려면 AWS Command Line Interface(AWS CLI)로 aws configure를 실행하세요.

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

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AccountId>:user/data-prepper-user"
      },
      "Action": "es:ESHttpGet",
      "Resource": [
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_cat/indices",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_search",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_search/scroll",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/*/_search"
      ]
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AccountId>:user/data-prepper-user"
      },
      "Action": "es:ESHttpPost",
      "Resource": [
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/*/_search/point_in_time",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/*/_search/scroll"
      ]
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AccountId>:user/data-prepper-user"
      },
      "Action": "es:ESHttpDelete",
      "Resource": [
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_search/point_in_time",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_search/scroll"
      ]
    }
  ]
}

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

OpenSearch Serverless 컬렉션 보안

opensearch 소스 플러그인은 Amazon OpenSearch Serverless 컬렉션에서 데이터를 받을 수 있어요.

가상 프라이빗 클라우드(VPC) 액세스를 사용하는 컬렉션에서는 데이터를 읽을 수 없어요. 컬렉션은 퍼블릭 네트워크에서 액세스할 수 있어야 해요. {: .warning}

파이프라인 역할 생성

OpenSearch Serverless 컬렉션 보안을 사용하려면, 파이프라인이 컬렉션에서 데이터를 읽을 때 수임할 IAM 역할을 생성해야 해요. 이 역할에는 다음과 같은 최소 권한이 있어야 해요:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "aoss:APIAccessAll"
            ],
            "Resource": "arn:aws:aoss:*:<AccountId>:collection/*"
        }
    ]
}

컬렉션 생성

다음으로, 다음 설정을 사용해 컬렉션을 생성하세요:

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

  • 필요한 권한을 파이프라인 역할에 부여하는 다음 데이터 액세스 정책. 다음 구성과 같이 설정돼요:

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

Principal 요소의 Amazon Resource Name(ARN)을 앞 단계에서 생성한 파이프라인 역할의 ARN으로 바꾸는 것을 잊지 마세요. {: .tip}

컬렉션 생성 방법에 대한 지침은 Amazon OpenSearch Service 문서의 컬렉션 생성을 참조하세요.

파이프라인 생성

pipeline.yaml 파일에서 OpenSearch Serverless 컬렉션 엔드포인트를 hosts 옵션으로 지정하세요. 또한 serverless 옵션을 true로 설정해야 해요. 다음 예제에서 보는 것처럼 sts_role_arn 옵션에 파이프라인 역할을 지정하세요:

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

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.