기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon Keyspaces(Apache Cassandra용) 문제 해결
이 안내서에서는 Amazon Keyspaces(Apache Cassandra용)를 사용할 때의 다양한 시나리오에 대한 문제 해결 단계를 다룹니다. 여기에는 일반 오류, 연결 문제, 용량 관리 문제 및 데이터 정의 언어(DDL) 오류 해결에 대한 정보가 포함됩니다.
+ **일반 오류**
+ `NoNodeAvailableException`, `NoHostAvailableException` 및 `AllNodesFailedException`과 같은 최상위 예외 문제 해결.
+ Java 드라이버 예외에서 기본 오류 격리.
+ 재시도 정책을 구현하고 연결을 올바르게 구성합니다.
+ **연결 문제**
+ `cqlsh` 또는 Apache Cassandra 클라이언트 드라이버를 사용하여 Amazon Keyspaces 엔드포인트에 연결할 때 발생하는 오류 해결.
+ VPC 엔드포인트 연결, Cassandra 스트레스 연결 및 IAM 구성 오류 문제 해결.
+ 데이터 가져오기 중 연결 손실 처리.
+ **용량 관리 오류**
+ 테이블, 파티션 및 연결과 관련된 용량 불충분 오류를 인식하고 해결합니다.
+ Amazon CloudWatch Logs에서 관련 Amazon Keyspaces 지표 모니터링.
+ 연결 및 처리량을 최적화하여 성능 개선.
+ **데이터 정의 언어(DDL) 오류**
+ 키스페이스 및 테이블을 생성, 액세스 또는 복원할 때 발생하는 오류 해결.
+ 사용자 지정 TTL(Time to Live) 설정, 열 제한 및 범위 삭제와 관련된 실패 처리.
+ 대량 삭제 워크로드에 대한 고려 사항.
IAM 액세스 관련 문제 해결 지침은 [Amazon Keyspaces ID 및 액세스 문제 해결](security_iam_troubleshoot.md)을 참조하세요. 보안 모범 사례에 대한 자세한 내용은 [Amazon Keyspaces의 보안 모범 사례](best-practices-security.md) 섹션을 참조하세요.
**Topics**
+ [일반 오류](troubleshooting.general.md)
+ [연결 오류](troubleshooting.connecting.md)
+ [용량 관리 오류](troubleshooting.serverless.md)
+ [데이터 정의 언어 오류](troubleshooting.cql.md)
# Amazon Keyspaces의 일반 오류 문제 해결
일반적인 오류가 발생합니까? 다음에서는 몇 가지 일반적인 문제와 이에 대한 해결 방법에 대해 설명합니다.
## 일반 오류
여러 가지 이유로 인해 발생할 수 있는 다음의 최상위 예외 중 하나가 발생합니다.
+ `NoNodeAvailableException`
+ `NoHostAvailableException`
+ `AllNodesFailedException`
이러한 예외는 클라이언트 드라이버에 의해 생성되며 제어 연결을 설정할 때 또는 읽기/쓰기/준비/실행/배치 요청을 수행할 때 발생할 수 있습니다.
제어 연결을 설정하는 동안 오류가 발생하면 애플리케이션에 지정된 모든 연락 지점에 연결할 수 없다는 신호입니다. 읽기/쓰기/준비/실행 쿼리를 수행하는 동안 오류가 발생하면 해당 요청에 대한 모든 재시도가 소진되었음을 나타냅니다. 기본 재시도 정책을 사용하는 경우 각 재시도는 다른 노드에서 시도됩니다.
### 최상위 Java 드라이버 예외에서 기본 오류를 분리하는 방법
이러한 일반적인 오류는 연결 문제로 인해 또는 읽기/쓰기/준비/실행 작업을 수행할 때 발생할 수 있습니다. 분산 시스템에서 일시적인 장애가 예상되어야 하며 요청을 다시 시도하여 처리해야 합니다. 연결 오류가 발생하면 Java 드라이버가 자동으로 재시도하지 않으므로 애플리케이션에서 드라이버 연결을 설정할 때 재시도 정책을 구현하는 것이 좋습니다. 연결 모범 사례에 대한 자세한 개요는 [서버리스 환경에 대한 클라이언트 드라이버 연결 최적화](connections.md) 섹션을 참조하세요.
기본적으로 Java 드라이버는 모든 요청에 대해 `idempotence`를 false로 설정하므로 Java 드라이버는 실패한 읽기/쓰기/준비 요청을 자동으로 다시 시도하지 않습니다. `idempotence`를 `true`로 설정하고 드라이버에 실패한 요청을 재시도하도록 지시하려면 몇 가지 방법을 사용할 수 있습니다. 다음은 Java 애플리케이션에서 단일 요청에 대해 프로그래밍 방식으로 멱등성을 설정하는 방법의 한 가지 예입니다.
```
Statement s = new SimpleStatement("SELECT * FROM my_table WHERE id = 1");
s.setIdempotent(true);
```
또는 다음 예제와 같이 프로그래밍 방식으로 전체 Java 애플리케이션의 기본 멱등성을 설정할 수 있습니다.
```
// Make all statements idempotent by default:
cluster.getConfiguration().getQueryOptions().setDefaultIdempotence(true);
//Set the default idempotency to true in your Cassandra configuration
basic.request.default-idempotence = true
```
또 다른 권장 사항은 애플리케이션 수준에서 재시도 정책을 생성하는 것입니다. 이 경우 애플리케이션은 `NoNodeAvailableException`을 포착하고 요청을 다시 시도해야 합니다. 지수 백오프가 10ms에서 시작하여 최대 100ms까지 작동하고 모든 재시도에 대해 총 시간이 1초인 재시도를 10회 수행하는 것이 좋습니다.
또 다른 옵션은 [Github](https://github.com/aws-samples/amazon-keyspaces-java-driver-helpers/blob/main/src/main/java/com/aws/ssa/keyspaces/retry/AmazonKeyspacesExponentialRetryPolicy.java)에서 제공하는 Java 드라이버 연결을 설정할 때 Amazon Keyspaces 지수 재시도 정책을 적용하는 것입니다.
기본 재시도 정책을 사용할 때 둘 이상의 노드에 대한 연결이 설정되었는지 확인합니다. Amazon Keyspaces에서 다음 쿼리를 사용하여 쿼리를 수행할 수 있습니다.
```
SELECT * FROM system.peers;
```
이 쿼리에 대한 응답이 비어 있는 경우 Amazon Keyspaces용 단일 노드로 작업하고 있음을 나타냅니다. 기본 재시도 정책을 사용하는 경우 기본 재시도는 항상 다른 노드에서 발생하므로 재시도가 발생하지 않습니다. VPC 엔드포인트를 통한 연결 설정에 대한 자세한 내용은 [Amazon Keyspaces에서 VPC 엔드포인트를 통해 연결을 구성하는 방법](connections.md#connections.VPCendpoints) 섹션을 참조하세요.
Datastax 4.x Cassandra 드라이버를 사용하여 Amazon Keyspaces에 연결하는 방법을 보여주는 단계별 자습서는 [Apache Cassandra용 4.x DataStax Java 드라이버와 SigV4 인증 플러그인을 사용하여 Amazon Keyspaces에 접속하는 단계별 튜토리얼](using_java_driver.md#java_tutorial.SigV4) 섹션을 참조하세요.
# Amazon Keyspaces의 연결 오류 문제 해결
연결에 문제가 있으신가요? 다음에서는 몇 가지 일반적인 문제와 이에 대한 해결 방법에 대해 설명합니다.
## Amazon Keyspaces 엔드포인트에 연결하는 오류
연결 실패 및 연결 오류로 인해 다른 오류 메시지가 표시될 수 있습니다. 다음 섹션에서는 가장 일반적인 시나리오를 다룹니다.
**Topics**
+ [cqlsh를 사용하여 Amazon Keyspaces에 연결할 수 없음](#troubleshooting.connection.cqlsh)
+ [Cassandra 클라이언트 드라이버를 사용하여 Amazon Keyspaces에 연결할 수 없음](#troubleshooting.connection.driver)
### cqlsh를 사용하여 Amazon Keyspaces에 연결할 수 없음
**cqlsh를 사용하여 Amazon Keyspaces 엔드포인트에 연결하려고 하는데 `Connection error`와 함께 연결이 실패합니다.**
Amazon Keyspaces 테이블에 연결하려고 하는데 cqlsh가 제대로 구성되지 않은 경우 연결이 실패합니다. 다음 섹션에서는 cqlsh를 사용하여 연결을 설정하려고 할 때 연결 오류가 발생하는 가장 일반적인 구성 문제의 예를 제공합니다.
**참고**
VPC에서 Amazon Keyspaces에 연결하려는 경우 추가 권한이 필요합니다. VPC 엔드포인트를 사용하여 연결을 성공적으로 구성하려면 [자습서: 인터페이스 VPC 엔드포인트를 사용하여 Amazon Keyspaces에 연결](vpc-endpoints-tutorial.md)의 단계를 따르세요.
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하는데 연결 `timed out` 오류가 발생합니다.**
올바른 포트를 제공하지 않은 경우 다음과 같은 오류가 발생할 수 있습니다.
```
# cqlsh cassandra.us-east-1.amazonaws.com 9140 -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.199': error(None, "Tried connecting to [('3.234.248.199', 9140)]. Last error: timed out")})
```
이 문제를 해결하려면 연결에 포트 9142를 사용하고 있는지 확인합니다.
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하는데 `Name or service not known` 오류가 발생합니다.**
철자가 틀렸거나 존재하지 않는 엔드포인트를 사용한 경우가 이에 해당할 수 있습니다. 다음 예에서는 엔드포인트 이름의 철자가 틀립니다.
```
# cqlsh cassandra.us-east-1.amazon.com 9142 -u "USERNAME" -p "PASSWORD" --ssl
Traceback (most recent call last):
File "/usr/bin/cqlsh.py", line 2458, in >module>
main(*read_options(sys.argv[1:], os.environ))
File "/usr/bin/cqlsh.py", line 2436, in main
encoding=options.encoding)
File "/usr/bin/cqlsh.py", line 484, in __init__
load_balancing_policy=WhiteListRoundRobinPolicy([self.hostname]),
File "/usr/share/cassandra/lib/cassandra-driver-internal-only-3.11.0-bb96859b.zip/cassandra-driver-3.11.0-bb96859b/cassandra/policies.py", line 417, in __init__
socket.gaierror: [Errno -2] Name or service not known
```
퍼블릭 엔드포인트를 사용하여 연결할 때 이 문제를 해결하려면 [Amazon Keyspaces의 서비스 엔드포인트](programmatic.endpoints.md)에서 사용 가능한 엔드포인트를 선택하고 엔드포인트 이름에 오류가 없는지 확인합니다. VPC 엔드포인트를 사용하여 연결하는 경우 cqlsh 구성에서 VPC 엔드포인트 정보가 올바른지 확인합니다.
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하지만 `OperationTimedOut` 오류를 수신합니다.**
Amazon Keyspaces에서는 강력한 보안을 보장하기 위해 연결에 SSL을 활성화해야 합니다. 다음 오류를 받는 경우 SSL 매개 변수가 누락될 수 있습니다.
```
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD"
Connection error: ('Unable to connect to any servers', {'3.234.248.192': OperationTimedOut('errors=Timed out creating connection (5 seconds), last_host=None',)})
#
```
이 문제를 해결하려면 cqlsh 연결 명령에 다음 플래그를 추가합니다.
```
--ssl
```
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하는데 `SSL transport factory requires a valid certfile to be specified` 오류를 수신합니다.**
이 경우 SSL/TLS 인증서 경로가 누락되어 다음 오류가 발생합니다.
```
# cat .cassandra/cqlshrc
[connection]
port = 9142
factory = cqlshlib.ssl.ssl_transport_factory
#
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Validation is enabled; SSL transport factory requires a valid certfile to be specified. Please provide path to the certfile in [ssl] section as 'certfile' option in /root/.cassandra/cqlshrc (or use [certfiles] section) or set SSL_CERTFILE environment variable.
#
```
이 문제를 해결하려면 컴퓨터에 있는 certfile에 경로를 추가합니다. 자세한 내용은 [TLS에 대한 `cqlsh` 연결을 수동으로 구성하는 방법](programmatic.cqlsh.md#encrypt_using_tls) 단원을 참조하십시오.
```
certfile = path_to_file/keyspaces-bundle.pem
```
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하지만 `No such file or directory` 오류를 수신합니다.**
컴퓨터에 있는 인증서 파일의 경로가 잘못되어 다음과 같은 오류가 발생할 수 있습니다.
```
# cat .cassandra/cqlshrc
[connection]
port = 9142
factory = cqlshlib.ssl.ssl_transport_factory
[ssl]
validate = true
certfile = /root/wrong_path/keyspaces-bundle.pem
#
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.192': IOError(2, 'No such file or directory')})
#
```
이 문제를 해결하려면 컴퓨터에 있는 certfile에 대한 경로가 올바른지 확인합니다. 자세한 내용은 [TLS에 대한 `cqlsh` 연결을 수동으로 구성하는 방법](programmatic.cqlsh.md#encrypt_using_tls) 단원을 참조하십시오.
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하지만 `[X509] PEM lib` 오류를 수신합니다.**
SSL/TLS 인증서 `pem` 파일이 유효하지 않아 다음 오류가 발생할 수 있습니다.
```
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.241': error(185090057, u"Tried connecting to [('3.234.248.241', 9142)]. Last error: [X509] PEM lib (_ssl.c:3063)")})
#
```
이 문제를 해결하려면 필요한 디지털 인증서를 다운로드했는지 확인합니다. 자세한 내용은 [TLS에 대한 `cqlsh` 연결을 수동으로 구성하는 방법](programmatic.cqlsh.md#encrypt_using_tls) 단원을 참조하십시오.
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하지만 `unknown` SSL 오류를 수신합니다.**
SSL/TLS 인증서 `pem` 파일이 비어 있는 경우 다음과 같은 오류가 발생할 수 있습니다.
```
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.220': error(0, u"Tried connecting to [('3.234.248.220', 9142)]. Last error: unknown error (_ssl.c:3063)")})
#
```
이 문제를 해결하려면 필요한 디지털 인증서를 다운로드했는지 확인합니다. 다음 주제의 단계를 사용하여 이를 확인할 수 있습니다[TLS에 대한 `cqlsh` 연결을 수동으로 구성하는 방법](programmatic.cqlsh.md#encrypt_using_tls).
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하지만 `SSL: CERTIFICATE_VERIFY_FAILED` 오류를 수신합니다.**
SSL/TLS 인증서 파일을 확인할 수 없어 다음 오류가 발생하는 경우가 이에 해당할 수 있습니다.
```
Connection error: ('Unable to connect to any servers', {'3.234.248.223': error(1, u"Tried connecting to [('3.234.248.223', 9142)]. Last error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:727)")})
```
이 문제를 해결하려면 필요한 디지털 인증서를 다운로드했는지 확인합니다. 다음 주제의 단계를 사용하여 이를 확인할 수 있습니다[TLS에 대한 `cqlsh` 연결을 수동으로 구성하는 방법](programmatic.cqlsh.md#encrypt_using_tls).
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하지만 `Last error: timed out` 오류를 수신합니다.**
Amazon EC2 보안 그룹에서 Amazon Keyspaces에 대한 아웃바운드 규칙을 구성하지 않은 경우일 수 있으며 그 결과 다음 오류가 발생합니다.
```
# cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.206': error(None, "Tried connecting to [('3.234.248.206', 9142)]. Last error: timed out")})
#
```
이 문제가가 아닌 Amazon EC2 인스턴스의 구성으로 인해 발생하는`cqlsh`지 확인하려면 AWS CLI예를 들어 다음 명령을 사용하여를 사용하여 키스페이스에 연결해 볼 수 있습니다.
```
aws keyspaces list-tables --keyspace-name 'my_keyspace'
```
이 명령도 시간 초과되면 Amazon EC2 인스턴스가 올바르게 구성되지 않은 것입니다.
Amazon Keyspaces에 액세스할 수 있는 충분한 권한이 있는지 확인하려면 AWS CloudShell 를 사용하여에 연결할 수 있습니다`cqlsh`. 해당 연결이 설정되면 Amazon EC2 인스턴스를 구성해야 합니다.
이 문제를 해결하려면 Amazon EC2 인스턴스에 Amazon Keyspaces로의 트래픽을 허용하는 아웃바운드 규칙이 있는지 확인하세요. 이 경우가 아니라면 EC2 인스턴스의 새 보안 그룹을 생성하고 Amazon Keyspaces 리소스로의 아웃바운드 트래픽을 허용하는 규칙을 추가해야 합니다. Amazon Keyspaces에 대한 트래픽을 허용하도록 아웃바운드 규칙을 업데이트하려면 **유형** 드롭다운 메뉴에서 **CQLSH/CASSANDRA**를 선택합니다.
아웃바운드 트래픽 규칙으로 새 보안 그룹을 생성한 후 인스턴스에 추가해야 합니다. 인스턴스를 선택한 다음 **작업**, **보안**, **보안 그룹 변경**을 차례로 선택합니다. 아웃바운드 규칙으로 새 보안 그룹을 추가하되 기본 그룹도 계속 사용할 수 있는지 확인합니다.
EC2 아웃바운드 규칙을 보고 편집하는 방법에 대한 자세한 내용은 [Amazon EC2 사용 설명서의 보안 그룹에 규칙 추가](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-security-groups.html#adding-security-group-rule)를 참조하세요.
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하지만 `Unauthorized` 오류를 수신합니다.**
이는 IAM 사용자 정책에서 Amazon Keyspaces 권한이 누락되어 다음 오류가 발생하는 경우일 수 있습니다.
```
# cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "testuser-at-12345678910" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.241': AuthenticationFailed('Failed to authenticate to 3.234.248.241: Error from server: code=2100 [Unauthorized] message="User arn:aws:iam::12345678910:user/testuser has no permissions."',)})
#
```
이 문제를 해결하려면 IAM 사용자 `testuser-at-12345678910`에게 Amazon Keyspaces에 액세스할 권한이 있는지 확인합니다. Amazon Keyspaces에 액세스 권한을 부여하는 IAM 정책의 예는 [Amazon Keyspaces ID 기반 정책 예제](security_iam_id-based-policy-examples.md) 섹션을 참조하세요.
IAM 액세스 관련 문제 해결 지침은 [Amazon Keyspaces ID 및 액세스 문제 해결](security_iam_troubleshoot.md) 섹션을 참조하세요.
**cqlsh를 사용하여 Amazon Keyspaces에 연결하려고 하지만 `Bad credentials` 오류를 수신합니다.**
사용자 이름이나 암호가 잘못되어 다음 오류가 발생하는 경우가 이에 해당할 수 있습니다.
```
# cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.248': AuthenticationFailed('Failed to authenticate to 3.234.248.248: Error from server: code=0100 [Bad credentials] message="Provided username USERNAME and/or password are incorrect"',)})
#
```
이 문제를 해결하려면 코드의 *사용자 이름* 및 *암호*가 [서비스별 보안 인증](programmatic.credentials.ssc.md)을 생성할 때 얻은 사용자 이름 및 암호와 일치하는지 확인합니다.
**중요**
cqlsh로 연결하려고 할 때 오류가 계속 표시되면 `--debug` 옵션을 사용하여 명령을 다시 실행하고 지원에 문의할 때 자세한 출력을 포함합니다.
### Cassandra 클라이언트 드라이버를 사용하여 Amazon Keyspaces에 연결할 수 없음
다음 섹션에서는 Cassandra 클라이언트 드라이버로 연결할 때 발생하는 가장 일반적인 오류를 보여 줍니다.
**DataStax Java 드라이버를 사용하여 Amazon Keyspaces 테이블에 연결하려고 하지만 `NodeUnavailableException` 오류를 수신합니다.**
요청을 시도하는 연결이 끊어지면 다음과 같은 오류가 발생합니다.
```
[com.datastax.oss.driver.api.core.NodeUnavailableException: No connection was available to Node(endPoint=vpce-22ff22f2f22222fff-aa1bb234.cassandra.us-west-2.vpce.amazonaws.com/11.1.1111.222:9142, hostId=1a23456b-c77d-8888-9d99-146cb22d6ef6, hashCode=123ca4567)]
```
이 문제를 해결하려면 하트비트 값을 확인하여 더 높으면 30초로 낮춥니다.
```
advanced.heartbeat.interval = 30 seconds
```
그런 다음 관련 제한 시간을 찾아 값이 5초 이상으로 설정되어 있는지 확인합니다.
```
advanced.connection.init-query-timeout = 5 seconds
```
**드라이버 및 SigV4 플러그인을 사용하여 Amazon Keyspaces 테이블에 연결하려고 하지만 `AttributeError` 오류를 수신합니다.**
보안 인증이 올바르게 구성되지 않은 경우 다음 오류가 발생합니다.
```
cassandra.cluster.NoHostAvailable: (‘Unable to connect to any servers’,
{‘44.234.22.154:9142’: AttributeError(“‘NoneType’ object has no attribute ‘access_key’“)})
```
이 문제를 해결하려면 SigV4 플러그인을 사용할 때 IAM 사용자 또는 역할과 관련된 보안 인증을 전달하고 있는지 확인합니다. SigV4 플러그인에는 다음 보안 인증이 필요합니다.
+ `AWS_ACCESS_KEY_ID` - IAM 사용자 또는 역할과 연결된 AWS 액세스 키를 지정합니다.
+ `AWS_SECRET_ACCESS_KEY` - 액세스 키와 연결된 보안 키를 지정합니다. 이는 액세스 키에 대한 기본적인 "암호"입니다.
액세스 키와 SigV4 플러그인에 대한 자세한 내용은 [Amazon Keyspaces에 대한 AWS 자격 증명 생성 및 구성](access.credentials.md) 섹션을 참조하세요.
**드라이버를 사용하여 Amazon Keyspaces 테이블에 연결하려고 하지만 `PartialCredentialsError` 오류를 수신합니다.**
`AWS_SECRET_ACCESS_KEY`가 누락된 경우 다음 오류가 발생할 수 있습니다.
```
cassandra.cluster.NoHostAvailable: (‘Unable to connect to any servers’, {‘44.234.22.153:9142’:
PartialCredentialsError(‘Partial credentials found in config-file, missing: aws_secret_access_key’)})
```
이 문제를 해결하려면 SigV4 플러그인을 사용할 때 `AWS_ACCESS_KEY_ID` 및 `AWS_SECRET_ACCESS_KEY`를 모두 전달하고 있는지 확인합니다. 액세스 키와 SigV4 플러그인에 대한 자세한 내용은 [Amazon Keyspaces에 대한 AWS 자격 증명 생성 및 구성](access.credentials.md) 섹션을 참조하세요.
**드라이버를 사용하여 Amazon Keyspaces 테이블에 연결하려고 하지만 `Invalid signature` 오류를 수신합니다.**
이는 서명에 필요한 구성 요소가 잘못되었거나 세션에 올바르게 정의되지 않았기 때문일 수 있습니다.
+ `AWS_ACCESS_KEY_ID`
+ `AWS_SECRET_ACCESS_KEY`
+ `AWS_DEFAULT_REGION`
다음 오류는 잘못된 액세스 키의 예입니다.
```
cassandra.cluster.NoHostAvailable: (‘Unable to connect to any servers’, {‘11.234.11.234:9142’:
AuthenticationFailed(‘Failed to authenticate to 11.234.11.234:9142: Error from server: code=0100
[Bad credentials] message=“Authentication failure: Invalid signature”’)})
```
이 문제를 해결하려면 SigV4 플러그인이 Amazon Keyspaces에 액세스하도록 액세스 키와가 올바르게 구성 AWS 리전 되었는지 확인합니다. 액세스 키와 SigV4 플러그인에 대한 자세한 내용은 [Amazon Keyspaces에 대한 AWS 자격 증명 생성 및 구성](access.credentials.md) 섹션을 참조하세요.
#### VPC 엔드포인트 연결이 제대로 작동하지 않음
**VPC 엔드포인트를 사용하여 Amazon Keyspaces에 연결하려고 하는데 토큰 맵 오류가 발생하거나 처리량이 낮습니다.**
VPC 엔드포인트 연결이 올바르게 구성되지 않은 경우가 이에 해당할 수 있습니다.
이러한 문제를 해결하려면 다음 구성 세부 정보를 확인합니다. 단계별 자습서를 따라 Amazon Keyspaces의 인터페이스 VPC 엔드포인트를 통한 연결을 구성하는 방법을 알아보려면 [자습서: 인터페이스 VPC 엔드포인트를 사용하여 Amazon Keyspaces에 연결](vpc-endpoints-tutorial.md) 섹션을 참조하세요.
1. Amazon Keyspaces에 연결하는 데 사용되는 IAM 엔티티가 다음 예와 같이 사용자 테이블에 대한 읽기/쓰기 액세스 권한과 시스템 테이블에 대한 읽기 권한을 가지고 있는지 확인합니다.
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"cassandra:Select",
"cassandra:Modify"
],
"Resource":[
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/mykeyspace/table/mytable",
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/system*"
]
}
]
}
```
1. 다음 예와 같이 Amazon Keyspaces에 연결하는 데 사용되는 IAM 엔티티에 Amazon EC2 인스턴스의 VPC 엔드포인트 정보에 액세스하는 데 필요한 읽기 권한이 있는지 확인합니다.
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"ListVPCEndpoints",
"Effect":"Allow",
"Action":[
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeVpcEndpoints"
],
"Resource":"*"
}
]
}
```
**참고**
관리형 정책 `AmazonKeyspacesReadOnlyAccess_v2` 및 `AmazonKeyspacesFullAccess`에는 Amazon Keyspaces가 Amazon EC2 인스턴스에 액세스하여 사용 가능한 인터페이스 VPC 엔드포인트에 대한 정보를 읽을 수 있도록 하는 데 필요한 권한이 포함되어 있습니다.
VPC 엔드포인트에 대한 자세한 내용은 [Amazon Keyspaces에 인터페이스 VPC 엔드포인트 사용](vpc-endpoints.md#using-interface-vpc-endpoints) 섹션을 참조하세요.
1. 이 예와 같이 Java 드라이버의 SSL 구성이 호스트 이름 검증을 false로 설정하는지 확인합니다.
```
hostname-validation = false
```
드라이버 구성에 대한 자세한 내용은 [2단계: 드라이버 구성](using_java_driver.md#java_tutorial.driverconfiguration) 섹션을 참조하세요.
1. VPC 엔드포인트가 올바르게 구성되었는지 확인하기 위해 VPC *내에서* 다음 문을 실행할 수 있습니다.
**참고**
로컬 개발자 환경 또는 Amazon Keyspaces CQL 편집기는 퍼블릭 엔드포인트를 사용하기 때문에 이 구성을 확인하기 위해 사용할 수 없습니다.
```
SELECT peer FROM system.peers;
```
출력은이 예제와 비슷해야 하며 VPC 설정 및 AWS 리전에 따라 IPv4 네트워크에서 연결할 때 프라이빗 IPv4 주소가 있는 2\$16개의 노드를 반환해야 합니다.
```
peer
---------------
192.0.2.0.15
192.0.2.0.24
192.0.2.0.13
192.0.2.0.7
192.0.2.0.8
(5 rows)
```
#### `cassandra-stress`를 사용하여 연결할 수 없음
**`cassandra-stress` 명령을 사용하여 Amazon Keyspaces에 연결하려고 하지만 `SSL context` 오류를 수신합니다.**
이 문제는 Amazon Keyspaces에 연결하려고 하지만 trustStore가 제대로 설정되지 않은 경우 발생합니다. Amazon Keyspaces에서는 클라이언트와의 연결을 보호하는 데 도움이 되는 전송 계층 보안(TLS)을 사용해야 합니다.
이 경우 다음 오류가 표시됩니다.
```
Error creating the initializing the SSL Context
```
이 문제를 해결하려면 이 주제 [시작하기 전 준비 사항](using_java_driver.md#using_java_driver.BeforeYouBegin)에 나와 있는 대로 trustStore를 설정하는 지침을 따르세요.
trustStore가 설정되면 다음 명령을 사용하여 연결할 수 있어야 합니다.
```
./cassandra-stress user profile=./profile.yaml n=100 "ops(insert=1,select=1)" cl=LOCAL_QUORUM -node "cassandra.eu-north-1.amazonaws.com" -port native=9142 -transport ssl-alg="PKIX" truststore="./cassandra_truststore.jks" truststore-password="trustStore_pw" -mode native cql3 user="user_name" password="password"
```
#### IAM ID를 사용하여 연결할 수 없음
**IAM ID를 사용하여 Amazon Keyspaces 테이블에 연결하려고 하지만 `Unauthorized` 오류를 수신합니다.**
정책을 구현하고 사용자에게 필요한 권한을 먼저 부여하지 않고 IAM ID(예: IAM 사용자)를 사용하여 Amazon Keyspaces 테이블에 연결하려고 하면 이 오류가 발생합니다.
이 경우 다음 오류가 표시됩니다.
```
Connection error: ('Unable to connect to any servers', {'3.234.248.202': AuthenticationFailed('Failed to authenticate to 3.234.248.202:
Error from server: code=2100 [Unauthorized] message="User arn:aws:iam::1234567890123:user/testuser has no permissions."',)})
```
이 문제를 해결하려면 IAM 사용자의 권한을 확인합니다. 표준 드라이버를 사용하여 연결하려면 사용자는 최소한 시스템 테이블에 대한 `SELECT` 액세스 권한을 가지고 있어야 합니다. 이는 대부분의 드라이버가 연결 시 시스템 키스페이스/테이블을 읽기 때문입니다.
Amazon Keyspaces 시스템 및 사용자 테이블에 액세스 권한을 부여하는 IAM 정책의 예는 [Amazon Keyspaces 테이블에 액세스](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-access-one-table) 섹션을 참조하세요.
IAM과 관련된 문제 해결 섹션을 검토하려면 [Amazon Keyspaces ID 및 액세스 문제 해결](security_iam_troubleshoot.md) 섹션을 참조하세요.
#### cqlsh를 사용하여 데이터를 가져오려고 하는데 Amazon Keyspaces 테이블에 대한 연결이 끊어졌습니다.
**cqlsh를 사용하여 Amazon Keyspaces에 데이터를 업로드하려고 하지만 연결 오류를 수신합니다.**
cqlsh 클라이언트가 서버로부터 유형에 상관없이 연속으로 세 개의 오류를 수신한 후 Amazon Keyspaces에 대한 연결이 실패합니다. cqlsh 클라이언트가 실패하고 다음 메시지가 표시됩니다.
```
Failed to import 1 rows: NoHostAvailable - , will retry later, attempt 3 of 100
```
이 오류를 해결하려면 가져올 데이터가 Amazon Keyspaces의 테이블 스키마와 일치하는지 확인해야 합니다. 가져오기 파일에 구문 분석 오류가 있는지 검토합니다. 오류를 격리하는 INSERT 문을 사용하여 단일 데이터 행을 사용해 볼 수 있습니다.
클라이언트는 자동으로 연결 재설정을 시도합니다.
# Amazon Keyspaces의 용량 관리 오류 문제 해결
서버리스 용량에 문제가 있으신가요? 다음에서는 몇 가지 일반적인 문제와 이에 대한 해결 방법에 대해 설명합니다.
## 서버리스 용량 오류
이 섹션에서는 서버리스 용량 관리와 관련된 오류를 인식하는 방법과 해결 방법을 설명합니다. 예를 들어 애플리케이션이 프로비저닝된 처리량 용량을 초과하면 용량 부족 이벤트가 관찰될 수 있습니다.
Apache Cassandra는 여러 노드에서 실행되도록 설계된 클러스터 기반 소프트웨어이므로 처리량 용량과 같은 서버리스 기능과 관련된 예외 메시지가 없습니다. 대부분의 드라이버는 Apache Cassandra에서 사용할 수 있는 오류 코드만 이해하므로 Amazon Keyspaces는 호환성을 유지하기 위해 동일한 오류 코드 세트를 사용합니다.
Cassandra 오류를 기본 용량 이벤트에 매핑하려면 Amazon CloudWatch를 사용하여 관련 Amazon Keyspaces 지표를 모니터링할 수 있습니다. 클라이언트 측 오류를 초래하는 용량 부족 이벤트는 이벤트를 일으킨 리소스에 따라 다음 세 그룹으로 분류할 수 있습니다.
+ **테이블** - 테이블에 대해 **프로비저닝된** 용량 모드를 선택했는데 애플리케이션이 프로비저닝된 처리량을 초과하는 경우 용량 부족 오류가 발생할 수 있습니다. 자세한 내용은 [Amazon Keyspaces의 읽기/쓰기 용량 모드 구성](ReadWriteCapacityMode.md) 단원을 참조하십시오.
+ **파티션** - 특정 파티션의 트래픽이 3,000RCU 또는 1,000WCU를 초과하는 경우 용량 부족 이벤트가 발생할 수 있습니다. 트래픽을 파티션 전체에 균일하게 분배하는 것이 가장 좋습니다. 자세한 내용은 [데이터 모델링 모범 사례: 데이터 모델 설계를 위한 권장 사항](data-modeling.md) 단원을 참조하십시오.
+ **연결** - 연결당 초당 최대 작업 수의 할당량을 초과하면 처리량이 부족해질 수 있습니다. 처리량을 늘리려면 드라이버로 연결을 구성할 때 기본 연결 수를 늘릴 수 있습니다.
Amazon Keyspaces에 대한 연결을 구성하는 방법은 [Amazon Keyspaces에서 연결을 구성하는 방법](connections.md#connections.howtoconfigure) 섹션을 참조하세요. VPC 엔드포인트를 통한 연결 최적화에 대한 자세한 내용은 [Amazon Keyspaces에서 VPC 엔드포인트를 통해 연결을 구성하는 방법](connections.md#connections.VPCendpoints) 섹션을 참조하세요.
클라이언트 측 오류를 반환하는 용량 부족 이벤트를 일으키는 리소스를 확인하려면 Amazon Keyspaces 콘솔에서 대시보드를 확인할 수 있습니다. 기본적으로 콘솔은 테이블의 **용량** 탭에 있는 **용량 및 관련 지표** 섹션에서 가장 일반적인 용량 및 트래픽 관련 CloudWatch 지표를 집계하여 제공합니다.
Amazon CloudWatch를 사용하여 자체 대시보드를 생성하려면 다음 Amazon Keyspaces 지표를 확인합니다.
+ `PerConnectionRequestRateExceeded` - 연결당 요청 속도에 대한 할당량을 초과하는 Amazon Keyspaces에 대한 요청입니다. Amazon Keyspaces에 대한 각 클라이언트 연결은 초당 최대 3000개의 CQL 요청을 지원할 수 있습니다. 여러 연결을 생성하여 초당 3000개 이상의 요청을 수행할 수 있습니다.
+ `ReadThrottleEvents` - 테이블의 읽기 용량을 초과하는 Amazon Keyspaces에 대한 요청입니다.
+ `StoragePartitionThroughputCapacityExceeded` - 파티션의 처리량 용량을 초과하는 Amazon Keyspaces 스토리지 파티션에 대한 요청입니다. Amazon Keyspaces 스토리지 파티션은 초당 최대 1000 WCU/WRU 및 초당 3000 RCU/RRU를 지원할 수 있습니다. 이러한 예외를 완화하려면 데이터 모델을 검토하여 더 많은 파티션에 읽기/쓰기 트래픽을 분산하는 것이 좋습니다.
+ `WriteThrottleEvents` - 테이블의 읽기 용량을 초과하는 Amazon Keyspaces에 대한 요청입니다.
CloudWatch에 대한 자세한 내용은 [Amazon CloudWatch를 사용하여 Amazon Keyspaces 모니터링](monitoring-cloudwatch.md) 섹션을 참조하세요. Amazon Keyspaces에 대한 사용 가능한 모든 CloudWatch 지표 목록은 [Amazon Keyspaces 지표 및 차원](metrics-dimensions.md) 섹션을 참조하세요.
**참고**
Amazon Keyspaces에서 일반적으로 관찰되는 모든 지표를 보여 주는 사용자 지정 대시보드를 시작하려면 [AWS 샘플](https://github.com/aws-samples/amazon-keyspaces-cloudwatch-cloudformation-templates) 리포지토리의 GitHub에 있는 사전 구축된 CloudWatch 템플릿을 사용할 수 있습니다.
**Topics**
+ [클라이언트 측 오류](#troubleshooting.serverless.clientside)
+ [데이터 가져오는 중 쓰기 제한 시간 오류](#troubleshooting.serverless.writetimeout)
+ [키스페이스 또는 테이블 스토리지 크기](#troubleshooting.serverless.storagesize)
### 클라이언트 드라이버로부터 `NoHostAvailable` 용량 부족 오류가 발생했습니다.
**테이블에 대한 `Read_Timeout` 또는 `Write_Timeout` 예외가 표시됩니다.**
용량이 충분하지 않은 상태에서 Amazon Keyspaces 테이블에 반복적으로 쓰거나 읽으려고 하면 드라이버와 관련된 클라이언트 측 오류가 발생할 수 있습니다.
CloudWatch를 사용하여 테이블에 대한 프로비저닝된 처리량 지표와 실제 처리량 지표 및 용량 부족 이벤트를 모니터링할 수 있습니다. 예를 들어 처리량 용량이 충분하지 않은 읽기 요청은 `Read_Timeout` 예외와 함께 실패하고 `ReadThrottleEvents` 지표에 게시됩니다. 처리량 용량이 충분하지 않은 쓰기 요청은 `Write_Timeout` 예외와 함께 실패하고 `WriteThrottleEvents` 지표에 게시됩니다. 이러한 지표에 대한 자세한 내용은 [Amazon Keyspaces 지표 및 차원](metrics-dimensions.md) 섹션을 참조하세요.
문제를 해결하려면 다음 옵션을 고려하세요.
+ 애플리케이션이 소비할 수 있는 최대 처리량 용량인 테이블에 대한 *프로비저닝된 처리량*을 늘립니다. 자세한 내용은 [읽기 용량 단위 및 쓰기 용량 단위](ReadWriteCapacityMode.Provisioned.md#ReadWriteCapacityMode.Provisioned.Units) 단원을 참조하십시오.
+ 자동 크기 조정을 통해 서비스가 사용자 대신 처리량 용량을 관리하도록 합니다. 자세한 내용은 [Amazon Keyspaces 오토 스케일링으로 처리량 용량 자동 관리](autoscaling.md) 단원을 참조하십시오.
+ 테이블에 **온디맨드** 용량 모드를 선택했습니다. 자세한 내용은 [온디맨드 용량 모드 구성](ReadWriteCapacityMode.OnDemand.md) 단원을 참조하십시오.
계정의 기본 용량 할당량을 늘려야 하는 경우 [Amazon Keyspaces(Apache Cassandra용)에 대한 할당량](quotas.md) 섹션을 참조하세요.
**파티션 용량 초과와 관련된 오류가 표시됩니다.**
오류가 표시되면 `StoragePartitionThroughputCapacityExceeded` 파티션 용량이 일시적으로 초과된 것입니다. 이는 적응형 용량 또는 온디맨드 용량으로 자동 처리될 수 있습니다. 이러한 오류를 완화하려면 데이터 모델을 검토하여 더 많은 파티션에 읽기/쓰기 트래픽을 분산하는 것이 좋습니다. Amazon Keyspaces 스토리지 파티션은 초당 최대 1000 WCU/WRU 및 초당 3000 RCU/RRU를 지원할 수 있습니다. 읽기/쓰기 트래픽을 더 많은 파티션에 분산하도록 데이터 모델을 개선하는 방법에 대한 자세한 내용은 [데이터 모델링 모범 사례: 데이터 모델 설계를 위한 권장 사항](data-modeling.md) 섹션을 참조하세요.
동일한 논리적 파티션에 정적 및 비정적 데이터를 포함하는 동시 쓰기 작업의 비율이 높아진 경우에도 `Write_Timeout` 예외가 발생할 수 있습니다. 트래픽이 동일한 논리적 파티션 내에서 정적 및 비정적 데이터를 포함하는 여러 개의 동시 쓰기 작업을 실행할 것으로 예상되는 경우 정적 데이터와 비정적 데이터를 따로 쓰는 것이 좋습니다. 데이터를 별도로 쓰는 것도 처리량 비용을 최적화하는 데 도움이 됩니다.
**연결 요청 속도 초과와 관련된 오류가 표시됩니다.**
다음 원인 중 하나로 인해 `PerConnectionRequestRateExceeded`가 표시됩니다.
+ 세션당 구성된 연결이 충분하지 않을 수 있습니다.
+ VPC 엔드포인트 권한이 올바르게 구성되어 있지 않기 때문에 사용 가능한 피어보다 연결 수가 적을 수 있습니다. VPC 엔드포인트 정책에 대한 자세한 내용은 [Amazon Keyspaces에 인터페이스 VPC 엔드포인트 사용](vpc-endpoints.md#using-interface-vpc-endpoints) 섹션을 참조하세요.
+ 4.x 드라이버를 사용하는 경우 호스트 이름 검증이 활성화되어 있는지 확인합니다. 드라이버는 기본적으로 TLS 호스트 이름 확인을 활성화합니다. 이 구성으로 인해 Amazon Keyspaces가 드라이버에 단일 노드 클러스터로 표시됩니다. 호스트 이름 인증을 끄는 것이 좋습니다.
다음 모범 사례를 따라 연결 및 처리량을 최적화하는 것이 좋습니다.
+ **CQL 쿼리 처리량 조정 구성**
Amazon Keyspaces는 TCP 연결당 초당 최대 3,000개의 CQL 쿼리를 지원하지만 드라이버가 설정할 수 있는 연결 수에는 제한이 없습니다.
대부분의 오픈 소스 Cassandra 드라이버는 Cassandra에 연결 풀을 설정하고 연결 풀 전체에 걸쳐 쿼리를 로드 밸런싱합니다. Amazon Keyspaces는 드라이버에게 9개의 피어 IP 주소를 노출합니다. 대부분의 드라이버의 기본 동작은 각 피어 IP 주소마다 하나의 연결을 설정하는 것입니다. 따라서 기본 설정을 사용하는 드라이버의 최대 CQL 쿼리 처리량은 초당 27,000개의 CQL 쿼리입니다.
이 수를 늘리려면 드라이버가 연결 풀에서 유지 관리하는 IP 주소당 연결 수를 늘리는 것이 좋습니다. 예를 들어 IP 주소당 최대 연결 수를 2로 설정하면 드라이버의 최대 처리량이 초당 54,000개의 CQL 쿼리로 두 배로 늘어납니다.
+ **단일 노드 연결을 최적화합니다.**
기본적으로 대부분의 오픈 소스 Cassandra 드라이버는 세션을 설정할 때 `system.peers` 테이블에 표시된 모든 IP 주소에 대해 하나 이상의 연결을 설정합니다. 하지만 특정 구성에서는 드라이버가 단일 Amazon Keyspaces IP 주소에 연결될 수 있습니다. 이는 드라이버가 피어 노드(예: DataStax Java 드라이버)의 SSL 호스트 이름 검증을 시도하거나 VPC 엔드포인트를 통해 연결할 때 발생할 수 있습니다.
여러 IP 주소에 연결할 때 드라이버와 동일한 가용성 및 성능을 얻으려면 다음을 수행하는 것이 좋습니다.
+ 원하는 클라이언트 처리량에 따라 IP당 연결 수를 9개 이상으로 늘립니다.
+ 동일한 노드에서 재시도가 실행되도록 하는 사용자 지정 재시도 정책을 생성합니다. 자세한 내용은 다음 섹션을 참조하세요.
[Amazon Keyspaces에서 연결에 대한 재시도 정책을 구성하는 방법](connections.md#connections.retry-policies).
+ VPC 엔드포인트를 사용하는 경우 Amazon Keyspaces에 연결하는 데 사용되는 IAM 엔티티에 엔드포인트 및 네트워크 인터페이스 정보에 대한 VPC를 쿼리할 수 있는 액세스 권한을 부여합니다. 이렇게 하면 로드 밸런싱이 개선되고 읽기/쓰기 처리량이 늘어납니다. 자세한 내용은 [인터페이스 VPC 엔드포인트 정보로 `system.peers` 테이블 항목 채우기](vpc-endpoints.md#system_peers) 단원을 참조하십시오.
### 데이터를 가져오는 동안 쓰기 제한 시간 오류가 발생함
** `cqlsh` `COPY` 명령을 사용하여 데이터를 업로드할 때 제한 시간 오류가 발생합니다.**
```
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`
+ `StoragePartitionThroughputCapacityExceeded`
데이터 로드 중 용량 부족 오류를 해결하려면 작업자당 쓰기 속도 또는 총 수집 속도를 낮춘 다음 행 업로드를 다시 시도합니다. 자세한 내용은 [4단계: `cqlsh COPY FROM` 설정 구성](bulk-upload-config.md) 단원을 참조하십시오. 보다 강력한 데이터 업로드 옵션을 원한다면 [GitHub 리포지토리](https://github.com/datastax/dsbulk)에서 제공되는 DSBulk를 사용해 보세요. 단계별 지침은 [자습서: DSBulk를 사용하여 Amazon Keyspaces에 데이터 로드](dsbulk-upload.md)섹션을 참조하세요.
### 키스페이스 또는 테이블의 실제 스토리지 크기를 볼 수 없음
**키스페이스 또는 테이블의 실제 스토리지 크기를 볼 수 없습니다.**
테이블의 스토리지 크기에 대한 자세한 내용은 [테이블 수준에서 비용 평가](CostOptimization_TableLevelCostAnalysis.md) 섹션을 참조하세요. 테이블의 행 크기 계산을 시작하여 스토리지 크기를 추정할 수도 있습니다. 행 크기 계산에 대한 자세한 지침은 [Amazon Keyspaces에서 행 크기 추정](calculating-row-size.md)에서 확인할 수 있습니다.
# Amazon Keyspaces의 데이터 정의 언어 오류 문제 해결
리소스 생성에 문제가 있으신가요? 다음에서는 몇 가지 일반적인 문제와 이에 대한 해결 방법에 대해 설명합니다.
## 데이터 정의 언어 오류
Amazon Keyspaces는 데이터 정의 언어(DDL) 작업을 비동기적으로 수행합니다(예: 키스페이스 및 테이블 생성 및 삭제). 애플리케이션이 준비가 되기 전에 리소스를 사용하려고 하면 작업이 실패합니다.
에서 새 키스페이스 및 테이블의 생성 상태를 모니터링할 수 있습니다. AWS Management Console이는 키스페이스 또는 테이블이 보류 중이거나 활성 상태인 시기를 나타냅니다. 또한 시스템 스키마 테이블을 쿼리하여 프로그래밍 방식으로 새 키스페이스 또는 테이블의 생성 상태를 모니터링할 수 있습니다. 키스페이스 또는 테이블을 사용할 준비가 되면 시스템 스키마에 해당 키스페이스나 테이블이 표시됩니다.
**참고**
를 사용하여 키스페이스 생성을 최적화하려면이 유틸리티를 사용하여 CQL 스크립트를 CloudFormation 템플릿으로 변환 CloudFormation할 수 있습니다. 도구는 [GitHub 리포지토리](https://github.com/aws/amazon-keyspaces-cql-to-cfn-converter)에서 제공됩니다.
**Topics**
+ [키스페이스 생성 오류](#troubleshooting.cql.keyspace)
+ [테이블 생성 오류](#troubleshooting.cql.table)
+ [Amazon Keyspaces 시점 복구(PITR)를 사용하여 테이블을 복원하려고 하지만 복원에 실패함](#troubleshooting.cql.pitr)
+ [INSERT/UPDATE를 사용하여 사용자 지정 TTL(Time To Live) 설정을 편집하려고 하지만 작업이 실패함](#troubleshooting.cql.ttl)
+ [열 초과됨](#troubleshooting.cql.upload)
+ [범위 삭제 오류](#troubleshooting.cql.rangedelete)
### 새 키스페이스를 생성했지만 해당 키스페이스를 보거나 액세스할 수 없음
**새 키스페이스에 액세스하려는 애플리케이션에서 오류가 발생합니다.**
아직 비동기적으로 생성 중인 새로 생성된 Amazon Keyspaces 키스페이스에 액세스하려고 하면 오류가 발생합니다. 다음은 오류의 예입니다.
```
InvalidRequest: Error from server: code=2200 [Invalid query] message="unconfigured keyspace mykeyspace"
```
새 키스페이스를 사용할 준비가 되면 확인하는 권장 설계 패턴은 Amazon Keyspaces 시스템 스키마 테이블(system\$1schema\$1mcs.\$1)을 폴링하는 것입니다.
자세한 내용은 [Amazon Keyspaces에서 키스페이스 생성 상태 확인](keyspaces-create.md) 단원을 참조하십시오.
### 새 테이블을 생성했지만 해당 테이블을 보거나 액세스할 수 없음
**새 테이블에 액세스하려는 애플리케이션에서 오류가 발생합니다.**
아직 비동기적으로 생성 중인 새로 생성된 Amazon Keyspaces 테이블에 액세스하려고 하면 오류가 발생합니다. 예를 들어 아직 사용할 수 없는 테이블을 쿼리하려고 하면 `unconfigured table` 오류로 실패합니다.
```
InvalidRequest: Error from server: code=2200 [Invalid query] message="unconfigured table mykeyspace.mytable"
```
`sync_table()`을 사용하여 테이블을 보려고 하면 `KeyError`로 실패합니다.
```
KeyError: 'mytable'
```
새 테이블을 사용할 준비가 되면 확인하는 권장 설계 패턴은 Amazon Keyspaces 시스템 스키마 테이블(system\$1schema\$1mcs.\$1)을 폴링하는 것입니다.
다음은 생성 중인 테이블의 예제 출력입니다.
```
user-at-123@cqlsh:system_schema_mcs> select table_name,status from system_schema_mcs.tables where keyspace_name='example_keyspace' and table_name='example_table';
table_name | status
------------+----------
example_table | CREATING
(1 rows)
```
다음은 활성화된 테이블의 예제 출력입니다.
```
user-at-123@cqlsh:system_schema_mcs> select table_name,status from system_schema_mcs.tables where keyspace_name='example_keyspace' and table_name='example_table';
table_name | status
------------+----------
example_table | ACTIVE
(1 rows)
```
자세한 내용은 [Amazon Keyspaces에서 테이블 생성 상태 확인](tables-create.md) 단원을 참조하십시오.
### Amazon Keyspaces 시점 복구(PITR)를 사용하여 테이블을 복원하려고 하지만 복원에 실패함
시점 복구(PITR)를 사용하여 Amazon Keyspaces 테이블을 복원하려고 할 때 복원 프로세스가 시작되었지만 성공적으로 완료되지 않은 경우 이 특정 테이블에 대한 복원 프로세스에 필요한 모든 필수 권한을 구성하지 않았을 수 있습니다.
사용자 권한 외에도 Amazon Keyspaces는 보안 주체를 대신하여 복원 프로세스 중에 작업을 수행할 수 있는 권한을 요구할 수 있습니다. 테이블이 고객 관리형 키로 암호화되거나 들어오는 트래픽을 제한하는 IAM 정책을 사용하는 경우가 이에 해당합니다.
예를 들어 IAM 정책에서 조건 키를 사용하여 소스 트래픽을 특정 엔드포인트 또는 IP 범위로 제한하는 경우 복원 작업이 실패합니다. Amazon Keyspaces가 보안 주체를 대신하여 테이블 복원 작업을 수행하도록 허용하려면 IAM 정책에 `aws:ViaAWSService` 글로벌 조건 키를 추가해야 합니다.
테이블 복원 권한에 대한 자세한 내용은 [Amazon Keyspaces PITR에 대한 복원 테이블 IAM 권한 구성](howitworks_restore_permissions.md) 섹션을 참조하세요.
### INSERT/UPDATE를 사용하여 사용자 지정 TTL(Time To Live) 설정을 편집하려고 하지만 작업이 실패함
사용자 지정 TTL 값을 삽입하거나 업데이트하려는 경우 다음 오류가 발생하여 작업이 실패할 수 있습니다.
```
TTL is not yet supported.
```
`INSERT` 또는 `UPDATE` 작업을 사용하여 행 또는 열의 사용자 지정 TTL 값을 지정하려면 먼저 테이블에 TTL을 활성화해야 합니다. `ttl` 사용자 지정 속성을 사용하여 테이블에 TTL을 활성화할 수 있습니다.
테이블에 대한 사용자 지정 TTL 설정을 활성화하는 방법에 대한 자세한 내용은 [사용자 지정 TTL(Time to Live)로 테이블 업데이트](TTL-how-to-enable-custom-alter.md) 섹션을 참조하세요.
### Amazon Keyspaces 테이블에 데이터를 업로드하려고 하는데 열 수를 초과한다는 오류가 발생함
**데이터를 업로드하고 있는데 동시에 업데이트할 수 있는 열 수를 초과했습니다.**
이 오류는 테이블 스키마가 최대 크기인 350KB를 초과할 때 발생합니다. 자세한 내용은 [Amazon Keyspaces(Apache Cassandra용)에 대한 할당량](quotas.md) 단원을 참조하십시오.
### Amazon Keyspaces 테이블에서 데이터를 삭제하려고 하는데 해당 범위에서 삭제가 실패함
**파티션 키로 데이터를 삭제하려고 하는데 범위 삭제 오류가 발생했습니다.**
이 오류는 한 번의 삭제 작업으로 1,000개 이상의 행을 삭제하려고 할 때 발생합니다.
```
Range delete requests are limited by the amount of items that can be deleted in a single range.
```
자세한 내용은 [범위 삭제](functional-differences.md#functional-differences.range-delete) 단원을 참조하십시오.
단일 파티션 내에서 1,000개가 넘는 행을 삭제하려면 다음 옵션을 고려해 보세요.
+ 파티션별 삭제 - 파티션 대다수가 1,000행 미만인 경우 파티션별로 데이터를 삭제해 볼 수 있습니다. 파티션에 1,000개 이상의 행이 포함된 경우 대신 클러스터링 열을 기준으로 삭제를 시도합니다.
+ 클러스터링 열별 삭제 - 모델에 클러스터링 열이 여러 개 있는 경우 열 계층 구조를 사용하여 여러 행을 삭제할 수 있습니다. 클러스터링 열은 중첩 구조이므로 최상위 열에 대해 작업하여 많은 행을 삭제할 수 있습니다.
+ 개별 행별 삭제 - 행을 반복하고 전체 프라이머리 키(파티션 열 및 클러스터링 열)로 각 행을 삭제할 수 있습니다.
+ 행을 여러 파티션으로 분할하는 것이 가장 좋습니다. Amazon Keyspaces에서는 처리량을 테이블 파티션에 분산하는 것이 좋습니다. 이렇게 하면 물리적 리소스 전체에 데이터와 액세스가 균등하게 분산되므로 처리량이 가장 좋습니다. 자세한 내용은 [데이터 모델링 모범 사례: 데이터 모델 설계를 위한 권장 사항](data-modeling.md) 단원을 참조하십시오.
워크로드가 많은 삭제 작업을 계획할 때는 다음 권장 사항도 고려해 보세요.
+ Amazon Keyspaces를 사용하면 파티션에 사실상 무제한의 행이 포함될 수 있습니다. 이를 통해 기존 Cassandra 지침인 100MB보다 “더 넓게” 파티션을 확장할 수 있습니다. 시간이 지남에 따라 시계열 또는 원장의 데이터가 1기가바이트 이상 증가하는 것은 드문 일이 아닙니다.
+ Amazon Keyspaces를 사용하면 과중한 워크로드로 인해 삭제 작업을 수행해야 할 때 고려할 압축 전략이나 삭제 표시가 없습니다. 읽기 성능에 영향을 주지 않으면서 원하는 만큼 데이터를 삭제할 수 있습니다.