Playbook: Elasticsearch 6.8 to OpenSearch 3.5 on EKS

원문 보기 위키 갱신 2026.10.14

Playbook: Elasticsearch 6.8 to OpenSearch 3.5 on EKS (existing VPC)

출처: 문서

본문

플레이북: EKS에서 Elasticsearch 6.8에서 OpenSearch 3.5로 마이그레이션 (기존 VPC)

이 플레이북은 일반적인 AWS 마이그레이션 패턴을 하나의 구체적인 런북으로 변환합니다: Amazon Elastic Kubernetes Service (EKS)에서 실행되는 자체 관리 Elasticsearch 6.8 클러스터에서 Amazon OpenSearch Service 3.5로 이동하며, Migration Assistant를 기존 가상 프라이빗 클라우드 (VPC)에 배포합니다.

이 패턴은 자체 관리 플러그인, 자체 서명 인증서, 애플리케이션 소유 자격 증명을 사용하는 자체 관리 검색 클러스터에서 VPC 격리, AWS Identity and Access Management (IAM) 기반 액세스, 유지 관리 부담이 줄어든 관리형 대상으로 마이그레이션할 때 적용됩니다.

이 플레이북은 의도적으로 종단 간(end-to-end)으로 구성되어 있습니다. 소스 준비, EKS 배포, 워크플로 구성, 파일럿 마이그레이션, 전체 마이그레이션, 검증, 전환, 제거가 포함됩니다.

예제 플레이스홀더

다음 플레이스홀더를 사용자 환경의 값으로 바꾸세요.

플레이스홀더	의미
`<ACCOUNT_ID>`	마이그레이션 환경을 호스팅하는 AWS 계정 ID
`<REGION>`	`us-east-2`와 같은 AWS 리전
`<STAGE>`	`dev` 또는 `prod`와 같은 배포 레이블
`<YOUR_VPC_ID>`	Migration Assistant가 배포되는 기존 VPC
`<SUBNET_1>,<SUBNET_2>`	서로 다른 가용 영역에 있는 최소 두 개의 서브넷
`<SOURCE_ENDPOINT>`	Elasticsearch 엔드포인트 또는 Network Load Balancer DNS 이름
`<TARGET_DOMAIN_NAME>`	OpenSearch Service 도메인 이름
`<TARGET_DOMAIN_ENDPOINT>`	OpenSearch Service 도메인 엔드포인트
`<PILOT_INDEX_NAME>`	파일럿 실행을 위한 작고 중요하지 않은 인덱스

예상 시간

다음 표는 마이그레이션의 각 단계별 예상 소요 시간을 제공합니다.

단계	일반적인 소요 시간
소스 준비 (플러그인, S3 액세스, 스냅샷 리포지토리)	15~25분
EKS에 Migration Assistant 배포	15~25분
구성 빌드 및 연결 테스트	5~10분
파일럿 마이그레이션	15~20분
전체 백필 전용 마이그레이션	데이터 크기와 대상 수집 용량에 따라 다름
전체 무중단 마이그레이션	백필 기간에 재생 따라잡기 시간 추가

무중단 마이그레이션의 경우 재생 시간은 백필 중에 축적된 트래픽 양과 Replayer에 구성된 speedupFactor에 따라 달라집니다. 일반적인 시작 값은 1.5에서 2.0입니다. 대상 클러스터를 모니터링하여 재생 속도를 유지할 수 있는지 확인하세요.

시작하기 전에

일반 플레이북 사전 요구 사항 외에도 마이그레이션을 시작하기 전에 다음을 확인하세요. 환경이 다른 경우 그에 따라 네트워크 및 아이덴티티 구성을 조정하세요.

소스 클러스터 요구 사항

소스 클러스터는 다음 요구 사항을 모두 충족해야 합니다.

Migration Assistant가 실행되는 VPC에서 연결 가능해야 합니다.
소스 엔드포인트를 알고 있어야 합니다.
소스 인증 방법을 알고 있어야 합니다.
Amazon S3에 스냅샷을 쓸 수 있어야 합니다.
repository-s3 플러그인이 포함되어 있어야 합니다.

소스가 자체 서명 인증서를 사용하는 경우 워크플로 구성에서 allowInsecure: true를 설정할 계획을 세우세요.

