Playbook: Amazon OpenSearch Service to Amazon OpenSearch Serverless NextGen

Playbook: Amazon OpenSearch Service to Amazon OpenSearch Serverless NextGen (vector search)

출처: 문서

본문

플레이북: Amazon OpenSearch Service에서 Amazon OpenSearch Serverless NextGen으로(벡터 검색)

이 플레이북은 Migration Assistant를 사용하여 Elasticsearch 7.10을 실행하는 Amazon OpenSearch Service 도메인을 Amazon OpenSearch Serverless NextGen 벡터 검색 컬렉션으로 마이그레이션하는 방법을 설명해요.

VECTORSEARCH 컬렉션 유형의 Amazon OpenSearch Serverless NextGen은 다음과 같은 이점을 제공해요.

• 클러스터 관리 불필요 -- 노드 크기 조정, 패치, 스케일링이 필요 없어요. AWS가 용량을 자동으로 관리해요.
• 내장 벡터 엔진 -- k-NN 검색, 의미론적 검색, 검색 증강 생성(RAG) 워크로드를 위해 설계되었어요.
• 사용량 기반 가격 -- OCU(OpenSearch Compute Unit) 기반 청구로 유휴 용량이 아닌 사용한 만큼만 지불해요.
• 자동 스케일링 -- 수요에 따라 인덱싱과 검색 용량을 독립적으로 스케일링해요.
• 내장 암호화 및 액세스 제어 -- 저장 데이터 및 전송 중 암호화, 세분화된 데이터 액세스 정책을 보안 플러그인 관리 없이 제공해요.

Amazon OpenSearch Service 도메인에서 벡터 또는 k-NN 워크로드를 실행 중이라면 Serverless NextGen은 메모리 및 컴퓨팅 집약적인 벡터 워크로드를 위해 인스턴스 유형을 수동으로 선택하고 스케일링할 필요를 없애줘요. {: .note }

OpenSearch Service와 OpenSearch Serverless NextGen 비교

다음 표는 Amazon OpenSearch Service와 Amazon OpenSearch Serverless NextGen의 주요 차이점을 보여줘요.

Migration Assistant는 데이터만 마이그레이션해요(메타데이터, 문서, 실시간 트래픽). 마이그레이션 후 대상에서 ISM 정책, 수집 파이프라인, 대시보드를 수동으로 다시 생성해야 해요. {: .warning }

예제 플레이스홀더

다음 표는 이 플레이북에서 사용되는 예제 값을 보여줘요.

이 플레이북의 계정 ID, 도메인 이름, 엔드포인트는 예시예요. 사용자 환경의 값으로 바꿔주세요. {: .note }

예상 소요 시간

다음 표는 마이그레이션의 각 단계별 대략적인 소요 시간을 보여줘요.

시작하기 전에

일반 플레이북 사전 준비 사항 외에도 마이그레이션을 시작하기 전에 다음을 확인해요.

소스 클러스터 요구 사항

Amazon OpenSearch Service 도메인이 다음 요구 사항을 모두 충족해야 해요.

• 도메인이 Elasticsearch 7.10(또는 지원되는 소스 버전)을 실행 중이어야 해요.
• 도메인이 VPC에 있고 Migration Assistant를 배포하는 VPC에서 접근 가능해야 해요.
• 도메인의 VPC 엔드포인트(예: https://vpc-my-source-domain-abc123example.us-east-2.es.amazonaws.com)를 알고 있어야 해요.
• 세분화된 액세스 제어(FGAC)가 활성화된 경우 Migration Assistant IAM 역할을 MasterUserARN으로 매핑해야 해요.

소스 도메인 세부 정보를 확인하려면 다음 명령을 실행해요.

aws opensearch describe-domain \
  --region us-east-2 \
  --domain-name my-source-domain \
  --query 'DomainStatus.{EngineVersion:EngineVersion,Endpoint:Endpoints.vpc,VPC:VPCOptions.VPCId,Subnets:VPCOptions.SubnetIds,SGs:VPCOptions.SecurityGroupIds,FGAC:AdvancedSecurityOptions.Enabled}' \
  --output table

{% include copy.html %}

예상 출력:

-----------------------------------------------------------
|                     DescribeDomain                      |
+-----------------+---------------------------------------+
| EngineVersion   | Elasticsearch_7.10                    |
| Endpoint        | vpc-my-source-domain-...    |
| FGAC            | True                                  |
| VPC             | vpc-009ea0f461cc426c6                 |
+-----------------+---------------------------------------+

대상 컬렉션 요구 사항

대상 Amazon OpenSearch Serverless NextGen 컬렉션은 다음과 같이 구성되어야 해요.

• 유형 -- 이 플레이북에서는 VECTORSEARCH예요. 다른 워크로드의 경우 SEARCH를 사용해요. TIMESERIES는 NextGen 출시 시 지원되지 않아요(Classic에서 사용 가능).
• 암호화 정책 -- 컬렉션을 포함하는 암호화 정책이 하나 이상 있어야 해요.
• 네트워크 정책 -- 요구 사항에 따라 퍼블릭 또는 VPC 액세스.
• 데이터 액세스 정책 -- Migration Assistant IAM 역할에 전체 인덱스 읽기 및 쓰기 액세스 권한을 부여해요.

이미 컬렉션이 있다면 5단계: Migration Assistant IAM 역할 매핑으로 건너뛰어요. 그렇지 않다면 컬렉션 생성을 진행해요.

인프라 요구 사항

다음 인프라가 필요해요.

• 소스 도메인이 있는 VPC의 VPC ID와 서로 다른 가용 영역에 있는 서브넷 ID가 두 개 이상 있어야 해요.
• 서브넷에 NAT 게이트웨이 액세스가 있거나 --create-vpc-endpoints 플래그를 사용할 거예요.
• AWS CLI 2.x와 kubectl이 설치되어 있거나 AWS CloudShell을 사용하고 있어야 해요.
• AWS 자격 증명에 계정 111122223333의 Admin 권한이 있어야 해요.

위 항목 중 하나라도 준비되지 않았다면 계속하기 전에 준비를 완료해요. {: .warning }

사전 준비: 컬렉션 생성

다음 단계를 완료하여 컬렉션을 생성해요.

1단계: 암호화 정책 생성

암호화 정책을 생성하려면 다음 명령을 실행해요.

aws opensearchserverless create-security-policy \
  --region us-east-2 \
  --name vector-search-enc \
  --type encryption \
  --policy '{
    "Rules": [
      {
        "ResourceType": "collection",
        "Resource": ["collection/my-target-collection"]
      }
    ],
    "AWSOwnedKey": true
  }'

