데이터베이스 액세스 문제 해결
데이터베이스 연결 시도가 **"dial tcp ... The Teleport Database Service requires connectivity to your database endpoints. Check that firewall rules (e.g., AWS security groups) allow connectivity between the Teleport Database Service and the database endpoint.
일반적인 문제와 해결 단계입니다.
연결 시도 실패#
타임아웃 오류#
데이터베이스 연결 시도가 **"dial tcp ... i/o timeout"**과 유사한 메시지와 함께 실패합니다.
The Teleport Database Service requires connectivity to your database endpoints.
Check that firewall rules (e.g., AWS security groups) allow connectivity between the Teleport Database Service and the database endpoint.
- Inbound firewall rules for the database must allow connections from the Teleport Database Service.
- Outbound firewall rules for the Teleport Database Service must allow connections to the database endpoint.
Debugging connection timeout errors in AWS
For deployments in AWS, it may be helpful to use AWS Reachability Analyzer to analyze the network path between the Teleport Database Service and the database.
- Identify the Elastic Network Interface (ENI) associated with the Teleport Database Service host. This can be found in the EC2 console.
- Identify the private IP address of the database.
- Create and analyze a network path:
- Set the path source to the ENI associated with the Teleport Database Service host.
- Set the path destination to the database IP.
- Check the analysis results to identify reachability issues.
If your database is registered dynamically or via auto-discovery, repeat the
above connectivity test for every* Teleport Database Service instance that
proxies this database. To list all Teleport Database Service instances
associated with a given database, run the tctl get db_server/<db_name>
command. For example:
$ tctl get db_server/postgres-instance-1 --format json | jq '.[] | {hostname: .spec.hostname, host_id: .spec.host_id, version: .spec.version, target_health: .status.target_health}'
{
"hostname": "ip-10-0-0-111.ca-central-1.compute.internal",
"host_id": "e5e670ac-a7b8-44ef-b373-6296d87f50e8",
"version": "18.3.0",
"target_health": {
"status": "unhealthy",
...
}
}
{
"hostname": "ip-10-0-0-222.ca-central-1.compute.internal",
...
}
If any of the Database Service instances listed here should not proxy the
database, (for example, a Database Service instance in a different VPC or AWS
region without connectivity), locate and update their configurations so they
only receive or discover databases they can reach. In most cases, you can
achieve this by refining your tag filters, such as adding the a vpc-id label.
인증서 만료 또는 아직 유효하지 않음#
데이터베이스 연결 시도가 실패하고 반환된 오류 메시지가 다음과 유사합니다: "Database service could not validate database's certificate: certificate expired."
해결책: 데이터베이스 인증서를 갱신하세요.
Teleport 데이터베이스 서비스는 Teleport 발급 인증서를 사용하여 데이터베이스와 인증합니다. 이 오류는 Teleport가 인증에 실패할 때 발생하며, 종종 만료된 인증서 때문입니다.
새 인증서를 생성하는 데 사용되는 명령은 tctl auth sign입니다. 예를 들어, PostgreSQL용 인증서를 생성하는 명령은 다음과 같습니다:
# Teleport의 인증 기관을 내보내고 호스트 db.example.com에 대한
# 3개월 유효 기간의 인증서/키 쌍을 생성합니다.
$ tctl auth sign --format=db --host=db.example.com --out=server --ttl=2190h
이 예시에서 db.example.com은 Teleport 데이터베이스 서비스가 PostgreSQL 서버에 접근할 수 있는 호스트명입니다.
각 데이터베이스는 서로 다른 형식을 사용합니다. 데이터베이스 가이드에서 자세한 내용과 예시를 확인할 수 있습니다:
새 인증서가 발급된 후 데이터베이스를 업데이트하여 적용하세요.
db에 대한 액세스 거부#
데이터베이스 연결 시도가 **"access to db denied"**와 유사한 오류 메시지와 함께 실패합니다.
해결책: 데이터베이스 인스턴스와 Teleport 역할 기반 액세스 제어(RBAC)를 구성하여 사용자에게 액세스를 허용하세요.
tsh를 통해 액세스하려는 데이터베이스 사용자와 데이터베이스 이름(스키마)이 데이터베이스 인스턴스에 존재하는지 확인하세요.
"데이터베이스 이름" 또는 db_names를 언급할 때, 이는 데이터베이스 서비스 구성의 db_service 섹션에 있는 name 필드와 다릅니다;
이는 특정 데이터베이스 인스턴스 내의 데이터베이스 이름 또는 스키마를 의미합니다.
데이터베이스 인스턴스가 구성되면 Teleport RBAC를 구성하여 액세스를 허용해야 합니다.
Teleport 사용자에게 데이터베이스 사용자, 데이터베이스 이름, 데이터베이스의 Teleport 정적 또는 동적 레이블과 일치하는 db_users, db_names, db_labels를 허용하는 역할을 할당하세요. 또한 사용자가 해당 db_users, db_names, db_labels를 거부하는 역할을 갖고 있지 않은지 확인하세요.
데이터베이스 이름은 PostgreSQL 및 MongoDB 데이터베이스에만 적용됩니다.
PostgreSQL 또는 MongoDB 인스턴스에 연결할 때 --db-name을 지정해야 합니다:
$ tsh db connect --db-user=exampleuser --db-name=exampledb
예를 들어, 다음 user 및 role 리소스는 Teleport 사용자 alice@example.com이
admin 데이터베이스 사용자 또는 postgres 데이터베이스 이름을 제외한 프로덕션 데이터베이스 내의
모든 데이터베이스 이름이나 데이터베이스 사용자에 액세스할 수 있도록 허용합니다:
kind: role
version: v5
metadata:
name: db-developer
description: "프로덕션 데이터베이스에 대한 제한적 액세스를 부여하는 예제 역할"
spec:
allow:
db_labels:
environment: ["prod"] # 이 예시에서는 프로덕션 데이터베이스가 Teleport 클러스터에서 이 레이블을 갖는다고 가정합니다
db_users: ["{{internal.db_users}}"]
db_names: ["{{internal.db_names}}"]
deny:
db_users: ["admin"]
db_names: ["postgres"]
---
kind: user
metadata:
name: alice@example.com
spec:
roles: ["db-developer"]
traits:
db_users: ["*"]
db_names: ["*"]
internal.db_users 및 internal.db_names 트레이트는
Teleport 로컬 사용자 데이터베이스의 값으로 대체됩니다. Teleport 역할에서 트레이트가 작동하는 방법에 대한 전체 세부 정보는 액세스 제어 레퍼런스를 참조하세요.
이제 Alice에게 더 많은 권한을 부여하고 싶다고 가정해 보겠습니다.
이 예시를 단순하게 유지하기 위해 Alice에게 다른 역할을 할당하겠습니다.
Alice의 역할을 모든 리소스에 대한 액세스를 허용하는 기본 Teleport 역할 access만 포함하도록 업데이트하세요.
tctl users update 또는 tctl create를 사용하여 명령줄에서 사용자 역할을 업데이트할 수 있습니다:
$ tctl users update alice@example.com --set-roles=access
텍스트 편집기에서 Alice의 사용자 리소스를 엽니다:
$ tctl edit users/alice@example.com
그런 다음 access 역할을 할당하도록 리소스를 수정합니다:
kind: user
metadata:
name: alice@example.com
spec:
roles: ["access"]
traits:
db_users: ["*"]
db_names: ["*"]
파일을 저장하고 닫아 변경 사항을 적용합니다.
이제 Alice는 모든 데이터베이스 사용자나 데이터베이스 이름을 사용하여 Teleport 클러스터의 모든 데이터베이스에 연결할 수 있습니다.
이 예시는 의도적으로 단순합니다. 더 세밀한 제어를 사용하여 Alice의 권한을 구성할 수 있었습니다. 데이터베이스 액세스 제어 및 액세스 제한 방법에 대한 자세한 내용은 RBAC 문서를 참조하세요.
MySQL 데이터베이스 연결 시 "Unknown system variable 'query_cache_size'" 오류 발생#
TLS 라우팅이 기본적으로 비활성화된 경우, Teleport 프록시 서비스는 MySQL 서버 버전으로 8.0.0-Teleport를 반환합니다. GUI 클라이언트로 연결하는 경우와 같은 일부 경우에는 MySQL 클라이언트와 서버 간에 MySQL 기능이 제대로 협상되지 않았음을 나타내는 Unknown system variable 'query_cache_size' 오류가 발생할 수 있습니다.
이 문제를 해결하는 한 가지 방법은 TLS 라우팅 기능 사용입니다. Teleport 프록시 서비스는 TLS 라우팅 확장을 통해 올바른 MySQL 서버 버전을 전파합니다.
TLS 라우팅으로의 마이그레이션이 불가능한 경우, 이 오류를 우회하는 또 다른 방법은 Teleport 로컬 프록시 명령을 사용하는 것입니다. 이를 통해 Teleport 클러스터에서 TLS 라우팅이 활성화되지 않은 경우에도 Teleport 프록시 서비스에 TLS 라우팅 연결을 설정할 수 있습니다.
proxy_service:
mysql_server_version: "8.0.4"