대상 클러스터 요구 사항

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

이미 존재해야 합니다.
동일한 VPC에서 연결 가능하거나 해당 VPC에서 라우팅 가능해야 합니다.
도메인 엔드포인트를 알고 있어야 합니다.
세분화된 액세스 제어가 활성화된 경우 Migration Assistant IAM 역할에 충분한 권한이 매핑되어 있어야 합니다.

인프라 요구 사항

다음 인프라가 필요합니다.

기존 VPC ID.
서로 다른 가용 영역에 있는 최소 두 개의 서브넷.
AWS CLI v2 및 kubectl 또는 AWS CloudShell.
EKS, AWS CloudFormation, IAM, S3, OpenSearch 리소스를 배포할 수 있는 권한.

1단계: 마이그레이션 스타일 선택

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

옵션 A: 계획된 다운타임

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

Elasticsearch에 대한 쓰기를 일시 중지합니다.
스냅샷을 생성합니다.
메타데이터를 마이그레이션합니다.
문서를 백필합니다.
대상을 검증합니다.
클라이언트를 OpenSearch로 지정합니다.

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

옵션 B: 무중단

무중단 마이그레이션의 경우 다음 단계를 따르세요.

캡처를 시작합니다.
클라이언트를 캡처 프록시로 라우팅합니다.
스냅샷을 생성합니다.
메타데이터를 마이그레이션합니다.
문서를 백필합니다.
대상이 따라잡을 때까지 캡처된 트래픽을 재생합니다.
대상을 검증합니다.
클라이언트를 OpenSearch로 전환합니다.

애플리케이션이 자동 생성된 문서 ID에 의존하는 경우 무중단 접근 방식을 선택하기 전에 캡처 및 재생을 철저히 테스트하세요. 자동 생성된 ID는 재생 중에 보존되지 않습니다.

2단계: 소스 클러스터 준비

repository-s3 플러그인 설치 및 스냅샷 리포지토리 등록을 포함하여 소스 클러스터를 준비합니다.

repository-s3 플러그인 설치

Migration Assistant는 백필에 스냅샷을 사용하므로 소스가 S3 스냅샷을 지원해야 합니다. repository-s3 플러그인에 대한 일반적인 정보는 Snapshot and restore를 참조하세요.

현재 플러그인 상태를 확인합니다.

curl -sk -u <SOURCE_USERNAME>:<SOURCE_PASSWORD> https://<SOURCE_ENDPOINT>:9200/_cat/plugins?v

{% include copy.html %}

repository-s3가 없고 소스가 Kubernetes에서 실행 중인 경우 일반적인 패턴은 init 컨테이너를 사용하여 설치하여 포드 재시작 후에도 유지되도록 하는 것입니다.

kubectl patch statefulset elasticsearch-master -n elasticsearch --type=strategic -p '{
  "spec": {
    "template": {
      "spec": {
        "initContainers": [
          {
            "name": "install-plugins",
            "image": "docker.elastic.co/elasticsearch/elasticsearch:6.8.22",
            "command": ["sh", "-c", "bin/elasticsearch-plugin install --batch repository-s3 && cp -r /usr/share/elasticsearch/plugins/* /plugins/"],
            "volumeMounts": [{"name": "plugins", "mountPath": "/plugins"}]
          }
        ],
        "containers": [
          {
            "name": "elasticsearch",
            "volumeMounts": [
              {"name": "plugins", "mountPath": "/usr/share/elasticsearch/plugins"}
            ]
          }
        ],
        "volumes": [
          {"name": "plugins", "emptyDir": {}}
        ]
      }
    }
  }
}'

{% include copy.html %}

그런 다음 롤아웃을 기다립니다.

kubectl rollout status statefulset/elasticsearch-master -n elasticsearch --timeout=300s

{% include copy.html %}

플러그인이 로드되었는지 확인합니다.

curl -sk -u <SOURCE_USERNAME>:<SOURCE_PASSWORD> https://<SOURCE_ENDPOINT>:9200/_cat/plugins?v

{% include copy.html %}

소스 클러스터에 S3 액세스 권한 부여