{% include copy.html %}

2단계: 네트워크 정책 생성

이 플레이북은 퍼블릭 액세스를 사용해요. 프로덕션 환경에서는 VPC 액세스를 고려해요. 네트워크 정책을 생성하려면 다음 명령을 실행해요.

aws opensearchserverless create-security-policy \
  --region us-east-2 \
  --name vector-search-net \
  --type network \
  --policy '[{
    "Rules": [
      {
        "ResourceType": "collection",
        "Resource": ["collection/my-target-collection"]
      },
      {
        "ResourceType": "dashboard",
        "Resource": ["collection/my-target-collection"]
      }
    ],
    "AllowFromPublic": true
  }]'

{% include copy.html %}

3단계: 데이터 액세스 정책 생성

이 정책은 계정 루트, Admin 역할, Migration Assistant 역할에 컬렉션 액세스 권한을 부여해요. 데이터 액세스 정책을 생성하려면 다음 명령을 실행해요.

aws opensearchserverless create-access-policy \
  --region us-east-2 \
  --name vector-search-access \
  --type data \
  --policy '[{
    "Rules": [
      {
        "ResourceType": "collection",
        "Resource": ["collection/my-target-collection"],
        "Permission": [
          "aoss:CreateCollectionItems",
          "aoss:DeleteCollectionItems",
          "aoss:UpdateCollectionItems",
          "aoss:DescribeCollectionItems"
        ]
      },
      {
        "ResourceType": "index",
        "Resource": ["index/my-target-collection/*"],
        "Permission": [
          "aoss:CreateIndex",
          "aoss:DeleteIndex",
          "aoss:UpdateIndex",
          "aoss:DescribeIndex",
          "aoss:ReadDocument",
          "aoss:WriteDocument"
        ]
      }
    ],
    "Principal": [
      "arn:aws:iam::111122223333:role/Admin",
      "arn:aws:iam::111122223333:root"
    ]
  }]'

{% include copy.html %}

4단계: 컬렉션 그룹 생성

NextGen 컬렉션은 컬렉션 그룹에 속해야 해요. 생성하려면 다음 명령을 실행해요.

aws opensearchserverless create-collection-group \
  --region us-east-2 \
  --name vector-search-group \
  --generation NEXTGEN \
  --standby-replicas ENABLED

{% include copy.html %}

5단계: 컬렉션 생성

컬렉션을 생성하려면 다음 명령을 실행해요.

aws opensearchserverless create-collection \
  --region us-east-2 \
  --name my-target-collection \
  --type VECTORSEARCH \
  --collection-group-name vector-search-group

{% include copy.html %}

컬렉션이 ACTIVE 상태가 될 때까지 기다려요(약 2~3분):

watch -n 10 "aws opensearchserverless batch-get-collection \
  --region us-east-2 \
  --names my-target-collection \
  --query 'collectionDetails[0].{Status:status,Endpoint:collectionEndpoint}' \
  --output table"

{% include copy.html %}

Status가 ACTIVE를 표시하면 엔드포인트를 기록해요. 다음 예제는 이 플레이북의 예상 출력을 보여줘요.

https://3nbrhts7rv9jxatilz9e.aoss.us-east-2.on.aws

6단계: 컬렉션에 접근 가능한지 확인

awscurl이 설치되어 있지 않다면 다음 명령을 실행하여 설치해요.

pip install awscurl

{% include copy.html %}

컬렉션에 접근할 수 있는지 확인하려면 다음 명령을 실행해요.

awscurl --service aoss --region us-east-2 \
  "https://3nbrhts7rv9jxatilz9e.aoss.us-east-2.on.aws/"

{% include copy.html %}

OpenSearch 버전이 포함된 JSON 응답이 표시될 거예요.

1단계: 마이그레이션 방식 선택

워크플로를 구성하기 전에 다음 마이그레이션 방식 중 하나를 선택해요.

옵션 A: 계획된 다운타임

계획된 다운타임 마이그레이션의 경우 다음 단계를 따라요.

1. 소스 도메인에 대한 쓰기를 중지해요.
2. 스냅샷을 생성해요.
3. 메타데이터를 마이그레이션해요.
4. 문서를 백필해요.
5. 대상을 검증해요.
6. 클라이언트를 Serverless NextGen 컬렉션 엔드포인트로 연결해요.

어떤 방식을 선택해야 할지 확실하지 않다면 계획된 다운타임을 사용해요. 구성 요소가 적고 위험이 낮기 때문이에요. {: .note }

옵션 B: 제로 다운타임

제로 다운타임 마이그레이션의 경우 다음 단계를 따라요.

