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

연결 시도가 실패함

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

데이터베이스에 연결하려고 할 때 실패하며, 반환되는 오류 메시지는 다음과 비슷합니다: "데이터베이스 서비스가 데이터베이스의 인증서를 검증할 수 없습니다: 인증서가 만료되었습니다.".

해결 방법: 데이터베이스 인증서를 갱신합니다.

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)를 구성하여 사용자가 접근할 수 있도록 합니다.

접근하려는 데이터베이스 사용자 및 데이터베이스 이름(즉, 스키마)이 해당 데이터베이스 인스턴스에 존재하는지 확인합니다. "데이터베이스 이름" 또는 db_names 언급 시 이는 데이터베이스 서비스 구성의 db_service 섹션에 있는 name 필드와 동일하지 않으며, 특정 데이터베이스 인스턴스 내의 데이터베이스 이름 또는 스키마를 참조합니다.

데이터베이스 인스턴스가 구성된 후에는 Teleport RBAC를 구성하여 접근을 허용해야 합니다. Teleport 사용자에게 db_users, db_names, 및 데이터베이스에 대한 Teleport 정적 또는 동적 레이블과 일치하는 역할을 부여합니다. 또한, 사용자가 해당 db_users, db_names, 또는 db_labels에 대해 접근을 거부하는 역할을 가지고 있지 않은지 확인합니다.

$ 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 역할 내 트레잇의 작동 방식에 대한 자세한 내용은 Teleport 접근 제어 참조를 참조하세요.

이제 Alice에게 더 관대한 접근을 부여하고 싶다고 가정해 보겠습니다. 이 예를 간단하게 유지하기 위해, 그냥 Alice에게 다른 역할을 부여합시다. Alice의 역할을 업데이트하여 기본 Teleport 역할인 access를 포함시킬 수 있으며, 이는 모든 리소스에 대한 접근을 허용합니다. 사용자의 역할을 명령줄에서 업데이트할 수 있는 방법은 tctl users update 또는 tctl create를 사용하는 것입니다:

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

$ tctl get users/alice@example.com > alice.yaml

kind: user
metadata:
  name: alice@example.com
spec:
  roles: ["access"]
  traits:
    db_users: ["*"]
    db_names: ["*"]

$ tctl create --force alice.yaml

이제 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 로컬 프록시 명령을 사용하는 것입니다. 이 명령은 TLS 라우팅이 Teleport 클러스터에서 활성화 되어 있지 않더라도 Teleport 프록시 서비스에 대한 TLS 라우팅 연결을 설정할 수 있게 해줍니다.

proxy_service:
  mysql_server_version: "8.0.4"