소스 클러스터는 스냅샷을 쓰기 위해 AWS 자격 증명이 필요합니다.

EKS의 자체 관리 Elasticsearch 클러스터의 경우 다음 단계를 수행하여 S3 액세스를 구성합니다.

IAM 역할에 인라인 S3 정책을 추가합니다.

aws iam put-role-policy \
  --role-name <ES_EKS_NODE_ROLE_NAME> \
  --policy-name es-snapshot-s3-access \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": ["s3:ListBucket", "s3:GetBucketLocation"],
        "Resource": "arn:aws:s3:::migrations-default-<ACCOUNT_ID>-<STAGE>-<REGION>"
      },
      {
        "Effect": "Allow",
        "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
        "Resource": "arn:aws:s3:::migrations-default-<ACCOUNT_ID>-<STAGE>-<REGION>/*"
      }
    ]
  }'

{% include copy.html %}

임시 헬퍼 포드를 생성합니다.

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: creds-helper
  namespace: elasticsearch
spec:
  hostNetwork: true
  containers:
  - name: helper
    image: amazon/aws-cli:latest
    command: ["sh", "-c", "sleep 300"]
  restartPolicy: Never
EOF

kubectl wait --for=condition=ready pod/creds-helper -n elasticsearch --timeout=60s

{% include copy.html %}

임시 자격 증명을 추출합니다.

ACCESS_KEY=$(kubectl exec creds-helper -n elasticsearch -- \
  sh -c 'TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"); ROLE=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/iam/security-credentials/); curl -s -H "X-aws-ec2-metadata-token: $TOKEN" "http://169.254.169.254/latest/meta-data/iam/security-credentials/$ROLE" | python3 -c "import json,sys; print(json.load(sys.stdin)[\"AccessKeyId\"])"')

SECRET_KEY=$(kubectl exec creds-helper -n elasticsearch -- \
  sh -c 'TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"); ROLE=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/iam/security-credentials/); curl -s -H "X-aws-ec2-metadata-token: $TOKEN" "http://169.254.169.254/latest/meta-data/iam/security-credentials/$ROLE" | python3 -c "import json,sys; print(json.load(sys.stdin)[\"SecretAccessKey\"])"')

SESSION_TOKEN=$(kubectl exec creds-helper -n elasticsearch -- \
  sh -c 'TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"); ROLE=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/iam/security-credentials/); curl -s -H "X-aws-ec2-metadata-token: $TOKEN" "http://169.254.169.254/latest/meta-data/iam/security-credentials/$ROLE" | python3 -c "import json,sys; print(json.load(sys.stdin)[\"Token\"])"')

{% include copy.html %}

각 포드의 Elasticsearch 키스토어에 자격 증명을 로드합니다.

for pod in elasticsearch-master-0 elasticsearch-master-1 elasticsearch-master-2; do
  kubectl exec $pod -n elasticsearch -c elasticsearch -- \
    sh -c "echo '${ACCESS_KEY}' | bin/elasticsearch-keystore add -f s3.client.default.access_key"
  kubectl exec $pod -n elasticsearch -c elasticsearch -- \
    sh -c "echo '${SECRET_KEY}' | bin/elasticsearch-keystore add -f s3.client.default.secret_key"
  kubectl exec $pod -n elasticsearch -c elasticsearch -- \
    sh -c "echo '${SESSION_TOKEN}' | bin/elasticsearch-keystore add -f s3.client.default.session_token"
done

{% include copy.html %}

보안 설정을 다시 로드합니다.

curl -sk -X POST -u <SOURCE_USERNAME>:<SOURCE_PASSWORD> \
  "https://<SOURCE_ENDPOINT>:9200/_nodes/reload_secure_settings"

{% include copy.html %}

헬퍼 포드를 제거합니다.

kubectl delete pod creds-helper -n elasticsearch --force

{% include copy.html %}

영구 프로덕션 설정의 경우 임시 자격 증명 주입보다는 소스 클러스터에 지속적인 아이덴티티 접근 방식을 선호합니다. {: .note }

스냅샷 리포지토리 등록

이 마이그레이션을 위해 전용 base_path를 사용하여 소스 클러스터에 리포지토리를 등록합니다.