1. 먼저 캡처를 시작해요.
2. 클라이언트를 캡처 프록시로 라우팅해요.
3. 스냅샷을 생성해요.
4. 메타데이터를 마이그레이션해요.
5. 문서를 백필해요.
6. 대상이 따라잡을 때까지 캡처된 트래픽을 재생해요.
7. 대상을 검증해요.
8. 클라이언트를 Serverless NextGen 컬렉션 엔드포인트로 전환해요.

이 옵션을 선택하는 경우 클라이언트는 인덱스 및 업데이트 작업에 명시적 문서 ID를 보내야 해요. 애플리케이션이 자동 생성 ID에 의존하는 경우 캡처 및 재생을 사용하지 마세요. {: .warning }

2단계: VPC 정보 수집

Migration Assistant 배포가 재사용하는 VPC 및 서브넷 정보를 수집해요.

소스 도메인의 VPC를 찾아요.

aws opensearch describe-domain \
  --region us-east-2 \
  --domain-name my-source-domain \
  --query 'DomainStatus.VPCOptions.{VPCId:VPCId,SubnetIds:SubnetIds,SecurityGroupIds:SecurityGroupIds}' \
  --output json

{% include copy.html %}

VPC ID(vpc-009ea0f461cc426c6)와 서브넷 ID를 기록해요.

서브넷 세부 정보를 찾아요.

aws ec2 describe-subnets \
  --region us-east-2 \
  --filters "Name=vpc-id,Values=vpc-009ea0f461cc426c6" \
  --query "Subnets[*].{SubnetId:SubnetId,AZ:AvailabilityZone,CidrBlock:CidrBlock,Name:Tags[?Key=='Name']|[0].Value}" \
  --output table

{% include copy.html %}

서로 다른 가용 영역에 있는 프라이빗 서브넷을 두 개 이상 선택해요. 쉼표로 구분된 문자열로 기록해요.

Migration Assistant를 소스 도메인과 동일한 VPC에 배포하거나 VPC 피어링을 사용하여 다른 VPC에 배포할 수 있어요. 동일한 VPC에 배포하면 구성이 더 적게 필요해요. 다른 VPC에 배포하는 경우 문제 해결 섹션을 참조해요. {: .note }

3단계: EKS에 Migration Assistant 배포

이 단계에서는 부트스트랩 스크립트를 사용하여 Amazon EKS에 Migration Assistant를 배포해요.

부트스트랩 스크립트를 다운로드해요.

curl -sL -o aws-bootstrap.sh \
  "https://github.com/opensearch-project/opensearch-migrations/releases/latest/download/aws-bootstrap.sh" \
  && chmod +x aws-bootstrap.sh

{% include copy.html %}

소스 도메인과 동일한 VPC에 배포해요.

./aws-bootstrap.sh \
  --deploy-import-vpc-cfn \
  --stack-name MA \
  --stage dev \
  --vpc-id vpc-009ea0f461cc426c6 \
  --subnet-ids subnet-055497d9551cc298a,subnet-0a776b7d7724f22ae \
  --region us-east-2

{% include copy.html %}

이 명령은 Amazon EKS 클러스터, Amazon ECR 리포지토리, IAM 역할을 생성한 다음 Migration Assistant Helm 차트를 설치하는 CloudFormation 스택을 배포해요. 배포에는 약 15~25분이 소요돼요.

./aws-bootstrap.sh \
  --deploy-import-vpc-cfn \
  --stack-name MA \
  --stage dev \
  --vpc-id vpc-009ea0f461cc426c6 \
  --subnet-ids subnet-055497d9551cc298a,subnet-0a776b7d7724f22ae \
  --create-vpc-endpoints \
  --region us-east-2

배포를 확인해요.

aws eks update-kubeconfig --region us-east-2 --name migration-eks-cluster-dev-us-east-2
kubectl get pods -n ma

{% include copy.html %}

모든 파드가 Running 상태와 1/1 준비 상태를 표시해야 해요.

4단계: CloudFormation 출력 확인

CloudFormation 출력을 확인하려면 다음 명령을 실행해요.

aws cloudformation describe-stacks \
  --region us-east-2 \
  --stack-name MA \
  --query "Stacks[0].Outputs[?contains(OutputKey,'MigrationsExportString')].OutputValue" \
  --output text

{% include copy.html %}

다음 표는 주요 출력 값을 보여줘요.

기본 Amazon S3 버킷은 s3://migrations-default-111122223333-dev-us-east-2예요.

5단계: Migration Assistant IAM 역할 매핑

배포 후 다음 단계를 완료하여 Migration Assistant IAM 역할에 소스와 대상 모두에 대한 액세스 권한을 부여해요.

1단계: Amazon OpenSearch Serverless NextGen 데이터 액세스 정책 업데이트

Migration Assistant를 배포한 후 migrations-role과 snapshot-role을 Amazon OpenSearch Serverless NextGen 데이터 액세스 정책에 추가해요.

# Get the current policy version
POLICY_VERSION=$(aws opensearchserverless get-access-policy \
  --region us-east-2 \
  --name vector-search-access \
  --type data \
  --query 'accessPolicyDetail.policyVersion' \
  --output text)

