Amazon OpenSearch Ingestion 파이프라인 생성 - Amazon OpenSearch 서비스
사전 조건 및 필요한 IAM 역할필수 IAM 권한파이프라인 버전 지정수집 경로 지정파이프라인 생성파이프라인 생성 상태 추적

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Amazon OpenSearch Ingestion 파이프라인 생성

파이프라인은 Amazon OpenSearch Ingestion이 데이터를 소스(데이터의 출처)에서 싱크 (데이터가 이동하는 곳)로 이동하는 데 사용하는 메커니즘입니다. OpenSearch Ingestion에서 싱크는 항상 단일 Amazon OpenSearch Service 도메인이지만, 데이터 소스는 Amazon S3, Fluent Bit 또는 OpenTelemetry Collector와 같은 클라이언트일 수 있습니다.

자세한 내용은 OpenSearch 설명서의 파이프라인을 참조하세요.

사전 조건 및 필요한 IAM 역할

OpenSearch Ingestion 파이프라인을 생성하려면 다음과 같은 리소스가 있어야 합니다.

  • 싱크에 쓰기 위해 OpenSearch Ingestion이 수임하는 IAM 역할. 파이프라인 구성에 이 역할 ARN을 포함시킬 것입니다.

  • 싱크 역할을 하는 OpenSearch Service 도메인 또는 OpenSearch Serverless 컬렉션입니다. 도메인에 쓰는 경우 OpenSearch 1.0 이상 또는 Elasticsearch 7.4 이상이 실행되고 있어야 합니다. 싱크에는 IAM 파이프라인 역할에 적절한 권한을 부여하는 액세스 정책이 있어야 합니다.

이러한 리소스를 만드는 방법 설명은 다음 주제를 참조하세요.

참고

세분화된 액세스 제어를 사용하는 도메인에 쓰는 경우 완료해야 할 추가 단계가 있습니다. 3단계: 파이프라인 역할 매핑(세분화된 액세스 제어를 사용하는 도메인에만 해당) 섹션을 참조하세요.

필수 IAM 권한

OpenSearch Ingestion은 다음 IAM 권한을 사용하여 파이프라인을 생성합니다.

  • osis:CreatePipeline - 파이프라인을 생성합니다.

  • osis:ValidatePipeline— 파이프라인 구성이 유효한지 확인하세요.

  • iam:PassRole - OpenSearch Ingestion에 파이프라인 역할을 전달하여 도메인에 데이터를 쓸 수 있도록 합니다. 이 권한은 파이프라인 역할 리소스(파이프라인 구성에서 sts_role_arn 옵션에 대해 지정한 ARN)에 있어야 하며, 각 파이프라인에서 다른 역할을 사용하려는 * 경우에만 가능합니다.

예를 들어 다음 정책에서 파이프라인을 호출할 권한을 부여합니다.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Resource":"*",
         "Action":[
            "osis:CreatePipeline",
            "osis:ListPipelineBlueprints",
            "osis:ValidatePipeline"
         ]
      },
      {
         "Resource":[
            "arn:aws:iam::your-account-id:role/pipeline-role"
         ],
         "Effect":"Allow",
         "Action":[
            "iam:PassRole"
         ]
      }
   ]
}

OpenSearch Ingestion에는 서명 버전 4를 사용하여 파이프라인에 서명된 요청을 보내는 데 필요한 osis:Ingest 권한도 포함되어 있습니다. 자세한 내용은 수집 역할 생성 단원을 참조하십시오.

참고

또한 계정에서 파이프라인을 생성하는 첫 번째 사용자에게 iam:CreateServiceLinkedRole 작업에 대한 권한이 있어야 합니다. 자세한 내용은 파이프라인 역할 리소스를 참조하세요.

각 권한에 대한 자세한 내용은 서비스 권한 부여 참조에서 OpenSearch Ingestion에 대한 작업, 리소스 및 조건 키에 대한 액션, 리소스 및 조건 키를 참조하세요.

파이프라인 버전 지정

파이프라인을 구성할 때 파이프라인이 실행할 Data Prepper의 메이저 버전을 지정해야 합니다. 버전을 지정하려면 파이프라인 구성에 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 버전 섹션을 참조하십시오.

블루/그린 배포를 시작하는 파이프라인을 변경할 때마다 OpenSearch Ingestion은 파이프라인 YAML 파일에 현재 구성되어 있는 메이저 버전의 최신 마이너 버전으로 업그레이드할 수 있습니다. 자세한 내용은 파이프라인 업데이트를 위한 블루/그린 배포 단원을 참조하십시오. OpenSearch Ingestion은 파이프라인 구성 내에서 version 옵션을 명시적으로 업데이트하지 않는 한 파이프라인의 메이저 버전을 변경할 수 없습니다.

수집 경로 지정

OTel 추적 및 oTel 지표와 같은 풀 기반 소스의 경우 OpenSearch Ingestion을 사용하려면 소스 구성에 path 옵션이 추가로 필요합니다. 경로는 수집을 위한 URI 경로를 나타내는 /log/ingest와 같은 문자열입니다. 이 경로는 파이프라인으로 데이터를 전송하는 데 사용하는 URI를 정의합니다.

