Amazon 통합 OpenSearch 파이프라인 생성

파이프라인은 Amazon OpenSearch Ingestion이 데이터를 소스 (데이터 출처) 에서 싱크 (데이터 전송 위치) 로 이동하는 데 사용하는 메커니즘입니다. 통합 OpenSearch 시 싱크는 항상 단일 Amazon OpenSearch 서비스 도메인이지만 데이터 소스는 Amazon S3, Fluent Bit 또는 컬렉터와 같은 클라이언트일 수 있습니다. OpenTelemetry

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

사전 조건 및 필수 역할

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

• OpenSearch 인제션이 싱크에 쓰기 위해 맡게 되는 IAM 역할. 파이프라인 구성에 이 역할 ARN을 포함시킬 것입니다.

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

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

• Amazon OpenSearch 통합 파이프라인에 도메인 액세스 권한 부여

• Amazon 통합 파이프라인에 OpenSearch 컬렉션에 대한 액세스 권한 부여

참고

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

필요한 권한

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

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

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

• iam:PassRole— Ingestion에 파이프라인 역할을 전달하여 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 수집에는 라는 권한도 포함되어 있는데osis:Ingest, 이 권한은 서명 버전 4를 사용하여 파이프라인에 서명된 요청을 전송하기 위해 필요합니다. 자세한 정보는 수집 역할 생성을 참조하세요.

참고

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

각 권한에 대한 자세한 내용은 서비스 권한 부여 참조의 OpenSearch 수집을 위한 작업, 리소스, 조건 키를 참조하십시오.

파이프라인 버전 지정

파이프라인을 구성할 때 파이프라인이 실행할 Data Prepper의 메이저 버전을 지정해야 합니다. 버전을 지정하려면 파이프라인 구성에 version 옵션을 포함하세요.

version: "2"
log-pipeline:
  source:
    ...   

생성을 선택하면 OpenSearch Ingestion은 지정한 메이저 버전의 사용 가능한 최신 마이너 버전을 확인하고 해당 버전으로 파이프라인을 프로비저닝합니다. 예를 들어 Data Prepper의 최신 지원 버전을 2.1.1로 지정하고 version: "2" 지정한 경우 OpenSearch Ingestion은 파이프라인을 버전 2.1.1로 프로비저닝합니다. 파이프라인이 실행 중인 마이너 버전은 공개적으로 표시하지 않습니다.

Data Prepper의 새 메이저 버전이 출시될 때 파이프라인을 업그레이드하려면 파이프라인 구성을 편집하고 새 버전을 지정하세요. 파이프라인을 이전 버전으로 다운그레이드할 수 없습니다.

참고

OpenSearch 인제션은 새 버전의 Data Prepper가 출시되자마자 바로 지원되지는 않습니다. 새 버전이 공개되는 시점과 Ingestion에서 새 버전이 지원되는 시점 사이에는 약간의 지연이 있을 수 있습니다. OpenSearch 또한 OpenSearch Ingestion은 특정 메이저 또는 마이너 버전을 명시적으로 지원하지 않을 수도 있습니다. 포괄적인 목록은 지원되는 Data Prepper 버전 섹션을 참조하십시오.

블루/그린 배포를 시작하는 파이프라인을 변경할 때마다 OpenSearch Ingestion은 파이프라인 YAML 파일에 현재 구성되어 있는 메이저 버전의 최신 마이너 버전으로 업그레이드할 수 있습니다. 자세한 내용은 을 참조하십시오. 파이프라인 업데이트를 위한 블루/그린 배포 OpenSearch 파이프라인 구성 내에서 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 파이프라인을 생성하는 방법을 설명합니다. OpenSearch AWS CLI

콘솔

파이프라인을 생성하려면

1. https://console.aws.amazon.com/aos/home 에서 아마존 OpenSearch 서비스 콘솔에 로그인합니다.

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

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

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