aws opensearchserverless update-access-policy \
  --region us-east-2 \
  --name vector-search-access \
  --type data \
  --policy-version "$POLICY_VERSION" \
  --policy '[{
    "Rules": [
      {
        "ResourceType": "collection",
        "Resource": ["collection/my-target-collection"],
        "Permission": [
          "aoss:CreateCollectionItems",
          "aoss:DeleteCollectionItems",
          "aoss:UpdateCollectionItems",
          "aoss:DescribeCollectionItems"
        ]
      },
      {
        "ResourceType": "index",
        "Resource": ["index/my-target-collection/*"],
        "Permission": [
          "aoss:CreateIndex",
          "aoss:DeleteIndex",
          "aoss:UpdateIndex",
          "aoss:DescribeIndex",
          "aoss:ReadDocument",
          "aoss:WriteDocument"
        ]
      }
    ],
    "Principal": [
      "arn:aws:iam::111122223333:role/Admin",
      "arn:aws:iam::111122223333:root",
      "arn:aws:iam::111122223333:role/migration-eks-cluster-dev-us-east-2-migrations-role",
      "arn:aws:iam::111122223333:role/migration-eks-cluster-dev-us-east-2-snapshot-role"
    ]
  }]'

{% include copy.html %}

2단계: 소스 도메인에서 Migration Assistant 역할 매핑

소스 도메인에 세분화된 액세스 제어(FGAC)가 활성화된 경우 Migration Assistant 역할을 MasterUserARN으로 구성해야 해요.

aws opensearch update-domain-config \
  --region us-east-2 \
  --domain-name my-source-domain \
  --advanced-security-options '{
    "Enabled": true,
    "MasterUserOptions": {
      "MasterUserARN": "arn:aws:iam::111122223333:role/migration-eks-cluster-dev-us-east-2-migrations-role"
    }
  }'

{% include copy.html %}

도메인 업데이트가 완료될 때까지 기다려요.

watch -n 10 "aws opensearch describe-domain \
  --region us-east-2 \
  --domain-name my-source-domain \
  --query 'DomainStatus.Processing'"

{% include copy.html %}

Processing이 False를 반환하면 도메인이 준비된 거예요.

이 작업은 기존 MasterUserARN을 대체해요. 기존 구성을 유지해야 하는 경우 OpenSearch Security API를 통해 Migration Assistant 역할을 all_access 백엔드 역할에 매핑해요. {: .warning }

6단계: 보안 그룹 액세스 구성

Migration Assistant EKS 클러스터 보안 그룹을 찾아요.

MA_SG=$(aws eks describe-cluster \
  --region us-east-2 \
  --name migration-eks-cluster-dev-us-east-2 \
  --query "cluster.resourcesVpcConfig.clusterSecurityGroupId" \
  --output text)
echo "MA EKS Security Group: $MA_SG"

{% include copy.html %}

Migration Assistant가 포트 443에서 소스 도메인에 접근할 수 있도록 인바운드 규칙을 추가해요.

aws ec2 authorize-security-group-ingress \
  --region us-east-2 \
  --group-id sg-07dcc2b6423c745a0 \
  --protocol tcp \
  --port 443 \
  --source-group "$MA_SG"

{% include copy.html %}

대상은 퍼블릭 네트워크 액세스가 있는 Amazon OpenSearch Serverless NextGen 컬렉션이므로 대상에 대한 보안 그룹 규칙이 필요하지 않아요. 컬렉션에 VPC 액세스를 구성한 경우 컬렉션의 VPC 엔드포인트 보안 그룹에도 인바운드 규칙을 추가해요. {: .note }

Step 7: Migration Console에 연결해요

Migration Console에 연결해요:

kubectl exec -it migration-console-0 -n ma -- /bin/bash

{% include copy.html %}

설치된 버전을 확인해요:

console --version

{% include copy.html %}

예상 출력: Migration Assistant 3.1.1 (또는 이후 버전).

소스 도메인에 Amazon S3 스냅샷 저장소를 등록해요

Amazon OpenSearch Service는 Amazon S3에 쓰기 위해 snapshot-role이 필요해요. CloudFormation 출력에서 snapshot-role을 사용하여 저장소를 등록해요:

console clusters curl source /_snapshot/migration-repo \
  -XPUT -H "Content-Type: application/json" \
  -d '{
    "type": "s3",
    "settings": {
      "bucket": "migrations-default-111122223333-dev-us-east-2",
      "region": "us-east-2",
      "role_arn": "arn:aws:iam::111122223333:role/migration-eks-cluster-dev-us-east-2-snapshot-role",
      "base_path": "aos-to-aoss-snapshots"
    }
  }'

{% include copy.html %}

저장소를 확인해요:

console clusters curl source /_snapshot/migration-repo/_verify?pretty

{% include copy.html %}

모든 노드가 출력에 나타나야 해요.

자체 관리 Elasticsearch와 달리 Amazon OpenSearch Service는 키스토어 자격 증명 대신 IAM role_arn을 사용하여 Amazon S3에 접근해요. snapshot-role에는 OpenSearch Service Principal(es.amazonaws.com)이 이를 수임할 수 있도록 하는 신뢰 정책이 있어야 해요. {: .note }

Step 8: 워크플로 구성을 만들어요

버전에 맞는 샘플을 로드하고 편집기를 열려면 다음 명령을 실행해요:

workflow configure sample --load
workflow configure edit

{% include copy.html %}

사용 가능한 모든 필드, 해당 유형, 기본값 및 설명에 대한 대화형 참조는 Migration Assistant Schema Viewer를 확인해요.

워크플로 구성 파일 내용을 다음 구성으로 바꿔요. <PILOT_INDEX_NAME>을 작고 중요하지 않은 인덱스 이름(예: test-index)으로 바꿔요:

{
  "sourceClusters": {
    "source": {
      "endpoint": "https://vpc-my-source-domain-abc123example.us-east-2.es.amazonaws.com",
      "allowInsecure": false,
      "version": "ES 7.10",
      "authConfig": {
        "sigv4": {
          "region": "us-east-2",
          "service": "es"
        }
      },
      "snapshotInfo": {
        "repos": {
          "migration-repo": {
            "awsRegion": "us-east-2",
            "s3RepoPathUri": "s3://migrations-default-111122223333-dev-us-east-2/aos-to-aoss-snapshots",
            "s3RoleArn": "arn:aws:iam::111122223333:role/migration-eks-cluster-dev-us-east-2-snapshot-role"
          }
        },
        "snapshots": {
          "migration-snapshot": {
            "repoName": "migration-repo",
            "config": {
              "createSnapshotConfig": {
                "indexAllowlist": ["<PILOT_INDEX_NAME>"],
                "includeGlobalState": true
              }
            }
          }
        }
      }
    }
  },
  "targetClusters": {
    "target": {
      "endpoint": "https://3nbrhts7rv9jxatilz9e.aoss.us-east-2.on.aws",
      "allowInsecure": false,
      "authConfig": {
        "sigv4": {
          "region": "us-east-2",
          "service": "aoss"
        }
      }
    }
  },
  "snapshotMigrationConfigs": [
    {
      "fromSource": "source",
      "toTarget": "target",
      "perSnapshotConfig": {
        "migration-snapshot": [
          {
            "metadataMigrationConfig": {
              "indexAllowlist": ["<PILOT_INDEX_NAME>"]
            },
            "documentBackfillConfig": {
              "podReplicas": 4
            }
          }
        ]
      }
    }
  ]
}

{% include copy.html %}

다음은 도메인 간 마이그레이션과의 주요 차이점이에요:

• Source는 service: "es"와 함께 sigv4를 사용해요: Amazon OpenSearch Service는 기본 인증 대신 IAM 인증을 사용해요.
• Target은 service: "aoss"와 함께 sigv4를 사용해요: Amazon OpenSearch Serverless NextGen은 AWS Signature Version 4 서명에 aoss 서비스 이름이 필요해요.
• **s3RoleArn**이 필요해요: Amazon OpenSearch Service는 Amazon S3에 스냅샷을 쓰기 위해 IAM 역할이 필요해요(키스토어 자격 증명을 사용하는 자체 관리 Elasticsearch와 다름).
• multiTypeBehavior 없음: Elasticsearch 7.10은 이미 단일 타입 인덱스를 사용하므로 타입 매핑 변환이 필요하지 않아요.

구성을 확인해요:

workflow configure view

{% include copy.html %}

Step 9: 연결을 테스트해요

Migration Console이 소스와 대상 모두에 연결될 수 있는지 확인하려면 다음 명령을 실행해요:

console clusters connection-check

{% include copy.html %}

소스와 대상 모두 Successfully connected!를 표시해야 해요.

소스에서 연결 시간 초과가 반환되면 다음을 확인해요:

1. Migration Assistant가 소스 도메인과 동일한 VPC에 배포되어 있는지(또는 VPC 피어링이 구성되어 있는지) 확인해요.
2. 소스 도메인의 보안 그룹이 Migration Assistant EKS 클러스터 보안 그룹의 인바운드 TCP 443을 허용하는지 확인해요.

대상에서 403이 반환되면 다음을 확인해요:

1. Amazon OpenSearch Serverless NextGen 데이터 접근 정책에 Migration Assistant 마이그레이션 역할이 포함되어 있는지 확인해요.
2. 네트워크 정책이 Migration Assistant 파드의 접근을 허용하는지 확인해요.

연결을 수동으로 테스트하려면 다음 명령을 실행해요:

console clusters curl source /
console clusters curl target /

{% include copy.html %}

Step 10: 파일럿 마이그레이션을 실행해요

모든 인덱스를 마이그레이션하기 전에 하나의 작은 인덱스에서 파일럿 마이그레이션을 실행해요.

워크플로를 제출해요:

workflow submit
workflow manage

{% include copy.html %}

workflow manage 명령은 대화형 텍스트 기반 사용자 인터페이스(TUI)를 열어요. 이를 사용하여 진행 상황을 모니터링하고, 로그를 확인하고, 게이트를 승인해요.

워크플로가 승인 게이트(⟳로 표시됨)에서 일시 중지되면 출력을 검토하고 승인해요:

# Approve metadata evaluation
workflow approve step "*.evaluatemetadata"

# Approve metadata migration
workflow approve step "*.migratemetadata"

{% include copy.html %}

게이트 이름은 소문자예요. 또는 workflow manage TUI에서 직접 게이트를 승인해요. {: .note }

워크플로가 완료된 후 메타데이터와 문서를 확인해요:

console clusters curl target /_cat/indices?v
console clusters curl target /<PILOT_INDEX_NAME>/_mapping
console clusters curl target /<PILOT_INDEX_NAME>/_count
console clusters curl target /<PILOT_INDEX_NAME>/_search?size=5&pretty

{% include copy.html %}

소스와 대상의 문서 수가 일치하는지 확인해요.

파일럿 마이그레이션이 실패하면 구성을 편집하고 다시 제출해요:

workflow configure edit
workflow submit
workflow manage

{% include copy.html %}

파일럿 마이그레이션이 성공적으로 완료될 때까지 전체 마이그레이션을 시작하지 마요. {: .note }

Step 11: 전체 마이그레이션을 실행해요

허용 목록을 확장하도록 구성을 편집해요:

workflow configure edit

{% include copy.html %}

모든 인덱스를 마이그레이션하려면 indexAllowlist를 빈 배열로 설정해요:

"metadataMigrationConfig": {
  "indexAllowlist": []
}

{% include copy.html %}

createSnapshotConfig를 업데이트해요:

"createSnapshotConfig": {
  "indexAllowlist": [],
  "includeGlobalState": true
}

{% include copy.html %}

다음 섹션에서는 각 마이그레이션 접근 방식의 단계를 설명해요. 1단계에서 선택한 접근 방식에 해당하는 섹션을 따라요.

