기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon Keyspaces로 데이터를 대량 업로드하거나 마이그레이션하는 데 적합한 도구를 선택하는 방법
이 섹션에서는 Amazon Keyspaces로 데이터를 대량 업로드하거나 마이그레이션하는 데 사용할 수 있는 다양한 도구를 검토하고 필요에 따라 올바른 도구를 선택하는 방법을 배울 수 있습니다. 또한이 섹션에서는 Amazon Keyspaces로 데이터를 가져오는 방법을 보여주는 사용 가능한 step-by-step 자습서에 대한 개요와 사용 사례를 제공합니다.
Apache Cassandra에서 Amazon Keyspaces로 워크로드를 마이그레이션하는 데 사용할 수 있는 전략을 검토하려면 [Apache Cassandra에서 Amazon Keyspaces로 마이그레이션하기 위한 마이그레이션 계획 생성](migrating-cassandra.md) 섹션을 참조하세요.
+ **마이그레이션 도구**
+ Github에서 사용할 수 있는 [Amazon Keyspaces(Apache Cassandra용)의 요금 계산기](https://aws-samples.github.io/sample-pricing-calculator-for-keyspaces/#cassandra)를 사용하면 기존 Apache Cassandra 워크로드를 기반으로 Amazon Keyspaces의 월별 비용을 추정할 수 있습니다. Cassandra nodetool 상태 출력의 지표와 Amazon Keyspaces의 의도된 서버리스 구성을 입력하여 두 솔루션 간의 직접 비용을 비교합니다. 이 계산기는 기존 Cassandra 배포와 비교하여 Amazon Keyspaces의 운영 비용에만 중점을 둡니다. 인프라 유지 관리, 운영 오버헤드 또는 Cassandra 지원 비용과 같은 총 소유 비용(TCO) 요소는 포함되지 않습니다.
+ **Amazon Keyspaces 마이그레이션을 위한 ZDM 듀얼 쓰기 프록시** - [Github](https://github.com/aws-samples/amazon-keyspaces-examples/blob/main/migration/online/zdm-proxy/README.md)에서 사용할 수 있는 ZDM 듀얼 쓰기 프록시는 Apache Cassandra에서 Amazon Keyspaces로의 제로 가동 중지 마이그레이션을 지원합니다.
+ **CQLReplicator** – CQLReplicator는 [Github](https://github.com/aws-samples/cql-replicator)에서 사용할 수 있는 오픈 소스 유틸리티로, Apache Cassandra에서 Amazon Keyspaces로 데이터를 거의 실시간으로 마이그레이션하는 데 도움이 됩니다.
자세한 내용은 [CQLReplicator를 사용하여 데이터 마이그레이션](migration-hybrid-cql-rep.md) 단원을 참조하십시오.
+ Amazon Managed Streaming for Apache Kafka를 사용하여 이중 쓰기를 사용하는 [온라인 마이그레이션](migrating-online.md) 프로세스를 구현하는 방법에 대한 자세한 내용은 [Guidance for continuous data migration from Apache Cassandra to Amazon Keyspaces](https://aws.amazon.com/solutions/guidance/continuous-data-migration-from-apache-cassandra-to-amazon-keyspaces/)를 참조하세요.
+ 대규모 마이그레이션의 경우 추출, 전환, 적재(ETL) 도구를 사용하는 것이 좋습니다. AWS Glue 를 사용하여 데이터 변환 마이그레이션을 빠르고 효과적으로 수행할 수 있습니다. 자세한 내용은 [오프라인 마이그레이션 프로세스: Apache Cassandra에서 Amazon Keyspaces로](migrating-offline.md) 단원을 참조하십시오.
+ Apache Cassandra Spark 커넥터를 사용하여 Amazon Keyspaces에 데이터를 쓰는 방법을 알아보려면 [자습서: Apache Spark와 통합하여 데이터 가져오기 또는 내보내기](spark-integrating.md) 섹션을 참조하세요.
+ cqlsh `COPY FROM` 명령을 사용하여 Amazon Keyspaces로 데이터를 빠르게 로드합니다. cqlsh는 Apache Cassandra에 포함되어 있으며 작은 데이터 세트 또는 테스트 데이터를 로드하는 데 가장 적합합니다. 단계별 지침은 [자습서: cqlsh를 사용하여 Amazon Keyspaces에 데이터 로드](bulk-upload.md)섹션을 참조하세요.
+ Apache Cassandra용 DataStax 벌크 로더를 사용하여 `dsbulk` 명령을 사용하여 Amazon Keyspaces에 데이터를 로드할 수도 있습니다. DSBulk는 cqlsh보다 더욱 강력한 가져오기 기능을 제공하며 [GitHub 리포지토리](https://github.com/datastax/dsbulk)에서 사용할 수 있습니다. 단계별 지침은 [자습서: DSBulk를 사용하여 Amazon Keyspaces에 데이터 로드](dsbulk-upload.md)섹션을 참조하세요.
Amazon Keyspaces에 데이터를 업로드하기 위한 일반적인 고려 사항
+ **데이터 업로드를 더 작은 구성 요소로 나눕니다.**
원시 데이터 크기 측면에서 다음과 같은 마이그레이션 단위와 잠재적 공간을 고려합니다. 한 단계 이상의 단계에서 소량의 데이터를 업로드하면 마이그레이션을 단순화하는 데 도움이 될 수 있습니다.
+ **클러스터별** - 모든 Cassandra 데이터를 한 번에 마이그레이션합니다. 이 접근 방식은 소규모 클러스터의 경우 괜찮을 수 있습니다.
+ **키스페이스 또는 테이블별** - 마이그레이션을 키스페이스 또는 테이블 그룹으로 나눕니다. 이 접근 방식을 사용하면 각 워크로드의 요구 사항에 따라 단계적으로 데이터를 마이그레이션할 수 있습니다.
+ **데이터별** - 데이터 크기를 더 줄이려면 특정 사용자 그룹 또는 제품에 대한 데이터를 마이그레이션하는 것을 고려합니다.
+ **단순성을 기반으로 먼저 업로드할 데이터의 우선 순위를 정합니다.**
먼저 더 쉽게 마이그레이션할 수 있는 데이터가 있는지 고려합니다. 예를 들어 특정 시간대에 변경되지 않는 데이터, 야간 배치 작업의 데이터, 오프라인 시간 동안 사용하지 않은 데이터 또는 내부 앱의 데이터 등이 여기에 해당하는지 고려합니다.
**Topics**
+ [자습서: cqlsh를 사용하여 Amazon Keyspaces에 데이터 로드](bulk-upload.md)
+ [자습서: DSBulk를 사용하여 Amazon Keyspaces에 데이터 로드](dsbulk-upload.md)
# 자습서: cqlsh를 사용하여 Amazon Keyspaces에 데이터 로드
이 자습서는 `cqlsh COPY FROM` 명령을 사용하여 Apache Cassandra에서 Amazon Keyspaces로 데이터를 마이그레이션하는 프로세스를 안내합니다. 이 `cqlsh COPY FROM` 명령은 학술 또는 테스트 목적으로 Amazon Keyspaces에 작은 데이터세트를 빠르고 쉽게 업로드하는 데 유용합니다. 프로덕션 워크로드를 마이그레이션하는 방법에 대한 자세한 내용은 [오프라인 마이그레이션 프로세스: Apache Cassandra에서 Amazon Keyspaces로](migrating-offline.md) 섹션을 참조하세요. 이 자습서에서는 다음 단계를 완료합니다.
사전 조건 - 자격 증명으로 AWS 계정을 설정하고, 인증서에 대한 JKS 트러스트 스토어 파일을 생성하고, Amazon Keyspaces에 연결`cqlsh`하도록를 구성합니다.
1. **소스 CSV 및 대상 테이블 생성** - 소스 데이터로 CSV 파일을 준비하고 Amazon Keyspaces에서 대상 키스페이스 및 테이블을 생성합니다.
1. **데이터 준비** - CSV 파일에서 데이터를 무작위 배정하고 분석하여 평균 및 최대 행 크기를 결정합니다.
1. **처리량 용량 설정** - 데이터 크기 및 원하는 로드 시간을 기준으로 필요한 쓰기 용량 단위(WCU)를 계산하고 테이블의 프로비저닝된 용량을 구성합니다.
1. **cqlsh 파라미터 구성** - 워크로드를 균등하게 분산하기 위해 `INGESTRATE`, `NUMPROCESSES`, `MAXBATCHSIZE`, `CHUNKSIZE`와 같은 `cqlsh COPY FROM` 파라미터의 최적 값을 결정합니다.
1. **`cqlsh COPY FROM` 명령 실행 ** - `cqlsh COPY FROM` 명령을 실행하여 CSV 파일의 데이터를 Amazon Keyspaces 테이블에 업로드하고 진행 상황을 모니터링합니다.
문제 해결 - 데이터 업로드 프로세스 중에 잘못된 요청, 구문 분석기 오류, 용량 오류 및 cqlsh 오류와 같은 일반적인 문제를 해결합니다.
**Topics**
+ [사전 조건: `cqlsh COPY FROM`을 사용하여 데이터를 업로드하기 전에 완료해야 하는 단계](bulk-upload-prequs.md)
+ [1단계: 데이터 업로드를 위해 소스 CSV 파일 및 대상 테이블 생성](bulk-upload-source.md)
+ [2단계: 성공적인 데이터 업로드를 위해 소스 데이터 준비](bulk-upload-prepare-data.md)
+ [3단계: 테이블의 처리량 용량 설정](bulk-upload-capacity.md)
+ [4단계: `cqlsh COPY FROM` 설정 구성](bulk-upload-config.md)
+ [5단계: `cqlsh COPY FROM` 명령을 실행하여 CSV 파일의 데이터를 대상 테이블에 업로드](bulk-upload-run.md)
+ [문제 해결](bulk-upload-troubleshooting.md)
# 사전 조건: `cqlsh COPY FROM`을 사용하여 데이터를 업로드하기 전에 완료해야 하는 단계
이 자습서를 시작하려면 먼저 다음 작업을 완료해야 합니다.
1. 아직 등록하지 않은 경우의 단계에 AWS 계정 따라에 가입합니다[설 AWS Identity and Access Management정](accessing.md#SettingUp.IAM).
1. [Amazon Keyspaces에 프로그래밍 방식으로 액세스하기 위한 서비스별 자격 증명 만들기](programmatic.credentials.ssc.md)의 단계에 따라 서비스별 자격 증명을 생성합니다.
1. Cassandra 쿼리 언어 쉘(cqlsh) 연결을 설정하고 [`cqlsh` 사용하여 Amazon Keyspace에 접속](programmatic.cqlsh.md)의 단계에 따라 Amazon Keyspaces에 연결할 수 있는지 확인합니다.
# 1단계: 데이터 업로드를 위해 소스 CSV 파일 및 대상 테이블 생성
이 자습서에서는 이름 `keyspaces_sample_table.csv`가 있는 쉼표로 구분된 값(CSV) 파일을 데이터 마이그레이션의 원본 파일로 사용합니다. 제공된 샘플 파일에는 이름이 `book_awards`인 테이블에 대한 몇 개의 데이터 행이 포함되어 있습니다.
1. 소스 파일을 생성합니다. 다음 옵션 중 하나를 선택할 수 있습니다.
+ 다음 아카이브 파일 [samplemigration.zip](samples/samplemigration.zip)에 포함된 샘플 CSV 파일(`keyspaces_sample_table.csv`)을 다운로드합니다. 아카이브의 압축을 풀고 `keyspaces_sample_table.csv`의 경로를 기록해 둡니다.
+ Apache Cassandra 데이터베이스에 저장된 자체 데이터로 CSV 파일을 채우려면 다음 예와 같이 `cqlsh` 및 `COPY TO` 문을 사용하여 소스 CSV 파일을 채울 수 있습니다.
```
cqlsh localhost 9042 -u "username" -p "password" --execute "COPY mykeyspace.mytable TO 'keyspaces_sample_table.csv' WITH HEADER=true";
```
생성한 CSV 파일이 다음 요구 사항을 충족하는지 확인합니다.
+ 첫 번째 행에는 열 이름이 포함됩니다.
+ 소스 CSV 파일의 열 이름은 대상 테이블의 열 이름과 일치합니다.
+ 데이터는 쉼표로 구분됩니다.
+ 모든 데이터 값은 유효한 Amazon Keyspaces 데이터 유형입니다. [데이터 타입](cql.elements.md#cql.data-types)을(를) 참조하세요.
1. Amazon Keyspaces에서 대상 키스페이스 및 테이블을 생성합니다.
1. `cqlsh`를 사용하여 Amazon Keyspaces에 연결하고 다음 예제의 서비스 엔드포인트, 사용자 이름 및 암호를 사용자 고유의 값으로 바꿉니다.
```
cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "111122223333" -p "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" --ssl
```
1. 다음 예제와 같이 이름 `catalog`를 사용하여 새 키스페이스를 생성합니다.
```
CREATE KEYSPACE catalog WITH REPLICATION = {'class': 'SingleRegionStrategy'};
```
1. 새 키스페이스를 사용할 수 있게 되면 다음 코드를 사용하여 대상 테이블 `book_awards`를 생성합니다.
```
CREATE TABLE "catalog.book_awards" (
year int,
award text,
rank int,
category text,
book_title text,
author text,
publisher text,
PRIMARY KEY ((year, award), category, rank)
);
```
Apache Cassandra가 원본 데이터 소스인 경우 헤더가 일치하는 Amazon Keyspaces 대상 테이블을 생성하는 간단한 방법은 다음 문과 같이 소스 테이블에서 `CREATE TABLE` 문을 생성하는 것입니다.
```
cqlsh localhost 9042 -u "username" -p "password" --execute "DESCRIBE TABLE mykeyspace.mytable;"
```
그런 다음 Cassandra 소스 테이블의 설명과 일치하는 열 이름 및 데이터 유형을 사용하여 Amazon Keyspaces에 대상 테이블을 생성합니다.
# 2단계: 성공적인 데이터 업로드를 위해 소스 데이터 준비
효율적인 전송을 위해 소스 데이터를 준비하는 것은 2단계 프로세스입니다. 먼저 데이터를 무작위화합니다. 두 번째 단계에서는 데이터를 분석하여 데이터 업로드가 성공적으로 이루어질 수 있도록 적절한 `cqlsh` 파라미터 값과 필요한 테이블 설정을 결정합니다.
**데이터 무작위화**
이 `cqlsh COPY FROM` 명령은 CSV 파일에 나타나는 것과 동일한 순서로 데이터를 읽고 씁니다. `cqlsh COPY TO` 명령을 사용하여 소스 파일을 만들면 데이터가 키 정렬된 순서대로 CSV에 기록됩니다. Amazon Keyspaces는 내부적으로 파티션 키를 사용하여 데이터를 분할합니다. Amazon Keyspaces에는 동일한 파티션 키에 대한 요청을 로드 밸런싱하는 데 도움이 되는 로직이 내장되어 있지만 순서를 무작위로 지정하면 데이터를 로드하는 것이 더 빠르고 효율적입니다. Amazon Keyspaces가 다른 파티션에 쓸 때 발생하는 내장된 로드 밸런싱을 활용할 수 있기 때문입니다.
쓰기를 파티션 전체에 균등하게 분산하려면 소스 파일의 데이터를 무작위화해야 합니다. 이 작업을 수행하는 애플리케이션을 작성하거나 [Shuf](https://en.wikipedia.org/wiki/Shuf)와 같은 오픈 소스 도구를 사용할 수 있습니다. Shuf는 Linux 배포판, macOS([homebrew](https://brew.sh)에 coreutils 설치), Windows(Windows Subsystem for Linux(WSL) 사용)에서 무료로 사용할 수 있습니다. 이 단계에서 열 이름이 있는 헤더 행이 섞이지 않도록 하려면 한 가지 추가 단계가 필요합니다.
헤더를 보존하면서 소스 파일을 무작위화하려면 다음 코드를 입력합니다.
```
tail -n +2 keyspaces_sample_table.csv | shuf -o keyspace.table.csv && (head -1 keyspaces_sample_table.csv && cat keyspace.table.csv ) > keyspace.table.csv1 && mv keyspace.table.csv1 keyspace.table.csv
```
Shuf는 `keyspace.table.csv`라는 새 CSV 파일에 데이터를 다시 씁니다. 이제 필요 없는 `keyspaces_sample_table.csv` 파일을 삭제할 수 있습니다.
**데이터 분석**
데이터를 분석하여 평균 및 최대 행 크기를 결정합니다.
이렇게 하는 이유는 다음과 같습니다.
+ 평균 행 크기는 전송할 총 데이터 양을 추정하는 데 도움이 됩니다.
+ 데이터 업로드에 필요한 쓰기 용량을 프로비저닝하려면 평균 행 크기가 필요합니다.
+ 각 행의 크기가 Amazon Keyspaces의 최대 행 크기인 1MB 미만인지 확인할 수 있습니다.
**참고**
이 할당량은 파티션 크기가 아니라 행 크기를 나타냅니다. Apache Cassandra 파티션과 달리 Amazon Keyspaces 파티션은 크기가 사실상 바인딩되지 않을 수 있습니다. 파티션 키와 클러스터링 열에는 메타데이터를 위한 추가 스토리지가 필요하며 이를 행의 원시 크기에 추가해야 합니다. 자세한 내용은 [Amazon Keyspaces에서 행 크기 추정](calculating-row-size.md) 단원을 참조하십시오.
다음 코드는 [AWK](https://en.wikipedia.org/wiki/AWK)를 사용하여 CSV 파일을 분석하고 평균 및 최대 행 크기를 인쇄합니다.
```
awk -F, 'BEGIN {samp=10000;max=-1;}{if(NR>1){len=length($0);t+=len;avg=t/NR;max=(len>max ? len : max)}}NR==samp{exit}END{printf("{lines: %d, average: %d bytes, max: %d bytes}\n",NR,avg,max);}' keyspace.table.csv
```
이 코드를 실행하면 다음과 같은 결과가 출력됩니다.
```
using 10,000 samples:
{lines: 10000, avg: 123 bytes, max: 225 bytes}
```
이 자습서의 다음 단계에서 평균 행 크기를 사용하여 테이블의 쓰기 용량을 프로비저닝합니다.
# 3단계: 테이블의 처리량 용량 설정
이 자습서에서는 설정된 시간 범위 내에서 데이터를 로드하도록 cqlsh를 조정하는 방법을 보여 줍니다. 얼마나 많은 읽기와 쓰기를 수행하는지 미리 알고 있기 때문에 프로비저닝된 용량 모드를 사용합니다. 데이터 전송을 완료한 후에는 애플리케이션의 트래픽 패턴에 맞게 테이블의 용량 모드를 설정해야 합니다. 용량 관리에 대한 자세한 내용은 [Amazon Keyspaces(Apache Cassandra용)에서 서버리스 리소스 관리](serverless_resource_management.md) 섹션을 참조하세요.
프로비저닝된 용량 모드를 사용하면 테이블에 프로비저닝할 읽기 및 쓰기 용량을 미리 지정할 수 있습니다. 쓰기 용량은 시간당 청구되며 쓰기 용량 단위(WCU)로 측정됩니다. 각 WCU는 초당 1KB의 데이터 쓰기를 지원하기에 충분한 쓰기 용량입니다. 데이터를 로드할 때 쓰기 속도는 대상 테이블에 설정된 최대 WCU(매개 변수: `write_capacity_units`) 미만이어야 합니다.
기본적으로 테이블에 최대 40,000WCU를 프로비저닝하고 계정의 모든 테이블에 80,000WCU를 프로비저닝할 수 있습니다. 추가 용량이 필요한 경우 [Service Quotas](https://console.aws.amazon.com/servicequotas/home#!/services/cassandra/quotas)에서 할당량 증가를 요청할 수 있습니다. 할당량에 대한 자세한 내용은 [Amazon Keyspaces(Apache Cassandra용)에 대한 할당량](quotas.md) 섹션을 참조하세요.
**삽입에 필요한 WCU의 평균 수를 계산합니다.**
초당 1KB의 데이터를 삽입하려면 1WCU가 필요합니다. 360,000개의 행이 있는 CSV 파일에 1시간 내에 모든 데이터를 로드하려면 초당 100개의 행을 작성해야 합니다(360,000행/60분/60초 = 초당 100행). 각 행에 최대 1KB의 데이터가 있는 경우 초당 100개의 행을 삽입하려면 테이블에 100WCU를 프로비저닝해야 합니다. 각 행에 1.5KB의 데이터가 있는 경우 초당 한 행을 삽입하려면 WCU 두 개가 필요합니다. 따라서 초당 100개의 행을 삽입하려면 200개의 WCU를 프로비저닝해야 합니다.
초당 행 하나를 삽입하는 데 필요한 WCU 수를 결정하려면 평균 행 크기(바이트)를 1024로 나누고 가장 가까운 정수로 반올림합니다.
예를 들어 평균 행 크기가 3000바이트인 경우 초당 한 행을 삽입하려면 WCU 3개가 필요합니다.
```
ROUNDUP(3000 / 1024) = ROUNDUP(2.93) = 3 WCUs
```
**데이터 로드 시간 및 용량 계산**
이제 CSV 파일의 평균 크기와 행 수를 알았으므로 주어진 시간 동안 데이터를 로드하는 데 필요한 WCU 수와 다양한 WCU 설정을 사용하여 CSV 파일의 모든 데이터를 로드하는 데 걸리는 대략적인 시간을 계산할 수 있습니다.
예를 들어 파일의 각 행이 1KB이고 CSV 파일에 1,000,000개의 행이 있는 경우 1시간 내에 데이터를 로드하려면 해당 시간 동안 테이블에 최소 278개의 WCU를 프로비저닝해야 합니다.
```
1,000,000 rows * 1 KBs = 1,000,000 KBs
1,000,000 KBs / 3600 seconds =277.8 KBs / second = 278 WCUs
```
**프로비저닝된 용량 설정 구성**
테이블을 생성할 때 또는 `ALTER TABLE` CQL 명령을 사용하여 테이블의 쓰기 용량 설정을 지정할 수 있습니다. 다음은 `ALTER TABLE` CQL 문을 사용하여 테이블의 프로비저닝된 용량 설정을 변경하는 구문입니다.
```
ALTER TABLE mykeyspace.mytable WITH custom_properties={'capacity_mode':{'throughput_mode': 'PROVISIONED', 'read_capacity_units': 100, 'write_capacity_units': 278}} ;
```
전체 언어 참조는 [ALTER TABLE](cql.ddl.table.md#cql.ddl.table.alter) 섹션을 참조하세요.
# 4단계: `cqlsh COPY FROM` 설정 구성
이 섹션에서는 `cqlsh COPY FROM`의 파라미터 값을 결정하는 방법을 간략하게 설명합니다. `cqlsh COPY FROM` 명령은 이전에 준비한 CSV 파일을 읽고 CQL을 사용하여 Amazon Keyspaces에 데이터를 삽입합니다. 이 명령은 행을 나누어 작업자 집합 간에 `INSERT` 작업을 분배합니다. 각 작업자는 Amazon Keyspaces와 연결을 설정하고 이 채널을 통해 `INSERT` 요청을 보냅니다.
`cqlsh COPY` 명령에는 작업자 간에 작업을 균등하게 분배하기 위한 내부 로직이 없습니다. 하지만 작업이 균등하게 분배되도록 수동으로 구성할 수 있습니다. 먼저 다음과 같은 주요 cqlsh 파라미터를 검토합니다.
+ **DELIMITER** - 쉼표 이외의 구분 기호를 사용한 경우 이 파라미터를 설정할 수 있습니다. 기본값은 쉼표입니다.
+ **INGESTRATE** - `cqlsh COPY FROM`이 초당 처리를 시도하는 대상 행 수입니다. 지정되지 않은 경우 기본값은 100,000입니다.
+ **NUMPROCESSES** - cqlsh가 `COPY FROM` 작업을 위해 생성하는 하위 작업자 프로세스의 수입니다. 이 설정의 최대값은 16이며, 기본값은 `num_cores - 1`입니다. 여기서 `num_cores`는 cqlsh를 실행하는 호스트의 프로세싱 코어 수입니다.
+ **MAXBATCHSIZE** – 배치 크기에 따라 단일 배치에서 대상 테이블에 삽입되는 최대 행 수가 결정됩니다. 설정되지 않은 경우 cqlsh는 삽입된 20개 행의 배치를 사용합니다.
+ **CHUNKSIZE** - 하위 작업자에게 전달되는 작업 단위의 크기입니다. 기본적으로 5,000으로 설정됩니다.
+ **MAXATTEMPTS** - 실패한 작업자 청크를 다시 시도할 수 있는 최대 횟수입니다. 최대 시도 횟수에 도달하면 실패한 레코드가 새 CSV 파일에 기록되며 실패를 조사한 후 나중에 다시 실행할 수 있습니다.
대상 테이블에 프로비저닝한 WCU 수를 기반으로 `INGESTRATE`를 설정합니다. `cqlsh COPY FROM` 명령의 `INGESTRATE`는 제한이 아니라 대상 평균입니다. 즉, 설정한 수치를 초과할 수 있으며 종종 그럴 수도 있습니다. 버스트를 허용하고 데이터 로드 요청을 처리할 수 있는 충분한 용량을 확보하려면 `INGESTRATE`를 테이블 쓰기 용량의 90% 설정합니다.
```
INGESTRATE = WCUs * .90
```
그런 다음 `NUMPROCESSES` 파라미터를 시스템의 코어 수보다 하나 적은 것으로 설정합니다. 다음 코드를 실행하여 시스템의 코어 수를 확인할 수 있습니다.
```
python -c "import multiprocessing; print(multiprocessing.cpu_count())"
```
이 자습서에서는 다음 값을 사용합니다.
```
NUMPROCESSES = 4
```
각 프로세스는 작업자를 생성하고 각 작업자는 Amazon Keyspaces에 대한 연결을 설정합니다. Amazon Keyspaces는 모든 연결에서 초당 최대 3,000개의 CQL 요청을 지원할 수 있습니다. 즉, 각 작업자가 처리하는 요청이 초당 3,000개 미만인지 확인해야 합니다.
`INGESTRATE`와 마찬가지로 작업자는 설정한 수를 초과하여 버스트하는 경우가 많으며 클록 초로 제한되지 않습니다. 따라서 버스트를 고려하려면 각 작업자가 초당 2,500개의 요청을 처리하게 지정하도록 cqlsh 파라미터를 설정합니다. 작업자에게 분배된 작업량을 계산하려면 다음 지침을 사용합니다.
+ `INGESTRATE`를 `NUMPROCESSES`로 나눕니다.
+ `INGESTRATE`/`NUMPROCESSES` > 2,500인 경우 `INGESTRATE`를 낮추면 이 공식이 true가 됩니다.
```
INGESTRATE / NUMPROCESSES <= 2,500
```
샘플 데이터의 업로드를 최적화하도록 설정을 구성하기 전에 `cqlsh` 기본 설정을 검토하고 기본 설정을 사용하는 것이 데이터 업로드 프로세스에 어떤 영향을 미치는지 살펴보겠습니다. `cqlsh COPY FROM`은 `CHUNKSIZE`를 사용하여 작업자에게 배포할 작업 청크(`INSERT` 문)를 만들기 때문에 작업이 자동으로 균등하게 분배되지 않습니다. `INGESTRATE` 설정에 따라 일부 작업자는 가만히 앉아 있을 수 있습니다.
작업자 간에 작업을 균등하게 분배하고 각 작업자가 초당 2,500개의 요청 속도를 최적화할 수 있도록 하려면 입력 파라미터를 변경하여 `CHUNKSIZE`, `MAXBATCHSIZE` 및 `INGESTRATE`를 설정해야 합니다. 데이터 로드 중에 네트워크 트래픽 사용률을 최적화하려면 `MAXBATCHSIZE`에 대해 최대값인 30에 가까운 값을 선택합니다. `CHUNKSIZE`를 100으로 `MAXBATCHSIZE`를 25로 변경하면 10,000개의 행이 네 명의 작업자 사이에 균등하게 분산됩니다(10,000/2500 = 4).
다음 코드 예제에서는 이를 보여 줍니다.
```
INGESTRATE = 10,000
NUMPROCESSES = 4
CHUNKSIZE = 100
MAXBATCHSIZE. = 25
Work Distribution:
Connection 1 / Worker 1 : 2,500 Requests per second
Connection 2 / Worker 2 : 2,500 Requests per second
Connection 3 / Worker 3 : 2,500 Requests per second
Connection 4 / Worker 4 : 2,500 Requests per second
```
요약하면 `cqlsh COPY FROM` 파라미터를 설정할 때 다음 공식을 사용합니다.
+ **INGESTRATE** = write\$1capacity\$1units \$1 .90
+ **NUMPROCESSES** = num\$1cores -1(기본값)
+ **INGESTRATE / NUMPROCESSES** = 2,500(true 문이어야 합니다.)
+ **MAXBATCHSIZE** = 30(기본값은 20입니다. Amazon Keyspaces는 최대 30개의 배치를 허용합니다.)
+ **CHUNKSIZE** = (INGESTRATE / NUMPROCESSES) / MAXBATCHSIZE
`NUMPROCESSES`, `INGESTRATE` 및 `CHUNKSIZE` 계산을 마쳤고 이제 데이터를 로드할 준비가 되었습니다.
# 5단계: `cqlsh COPY FROM` 명령을 실행하여 CSV 파일의 데이터를 대상 테이블에 업로드
`cqlsh COPY FROM` 명령을 실행하려면 다음 단계를 완료합니다.
1. cqlsh를 사용하여 Amazon Keyspaces에 연결합니다.
1. 다음 코드를 사용하여 키스페이스를 선택합니다.
```
USE catalog;
```
1. 쓰기 일관성을 `LOCAL_QUORUM`으로 설정합니다. 데이터 내구성을 보장하기 위해 Amazon Keyspaces는 다른 쓰기 일관성 설정을 허용하지 않습니다. 다음 코드를 확인합니다.
```
CONSISTENCY LOCAL_QUORUM;
```
1. 다음 코드 예제를 사용하여 `cqlsh COPY FROM` 구문을 준비합니다.
```
COPY book_awards FROM './keyspace.table.csv' WITH HEADER=true
AND INGESTRATE=calculated ingestrate
AND NUMPROCESSES=calculated numprocess
AND MAXBATCHSIZE=20
AND CHUNKSIZE=calculated chunksize;
```
1. 이전 단계에서 준비한 문을 실행합니다. cqlsh는 구성한 모든 설정을 다시 실행합니다.
1. 설정이 입력과 일치하는지 확인합니다. 다음 예를 참조하세요.
```
Reading options from the command line: {'chunksize': '120', 'header': 'true', 'ingestrate': '36000', 'numprocesses': '15', 'maxbatchsize': '20'}
Using 15 child processes
```
1. 다음 예와 같이 전송된 행 수와 현재 평균 비율을 검토합니다.
```
Processed: 57834 rows; Rate: 6561 rows/s; Avg. rate: 31751 rows/s
```
1. cqlsh가 데이터 업로드를 완료하면 다음 예와 같이 데이터 로드 통계 요약(읽은 파일 수, 런타임, 건너뛴 행 수)을 검토합니다.
```
15556824 rows imported from 1 files in 8 minutes and 8.321 seconds (0 skipped).
```
자습서의 마지막 단계에서는 Amazon Keyspaces에 데이터를 업로드했습니다.
**중요**
이제 데이터를 전송했으니 대상 테이블의 용량 모드 설정을 애플리케이션의 일반 트래픽 패턴에 맞게 조정합니다. 용량을 변경하기 전까지는 프로비저닝된 용량에 대해 시간당 요금이 부과됩니다.
# 문제 해결
데이터 업로드가 완료된 후 행을 건너뛰었는지 확인합니다. 이렇게 하려면 원본 CSV 파일의 소스 디렉터리로 이동하여 다음 이름의 파일을 검색합니다.
```
import_yourcsvfilename.err.timestamp.csv
```
cqlsh는 건너뛴 데이터 행을 해당 이름의 파일에 기록합니다. 파일이 소스 디렉터리에 있고 그 안에 데이터가 있는 경우 이 행은 Amazon Keyspaces에 업로드되지 않았습니다. 이러한 행을 다시 시도하려면 먼저 업로드 중에 발생한 오류가 있는지 확인하고 그에 따라 데이터를 조정합니다. 이러한 행을 다시 시도하려면 프로세스를 다시 실행하면 됩니다.
**일반적인 오류**
행이 로드되지 않는 가장 일반적인 이유는 용량 오류와 구문 분석 오류입니다.
**Amazon Keyspaces에 데이터를 업로드할 때 잘못된 요청 오류**
다음 예제의 소스 테이블에는 카운터 열이 포함되어 있으며 이로 인해 cqlsh `COPY` 명령의 배치 호출이 로그됩니다. 로그된 배치 호출은 Amazon Keyspaces에서 지원되지 않습니다.
```
Failed to import 10 rows: InvalidRequest - Error from server: code=2200 [Invalid query] message=“Only UNLOGGED Batches are supported at this time.“, will retry later, attempt 22 of 25
```
이 오류를 해결하려면 DSBulk를 사용하여 데이터를 마이그레이션합니다. 자세한 내용은 [자습서: DSBulk를 사용하여 Amazon Keyspaces에 데이터 로드](dsbulk-upload.md) 단원을 참조하십시오.
**Amazon Keyspaces에 데이터를 업로드할 때 구문 분석기 오류**
다음 예는 `ParseError`로 인해 건너뛴 행을 보여 줍니다.
```
Failed to import 1 rows: ParseError - Invalid ... –
```
이 오류를 해결하려면 가져올 데이터가 Amazon Keyspaces의 테이블 스키마와 일치하는지 확인해야 합니다. 가져오기 파일에 구문 분석 오류가 있는지 검토합니다. 오류를 격리하는 `INSERT` 문을 사용하여 단일 데이터 행을 사용해 볼 수 있습니다.
**Amazon Keyspaces에 데이터를 업로드할 때 용량 오류**
```
Failed to import 1 rows: WriteTimeout - Error from server: code=1100 [Coordinator node timed out waiting for replica nodes' responses]
message="Operation timed out - received only 0 responses." info={'received_responses': 0, 'required_responses': 2, 'write_type': 'SIMPLE', 'consistency':
'LOCAL_QUORUM'}, will retry later, attempt 1 of 100
```
Amazon Keyspaces는 처리량 용량이 충분하지 않아 쓰기 요청이 실패하는 경우를 나타내기 위해 `ReadTimeout` 및 `WriteTimeout` 예외를 사용합니다. 용량 부족 예외를 진단하는 데 도움이 되도록 Amazon Keyspaces는 Amazon CloudWatch에 `WriteThrottleEvents` 및 `ReadThrottledEvents` 지표를 게시합니다. 자세한 내용은 [Amazon CloudWatch를 사용하여 Amazon Keyspaces 모니터링](monitoring-cloudwatch.md) 단원을 참조하십시오.
**Amazon Keyspaces에 데이터를 업로드할 때 cqlsh 오류**
cqlsh 오류를 해결하는 데 도움이 되도록 `--debug` 플래그를 사용하여 실패한 명령을 다시 실행합니다.
호환되지 않는 버전의 cqlsh를 사용하는 경우 다음 오류가 표시됩니다.
```
AttributeError: 'NoneType' object has no attribute 'is_up'
Failed to import 3 rows: AttributeError - 'NoneType' object has no attribute 'is_up', given up after 1 attempts
```
다음 명령을 실행하여 올바른 cqlsh 버전이 설치되어 있는지 확인합니다.
```
cqlsh --version
```
출력에 대해 다음과 같은 내용이 표시되어야 합니다.
```
cqlsh 5.0.1
```
Windows를 사용하는 경우 `cqlsh`의 모든 인스턴스를 `cqlsh.bat`로 바꿉니다. 예를 들어 Windows에서 cqlsh 버전을 확인하려면 다음 명령을 실행합니다.
```
cqlsh.bat --version
```
cqlsh 클라이언트가 서버로부터 유형에 상관없이 연속으로 세 개의 오류를 수신한 후 Amazon Keyspaces에 대한 연결이 실패합니다. cqlsh 클라이언트가 실패하고 다음 메시지가 표시됩니다.
```
Failed to import 1 rows: NoHostAvailable - , will retry later, attempt 3 of 100
```
이 오류를 해결하려면 가져올 데이터가 Amazon Keyspaces의 테이블 스키마와 일치하는지 확인해야 합니다. 가져오기 파일에 구문 분석 오류가 있는지 검토합니다. 오류를 격리하는 INSERT 문을 사용하여 단일 데이터 행을 사용해 볼 수 있습니다.
클라이언트는 자동으로 연결 재설정을 시도합니다.
# 자습서: DSBulk를 사용하여 Amazon Keyspaces에 데이터 로드
[GitHub](https://github.com/datastax/dsbulk.git)에서 제공하는 DataStax 벌크 로더(DSBulk)를 사용하여 Apache Cassandra에서 Amazon Keyspaces로 데이터를 마이그레이션하는 방법에 대한 단계별 자습서입니다. DSBulk를 사용하면 학습 또는 테스트 목적으로 Amazon Keyspaces에 데이터세트를 업로드하는 데 유용합니다. 프로덕션 워크로드를 마이그레이션하는 방법에 대한 자세한 내용은 [오프라인 마이그레이션 프로세스: Apache Cassandra에서 Amazon Keyspaces로](migrating-offline.md) 섹션을 참조하세요. 이 자습서에서는 다음 단계를 완료합니다.
사전 조건 - 자격 증명으로 AWS 계정을 설정하고, 인증서에 대한 JKS 트러스트 스토어 파일을 생성하고,를 구성하고`cqlsh`, DSBulk를 다운로드 및 설치하고, `application.conf` 파일을 구성합니다.
1. **소스 CSV 및 대상 테이블 생성** - 소스 데이터로 CSV 파일을 준비하고 Amazon Keyspaces에서 대상 키스페이스 및 테이블을 생성합니다.
1. **데이터 준비** - CSV 파일에서 데이터를 무작위 배정하고 분석하여 평균 및 최대 행 크기를 결정합니다.
1. **처리량 용량 설정** - 데이터 크기 및 원하는 로드 시간을 기준으로 필요한 쓰기 용량 단위(WCU)를 계산하고 테이블의 프로비저닝된 용량을 구성합니다.
1. **DSBulk 설정 구성** - 인증, SSL/TLS, 일관성 수준 및 연결 풀 크기와 같은 설정을 사용하여 DSBulk 구성 파일을 생성합니다.
1. **DSBulk 로드 명령 실행** - DSBulk 로드 명령을 실행하여 CSV 파일에서 Amazon Keyspaces 테이블로 데이터를 업로드하고 진행 상황을 모니터링합니다.
**Topics**
+ [사전 조건: DSBulk를 사용하여 데이터를 업로드하기 전에 완료해야 하는 단계](dsbulk-upload-prequs.md)
+ [1단계: DSBulk를 사용하여 데이터 업로드를 위한 소스 CSV 파일 및 대상 테이블 생성](dsbulk-upload-source.md)
+ [2단계: DSBulk를 사용하여 업로드할 데이터 준비](dsbulk-upload-prepare-data.md)
+ [3단계: 대상 테이블의 처리량 용량 설정](dsbulk-upload-capacity.md)
+ [4단계: CSV 파일에서 대상 테이블로 데이터를 업로드하도록 `DSBulk` 설정 구성](dsbulk-upload-config.md)
+ [5단계: DSBulk `load` 명령을 실행하여 CSV 파일의 데이터를 대상 테이블에 업로드](dsbulk-upload-run.md)
# 사전 조건: DSBulk를 사용하여 데이터를 업로드하기 전에 완료해야 하는 단계
이 자습서를 시작하려면 먼저 다음 작업을 완료해야 합니다.
1. 아직 등록하지 않은 경우의 단계에 따라 AWS 계정에 가입합니다[설 AWS Identity and Access Management정](accessing.md#SettingUp.IAM).
1. [Amazon Keyspaces에 대한 AWS 자격 증명 생성 및 구성](access.credentials.md)의 단계에 따라 자격 증명을 생성합니다.
1. JKS 신뢰 저장소 파일을 생성합니다.
1. 다음 디지털 인증서를 다운로드하고 파일을 로컬 또는 홈 디렉터리에 저장합니다.
1. AmazonRootCA1
1. AmazonRootCA2
1. AmazonRootCA3
1. AmazonRootCA4
1. Starfield 클래스 2 루트(선택 사항 - 이전 버전과의 호환성을 위해)
인증서를 다운로드하려면 다음 명령을 사용할 수 있습니다.
```
curl -O https://www.amazontrust.com/repository/AmazonRootCA1.pem
curl -O https://www.amazontrust.com/repository/AmazonRootCA2.pem
curl -O https://www.amazontrust.com/repository/AmazonRootCA3.pem
curl -O https://www.amazontrust.com/repository/AmazonRootCA4.pem
curl -O https://certs.secureserver.net/repository/sf-class2-root.crt
```
**참고**
Amazon Keyspaces는 이전에 Starfield Class 2 CA에 고정된 TLS 인증서를 사용했습니다. AWS 는 Amazon Trust Services(Amazon Root CA 1\$14)에 따라 발급된 인증서 AWS 리전 로 모두 마이그레이션하고 있습니다. CAs 이 전환 중에 Amazon Root CAs1\$14와 Starfield 루트를 모두 신뢰하도록 클라이언트를 구성하여 모든 리전에서 호환성을 보장합니다.
1. 디지털 인증서를 trustStore 파일로 변환하고 키 스토어에 추가합니다.
```
openssl x509 -outform der -in AmazonRootCA1.pem -out temp_file.der
keytool -import -alias amazon-root-ca-1 -keystore cassandra_truststore.jks -file temp_file.der
openssl x509 -outform der -in AmazonRootCA2.pem -out temp_file.der
keytool -import -alias amazon-root-ca-2 -keystore cassandra_truststore.jks -file temp_file.der
openssl x509 -outform der -in AmazonRootCA3.pem -out temp_file.der
keytool -import -alias amazon-root-ca-3 -keystore cassandra_truststore.jks -file temp_file.der
openssl x509 -outform der -in AmazonRootCA4.pem -out temp_file.der
keytool -import -alias amazon-root-ca-4 -keystore cassandra_truststore.jks -file temp_file.der
openssl x509 -outform der -in sf-class2-root.crt -out temp_file.der
keytool -import -alias cassandra -keystore cassandra_truststore.jks -file temp_file.der
```
마지막 단계에서는 키 스토어의 암호를 생성하고 각 인증서를 신뢰해야 합니다. 대화형 명령은 다음과 같습니다.
```
Enter keystore password:
Re-enter new password:
Owner: CN=Amazon Root CA 1, O=Amazon, C=US
Issuer: CN=Amazon Root CA 1, O=Amazon, C=US
Serial number: 66c9fcf99bf8c0a39e2f0788a43e696365bca
Valid from: Tue May 26 00:00:00 UTC 2015 until: Sun Jan 17 00:00:00 UTC 2038
Certificate fingerprints:
SHA1: 8D:A7:F9:65:EC:5E:FC:37:91:0F:1C:6E:59:FD:C1:CC:6A:6E:DE:16
SHA256: 8E:CD:E6:88:4F:3D:87:B1:12:5B:A3:1A:C3:FC:B1:3D:70:16:DE:7F:57:CC:90:4F:E1:CB:97:C6:AE:98:19:6E
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#2: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
DigitalSignature
Key_CertSign
Crl_Sign
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 84 18 CC 85 34 EC BC 0C 94 94 2E 08 59 9C C7 B2 ....4.......Y...
0010: 10 4E 0A 08 .N..
]
]
Trust this certificate? [no]: yes
Certificate was added to keystore
Enter keystore password:
Owner: CN=Amazon Root CA 2, O=Amazon, C=US
Issuer: CN=Amazon Root CA 2, O=Amazon, C=US
Serial number: 66c9fd29635869f0a0fe58678f85b26bb8a37
Valid from: Tue May 26 00:00:00 UTC 2015 until: Sat May 26 00:00:00 UTC 2040
Certificate fingerprints:
SHA1: 5A:8C:EF:45:D7:A6:98:59:76:7A:8C:8B:44:96:B5:78:CF:47:4B:1A
SHA256: 1B:A5:B2:AA:8C:65:40:1A:82:96:01:18:F8:0B:EC:4F:62:30:4D:83:CE:C4:71:3A:19:C3:9C:01:1E:A4:6D:B4
Signature algorithm name: SHA384withRSA
Subject Public Key Algorithm: 4096-bit RSA key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#2: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
DigitalSignature
Key_CertSign
Crl_Sign
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: B0 0C F0 4C 30 F4 05 58 02 48 FD 33 E5 52 AF 4B ...L0..X.H.3.R.K
0010: 84 E3 66 52 ..fR
]
]
Trust this certificate? [no]: yes
Certificate was added to keystore
Enter keystore password:
Owner: CN=Amazon Root CA 3, O=Amazon, C=US
Issuer: CN=Amazon Root CA 3, O=Amazon, C=US
Serial number: 66c9fd5749736663f3b0b9ad9e89e7603f24a
Valid from: Tue May 26 00:00:00 UTC 2015 until: Sat May 26 00:00:00 UTC 2040
Certificate fingerprints:
SHA1: 0D:44:DD:8C:3C:8C:1A:1A:58:75:64:81:E9:0F:2E:2A:FF:B3:D2:6E
SHA256: 18:CE:6C:FE:7B:F1:4E:60:B2:E3:47:B8:DF:E8:68:CB:31:D0:2E:BB:3A:DA:27:15:69:F5:03:43:B4:6D:B3:A4
Signature algorithm name: SHA256withECDSA
Subject Public Key Algorithm: 256-bit EC (secp256r1) key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#2: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
DigitalSignature
Key_CertSign
Crl_Sign
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: AB B6 DB D7 06 9E 37 AC 30 86 07 91 70 C7 9C C4 ......7.0...p...
0010: 19 B1 78 C0 ..x.
]
]
Trust this certificate? [no]: yes
Certificate was added to keystore
Enter keystore password:
Owner: CN=Amazon Root CA 4, O=Amazon, C=US
Issuer: CN=Amazon Root CA 4, O=Amazon, C=US
Serial number: 66c9fd7c1bb104c2943e5717b7b2cc81ac10e
Valid from: Tue May 26 00:00:00 UTC 2015 until: Sat May 26 00:00:00 UTC 2040
Certificate fingerprints:
SHA1: F6:10:84:07:D6:F8:BB:67:98:0C:C2:E2:44:C2:EB:AE:1C:EF:63:BE
SHA256: E3:5D:28:41:9E:D0:20:25:CF:A6:90:38:CD:62:39:62:45:8D:A5:C6:95:FB:DE:A3:C2:2B:0B:FB:25:89:70:92
Signature algorithm name: SHA384withECDSA
Subject Public Key Algorithm: 384-bit EC (secp384r1) key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#2: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
DigitalSignature
Key_CertSign
Crl_Sign
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: D3 EC C7 3A 65 6E CC E1 DA 76 9A 56 FB 9C F3 86 ...:en...v.V....
0010: 6D 57 E5 81 mW..
]
]
Trust this certificate? [no]: yes
Certificate was added to keystore
Enter keystore password:
Owner: OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US
Issuer: OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US
Serial number: 0
Valid from: Tue Jun 29 17:39:16 UTC 2004 until: Thu Jun 29 17:39:16 UTC 2034
Certificate fingerprints:
SHA1: AD:7E:1C:28:B0:64:EF:8F:60:03:40:20:14:C3:D0:E3:37:0E:B5:8A
SHA256: 14:65:FA:20:53:97:B8:76:FA:A6:F0:A9:95:8E:55:90:E4:0F:CC:7F:AA:4F:B7:C2:C8:67:75:21:FB:5F:B6:58
Signature algorithm name: SHA1withRSA (weak)
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: BF 5F B7 D1 CE DD 1F 86 F4 5B 55 AC DC D7 10 C2 ._.......[U.....
0010: 0E A9 88 E7 ....
]
[OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US]
SerialNumber: [ 00]
]
#2: ObjectId: 2.5.29.19 Criticality=false
BasicConstraints:[
CA:true
PathLen:2147483647
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: BF 5F B7 D1 CE DD 1F 86 F4 5B 55 AC DC D7 10 C2 ._.......[U.....
0010: 0E A9 88 E7 ....
]
]
Warning:
The input uses the SHA1withRSA signature algorithm which is considered a security risk. This algorithm will be disabled in a future update.
Trust this certificate? [no]: yes
Certificate was added to keystore
```
1. Cassandra 쿼리 언어 쉘(cqlsh) 연결을 설정하고 [`cqlsh` 사용하여 Amazon Keyspace에 접속](programmatic.cqlsh.md)의 단계에 따라 Amazon Keyspaces에 연결할 수 있는지 확인합니다.
1. DSBulk를 다운로드하여 설치합니다.
**참고**
이 자습서에 표시된 버전은 사용 가능한 최신 버전이 아닐 수 있습니다. DSBulk를 다운로드하기 전에 [DataStax Bulk Loader 다운로드 페이지에서](https://downloads.datastax.com/#bulk-loader) 최신 버전을 확인하고 다음 명령에서 버전 번호를 적절히 업데이트합니다.
1. DSBulk를 다운로드하려면 다음 코드를 사용할 수 있습니다.
```
curl -OL https://downloads.datastax.com/dsbulk/dsbulk-1.8.0.tar.gz
```
1. 그런 후 다음 예제와 같이 tar 파일의 압축을 풀고 `PATH`에 DSBulk를 추가합니다.
```
tar -zxvf dsbulk-1.8.0.tar.gz
# add the DSBulk directory to the path
export PATH=$PATH:./dsbulk-1.8.0/bin
```
1. DSBulk에서 사용할 설정을 저장할 `application.conf` 파일을 생성합니다. `./dsbulk_keyspaces.conf`로 다음 예제를 저장할 수 있습니다. 로컬 노드에 있지 않은 경우 `localhost`를 로컬 Cassandra 클러스터의 연락처(예: DNS 이름 또는 IP 주소)로 바꿉니다. 나중에 `dsbulk load` 명령에서 지정해야 하므로 파일 이름과 경로를 기록해 둡니다.
```
datastax-java-driver {
basic.contact-points = [ "localhost"]
advanced.auth-provider {
class = software.aws.mcs.auth.SigV4AuthProvider
aws-region = us-east-1
}
}
```
1. SigV4 지원을 활성화하려면 [GitHub](https://github.com/aws/aws-sigv4-auth-cassandra-java-driver-plugin/releases/)에서 음영 처리된 `jar` 파일을 다운로드하고 다음 예와 같이 DSBulk `lib` 폴더에 저장합니다.
```
curl -O -L https://github.com/aws/aws-sigv4-auth-cassandra-java-driver-plugin/releases/download/4.0.6-shaded-v2/aws-sigv4-auth-cassandra-java-driver-plugin-4.0.6-shaded.jar
```
# 1단계: DSBulk를 사용하여 데이터 업로드를 위한 소스 CSV 파일 및 대상 테이블 생성
이 자습서에서는 이름 `keyspaces_sample_table.csv`가 있는 쉼표로 구분된 값(CSV) 파일을 데이터 마이그레이션의 원본 파일로 사용합니다. 제공된 샘플 파일에는 이름이 `book_awards`인 테이블에 대한 몇 개의 데이터 행이 포함되어 있습니다.
1. 소스 파일을 생성합니다. 다음 옵션 중 하나를 선택할 수 있습니다.
+ 다음 아카이브 파일 [samplemigration.zip](samples/samplemigration.zip)에 포함된 샘플 CSV 파일(`keyspaces_sample_table.csv`)을 다운로드합니다. 아카이브의 압축을 풀고 `keyspaces_sample_table.csv`의 경로를 기록해 둡니다.
+ Apache Cassandra 데이터베이스에 저장된 자체 데이터로 CSV 파일을 채우려면 다음 예와 같이 `dsbulk unload`를 사용하여 소스 CSV 파일을 채울 수 있습니다.
```
dsbulk unload -k mykeyspace -t mytable -f ./my_application.conf > keyspaces_sample_table.csv
```
생성한 CSV 파일이 다음 요구 사항을 충족하는지 확인합니다.
+ 첫 번째 행에는 열 이름이 포함됩니다.
+ 소스 CSV 파일의 열 이름은 대상 테이블의 열 이름과 일치합니다.
+ 데이터는 쉼표로 구분됩니다.
+ 모든 데이터 값은 유효한 Amazon Keyspaces 데이터 유형입니다. [데이터 타입](cql.elements.md#cql.data-types)을(를) 참조하세요.
1. Amazon Keyspaces에서 대상 키스페이스 및 테이블을 생성합니다.
1. `cqlsh`를 사용하여 Amazon Keyspaces에 연결하고 다음 예제의 서비스 엔드포인트, 사용자 이름 및 암호를 사용자 고유의 값으로 바꿉니다.
```
cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "111122223333" -p "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" --ssl
```
1. 다음 예제와 같이 이름 `catalog`를 사용하여 새 키스페이스를 생성합니다.
```
CREATE KEYSPACE catalog WITH REPLICATION = {'class': 'SingleRegionStrategy'};
```
1. 새 키스페이스가 사용 가능 상태가 되면 다음 코드를 사용하여 대상 테이블 `book_awards`를 생성합니다. 비동기 리소스 생성 및 리소스가 사용 가능한지 확인하는 방법에 대한 자세한 내용은 [Amazon Keyspaces에서 키스페이스 생성 상태 확인](keyspaces-create.md) 섹션을 참조하세요.
```
CREATE TABLE catalog.book_awards (
year int,
award text,
rank int,
category text,
book_title text,
author text,
publisher text,
PRIMARY KEY ((year, award), category, rank)
);
```
Apache Cassandra가 원본 데이터 소스인 경우 헤더가 일치하는 Amazon Keyspaces 대상 테이블을 생성하는 간단한 방법은 다음 문과 같이 소스 테이블에서 `CREATE TABLE` 문을 생성하는 것입니다.
```
cqlsh localhost 9042 -u "username" -p "password" --execute "DESCRIBE TABLE mykeyspace.mytable;"
```
그런 다음 Cassandra 소스 테이블의 설명과 일치하는 열 이름 및 데이터 유형을 사용하여 Amazon Keyspaces에 대상 테이블을 생성합니다.
# 2단계: DSBulk를 사용하여 업로드할 데이터 준비
효율적인 전송을 위해 소스 데이터를 준비하는 것은 2단계 프로세스입니다. 먼저 데이터를 무작위화합니다. 두 번째 단계에서는 데이터를 분석하여 적절한 `dsbulk` 파라미터 값과 필요한 테이블 설정을 결정합니다.
**데이터 무작위화**
이 `dsbulk` 명령은 CSV 파일에 나타나는 것과 동일한 순서로 데이터를 읽고 씁니다. `dsbulk` 명령을 사용하여 소스 파일을 만들면 데이터가 키 정렬된 순서대로 CSV에 기록됩니다. Amazon Keyspaces는 내부적으로 파티션 키를 사용하여 데이터를 분할합니다. Amazon Keyspaces에는 동일한 파티션 키에 대한 요청을 로드 밸런싱하는 데 도움이 되는 로직이 내장되어 있지만 순서를 무작위로 지정하면 데이터를 로드하는 것이 더 빠르고 효율적입니다. Amazon Keyspaces가 다른 파티션에 쓸 때 발생하는 내장된 로드 밸런싱을 활용할 수 있기 때문입니다.
쓰기를 파티션 전체에 균등하게 분산하려면 소스 파일의 데이터를 무작위화해야 합니다. 이 작업을 수행하는 애플리케이션을 작성하거나 [Shuf](https://en.wikipedia.org/wiki/Shuf)와 같은 오픈 소스 도구를 사용할 수 있습니다. Shuf는 Linux 배포판, macOS([homebrew](https://brew.sh)에 coreutils 설치), Windows(Windows Subsystem for Linux(WSL) 사용)에서 무료로 사용할 수 있습니다. 이 단계에서 열 이름이 있는 헤더 행이 섞이지 않도록 하려면 한 가지 추가 단계가 필요합니다.
헤더를 보존하면서 소스 파일을 무작위화하려면 다음 코드를 입력합니다.
```
tail -n +2 keyspaces_sample_table.csv | shuf -o keyspace.table.csv && (head -1 keyspaces_sample_table.csv && cat keyspace.table.csv ) > keyspace.table.csv1 && mv keyspace.table.csv1 keyspace.table.csv
```
Shuf는 `keyspace.table.csv`라는 새 CSV 파일에 데이터를 다시 씁니다. 이제 필요 없는 `keyspaces_sample_table.csv` 파일을 삭제할 수 있습니다.
**데이터 분석**
데이터를 분석하여 평균 및 최대 행 크기를 결정합니다.
이렇게 하는 이유는 다음과 같습니다.
+ 평균 행 크기는 전송할 총 데이터 양을 추정하는 데 도움이 됩니다.
+ 데이터 업로드에 필요한 쓰기 용량을 프로비저닝하려면 평균 행 크기가 필요합니다.
+ 각 행의 크기가 Amazon Keyspaces의 최대 행 크기인 1MB 미만인지 확인할 수 있습니다.
**참고**
이 할당량은 파티션 크기가 아니라 행 크기를 나타냅니다. Apache Cassandra 파티션과 달리 Amazon Keyspaces 파티션은 크기가 사실상 바인딩되지 않을 수 있습니다. 파티션 키와 클러스터링 열에는 메타데이터를 위한 추가 스토리지가 필요하며 이를 행의 원시 크기에 추가해야 합니다. 자세한 내용은 [Amazon Keyspaces에서 행 크기 추정](calculating-row-size.md) 단원을 참조하십시오.
다음 코드는 [AWK](https://en.wikipedia.org/wiki/AWK)를 사용하여 CSV 파일을 분석하고 평균 및 최대 행 크기를 인쇄합니다.
```
awk -F, 'BEGIN {samp=10000;max=-1;}{if(NR>1){len=length($0);t+=len;avg=t/NR;max=(len>max ? len : max)}}NR==samp{exit}END{printf("{lines: %d, average: %d bytes, max: %d bytes}\n",NR,avg,max);}' keyspace.table.csv
```
이 코드를 실행하면 다음과 같은 결과가 출력됩니다.
```
using 10,000 samples:
{lines: 10000, avg: 123 bytes, max: 225 bytes}
```
최대 행 크기가 1MB를 초과하지 않는지 확인합니다. 그럴 경우 행을 분할하거나 데이터를 압축하여 행 크기를 1MB 미만으로 가져와야 합니다. 이 자습서의 다음 단계에서 평균 행 크기를 사용하여 테이블의 쓰기 용량을 프로비저닝합니다.
# 3단계: 대상 테이블의 처리량 용량 설정
이 자습서에서는 설정된 시간 범위 내에서 데이터를 로드하도록 DSBulk 를 조정하는 방법을 보여 줍니다. 얼마나 많은 읽기와 쓰기를 수행하는지 미리 알고 있기 때문에 프로비저닝된 용량 모드를 사용합니다. 데이터 전송을 완료한 후에는 애플리케이션의 트래픽 패턴에 맞게 테이블의 용량 모드를 설정해야 합니다. 용량 관리에 대한 자세한 내용은 [Amazon Keyspaces(Apache Cassandra용)에서 서버리스 리소스 관리](serverless_resource_management.md) 섹션을 참조하세요.
프로비저닝된 용량 모드를 사용하면 테이블에 프로비저닝할 읽기 및 쓰기 용량을 미리 지정할 수 있습니다. 쓰기 용량은 시간당 청구되며 쓰기 용량 단위(WCU)로 측정됩니다. 각 WCU는 초당 1KB의 데이터 쓰기를 지원하기에 충분한 쓰기 용량입니다. 데이터를 로드할 때 쓰기 속도는 대상 테이블에 설정된 최대 WCU(매개 변수: `write_capacity_units`) 미만이어야 합니다.
기본적으로 테이블에 최대 40,000WCU를 프로비저닝하고 계정의 모든 테이블에 80,000WCU를 프로비저닝할 수 있습니다. 추가 용량이 필요한 경우 [Service Quotas](https://console.aws.amazon.com/servicequotas/home#!/services/cassandra/quotas)에서 할당량 증가를 요청할 수 있습니다. 할당량에 대한 자세한 내용은 [Amazon Keyspaces(Apache Cassandra용)에 대한 할당량](quotas.md) 섹션을 참조하세요.
**삽입에 필요한 WCU의 평균 수를 계산합니다.**
초당 1KB의 데이터를 삽입하려면 1WCU가 필요합니다. 360,000개의 행이 있는 CSV 파일에 1시간 내에 모든 데이터를 로드하려면 초당 100개의 행을 작성해야 합니다(360,000행/60분/60초 = 초당 100행). 각 행에 최대 1KB의 데이터가 있는 경우 초당 100개의 행을 삽입하려면 테이블에 100WCU를 프로비저닝해야 합니다. 각 행에 1.5KB의 데이터가 있는 경우 초당 한 행을 삽입하려면 WCU 두 개가 필요합니다. 따라서 초당 100개의 행을 삽입하려면 200개의 WCU를 프로비저닝해야 합니다.
초당 행 하나를 삽입하는 데 필요한 WCU 수를 결정하려면 평균 행 크기(바이트)를 1024로 나누고 가장 가까운 정수로 반올림합니다.
예를 들어 평균 행 크기가 3000바이트인 경우 초당 한 행을 삽입하려면 WCU 3개가 필요합니다.
```
ROUNDUP(3000 / 1024) = ROUNDUP(2.93) = 3 WCUs
```
**데이터 로드 시간 및 용량 계산**
이제 CSV 파일의 평균 크기와 행 수를 알았으므로 주어진 시간 동안 데이터를 로드하는 데 필요한 WCU 수와 다양한 WCU 설정을 사용하여 CSV 파일의 모든 데이터를 로드하는 데 걸리는 대략적인 시간을 계산할 수 있습니다.
예를 들어 파일의 각 행이 1KB이고 CSV 파일에 1,000,000개의 행이 있는 경우 1시간 내에 데이터를 로드하려면 해당 시간 동안 테이블에 최소 278개의 WCU를 프로비저닝해야 합니다.
```
1,000,000 rows * 1 KBs = 1,000,000 KBs
1,000,000 KBs / 3600 seconds =277.8 KBs / second = 278 WCUs
```
**프로비저닝된 용량 설정 구성**
테이블을 생성할 때 또는 `ALTER TABLE` 명령을 사용하여 테이블의 쓰기 용량 설정을 지정할 수 있습니다. 다음은 `ALTER TABLE` 명령을 사용하여 테이블의 프로비저닝된 용량 설정을 변경하는 구문입니다.
```
ALTER TABLE catalog.book_awards WITH custom_properties={'capacity_mode':{'throughput_mode': 'PROVISIONED', 'read_capacity_units': 100, 'write_capacity_units': 278}} ;
```
전체 언어 참조는 [CREATE TABLE](cql.ddl.table.md#cql.ddl.table.create) 및 [ALTER TABLE](cql.ddl.table.md#cql.ddl.table.alter) 섹션을 참조하세요.
# 4단계: CSV 파일에서 대상 테이블로 데이터를 업로드하도록 `DSBulk` 설정 구성
이 섹션에서는 Amazon Keyspaces에 데이터를 업로드하기 위해 DSBulk를 구성하는 데 필요한 단계를 간략하게 설명합니다. 구성 파일을 사용하여 DSBulk를 구성합니다. 구성 파일은 명령줄에서 직접 지정합니다.
1. Amazon Keyspaces로 마이그레이션하기 위한 DSBulk 구성 파일을 생성합니다. 이 예에서는 파일 이름 `dsbulk_keyspaces.conf`를 사용합니다. DSBulk 구성 파일에 다음 설정을 지정합니다.
1. *`PlainTextAuthProvider`* - `PlainTextAuthProvider` 클래스를 사용하여 인증 제공자를 생성합니다. `ServiceUserName` 및 `ServicePassword`는 [Amazon Keyspaces에 프로그래밍 방식으로 액세스하기 위한 자격 증명 만들기](programmatic.credentials.md)의 단계에 따라 서비스별 자격 증명을 생성할 때 얻은 사용자 이름 및 암호와 일치해야 합니다.
1. *`local-datacenter`* -의 값을 연결 AWS 리전 중인 `local-datacenter`로 설정합니다. 예를 들어 애플리케이션이 `cassandra.us-east-1.amazonaws.com`에 연결 중인 경우 로컬 데이터 센터를 `us-east-1`로 설정합니다. 사용 가능한 모든 항목은 섹션을 AWS 리전참조하세요[Amazon Keyspaces의 서비스 엔드포인트](programmatic.endpoints.md). 복제본을 피하려면 `slow-replica-avoidance`를 `false`로 설정합니다.
1. *`SSLEngineFactory`* - SSL/TLS를 구성하려면 `class = DefaultSslEngineFactory`로 클래스를 지정하는 한 줄로 구성 파일에 섹션을 추가하여 `SSLEngineFactory`를 초기화합니다. `cassandra_truststore.jks`의 경로와 이전에 만든 암호를 입력합니다.
1. *`consistency`* - 일관성 수준을 `LOCAL QUORUM`으로 설정합니다. 다른 쓰기 일관성 수준은 지원되지 않습니다. 자세한 내용은 [지원되는 Apache Cassandra 읽기 및 쓰기 일관성 수준 및 관련 비용](consistency.md) 섹션을 참조하세요.
1. Java 드라이버에서 풀당 연결 수를 구성할 수 있습니다. 이 예제에서는 `advanced.connection.pool.local.size`를 3으로 설정합니다.
다음은 전체 샘플 구성 파일입니다.
```
datastax-java-driver {
basic.contact-points = [ "cassandra.us-east-1.amazonaws.com:9142"]
advanced.auth-provider {
class = PlainTextAuthProvider
username = "ServiceUserName"
password = "ServicePassword"
}
basic.load-balancing-policy {
local-datacenter = "us-east-1"
slow-replica-avoidance = false
}
basic.request {
consistency = LOCAL_QUORUM
default-idempotence = true
}
advanced.ssl-engine-factory {
class = DefaultSslEngineFactory
truststore-path = "./cassandra_truststore.jks"
truststore-password = "my_password"
hostname-validation = false
}
advanced.connection.pool.local.size = 3
}
```
1. DSBulk `load` 명령의 파라미터를 검토합니다.
1. *`executor.maxPerSecond`* - load 명령이 초당 동시에 처리하려고 시도하는 최대 행 수입니다. 설정하지 않으면 이 설정이 -1로 비활성화됩니다.
대상 테이블에 프로비저닝한 WCU 수를 기반으로 `executor.maxPerSecond`를 설정합니다. `load` 명령의 `executor.maxPerSecond`는 제한이 아니라 대상 평균입니다. 즉, 설정한 수치를 초과할 수 있으며 종종 그럴 수도 있습니다. 버스트를 허용하고 데이터 로드 요청을 처리할 수 있는 충분한 용량을 확보하려면 `executor.maxPerSecond`를 테이블 쓰기 용량의 90% 설정합니다.
```
executor.maxPerSecond = WCUs * .90
```
이 자습서에서는 `executor.maxPerSecond`를 5로 설정했습니다.
**참고**
DSBulk 1.6.0 이상을 사용하는 경우 대신 `dsbulk.engine.maxConcurrentQueries`를 사용할 수 있습니다.
1. DSBulk `load` 명령에 대해 이러한 추가 파라미터를 구성합니다.
+ *`batch-mode`* - 이 파라미터는 파티션 키별로 작업을 그룹화하도록 시스템에 지시합니다. 핫키 시나리오와 `WriteThrottleEvents` 원인이 발생할 수 있으므로 배치 모드를 비활성화하는 것이 좋습니다.
+ *`driver.advanced.retry-policy-max-retries`* - 실패한 쿼리를 재시도할 횟수를 결정합니다. 설정하지 않은 경우 기본값은 10입니다. 필요에 따라 이 값을 조정할 수 있습니다.
+ *`driver.basic.request.timeout`* - 시스템에서 쿼리가 반환되기를 기다리는 시간(분)입니다. 설정하지 않은 경우 기본값은 "5분"입니다. 필요에 따라 이 값을 조정할 수 있습니다.
# 5단계: DSBulk `load` 명령을 실행하여 CSV 파일의 데이터를 대상 테이블에 업로드
이 자습서의 마지막 단계에서는 Amazon Keyspaces에 데이터를 업로드합니다.
DSBulk `load` 명령을 실행하려면 다음 단계를 완료합니다.
1. 다음 코드를 실행하여 csv 파일의 데이터를 Amazon Keyspaces 테이블에 업로드합니다. 이전에 생성한 애플리케이션 구성 파일의 경로를 업데이트해야 합니다.
```
dsbulk load -f ./dsbulk_keyspaces.conf --connector.csv.url keyspace.table.csv -header true --batch.mode DISABLED --executor.maxPerSecond 5 --driver.basic.request.timeout "5 minutes" --driver.advanced.retry-policy.max-retries 10 -k catalog -t book_awards
```
1. 출력에는 성공한 작업과 실패한 작업을 자세히 설명하는 로그 파일의 위치가 포함됩니다. 이 파일은 다음 디렉터리에 저장됩니다.
```
Operation directory: /home/user_name/logs/UNLOAD_20210308-202317-801911
```
1. 로그 파일 항목에는 다음 예와 같은 지표가 포함됩니다. 행 수가 csv 파일의 행 수와 일치하는지 확인합니다.
```
total | failed | rows/s | p50ms | p99ms | p999ms
200 | 0 | 200 | 21.63 | 21.89 | 21.89
```
**중요**
이제 데이터를 전송했으니 대상 테이블의 용량 모드 설정을 애플리케이션의 일반 트래픽 패턴에 맞게 조정합니다. 용량을 변경하기 전까지는 프로비저닝된 용량에 대해 시간당 요금이 부과됩니다. 자세한 내용은 [Amazon Keyspaces의 읽기/쓰기 용량 모드 구성](ReadWriteCapacityMode.md) 단원을 참조하십시오.