5. 통합 OpenSearch 컴퓨팅 유닛 (OCU) 에서 최소 및 최대 파이프라인 용량을 구성합니다. 자세한 정보는 파이프라인 크기 조정을 참조하세요.

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

   참고

   각 하위 파이프라인에 sts_role_arn 및 sigv4 옵션을 포함해야 합니다. 파이프라인은 에 정의된 역할을 맡아 도메인에 요청을 서명합니다. sts_role_arn 자세한 정보는 Amazon OpenSearch 통합 파이프라인에 도메인 액세스 권한 부여을 참조하세요.

   다음 샘플 구성 파일은 HTTP 소스 및 Grok 플러그인을 사용하여 구조화되지 않은 로그 데이터를 처리하고 이를 서비스 도메인으로 전송합니다. OpenSearch 하위 파이프라인은 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"

   참고

   YAML 파이프라인 정의 내에 싱크를 여러 개 지정하는 경우 모두 동일한 서비스 도메인이어야 합니다. OpenSearch OpenSearch 통합 파이프라인은 서로 다른 여러 도메인에 쓸 수 없습니다.

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

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

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

   설정	설명
   VPC	사용하려는 Virtual Private Cloud(VPC)를 선택합니다. VPC와 파이프라인의 AWS 리전(은)는 동일해야 합니다.
   서브넷	하나 이상의 서브넷을 선택합니다. OpenSearch 서비스는 VPC 엔드포인트와 엘라스틱 네트워크 인터페이스를 서브넷에 배치합니다.
   보안 그룹	필요한 애플리케이션이 파이프라인에 노출된 포트 (80 또는 443) 및 프로토콜 (HTTP 또는 HTTP) 의 OpenSearch 통합 파이프라인에 도달하도록 허용하는 VPC 보안 그룹을 하나 이상 선택합니다.
   VPC 연결 옵션	소스가 자체 관리형 엔드포인트인 경우 파이프라인을 VPC에 연결하세요. 제공된 기본 CIDR 옵션 중 하나를 선택하거나 사용자 지정 CIDR을 사용하십시오.

   자세한 정보는 Amazon OpenSearch 통합 파이프라인에 대한 VPC 액세스 구성을 참조하세요.

9. (선택 사항) 태그에서 파이프라인에 하나 이상의 태그(키-값 쌍)를 추가합니다. 자세한 정보는 Amazon OpenSearch Ingestion 파이프라인 태그 지정을 참조하세요.

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

11. 다음을 선택하세요.

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

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

AWS CLI

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 인제션은 비동기 프로세스를 실행하여 파이프라인을 빌드합니다. 파이프라인이 Active 상태가 되면 데이터 수집을 시작할 수 있습니다. 파이프라인 상태를 확인하려면 명령어를 사용하세요. GetPipeline

OpenSearch 통합 API

통합 API를 사용하여 OpenSearch 통합 파이프라인을 만들려면 작업을 OpenSearch 호출하십시오. CreatePipeline

파이프라인이 성공적으로 생성되면 클라이언트를 구성하고 서비스 도메인으로 데이터 수집을 시작할 수 있습니다. OpenSearch 자세한 정보는 Amazon 통합 파이프라인 OpenSearch 연동 사용하기을 참조하세요.

파이프라인 생성 상태 추적

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

콘솔

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

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

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

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

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

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

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

CLI

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 통합 API

OpenSearch 통합 API를 사용하여 파이프라인 생성 상태를 추적하려면 작업을 호출하십시오. GetPipelineChangeProgress

청사진을 사용하여 파이프라인 생성

파이프라인 정의를 처음부터 생성하는 대신 Trace Analytics 또는 Apache 로그와 같은 일반적인 수집 시나리오를 위해 사전 구성된 YAML 템플릿인 구성 청사진을 사용할 수 있습니다. 구성 청사진을 사용하면 구성을 처음부터 작성하지 않고도 파이프라인을 쉽게 프로비저닝할 수 있습니다.

콘솔

파이프라인 청사진 사용

1. https://console.aws.amazon.com/aos/home 에서 아마존 OpenSearch 서비스 콘솔에 로그인합니다.

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

3. 청사진를 선택합니다. 파이프라인 구성은 선택한 사용 사례의 하위 파이프라인으로 채워집니다.

4. 청사진 구성 과정을 안내하는 주석이 달린 텍스트를 검토하세요.

   중요

   파이프라인 청사진은 현재 상태로는 유효하지 않습니다. 인증에 사용할 AWS 리전 및 역할 ARN을 제공하는 등 일부 수정이 필요합니다. 그렇지 않으면 파이프라인 검증이 실패합니다.

CLI

를 사용하여 사용 가능한 모든 블루프린트 목록을 가져오려면 요청을 list-pipeline-blueprints보내십시오. AWS CLI

aws osis list-pipeline-blueprints 

이 요청은 사용 가능한 모든 청사진의 목록을 반환합니다.

특정 블루프린트에 대한 자세한 정보를 얻으려면 다음 명령어를 사용하세요. get-pipeline-blueprint

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 a Role ARN with access to the domain. This role should have a trust relationship with osis-pipelines.amazonaws.com\n          # sts_role_arn: \"arn:aws:iam::123456789012:role/Example-Role\"\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            # sts_role_arn: \"arn:aws:iam::123456789012:role/Example-Role\"\n",
      "BlueprintName":"AWS-ApacheLogPipeline"
   }
}

OpenSearch 통합 API

OpenSearch Ingestion API를 사용하여 파이프라인 블루프린트에 대한 정보를 가져오려면 및 작업을 사용하십시오. ListPipelineBlueprintsGetPipelineBlueprint