계획된 다운타임 방식

계획된 다운타임 마이그레이션의 경우 다음 단계를 따라요:

1. 소스 도메인에 쓰기를 중지해요.

2. 워크플로를 제출해요:

   workflow submit
   workflow manage
   

   {% include copy.html %}

3. 각 단계를 확인한 후 게이트를 승인해요.

4. 백필이 완료된 후 대상을 확인해요:

   console clusters curl target /_cat/indices?v
   console clusters curl target /_cat/aliases?v
   

   {% include copy.html %}

5. Migration Assistant가 마이그레이션하지 않는 구성 요소(ISM 또는 ILM 정책, 수집 파이프라인, 대시보드, 클러스터 설정)를 검토해요. Amazon OpenSearch Serverless NextGen은 이러한 기능을 지원하지 않아요. 진행하기 전에 워크로드에 대안이 필요한지 결정해요.

6. 클라이언트를 Serverless NextGen 컬렉션 엔드포인트로 지정해요: https://3nbrhts7rv9jxatilz9e.aoss.us-east-2.on.aws.

7. 클라이언트 인증을 기본 인증 또는 service: es를 사용하는 IAM AWS Signature Version 4에서 service: aoss를 사용하는 IAM AWS Signature Version 4로 업데이트해요.

제로 다운타임 방식

제로 다운타임 마이그레이션의 경우 다음 섹션을 순서대로 완료해요.

Step 1: 트래픽 섹션을 구성해요

워크플로 구성에 traffic 섹션을 추가하려면 편집기를 열어요:

workflow configure edit

{% include copy.html %}

sourceClusters, targetClusters, snapshotMigrationConfigs와 같은 수준에 다음 traffic 블록을 추가해요:

"traffic": {
  "proxies": {
    "capture": {
      "source": "source",
      "proxyConfig": {
        "listenPort": 443,
        "podReplicas": 2
      }
    }
  },
  "replayers": {
    "replay": {
      "fromProxy": "capture",
      "toTarget": "target",
      "dependsOnSnapshotMigrations": [
        {
          "source": "source",
          "snapshot": "migration-snapshot"
        }
      ],
      "replayerConfig": {
        "podReplicas": 2,
        "speedupFactor": 2.0
      }
    }
  }
}

{% include copy.html %}

모든 인덱스를 마이그레이션하려면 indexAllowlist를 빈 배열로 설정해요:

"metadataMigrationConfig": {
  "indexAllowlist": []
}

{% include copy.html %}

Step 2: 워크플로를 제출해요

워크플로를 제출하고 모니터링 인터페이스를 열려면 다음 명령을 실행해요:

workflow submit
workflow manage

{% include copy.html %}

워크플로는 Apache Kafka 클러스터, 캡처 프록시, 스냅샷, 스냅샷 마이그레이션, Traffic Replayer의 다섯 가지 병렬 트랙을 생성해요. 스냅샷은 캡처 프록시가 준비될 때까지 기다렸다가 진행해요.

Step 3: 캡처 프록시 엔드포인트를 찾아요

캡처 프록시는 소스 도메인의 포트(Amazon OpenSearch Service의 경우 443)를 사용해요. 엔드포인트를 찾으려면 다음 명령을 실행해요:

kubectl get svc capture -n ma

{% include copy.html %}

EXTERNAL-IP 열은 Network Load Balancer 엔드포인트를 보여줘요. 애플리케이션 클라이언트를 이 엔드포인트로 리디렉션해요.

캡처 프록시는 모든 요청을 소스 도메인으로 전달하고 동시에 Kafka에 기록하여 재생해요. 프록시는 AWS Signature Version 4를 사용하여 소스에 인증하므로 클라이언트는 기존 인증 방법을 계속 사용할 수 있어요. {: .note }

Step 4: 워크플로 단계를 승인해요

승인 작업을 수행하려면 다음 명령을 실행해요:

workflow approve step "*.evaluatemetadata"
workflow approve step "*.migratemetadata"

{% include copy.html %}

Step 5: 재생 진행 상황을 모니터링해요

백필이 완료된 후 Replayer가 캡처된 트래픽 처리를 시작해요:

kubectl logs deployment/capture-target-replay -n ma --tail=5

{% include copy.html %}

ReplayHeartbeat 줄을 찾아요:

ReplayHeartbeat - tasksOutstanding=437 schedulingLag=1s lastCompletedSourceTime=2026-05-03T16:01:16.565Z targetResponses={}

다음 표는 하트비트 출력의 필드를 설명해요.

Step 6: 문서 수가 일치하는지 확인해요

소스와 대상 간의 문서 수를 비교하려면 다음 명령을 실행해요:

console clusters curl source /_cat/indices?v
console clusters curl target /_cat/indices?v

{% include copy.html %}

재생이 완료되면 대상의 문서 수가 소스와 일치해야 해요.

Step 7: 트래픽을 대상으로 전환해요

재생이 완료되고 검증을 통해 대상이 올바른 것으로 확인되면 애플리케이션 클라이언트를 캡처 프록시에서 Serverless NextGen 컬렉션 엔드포인트로 직접 전환해요:

https://3nbrhts7rv9jxatilz9e.aoss.us-east-2.on.aws

클라이언트의 AWS Signature Version 4 서명을 service: es에서 service: aoss로 업데이트해요.

Step 12: 소스를 대체 수단으로 사용할 수 있게 유지해요

전환 직후 소스 도메인을 삭제하지 마요. 대상 컬렉션 상태, 애플리케이션 오류율, 운영 도구를 모니터링하는 동안 최소 24~72시간 동안 사용 가능하게 유지해요.

Step 13: 마이그레이션 인프라를 제거해요