예를 들어, 이름이 logs인 수집 파이프라인에 대해 다음과 같은 입력 하위 파이프라인을 지정한다고 가정해 보겠습니다.

entry-pipeline:
  source:
    http:
      path: "/my/test_path"

파이프라인으로 데이터를 수집할 때는 클라이언트 구성에서 https://logs-abcdefgh.us-west-2.osis.amazonaws.com/my/test_path와 같은 엔드포인트를 지정해야 합니다.

경로는 슬래시(/) 로 시작해야 하며 특수 문자 '-', '_', '.', '/'를 비롯해 ${pipelineName} 자리 표시자를 포함할 수 있습니다. ${pipelineName}(예:path: "/${pipelineName}/test_path")를 사용하면 변수가 관련 하위 파이프라인의 이름으로 대체됩니다. 이 예제에서는 https://logs.us-west-2.osis.amazonaws.com/entry-pipeline/test_path입니다.

파이프라인 생성

이 섹션에서는 OpenSearch Service 콘솔 및 AWS CLI을 사용하여 OpenSearch Ingestion 파이프라인을 생성하는 방법을 설명합니다.

파이프라인을 생성하려면

  1. https://console.aws.amazon.com/aos/home에서 Amazon OpenSearch Service 콘솔에 로그인합니다.

  2. 왼쪽 탐색 창에서 파이프라인을 선택한 후 파이프라인 생성을 선택합니다.

  3. 빈 파이프라인을 선택하거나 구성 블루프린트를 선택합니다. 블루프린트에는 다양한 공통 사용 사례를 위한 사전 구성된 YAML 및 JSON 구성 파일이 포함됩니다. 자세한 내용은 청사진을 사용하여 파이프라인 생성 단원을 참조하십시오.

    블루프린트 선택을 선택합니다.

  4. 파이프라인 이름을 입력합니다.

  5. (선택 사항) 영구 버퍼 활성화를 선택합니다. 영구 버퍼는 여러 AZ 간에서 디스크 기반 버퍼에 데이터를 저장합니다. 더 자세한 내용은 영구 버퍼링을 참조하세요. 영구 버퍼를 활성화하는 경우 버퍼 데이터를 암호화할 AWS Key Management Service 키를 선택합니다.

  6. Ingestion OpenSearch Compute Units(OCU)의 최소 및 최대 파이프라인 용량을 구성합니다. 자세한 내용은 파이프라인 크기 조정 단원을 참조하십시오.

  7. 파이프라인 구성에서 YAML 형식의 파이프라인 구성을 제공합니다. 블루프린트를 사용하는 경우 구성이 이미 사전에 채워져 있지만 몇 가지 수정을 해야 합니다.

    단일 파이프라인 구성 파일은 1~10개의 하위 파이프라인을 포함할 수 있습니다. 각 하위 파이프라인은 단일 소스, 0개 이상의 프로세서, 단일 싱크의 조합입니다. OpenSearch Ingestion의 경우 싱크는 항상 OpenSearch Service 도메인이어야 합니다. ///지원되는 작업 목록은 Amazon OpenSearch Ingestion 파이프라인에 지원되는 플러그인 및 옵션 항목을 참조하세요.

    참고

    각 하위 파이프라인에 sts_role_arn 옵션을 포함해야 합니다. 파이프라인은 도메인에 대한 요청에 서명하기 위해 sts_role_arn에 정의된 역할을 수임합니다. 자세한 내용은 도메인에 대한 Amazon OpenSearch Ingestion 파이프라인 액세스 권한 부여 단원을 참조하십시오.

    다음 샘플 구성 파일은 HTTP 소스 및 Grok 플러그인을 사용하여 구조화되지 않은 로그 데이터를 처리하고 이를 OpenSearch Service 도메인으로 보냅니다. 하위 파이프라인은 log-pipeline으로 지정되었습니다.

    version: "2"
