Deploy
출처: 문서
본문
배포
이 퀵스타트는 시작하기 전에 업그레이드 시 호환성이 깨지는 변경 사항과 제한 사항을 파악할 수 있도록 평가를 이미 수행했다고 가정해요.
이 퀵스타트에서는 Migration Assistant for OpenSearch를 배포하고 Reindex-from-Snapshot(RFS)를 사용해 기존 데이터 마이그레이션을 실행하는 방법을 설명해요. 설명을 위해 AWS를 사용하지만, 다른 클라우드 프로바이더에서 사용할 수 있도록 단계를 수정할 수도 있어요.
참고: 이 페이지는 RFS만 사용하는 배포를 중심으로 다루지만, 구성 옵션에서 설명하는 것처럼 Capture and Replay 기능을 추가하거나 RFS 옵션을 Capture and Replay로 대체할 수도 있어요.
이 퀵스타트를 사용하기 전에 Migration Assistant가 적합한지 확인하기를 먼저 살펴보세요.
이 가이드는 AWS Cloud Development Kit (AWS CDK)를 사용하기 때문에, CDKToolkit 스택이 존재하고 CREATE_COMPLETE 상태인지 확인해야 해요. 설정 방법은 CDK Toolkit 문서를 참고하세요.
배포 환경 계획하기
배포를 시작하기 전에 다음 환경 계획 단계를 고려해 보세요:
- 고유한 stage 이름 선택하기: 기존 배포가 있거나 충돌 가능성이 있다면
dev사용은 피하세요. "test", "staging", "prod" 또는 설명이 잘 되는 다른 이름을 사용해 보세요. - 도메인 엔드포인트 확인하기: 소스 클러스터와 타겟 클러스터 엔드포인트에 액세스할 수 있고 형식이 올바른지 확인하세요.
- 인증 준비하기: 클러스터 자격 증명과 AWS Secrets Manager Amazon Resource Name(ARN)을 미리 준비해 두세요.
- AWS 자격 증명 확인하기: 대상 계정과 AWS 리전에 맞게 AWS 자격 증명이 올바르게 구성되어 있는지 확인하세요.
사전 준비 사항
배포를 진행하기 전에 다음 사전 준비 사항을 완료했는지 확인하세요.
AWS 환경 설정
- AWS 자격 증명 구성하기:
aws configure를 실행해 자격 증명을 설정하거나 환경 변수가 올바르게 설정되어 있는지 확인하세요. - 계정 액세스 확인하기:
aws sts get-caller-identity로 자격 증명을 테스트해 보세요. - 리전 확인하기: 올바른 AWS 리전에 배포하고 있는지 확인하세요.
1단계: Amazon EC2 인스턴스에 Bootstrap 설치하기 (~10분)
마이그레이션을 시작하려면 다음 단계에 따라 Amazon Elastic Compute Cloud(Amazon EC2) 인스턴스에 bootstrap 박스를 설치하세요. 이 인스턴스는 AWS CloudFormation을 사용해 스택을 생성하고 관리해요.
- Migration Assistant를 배포하려는 대상 AWS 계정에 로그인하세요.
- 대상 AWS 계정에 로그인된 브라우저에서 여기를 마우스 오른쪽 버튼으로 클릭해 새 브라우저 탭에서 CloudFormation 템플릿을 불러오세요.
- CloudFormation 스택 마법사를 따르세요:
- Stack Name:
MigrationBootstrap - Stage Name:
dev - 각 단계를 마칠 때마다 Next > Acknowledge > Submit을 선택하세요.
- Bootstrap 스택이 존재하고
CREATE_COMPLETE상태로 설정되어 있는지 확인하세요. 이 과정은 완료까지 약 10분 정도 걸려요.
2단계: Bootstrap 인스턴스 액세스 설정하기 (~5분)
다음 단계에 따라 Bootstrap 인스턴스 액세스를 설정하세요:
- 배포가 완료되면
bootstrap-dev-instance의 EC2 인스턴스 ID를 찾으세요. - 다음 스니펫을 사용해 AWS Identity and Access Management(IAM) 정책을 생성하되,
<aws-region>,<aws-account>,<stage>,<ec2-instance-id>는 각자의 정보로 바꾸세요:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:StartSession",
"Resource": [
"arn:aws:ec2:<aws-region>:<aws-account>:instance/<ec2-instance-id>",
"arn:aws:ssm:<aws-region>:<aws-account>:document/BootstrapShellDoc-<stage>-<aws-region>"
]
}
]
}
{% include copy.html %}
- 정책 이름을 지정하고(예:
SSM-OSMigrationBootstrapAccess) Create policy를 선택해 정책을 생성하세요. - 새로 만든 정책을 EC2 인스턴스의 IAM 역할에 연결하세요.
3단계: Bootstrap에 로그인하고 Migration Assistant 빌드하기 (~15분)
이제 다음 단계에 따라 Bootstrap에 로그인하고 Migration Assistant를 빌드하세요.
사전 준비 사항
이 단계를 수행하려면 다음 사전 준비 사항을 충족해야 해요:
- 인스턴스에 AWS Command Line Interface(AWS CLI)와 AWS Session Manager 플러그인이 설치되어 있어야 해요.
- 인스턴스에 AWS 자격 증명이 구성되어 있어야 해요(
aws configure).
단계
- 터미널에 AWS 자격 증명을 로드하세요.
- 다음 명령어로 인스턴스에 로그인하되,
<instance-id>와<aws-region>은 각자의 인스턴스 ID와 리전으로 바꾸세요:
aws ssm start-session --document-name BootstrapShellDoc-<stage>-<aws-region> --target <instance-id> --region <aws-region> [--profile <profile-name>]
{% include copy.html %}
- 로그인한 후에는 Bootstrap 인스턴스 셸에서
/opensearch-migrations디렉터리 안에서 다음 명령어를 실행하세요:
./initBootstrap.sh && cd deployment/cdk/opensearch-service-migration
{% include copy.html %}
- 빌드가 성공하면 인프라 배포에 사용할 경로를 메모해 두세요. 이 경로는 다음 단계에서 사용돼요.
4단계: RFS 구성 및 배포하기 (~20분)
RFS와 함께 Migration Assistant를 배포하려면 다음 스택을 배포해야 해요:
Migration Assistant network스택RFS스택Migration Console스택
RFS 파라미터
배포를 구성하기 전에 RFS 파라미터를 먼저 이해해 두세요. 마이그레이션 도구를 사용해 스냅샷을 생성하는 경우 이 파라미터는 자동으로 구성돼요. 기존 스냅샷을 사용하는 경우에는 reindexFromSnapshotExtraArgs 설정을 다음 값으로 수정해야 해요:
"reindexFromSnapshotExtraArgs": "--s3-repo-uri s3://<bucket-name>/<repo> --s3-region <region> --snapshot-name <name>"
{% include copy.html %}
또한 migrationconsole 및 reindexFromSnapshot 태스크 역할에 S3 버킷 권한을 부여해야 해요.
구성 및 배포 단계
다음 단계에 따라 RFS를 구성·배포하고, Migration Assistant를 배포한 다음, 필요한 스택이 설치되었는지 확인하세요:
- 인증 시크릿 설정하기: 소스 클러스터와 타겟 클러스터 양쪽의 기본 인증 정보(사용자 이름과 비밀번호)를 AWS Secrets Manager에 별도의 시크릿으로 추가하세요. 각 시크릿에는 사용자 이름용 하나와 비밀번호용 하나, 이렇게 두 개의 키-값 쌍이 반드시 포함되어야 해요. 각 시크릿의 평문은 다음 예시와 비슷한 형태여야 해요:
{"username":"admin","password":"myStrongPassword123!"}
배포 중에 사용할 수 있도록 시크릿의 Amazon Resource Name(ARN)을 반드시 복사해 두세요.
- 배포 컨텍스트 구성하기: Bootstrap 인스턴스와 같은 셸에서
/opensearch-migrations/deployment/cdk/opensearch-service-migration디렉터리에 있는cdk.context.json파일을 수정하고 다음 설정을 구성하세요:
{
"default": {
"stage": "dev",
"vpcId": "<TARGET CLUSTER VPC ID>",
"targetCluster": {
"endpoint": "<TARGET CLUSTER ENDPOINT>",
"auth": {
"type": "basic",
"userSecretArn": "<SECRET_WITH_USERNAME_AND_PASSWORD_KEYS>"
}
},
"sourceCluster": {
"endpoint": "<SOURCE CLUSTER ENDPOINT>",
"version": "<SOURCE ENGINE VERSION>",
"auth": {
"type": "basic",
"userSecretArn": "<SECRET_WITH_USERNAME_AND_PASSWORD_KEYS>"
}
},
"reindexFromSnapshotExtraArgs": "<RFS PARAMETERS (see the preceding section)>",
"reindexFromSnapshotMaxShardSizeGiB": 80
}
}
{% include copy.html %}
소스 클러스터와 타겟 클러스터의 인증 방식은 권한 없음, 사용자 이름과 비밀번호를 사용하는 basic, 또는 sigv4로 구성할 수 있어요.
환경 구성 예시
기존 배포와의 충돌을 피하려면 서로 다른 컨텍스트 ID와 stage 이름을 사용하는 것을 고려해 보세요:
{
"test-deploy": {
"stage": "test",
"reindexFromSnapshotServiceEnabled": true,
"sourceCluster": {
"endpoint": "https://migration-source-es710.us-west-2.es.amazonaws.com",
"version": "ES_7.10",
"auth": {
"type": "basic",
"userSecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:migration-source-password"
}
},
"targetCluster": {
"endpoint": "https://migration-target-os219.us-west-2.es.amazonaws.com",
"auth": {
"type": "basic",
"userSecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:migration-target-password"
}
}
},
"prod-deploy": {
"stage": "prod",
"reindexFromSnapshotServiceEnabled": true,
"// ... additional production-specific configuration"
}
}
{% include copy.html %}
중요 구성 참고 사항:
- 리소스 이름 충돌을 방지하려면 고유한
stage값을 사용하세요. - 시크릿 ARN이 완전한 형태이고 배포 대상 AWS 리전에서 액세스 가능한지 확인하세요.
- 도메인 엔드포인트는 축약된 이름이나 전체 AWS URL로 지정할 수 있어요.
./deploy.sh <contextId>로 배포하세요(예:./deploy.sh test-deploy).
- CDK 부트스트랩하기:
cdk.context.json파일 구성을 모두 마친 후 다음 명령어로 계정을 부트스트랩하고 필요한 스택을 배포하세요:
cdk bootstrap --c contextId=default --require-approval never
{% include copy.html %}
- Migration Assistant 배포하기: 다음 명령어로 Migration Assistant를 배포하세요:
cdk deploy "*" --c contextId=default --require-approval never --concurrency 5
{% include copy.html %}
- 배포 확인하기: 같은 Bootstrap 인스턴스 셸에서 모든 CloudFormation 스택이 성공적으로 설치되었는지 확인하세요:
aws cloudformation list-stacks --query "StackSummaries[?StackStatus!='DELETE_COMPLETE'].[StackName,StackStatus]" --output table
{% include copy.html %}
여러분의 리전에 대해 다음과 비슷한 출력이 표시될 거예요:
------------------------------------------------------------------------
| ListStacks |
+--------------------------------------------------+-------------------+
| OSMigrations-dev-us-east-1-MigrationConsole | CREATE_COMPLETE |
| OSMigrations-dev-us-east-1-ReindexFromSnapshot | CREATE_COMPLETE |
| OSMigrations-dev-us-east-1-MigrationInfra | CREATE_COMPLETE |
| OSMigrations-dev-us-east-1-default-NetworkInfra | CREATE_COMPLETE |
| MigrationBootstrap | CREATE_COMPLETE |
| CDKToolkit | CREATE_COMPLETE |
+--------------------------------------------------+-------------------+
5단계: Migration Console 액세스하기
다음 명령어를 실행해 Migration Console에 액세스하세요:
./accessContainer.sh migration-console dev <region>
{% include copy.html %}
accessContainer.sh 파일은 Bootstrap 인스턴스의 /opensearch-migrations/deployment/cdk/opensearch-service-migration/에 있어요. 자세한 내용은 Migration Console 액세스하기를 참고하세요.
{: .note}
6단계: 소스 클러스터와 타겟 클러스터 연결 확인하기
클러스터 연결을 확인하려면 다음 명령어를 실행하세요:
console clusters connection-check
{% include copy.html %}
다음과 같은 출력이 표시될 거예요:
SOURCE CLUSTER
ConnectionResult(connection_message='Successfully connected!', connection_established=True, cluster_version='')
TARGET CLUSTER
ConnectionResult(connection_message='Successfully connected!', connection_established=True, cluster_version='')
Migration Console 명령어에 대해 자세히 알아보려면 Migration Console 명령어 레퍼런스를 참고하세요.
문제 해결
다음 섹션에서는 흔히 발생하는 배포 문제와 해결 방법을 설명해요.
일반적인 배포 문제
문제: AWS 자격 증명이 구성되지 않음
Unable to locate credentials. You can configure credentials by running "aws configure".
해결 방법:
aws configure를 실행하고 액세스 키, 시크릿 키, 리전을 입력하세요.- 또는 환경 변수를 설정하세요:
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_DEFAULT_REGION. aws sts get-caller-identity로 자격 증명을 확인하세요.
문제: 스택 이름 충돌
Stack with id OSMigrations-dev-us-west-2-MigrationConsole already exists
해결 방법:
- 컨텍스트 구성에서 다른
stage값을 사용하세요(예: "test", "staging"). - 또는 기존 스택을 삭제하세요:
cdk destroy "*" --c contextId=<existing-context>. - 병렬로 배포할 때는 고유한 컨텍스트 ID를 사용하세요.
문제: Docker 빌드 실패
ERROR: failed to solve: public.ecr.aws/sam/build-nodejs18.x: pulling from host public.ecr.aws failed
해결 방법:
docker logout public.ecr.aws를 실행해 인증 캐시를 지우세요.- 빌드 과정을 다시 시도하세요:
./buildDockerImages.sh.
문제: CDK 부트스트랩 필요
This stack uses assets, so the toolkit stack must be deployed to the environment
해결 방법:
- 여러분의 리전에서 CDK를 부트스트랩하세요:
cdk bootstrap --c contextId=<your-context>. - 올바른 AWS 자격 증명과 리전이 구성되어 있는지 확인하세요.
롤백 절차
배포를 제거해야 한다면:
- 실행 중인 모든 서비스 중지하기:
console backfill stop # If backfill is running
- CDK 스택 삭제하기:
cdk destroy "*" --c contextId=<your-context> --force
- 필요하면 수동으로 정리하기:
- AWS Management Console에서 남아 있는 CloudFormation 스택을 제거하세요.
- Amazon Elastic Container Service(Amazon ECS) 태스크나 로드 밸런서 같은 고아 리소스가 남아 있다면 삭제하세요.
다음 단계
배포를 마친 후에는 마이그레이션 단계를 진행하세요:
- 스냅샷 생성: 소스 클러스터의 스냅샷을 생성하세요.
- 메타데이터 마이그레이션: 클러스터 메타데이터를 타겟으로 마이그레이션하세요.
- 백필: 문서를 마이그레이션하고 진행 상황을 모니터링하세요.
전체 마이그레이션 과정에 대해 자세히 알아보려면 마이그레이션 단계를 참고하세요.
{% include migration-phase-navigation.html %}