curl -sk -X PUT -u <SOURCE_USERNAME>:<SOURCE_PASSWORD> \
  "https://<SOURCE_ENDPOINT>:9200/_snapshot/migration-repo" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "s3",
    "settings": {
      "bucket": "migrations-default-<ACCOUNT_ID>-<STAGE>-<REGION>",
      "region": "<REGION>",
      "base_path": "es68-snapshots"
    }
  }'

{% include copy.html %}

리포지토리를 확인합니다.

curl -sk -X POST -u <SOURCE_USERNAME>:<SOURCE_PASSWORD> \
  "https://<SOURCE_ENDPOINT>:9200/_snapshot/migration-repo/_verify?pretty"

{% include copy.html %}

워크플로는 외부 관리 스냅샷을 지원하지만 프로덕션 마이그레이션의 권장 접근 방식은 Migration Assistant가 스냅샷을 생성하도록 하는 것입니다. 이렇게 하면 스냅샷 생성, 메타데이터 마이그레이션, 백필이 일관된 승인, 검증, 복구 단계를 포함하는 단일 반복 가능한 워크플로에 유지됩니다. 외부 관리 스냅샷은 테스트 마이그레이션, 문제 해결 또는 복구 시나리오에 적합합니다. {: .note }

3단계: VPC 정보 수집

VPC를 찾습니다.

aws ec2 describe-vpcs \
  --region <REGION> \
  --query "Vpcs[*].{VpcId:VpcId,Name:Tags[?Key=='Name']|[0].Value,CidrBlock:CidrBlock}" \
  --output table

{% include copy.html %}

VPC의 서브넷을 찾으려면 다음 명령을 실행합니다.

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

{% include copy.html %}

서로 다른 가용 영역에 있는 최소 두 개의 서브넷을 선택합니다.

4단계: 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에 Migration Assistant를 배포합니다.

./aws-bootstrap.sh \
  --deploy-import-vpc-cfn \
  --stack-name MA \
  --stage <STAGE> \
  --vpc-id <YOUR_VPC_ID> \
  --subnet-ids <SUBNET_1>,<SUBNET_2> \
  --region <REGION>

{% include copy.html %}

격리된 서브넷의 경우

서브넷에 직접적인 인터넷 이그레스가 없는 경우 VPC 엔드포인트 플래그를 추가합니다.

./aws-bootstrap.sh \
  --deploy-import-vpc-cfn \
  --stack-name MA \
  --stage <STAGE> \
  --vpc-id <YOUR_VPC_ID> \
  --subnet-ids <SUBNET_1>,<SUBNET_2> \
  --create-vpc-endpoints \
  --region <REGION>

{% include copy.html %}

배포를 확인합니다.

aws eks update-kubeconfig --region <REGION> --name migration-eks-cluster-<STAGE>-<REGION>
kubectl get pods -n ma

{% include copy.html %}

모든 핵심 포드가 실행 중이어야 합니다.

5단계: 출력 확인 및 대상 액세스 매핑

CloudFormation 출력을 읽습니다.

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

{% include copy.html %}

출력에는 다음 값이 포함됩니다.

EKS 클러스터 이름
스냅샷 역할 ARN
마이그레이션 IAM 역할 정보
EKS 클러스터 보안 그룹

대상 도메인이 세분화된 액세스 제어를 사용하는 경우 Migration Assistant IAM 역할에 충분한 권한을 매핑합니다. 한 가지 옵션은 MasterUserARN으로 설정하는 것입니다.

aws opensearch update-domain-config \
  --region <REGION> \
  --domain-name <TARGET_DOMAIN_NAME> \
  --advanced-security-options '{
    "Enabled": true,
    "MasterUserOptions": {
      "MasterUserARN": "arn:aws:iam::<ACCOUNT_ID>:role/migration-eks-cluster-<STAGE>-<REGION>-migrations-role"
    }
  }'

{% include copy.html %}

계속하기 전에 도메인 처리 상태가 false를 반환할 때까지 기다립니다. 상태를 확인하려면 다음 명령을 실행합니다.

aws opensearch describe-domain \
  --region <REGION> \
  --domain-name <TARGET_DOMAIN_NAME> \
  --query "DomainStatus.Processing"

{% include copy.html %}

