일반적인 문제 및 해결 단계.

연결 시도 실패

인증서가 만료되었거나 아직 유효하지 않음

데이터베이스에 연결하려는 시도가 실패하고 반환된 오류 메시지는 **"데이터베이스 서비스가 데이터베이스 인증서를 검증할 수 없습니다: 인증서가 만료되었습니다."**와 유사합니다.

해결 방법: 데이터베이스 인증서를 갱신하십시오.

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 서버에 도달할 수 있는 호스트명입니다.

각 데이터베이스는 서로 다른 형식을 사용합니다. 더 자세한 정보 및 예시를 보려면 데이터베이스 가이드를 확인하십시오:

• PostgreSQL
• MySQL/MariaDB
• MongoDB
• CockroachDB
• Redis
• Redis Cluster

새 인증서를 발급받은 후, 데이터베이스를 업데이트하여 적용되도록 하십시오.

db 접근 거부

데이터베이스에 연결하려는 시도가 **"db 접근 거부"**와 유사한 오류 메시지로 실패합니다.

해결 방법: 데이터베이스 인스턴스 및 Teleport 역할 기반 접근 제어(RBAC)를 구성하여 사용자에게 접근을 허용합니다.

tsh 를 통해 접근하려는 데이터베이스 사용자와 데이터베이스 이름(즉, 스키마)이 데이터베이스 인스턴스에 존재하는지 확인하십시오. "데이터베이스 이름" 또는 db_names 를 언급할 때, 이는 데이터베이스 서비스 구성의 db_service 섹션에 있는 name 필드와 동일하지 않습니다; 이는 특정 데이터베이스 인스턴스 내의 데이터베이스 이름 또는 스키마를 의미합니다.

데이터베이스 인스턴스가 구성되면, Teleport RBAC도 접근을 허용하도록 구성해야 합니다. Teleport 사용자에게 허용하는 역할을 할당하여 db_users , db_names , 및 데이터베이스의 Teleport 정적 또는 동적 레이블과 일치시킵니다. 또한 사용자에게 해당 db_users , db_names 또는 db_labels 를 거부하는 역할이 없도록 확인하십시오.

예를 들어, 다음 user 및 role 리소스는 Teleport 사용자 alice@example.com 이 프로덕션 데이터베이스 내의 모든 데이터베이스 이름 또는 데이터베이스 사용자에 접근하도록 허용합니다. 단, admin 데이터베이스 사용자 또는 postgres 데이터베이스 이름은 제외됩니다.

kind: role
version: v5
metadata:
  name: db-developer
  description: "프로덕션 데이터베이스에 대한 제한된 접근을 부여하는 예시 역할"
spec:
  allow:
    db_labels:
      environment: ["prod"] # 이 예를 위해, 프로덕션 데이터베이스에 이 레이블이 있다고 가정합니다.
    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 역할에서 특성이 작동하는 방법에 대한 자세한 내용은 Teleport 접근 제어 참조를 참조하십시오.

이제 Alice에게 더 많은 권한을 부여하고 싶다고 가정합니다. 이 예를 간단하게 유지하기 위해, Alice에게 다른 역할을 지정하겠습니다. Alice의 역할을 모든 리소스에 접근할 수 있는 기본 Teleport 역할인 access 로 업데이트합니다. 사용자의 역할을 명령줄에서 tctl users update 또는 tctl create 를 사용하여 업데이트할 수 있습니다:

$ tctl users update alice@example.com --set-roles=access

tctl edit users/alice@example.com

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 Proxy Service는 MySQL 서버 버전으로 8.0.0-Teleport 를 반환합니다. GUI 클라이언트를 통해 연결할 경우, 이로 인해 MySQL 클라이언트와 서버 간에 MySQL 기능이 제대로 협상되지 않았음을 나타내는 Unknown system variable 'query_cache_size' 오류가 발생할 수 있습니다.

이 문제를 해결하는 한 가지 방법은 TLS 라우팅 기능을 사용하는 것입니다. 이 경우 Teleport Proxy Service가 TLS 라우팅 확장을 통해 올바른 MySQL 서버 버전을 전파합니다.

TLS 라우팅으로의 마이그레이션이 불가능한 경우, 이 오류를 우회하는 또 다른 방법은 Teleport 로컬 프록시 명령을 사용하는 것입니다. 이 명령을 사용하면 Teleport 클러스터에서 TLS 라우팅이 활성화되어 있지 않더라도 Teleport Proxy Service에 대한 TLS 라우팅 연결을 설정할 수 있습니다.

proxy_service:
  mysql_server_version: "8.0.4"