Migration Assistant를 제거하기 전에 다음 사항을 모두 확인해요:

1. 모든 클라이언트 트래픽이 Serverless NextGen 컬렉션을 직접 가리키고 더 이상 캡처 프록시를 가리키지 않아요.
2. 캡처 프록시와 Replayer가 더 이상 필요하지 않아요.
3. 소스 도메인을 최소 24~72시간 동안 대체 수단으로 사용 가능하게 유지했어요.
4. 대상 컬렉션이 정상이고 애플리케이션 오류율이 정상이에요.

어떤 클라이언트가 여전히 캡처 프록시 엔드포인트로 트래픽을 보내고 있다면 Migration Assistant를 제거할 때 해당 트래픽이 손실돼요. 진행하기 전에 모든 클라이언트가 대상으로 리디렉션되었는지 확인해요. {: .warning }

Step 1: Helm 릴리스와 네임스페이스를 제거해요

Migration Assistant Helm 릴리스를 제거하고 네임스페이스를 삭제하려면 다음 명령을 실행해요:

helm uninstall -n ma ma
kubectl -n ma delete pvc --all
kubectl delete namespace ma --timeout=120s

{% include copy.html %}

Step 2: CloudFormation 스택을 삭제해요

CloudFormation 스택과 관련된 모든 리소스를 삭제하려면 다음 명령을 실행해요:

aws cloudformation delete-stack --region us-east-2 --stack-name MA
aws cloudformation wait stack-delete-complete --region us-east-2 --stack-name MA

{% include copy.html %}

이 명령은 Migration Assistant가 생성한 Amazon EKS 클러스터, Amazon ECR 리포지토리, IAM 역할, VPC 엔드포인트를 삭제해요. 소스 도메인, Serverless NextGen 컬렉션, Amazon S3 스냅샷 버킷은 삭제하지 않아요.

Step 3 (선택 사항): 스냅샷 버킷을 삭제해요

스냅샷 버킷을 삭제하려면 다음 명령을 실행해요:

aws s3 rb s3://migrations-default-111122223333-dev-us-east-2 --force

{% include copy.html %}

Step 4 (선택 사항): Amazon OpenSearch Serverless NextGen 컬렉션을 삭제해요

테스트를 위해 컬렉션을 생성했고 더 이상 필요하지 않으면 다음 명령을 실행해요:

aws opensearchserverless delete-collection \
  --region us-east-2 \
  --id 3nbrhts7rv9jxatilz9e

{% include copy.html %}

그런 다음 정책을 제거해요:

aws opensearchserverless delete-access-policy \
  --region us-east-2 --name vector-search-access --type data

aws opensearchserverless delete-security-policy \
  --region us-east-2 --name vector-search-net --type network

aws opensearchserverless delete-security-policy \
  --region us-east-2 --name vector-search-enc --type encryption

{% include copy.html %}

검증

워크플로가 완료된 후 세 가지 수준에서 마이그레이션을 검증해요.

Level 1: 문서 수 비교

모든 사용자 인덱스에 대해 소스와 대상 간의 문서 수를 비교해요:

console clusters curl source /_cat/indices?v
console clusters curl target /_cat/indices?v

{% include copy.html %}

각 사용자 인덱스에 대해 수가 일치하는지 확인해요:

console clusters curl source /<INDEX_NAME>/_count
console clusters curl target /<INDEX_NAME>/_count

{% include copy.html %}

Level 2: 상태 코드 비교(튜플 메트릭)

제로 다운타임 방식을 사용한 경우 Replayer가 tupleComparison 메트릭을 CloudWatch에 기록해요:

aws logs start-query \
  --region us-east-2 \
  --log-group-name "/metrics/OpenSearchMigrations" \
  --start-time $(date -u -v-3H +%s) \
  --end-time $(date -u +%s) \
  --query-string 'fields @message
    | filter @message like /tupleComparison/
    | parse @message /\"method\":\"(?<method>[^\"]+)\".*\"sourceStatusCode\":\"(?<srcCode>[^\"]+)\".*\"statusCodesMatch\":\"(?<match>[^\"]+)\".*\"targetStatusCode\":\"(?<tgtCode>[^\"]+)\"/
    | stats count() as requests by method, srcCode, tgtCode, match
    | sort requests desc'

{% include copy.html %}

몇 초 기다린 후 결과를 검색해요:

aws logs get-query-results --region us-east-2 --query-id <QUERY_ID>

{% include copy.html %}

POST 또는 PUT 메서드와 관련된 불일치를 조사해요. 이러한 메서드는 쓰기 작업으로, 불일치는 데이터 손실을 나타낼 수 있어요.

Level 3: 샘플 쿼리 비교

두 클러스터에서 대표 쿼리를 실행하고 결과를 비교해요:

console clusters curl source /<INDEX_NAME>/_search?size=5&pretty
console clusters curl target /<INDEX_NAME>/_search?size=5&pretty

{% include copy.html %}

매핑 검증

인덱스 매핑이 올바르게 마이그레이션되었는지 확인해요:

console clusters curl target /<INDEX_NAME>/_mapping

{% include copy.html %}

Migration Console에 다시 연결해요

새 셸 세션에서 Migration Console에 다시 연결해야 하는 경우 다음 명령을 실행해요:

aws eks update-kubeconfig --region us-east-2 --name migration-eks-cluster-dev-us-east-2
kubectl exec -it migration-console-0 -n ma -- /bin/bash

{% include copy.html %}

문제 해결

다음은 일반적인 문제와 해결 방법이에요.

대상이 403 forbidden을 반환해요

Migration Assistant IAM 역할이 Amazon OpenSearch Serverless NextGen 데이터 액세스 정책에 포함되어 있지 않아요. 정책을 업데이트하세요:

POLICY_VERSION=$(aws opensearchserverless get-access-policy \
  --region us-east-2 --name vector-search-access --type data \
  --query 'accessPolicyDetail.policyVersion' --output text)

echo "Current policy version: $POLICY_VERSION"

{% include copy.html %}

그런 다음 올바른 정책 버전으로 Step 5: Map the Migration Assistant IAM role의 update-access-policy 명령을 다시 실행하세요.

소스가 connection timeout을 반환해요

1. Migration Assistant가 소스 도메인과 동일한 VPC에 있는지 확인하세요:

   aws eks describe-cluster \
     --region us-east-2 \
     --name migration-eks-cluster-dev-us-east-2 \
     --query 'cluster.resourcesVpcConfig.vpcId' \
     --output text
   

   {% include copy.html %}

2. 소스 도메인의 보안 그룹이 Migration Assistant EKS 클러스터 보안 그룹의 443 포트를 허용하는지 확인하세요.

소스와 대상이 다른 VPC에 있어요

Migration Assistant가 소스 도메인과 다른 VPC에 있다면 VPC 피어링 연결을 생성하세요:

PEERING_ID=$(aws ec2 create-vpc-peering-connection \
  --region us-east-2 \
  --vpc-id <MA_VPC_ID> \
  --peer-vpc-id <SOURCE_VPC_ID> \
  --query "VpcPeeringConnection.VpcPeeringConnectionId" \
  --output text)

aws ec2 accept-vpc-peering-connection \
  --region us-east-2 \
  --vpc-peering-connection-id "$PEERING_ID"

# Add routes in both directions
aws ec2 create-route \
  --region us-east-2 \
  --route-table-id <MA_PRIVATE_ROUTE_TABLE> \
  --destination-cidr-block <SOURCE_VPC_CIDR> \
  --vpc-peering-connection-id "$PEERING_ID"

aws ec2 create-route \
  --region us-east-2 \
  --route-table-id <SOURCE_ROUTE_TABLE> \
  --destination-cidr-block <MA_VPC_CIDR> \
  --vpc-peering-connection-id "$PEERING_ID"

{% include copy.html %}

그런 다음 Migration Assistant EKS 클러스터 보안 그룹을 소스 도메인의 보안 그룹 인바운드 규칙에 추가하세요(Step 6: Configure security group access). 보안 그룹 참조 대신 Migration Assistant VPC CIDR을 사용하세요. VPC 간 보안 그룹 참조는 피어링 연결이 필요하기 때문이에요.

스냅샷 리포지토리 등록이 실패해요

Amazon OpenSearch Service의 경우 스냅샷 역할은 다음을 충족해야 해요:

1. 스냅샷 버킷에 대해 s3:ListBucket, s3:GetObject, s3:PutObject, s3:DeleteObject를 허용하는 IAM 정책을 포함해야 해요.
2. es.amazonaws.com이 역할을 수임할 수 있도록 신뢰 정책을 포함해야 해요.
3. role_arn 설정을 통해 _snapshot API에 전달되어야 해요.

스냅샷 역할 신뢰 정책을 확인하세요:

aws iam get-role \
  --role-name migration-eks-cluster-dev-us-east-2-snapshot-role \
  --query 'Role.AssumeRolePolicyDocument' \
  --output json

{% include copy.html %}

재제출 시 Consistency guard 오류

먼저 오래된 사용자 정의 리소스를 삭제하세요:

kubectl delete snapshotmigration --all -n ma
kubectl delete datasnapshot --all -n ma
kubectl delete capturedtraffic --all -n ma
kubectl delete captureproxy --all -n ma
kubectl delete trafficreplay --all -n ma
kubectl delete kafkacluster --all -n ma

{% include copy.html %}

그런 다음 워크플로를 다시 제출하세요:

workflow submit

{% include copy.html %}

Amazon OpenSearch Serverless NextGen 오류

다음 오류는 Amazon OpenSearch Serverless NextGen 대상에 특화된 오류예요.

대상에서 Index not found exception

Amazon OpenSearch Serverless NextGen은 Amazon OpenSearch Service와 같은 방식으로 _cluster/settings API나 템플릿을 통한 자동 인덱스 생성을 지원하지 않아요. 백필 전에 메타데이터 마이그레이션이 성공적으로 완료되었는지 확인하세요:

console clusters curl target /_cat/indices?v

{% include copy.html %}

Security exception (권한 오류)

Amazon OpenSearch Serverless NextGen 데이터 액세스 정책에 권한이 누락되었어요. 정책에 Migration Assistant 역할에 대한 컬렉션 수준 및 인덱스 수준 권한이 모두 포함되어 있는지 확인하세요.

Bulk indexing이 413: Request too large를 반환해요

Amazon OpenSearch Serverless NextGen에는 10MB 요청 페이로드 제한이 있어요. 문서가 큰 경우 워크플로 구성에서 벌크 배치 크기를 줄이세요:

"documentBackfillConfig": {
  "podReplicas": 4,
  "maxBulkSizeBytes": 5242880
}

{% include copy.html %}

관련 문서

자세한 내용은 다음 리소스를 참조하세요:

• Is Migration Assistant right for you?
• Migrate to OpenSearch Serverless NextGen
• Deploying to EKS
• Using the Workflow CLI
• Backfill
• Removing Migration Assistant
• Elasticsearch 6.8 → OpenSearch 3.5 playbook
• Migration Assistant Schema Viewer

더 알아보기 (Learn more)

• 원문 전체: https://docs.opensearch.org/latest/migration-assistant/playbook-amazon-opensearch-service-to-serverless/