기존 MasterUserARN 구성을 유지하려면 역할을 교체하지 않고 적절한 백엔드 역할에 매핑하세요. {: .warning }

6단계: 네트워크 액세스 허용

EKS 클러스터 보안 그룹을 찾습니다.

aws eks describe-cluster \
  --region <REGION> \
  --name migration-eks-cluster-<STAGE>-<REGION> \
  --query "cluster.resourcesVpcConfig.clusterSecurityGroupId" \
  --output text

{% include copy.html %}

그런 다음 Migration Assistant가 소스 및 대상 클러스터에 도달할 수 있도록 인바운드 규칙을 추가합니다.

aws ec2 authorize-security-group-ingress \
  --region <REGION> \
  --group-id <SOURCE_CLUSTER_SG> \
  --protocol tcp \
  --port 9200 \
  --source-group <MA_EKS_CLUSTER_SG>

aws ec2 authorize-security-group-ingress \
  --region <REGION> \
  --group-id <TARGET_DOMAIN_SG> \
  --protocol tcp \
  --port 443 \
  --source-group <MA_EKS_CLUSTER_SG>

{% include copy.html %}

소스와 대상 클러스터가 다른 VPC에 있는 경우 라우팅 및 보안 정책이 VPC 간 통신을 허용하는지 확인합니다.

7단계: Migration Console에 연결 및 시크릿 생성

Migration Console을 엽니다.

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

{% include copy.html %}

설치된 버전을 확인합니다.

console --version

{% include copy.html %}

소스가 기본 인증을 사용하는 경우 Kubernetes 시크릿을 생성합니다.

kubectl create secret generic source-credentials \
  --from-literal=username=<SOURCE_USERNAME> \
  --from-literal=password='<SOURCE_PASSWORD>' \
  -n ma

{% include copy.html %}

AWS Signature Version 4를 사용하는 OpenSearch Service 대상의 경우 대상 자격 증명 시크릿이 필요하지 않습니다. Migration Assistant 포드는 AWS 아이덴티티를 사용합니다.

8단계: 파일럿 워크플로 구성 빌드

현재 스키마 샘플에서 시작합니다.

workflow configure sample --load
workflow configure edit

{% include copy.html %}

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

다음과 유사한 파일럿 구성을 사용합니다.

{
  "sourceClusters": {
    "source": {
      "endpoint": "https://<SOURCE_ENDPOINT>:9200",
      "allowInsecure": true,
      "version": "ES 6.8",
      "authConfig": {
        "basic": {
          "secretName": "source-credentials"
        }
      },
      "snapshotInfo": {
        "repos": {
          "migration-repo": {
            "awsRegion": "<REGION>",
            "s3RepoPathUri": "s3://migrations-default-<ACCOUNT_ID>-<STAGE>-<REGION>/es68-snapshots"
          }
        },
        "snapshots": {
          "migration-snapshot": {
            "repoName": "migration-repo",
            "config": {
              "createSnapshotConfig": {
                "indexAllowlist": ["<PILOT_INDEX_NAME>"],
                "includeGlobalState": true
              }
            }
          }
        }
      }
    }
  },
  "targetClusters": {
    "target": {
      "endpoint": "https://<TARGET_DOMAIN_ENDPOINT>",
      "authConfig": {
        "sigv4": {
          "region": "<REGION>",
          "service": "es"
        }
      }
    }
  },
  "snapshotMigrationConfigs": [
    {
      "fromSource": "source",
      "toTarget": "target",
      "perSnapshotConfig": {
        "migration-snapshot": [
          {
            "metadataMigrationConfig": {
              "indexAllowlist": ["<PILOT_INDEX_NAME>"],
              "multiTypeBehavior": "UNION"
            },
            "documentBackfillConfig": {
              "indexAllowlist": ["<PILOT_INDEX_NAME>"],
              "podReplicas": 4
            }
          }
        ]
      }
    }
  ]
}

{% include copy.html %}

이 예제에서 주목할 만한 구성 세부 사항은 다음과 같습니다.