log-pipeline:
  source:
    http:
      path: "/log/ingest"
  processor:
    - grok:
        match:
          log: [ '%{COMMONAPACHELOG}' ]
    - date:
        from_time_received: true
        destination: "@timestamp"
  sink:
    - opensearch:
        hosts: [ "https://search-my-domain.us-east-1.es.amazonaws.com" ]
        index: "apache_logs"
        aws:
          sts_role_arn: "arn:aws:iam::123456789012:role/{pipeline-role}"
          region: "us-east-1"

    자체 파이프라인 구성을 구축하거나 파일 업로드를 선택하고 자체 관리형 Data Prepper 파이프라인의 기존 구성을 가져올 수 있습니다. 또는 구성 청사진을 사용할 수 있습니다.

  8. 파이프라인을 구성한 후 파이프라인 검증을 선택하여 구성이 올바른지 확인합니다. 검증이 실패하면 오류를 수정하고 검증을 다시 실행하세요.

  9. 네트워크 구성에서 VPC 액세스 또는 퍼블릭 액세스를 선택합니다. 퍼블릭 액세스(Public access)를 선택한 경우, 다음 단계로 건너뜁니다. VPC 액세스를 선택하는 경우 다음 설정을 구성하세요.

    설정 설명
    엔드포인트 관리

    VPC 엔드포인트를 직접 생성할지 아니면 OpenSearch Ingestion에서 자동으로 생성할지 선택합니다. 엔드포인트 관리는 기본적으로 OpenSearch Ingestion에서 관리하는 엔드포인트로 설정됩니다.
    VPC

    사용하려는 Virtual Private Cloud(VPC)를 선택합니다. VPC와 파이프라인의 AWS 리전(은)는 동일해야 합니다.
    서브넷

    서브넷을 하나 이상 선택합니다. OpenSearch Service가 서브넷에 VPC 엔드포인트와 탄력적 네트워크 인터페이스를 배치합니다.
    보안 그룹

    필요한 애플리케이션이 파이프라인에 의해 노출된 포트(80 또는 443) 및 프로토콜(HTTP 또는 HTTPS)에서 OpenSearch Ingestion 파이프라인에 도달하도록 허용하는 VPC 보안 그룹을 하나 이상 선택합니다.
    VPC 연결 옵션

    소스가 자체 관리형 엔드포인트인 경우 파이프라인을 VPC에 연결합니다. 제공된 기본 CIDR 옵션 중 하나를 선택하거나 사용자 지정 CIDR을 사용합니다.

    자세한 내용은 Amazon OpenSearch Ingestion 파이프라인에 대한 VPC 액세스 구성 단원을 참조하십시오.

  10. (선택 사항) 태그에서 파이프라인에 하나 이상의 태그(키-값 쌍)를 추가합니다. 자세한 내용은 Amazon OpenSearch Ingestion 파이프라인 태그 지정 단원을 참조하십시오.

  11. (선택 사항) 로그 게시 옵션에서 Amazon CloudWatch Logs에 대한 파이프라인 로그 게시를 활성화합니다. 파이프라인 문제를 보다 쉽게 해결할 수 있도록 로그 게시를 활성화하는 것이 좋습니다. 자세한 내용은 파이프라인 모니터링 단원을 참조하십시오.

  12. Next(다음)를 선택합니다.

  13. 파이프라인 구성을 검토하고 생성을 선택합니다.

OpenSearch Ingestion은 비동기 프로세스를 실행하여 파이프라인을 구축합니다. 파이프라인이 Active 상태가 되면 데이터 수집을 시작할 수 있습니다.

create-pipeline 명령어는 파이프라인 구성을 문자열 또는 .yaml 파일 내에서 받아들입니다. 구성을 문자열로 제공하는 경우 각 새 줄을 \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"

OpenSearch Ingestion은 비동기 프로세스를 실행하여 파이프라인을 구축합니다. 파이프라인이 Active 상태가 되면 데이터 수집을 시작할 수 있습니다. 파이프라인 상태를 확인하려면 GetPipeline 명령을 사용하세요.

OpenSearch Ingestion API를 사용하여 OpenSearch Ingestion 파이프라인을 생성하려면 CreatePipeline 작업을 호출하세요.

파이프라인이 성공적으로 생성되면 클라이언트를 구성하고 OpenSearch Service 도메인으로 데이터 수집을 시작할 수 있습니다. 자세한 내용은 Amazon OpenSearch Ingestion 파이프라인을 다른 서비스 및 애플리케이션과 통합 단원을 참조하십시오.

파이프라인 생성 상태 추적

OpenSearch Ingestion이 파이프라인을 프로비저닝하고 데이터 수집을 준비할 때 파이프라인의 상태를 추적할 수 있습니다.

파이프라인을 처음 생성한 후에는 OpenSearch Ingestion에서 데이터 수집을 준비하면서 여러 단계를 거칩니다. 파이프라인 생성의 다양한 단계를 보려면 파이프라인 이름을 선택하여 해당 파이프라인 설정 페이지를 확인하세요. 상태에서 세부 정보 보기를 선택합니다.

파이프라인은 다음 단계를 거친 후 데이터를 수집할 수 있게 됩니다.

  • 검증 — 파이프라인 구성을 검증합니다. 이 단계가 완료되면 모든 검증이 성공한 것입니다.

  • 환경 조성 — 리소스를 준비 및 프로비저닝합니다. 이 단계가 완료되면 새 파이프라인 환경이 만들어진 것입니다.

  • 파이프라인 배포 - 파이프라인을 배포합니다. 이 단계가 완료되면 파이프라인이 성공적으로 배포된 것입니다.

  • 파이프라인 상태 확인 - 파이프라인 상태를 확인합니다. 이 단계가 완료되면 모든 상태 확인이 통과된 것입니다.

  • 트래픽 활성화 - 파이프라인이 데이터를 수집할 수 있도록 합니다. 이 단계가 완료되면 파이프라인으로 데이터 수집을 시작할 수 있습니다.

파이프라인 상태를 확인하려면 get-pipeline-change-progress 명령을 사용하세요. 다음 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를 사용하여 파이프라인 생성 상태를 추적하려면 GetPipelineChangeProgress 작업을 호출하세요.