소스는 HTTPS를 사용하며 allowInsecure: true로 설정되어 있습니다. EKS의 자체 관리 Elasticsearch는 종종 자체 서명 인증서를 사용하기 때문입니다.
소스 버전은 ES 6.8입니다.
대상은 서비스 es와 함께 AWS Signature Version 4를 사용합니다.
UNION으로 설정된 multiTypeBehavior는 Elasticsearch 6.8 소스에 실용적인 시작점입니다.
파일럿은 스냅샷 생성, 메타데이터 마이그레이션, 백필을 하나의 작은 인덱스로 제한합니다.

9단계: 연결 테스트

내장된 연결 테스트를 실행합니다.

console clusters connection-check
console clusters curl source /
console clusters curl target /

{% include copy.html %}

소스와 대상 클러스터 모두 성공적으로 연결되어야 합니다. 대상 클러스터가 403을 반환하면 대상 IAM 매핑이 완료되지 않은 것입니다.

10단계: 파일럿 마이그레이션 실행

워크플로를 제출합니다.

workflow submit
workflow manage

{% include copy.html %}

workflow manage를 기본 인터페이스로 사용합니다. 승인이 나타나면 출력을 검증하고 승인하거나 CLI를 직접 사용합니다.

workflow approve step "*.evaluateMetadata"
workflow approve step "*.migrateMetadata"

{% include copy.html %}

파일럿이 완료된 후 대상 클러스터를 검증합니다.

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 %}

파일럿이 깔끔해 보일 때까지 전체 마이그레이션을 시작하지 마세요. {: .note }

Step 11: 전체 마이그레이션 실행하기

모든 인덱스로 마이그레이션을 확장하려면 워크플로 구성을 편집하세요.

workflow configure edit

{% include copy.html %}

전체 클러스터 백필 전용 마이그레이션의 경우 구성을 다음과 같이 업데이트하세요.

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

{% include copy.html %}

"metadataMigrationConfig": {
  "indexAllowlist": [],
  "multiTypeBehavior": "UNION"
}

{% include copy.html %}

"documentBackfillConfig": {
  "indexAllowlist": [],
  "podReplicas": 4
}

{% include copy.html %}

빈 메타데이터 또는 RFS indexAllowlist는 스냅샷에서 적격한 모든 인덱스를 지정해요.

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

계획된 다운타임 경로

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

Elasticsearch에 쓰기를 중지하세요.
워크플로를 제출하세요.
필요에 따라 게이트를 모니터링하고 승인하세요.
대상을 검증하세요.
Migration Assistant가 자동으로 이동하지 않는 항목(보안 구성, ISM 또는 ILM, 대시보드, 파이프라인, 클러스터 튜닝 등)을 다시 생성하세요.
클라이언트를 대상으로 지정하세요.
쓰기를 재개하세요.

제로 다운타임 경로

제로 다운타임 마이그레이션의 경우 워크플로 구성에 트래픽 섹션을 추가하세요. 이 섹션은 캡처 프록시와 리플레이어를 구성해요.

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

{% include copy.html %}

VPC 외부에 프록시를 노출하려면 제출 전에 워크플로 구성에서 internetFacing을 true로 설정하세요. 제출 후에는 Kubernetes Service 리소스를 수정하지 마세요.

그런 다음 다음 단계를 따르세요.

워크플로를 제출하세요.
캡처 프록시 Kubernetes Service를 사용할 수 있을 때까지 기다리세요.
스냅샷 및 백필 기간이 시작되기 전에 클라이언트를 프록시로 라우팅하세요.
스냅샷, 메타데이터 마이그레이션, 백필이 완료되도록 허용하세요.
리플레이가 실시간 경계에 도달할 때까지 기다리세요.
대상을 검증하세요.
클라이언트를 프록시에서 대상 엔드포인트로 전환하세요.

프록시 엔드포인트 찾기:

kubectl get svc -n ma

{% include copy.html %}

리플레이 기간은 백필 중에 축적된 트래픽 양과 구성된 speedupFactor에 따라 달라져요.

Step 12: 트래픽 검증 및 전환

트래픽을 전환하기 전에 다음을 검증하세요.

대상 클러스터 상태
대상 인덱스 목록
문서 수
대표 검색 결과
마이그레이션된 다중 유형 데이터의 매핑 동작

검증하려면 다음 명령을 실행하세요.

console clusters curl source /_cat/indices?v
console clusters curl target /_cat/indices?v
console clusters curl target /_cat/aliases?v
console clusters curl target /_cluster/health

{% include copy.html %}

선택 사항: EKS에서 고급 검증

EKS에서는 Amazon CloudWatch에서 추가 리플레이 및 비교 텔레메트리를 검토할 수 있어요. 다음을 확인하세요.

리플레이 진행 상황을 확인하기 위해 리플레이 하트비트 로그
소스와 대상의 응답 동작을 비교하기 위한 tupleComparison 메트릭
쓰기 불일치에 대한 대상 측 오류

이 검증은 문서 수 비교만으로는 충분하지 않은 제로 다운타임 마이그레이션에서 특히 중요해요.

검증을 통해 대상이 올바른 것으로 확인되면 클라이언트를 OpenSearch Service 도메인 엔드포인트로 리디렉션하세요.

Step 13: 소스를 대체 수단으로 유지

트래픽 전환 직후에 소스 클러스터를 제거하지 마세요. 다음을 확인할 때까지 소스를 계속 사용할 수 있도록 유지하세요.

프로덕션 트래픽이 대상에서 안정적이에요.
애플리케이션 오류율이 예상 범위 내에 있어요.
대시보드와 운영 도구가 올바르게 작동해요.
모든 클라이언트가 캡처 프록시에서 리디렉션되었어요.

24시간에서 72시간의 롤백 기간을 권장해요.

Step 14: 마이그레이션 인프라 제거

롤백 기간이 지난 후에만 인프라를 제거하세요.

Helm 릴리스와 네임스페이스를 제거하세요.

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

{% include copy.html %}

CloudFormation 스택을 삭제하세요.

aws cloudformation delete-stack --region <REGION> --stack-name MA
aws cloudformation wait stack-delete-complete --region <REGION> --stack-name MA

{% include copy.html %}

이렇게 하면 Migration Assistant EKS 환경이 제거돼요. 소스 클러스터, 대상 도메인 또는 스냅샷 데이터는 자동으로 제거되지 않아요.

스냅샷 버킷이 더 이상 필요하지 않으면 다음 명령을 실행하여 삭제하세요.

aws s3 rb s3://migrations-default-<ACCOUNT_ID>-<STAGE>-<REGION> --force

{% include copy.html %}

문제 해결

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

CloudFormation 중 부트스트랩 실패

CloudFormation 스택 상태를 확인하려면 다음 명령을 실행하세요.

aws cloudformation describe-stacks --region <REGION> --stack-name MA --query "Stacks[0].StackStatus"

{% include copy.html %}

스택 상태가 ROLLBACK_COMPLETE 또는 CREATE_FAILED인 경우 스택을 삭제하고 부트스트랩 스크립트를 다시 실행하세요.

CloudFormation 이후 Helm 배포 전 부트스트랩 실패

부트스트랩 스크립트를 다시 실행하세요.

./aws-bootstrap.sh --skip-cfn-deploy --stage <STAGE> --region <REGION>

{% include copy.html %}

대상이 403 반환

Migration Assistant IAM 역할에 대상 도메인에 대한 충분한 권한이 없어요. 대상 클러스터 보안 구성에서 역할을 적절한 백엔드 역할에 매핑하세요.

ExpiredToken으로 스냅샷 생성 실패

소스 클러스터의 임시 S3 자격 증명이 만료되었어요. 자격 증명을 새로 고치고 보안 설정을 다시 로드하세요.

curl -sk -X POST -u <SOURCE_USERNAME>:<SOURCE_PASSWORD> \
  "https://<SOURCE_ENDPOINT>:9200/_nodes/reload_secure_settings"

{% include copy.html %}

콘솔에서는 파일럿 성공하지만 워크플로 실패

이 문제는 콘솔 포드 액세스와 워크플로 실행자 포드 액세스 간의 차이를 나타내요. EKS에서 워크플로 실행자 서비스 계정에 필요한 AWS 자격 증명과 네트워크 액세스가 있는지 확인하세요.

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/migration-assistant/playbook-elasticsearch-6-8-to-opensearch-3/

Playbook: Elasticsearch 6.8 to OpenSearch 3.5 on EKS