이 가이드는 인기 있는 그래픽 데이터베이스 클라이언트를 Teleport와 함께 작동하도록 설정하는 방법을 설명합니다.

Teleport Connect를 사용하여 데이터베이스에 접근하는 경우, 앱 내 지침에 따라 GUI 클라이언트를 연결할 수 있습니다. Teleport Connect 사용하기를 참조하세요.

사전 요구 사항#

• 실행 중인 Teleport 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 설정하세요.

• tsh 클라이언트 도구. tsh를 다운로드하는 방법은 설치를 참조하세요. tsh를 포함한 그래픽 데스크톱 클라이언트가 필요하다면 Teleport Connect 사용하기 가이드를 참조하세요.

• Teleport 클러스터에 연결할 수 있는지 확인하려면 tsh login으로 로그인하세요. 예:

  $ tsh login --proxy=teleport.example.com --user=myuser@example.com
  

• 데이터베이스에 접근하도록 구성된 Teleport 데이터베이스 서비스. 사용 중인 데이터베이스에 맞게 Teleport 데이터베이스 서비스를 설정하는 방법은 가이드 중 하나를 참조하세요.

GUI 클라이언트가 Teleport로 보호되는 데이터베이스에 접근하는 방식#

일반적인 설정에서는 Teleport로 보호되는 데이터베이스에 접근하는 클라이언트가 데이터베이스의 네이티브 프로토콜로 Teleport 프록시 서비스에 트래픽을 전송하고, 프록시 서비스가 보호되는 데이터베이스와 트래픽을 주고받습니다. 최종 사용자는 TLS 인증서를 사용하여 Teleport로 보호되는 데이터베이스에 대해 인증합니다.

GUI 클라이언트는 Teleport 데이터베이스 서비스에 인증서를 제시하고, Teleport로 보호되는 데이터베이스가 발급한 데이터베이스 서버 인증서를 확인해야 합니다. 이를 수행하는 방법은 세 가지가 있습니다:

• 인증된 터널(권장): tsh 또는 Teleport Connect가 로컬 프록시를 시작합니다. 데이터베이스 GUI 클라이언트는 로컬 프록시와 인증되지 않은 연결을 맺습니다. 로컬 프록시는 연결을 Teleport로 보호되는 데이터베이스로 전달하기 전에, Teleport 사용자의 클라이언트 인증서로 연결을 자동으로 보호합니다.
• 인증되지 않은 로컬 프록시: tsh가 Teleport로 보호되는 데이터베이스로 연결을 라우팅하는 로컬 프록시를 시작하지만, 프록시 자체는 인증을 처리하지 않습니다. 사용자는 tsh가 출력한 경로에 있는 사용자 인증서, 개인 키, CA 인증서를 제공하도록 데이터베이스 GUI 클라이언트를 구성합니다. (Teleport Connect는 인증된 터널은 시작할 수 있지만 인증되지 않은 로컬 프록시는 시작할 수 없습니다.)
• 원격 호스트와 포트 사용: Teleport 프록시 서비스에서 TLS 다중화가 비활성화된 자체 호스팅 클러스터의 경우, 보호되는 데이터베이스의 프로토콜용 트래픽 전용으로 프록시 서비스에 예약된 포트와 통신하도록 GUI 클라이언트를 구성할 수 있습니다. 일반적인 Teleport 클러스터에는 TLS 다중화를 권장하며, Teleport Cloud에서는 기본적으로 활성화되어 있습니다.

GUI 클라이언트로 Teleport에서 보호되는 데이터베이스에 접근하려면, 클라이언트에 전달할 연결 정보를 가져와야 합니다.

연결할 수 있는 데이터베이스 목록을 조회하여 접근할 데이터베이스를 확인하세요:

$ tsh db ls
# Name
# -------------------
# database-name

database-name를 연결하려는 데이터베이스의 이름으로 바꾸세요.

인증된 터널#

로컬 인증 터널을 시작하려면 다음 명령을 실행하세요.

$ tsh proxy db --tunnel database-name
Started authenticated tunnel for the <engine> database "database-name" in cluster "<cluster-name>" on 127.0.0.1:62652.

--tunnel 플래그와 함께 로컬 데이터베이스 프록시를 시작하면, 데이터베이스 인스턴스에 연결하는 데 사용할 수 있는 인증된 터널이 생성됩니다.

데이터베이스에 연결할 때 기본으로 사용할 데이터베이스 이름과 사용자를 선택적으로 지정할 수 있습니다:

$ tsh proxy db --db-user=my-database-user --db-name=my-schema --tunnel database-name

이제 프록시 명령이 반환한 주소로 연결할 수 있습니다. 이 예제에서는 127.0.0.1:62652입니다.

로컬 프록시 서버#

tsh proxy db 명령을 사용하여 데이터베이스 GUI 클라이언트가 연결할 로컬 TLS 프록시를 시작하세요.

다음과 유사한 명령을 실행하세요:

$ tsh proxy db database-name
Started DB proxy on 127.0.0.1:61740

Use following credentials to connect to the database-name proxy:
  ca_file=/Users/r0mant/.tsh/keys/root.gravitational.io/certs.pem
  cert_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice-db/root/database-name-x509.pem
  key_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice

아래에서 GUI 클라이언트를 구성할 때 표시된 로컬 프록시 호스트/포트와 자격 증명 경로를 사용하세요. 호스트 이름을 입력할 때는 127.0.0.1 대신 localhost를 사용하세요.

원격 호스트와 포트#

Teleport를 자체 호스팅하고 TLS 라우팅을 사용하지 않는 경우, 다음 명령을 실행하여 데이터베이스 연결 정보를 확인하세요:

# 로그인한 데이터베이스의 구성을 확인합니다.
$ tsh db config
# 여러 데이터베이스에 로그인한 경우 특정 데이터베이스의 구성을 확인합니다.
$ tsh db config example

로컬에 캐시된 인증서 및 키 파일의 경로가 표시됩니다:

Name:      example
Host:      teleport.example.com
Port:      3080
User:      postgres
Database:  postgres
CA:        /Users/alice/.tsh/keys/teleport.example.com/certs.pem
Cert:      /Users/alice/.tsh/keys/teleport.example.com/alice-db/root/example-x509.pem
Key:       /Users/alice/.tsh/keys/teleport.example.com/alice

표시된 CA, Cert, Key 파일은 pgAdmin 4, MySQL Workbench 등 상호 TLS 인증을 지원하는 그래픽 데이터베이스 클라이언트를 통해 연결하는 데 사용됩니다.

MongoDB Compass#

Compass는 공식 MongoDB 그래픽 클라이언트입니다.

"New Connection" 패널에서 "Fill in connection fields individually"를 클릭하세요.

"Hostname" 탭에서 데이터베이스에 접근하는 데 사용할 프록시의 호스트 이름과 포트를 입력하세요 (연결 정보 가져오기 참조). "Authentication"은 None으로 둡니다.

"More Options" 탭에서 SSL을 "Client and Server Validation"으로 설정하고 CA와 클라이언트 키, 인증서를 설정하세요. CA 경로는 반드시 제공되어야 하며, Teleport 프록시 서비스의 웹 엔드포인트가 제시하는 인증서를 검증할 수 있어야 합니다.

More Options 탭의 다음 필드는 앞서 실행한 tsh proxy db 명령이 출력한 경로와 일치해야 합니다:

"Connect" 버튼을 클릭하세요.

MySQL DBeaver#

메인 화면의 "Database Navigator" 메뉴에서 오른쪽 클릭하고 Create > Connection을 선택하세요:

열리는 "Connect to a database" 창의 검색창에 "mysql"을 입력하고 MySQL 드라이버를 선택한 후 "Next"를 클릭하세요:

새로 열린 "Connection Settings" 탭에서 Host를 localhost로, Port를 프록시 명령이 반환한 포트(위 예제에서는 62652)로 사용하세요:

같은 탭에서 사용자 이름을 Teleport로 연결할 때 사용하는 이름과 일치하도록 설정하고, "Save password locally" 확인란을 해제하세요:

"Main" 탭에서 "Edit Driver Settings" 버튼을 클릭하고 "No Authentication" 확인란을 체크한 다음 "Ok"를 클릭하여 저장하세요:

"Connection Settings" 창으로 돌아오면 "Ok"를 클릭하여 완료하면 DBeaver가 자동으로 원격 MySQL 서버에 연결됩니다.

MySQL Workbench#

MySQL Workbench는 포괄적인 MySQL 관리 및 SQL 개발 도구를 제공하는 GUI 애플리케이션입니다.

MySQL Workbench의 "Setup New Connection" 대화 상자에서 "Connection Name", "Hostname", "Port", "Username"을 입력하세요:

"SSL" 탭에서 "Use SSL"을 Require and Verify Identity로 설정하고 CA, 인증서, 개인 키 파일의 경로를 입력하세요 (연결 정보 가져오기 참조):

SSL 탭의 다음 필드는 앞서 실행한 tsh proxy db 명령이 출력한 경로와 일치해야 합니다:

선택적으로 "Test Connection"을 클릭하여 연결 상태를 확인하세요:

연결을 저장하고 데이터베이스에 연결하세요.

NoSQL Workbench#

NoSQL Workbench 시작 화면에서 Amazon DynamoDB 옆의 Launch를 클릭하세요. 왼쪽 메뉴에서 Operation builder를 선택한 다음 + Add connection을 클릭하세요. DynamoDB local 탭을 선택하고 프록시의 엔드포인트를 가리키도록 하세요. 위 예제에서는 localhost:62652입니다. (자세한 내용은 연결 정보 가져오기를 참조하세요.)

SQL Server와 Azure Data Studio#

Azure Data Studio에서 프록시의 엔드포인트를 사용하여 연결을 생성하세요. 위 예제에서는 localhost,62652입니다. Windows 머신에서는 localhost 대신 127.0.0.1,62652 형식의 주소가 필요할 수 있습니다. (자세한 내용은 연결 정보 가져오기를 참조하세요.)

다음 설정으로 Microsoft SQL Server에 연결을 생성하세요:

예:

Connect를 클릭하여 연결하세요.

PostgreSQL DBeaver#

PostgreSQL 인스턴스에 연결하려면 인증된 프록시 주소를 사용하세요. 위 예제에서는 127.0.0.1:62652입니다(자세한 내용은 연결 정보 가져오기의 "Authenticated Proxy" 섹션을 참조하세요).

비밀번호를 비운 채로 "Database native" 인증을 사용하세요:

"Test connection"을 클릭하면 연결 성공 메시지가 표시되어야 합니다. 그런 다음 "Finish"를 클릭하여 구성을 저장하세요.

PostgreSQL pgAdmin 4#

pgAdmin 4는 PostgreSQL 서버용으로 널리 사용되는 그래픽 클라이언트입니다.

새 연결을 구성하려면 메인 브라우저 화면에서 "Servers"를 오른쪽 클릭하고 새 서버를 생성하세요:

새 서버 대화 상자의 "General" 탭에서 서버 연결 이름을 입력하세요:

"Connection" 탭에서 위 구성 정보의 호스트 이름, 포트, 사용자, 데이터베이스 이름을 입력하세요:

"SSL" 탭에서 "SSL Mode"를 Verify-Full로 설정하고 위 구성 정보의 클라이언트 인증서, 키, 루트 인증서 경로를 입력하세요:

SSL 탭의 다음 필드는 앞서 실행한 tsh proxy db 명령이 출력한 경로와 일치해야 합니다:

"Save"를 클릭하면 pgAdmin이 즉시 연결됩니다. pgAdmin이 비밀번호를 요청하면 비밀번호 필드를 비워 두고 OK를 클릭하세요.

Microsoft SQL Server Management Studio#

Microsoft SQL Server Management Studio에서 프록시의 엔드포인트를 사용하여 데이터베이스 엔진에 연결하세요. 위 예제에서는 localhost,62652입니다. Windows 머신에서는 localhost 대신 IP 127.0.0.1,62652 연결이 필요할 수 있습니다. (자세한 내용은 연결 정보 가져오기를 참조하세요.)

다음 설정으로 Microsoft SQL Server에 연결을 생성하세요:

예:

Connect를 클릭하여 연결하세요.

Redshift DBeaver#

Redshift 인스턴스에 연결하려면 인증된 프록시 주소를 사용하세요. 위 예제에서는 127.0.0.1:62652입니다(자세한 내용은 연결 정보 가져오기의 "Authenticated Proxy" 섹션을 참조하세요).

"Username/password" 인증을 사용하세요. 사용자 이름을 --db-user에 전달한 데이터베이스 사용자와 일치하도록 설정하고 비밀번호는 비워 두세요:

Driver Properties로 이동하여 ssl=false로 설정하세요. 이는 로컬 연결에서만 암호화를 비활성화합니다 — Redshift로의 연결은 Teleport에 의해 암호화됩니다.

"Test connection"을 클릭하면 연결 성공 메시지가 표시되어야 합니다. 그런 다음 "Finish"를 클릭하여 구성을 저장하세요.

Redis Insight#

Redis Insight를 연 후 ADD REDIS DATABASE를 클릭하세요.

이제 Redis 인스턴스로 향하는 로컬 프록시를 시작하세요:

tsh proxy db --db-user=alice redis-db-name.

Add Database Manually를 클릭하세요. Host로 127.0.0.1을 사용하세요. 연결 정보 가져오기에서 실행한 tsh 명령이 출력한 포트를 사용하세요.

Username으로 Redis 사용자 이름을, Password로 비밀번호를 입력하세요.

다음으로 Use TLS와 Verify TLS Certificates 확인란을 체크하세요. 앞서 실행한 tsh proxy db 명령이 반환한 경로에 있는 파일의 내용을 복사하여 해당하는 필드에 붙여넣으세요. 아래 표에서 각 경로에 해당하는 Redis Insight 필드를 확인하세요:

Add Redis Database를 클릭하세요.

축하합니다! 이제 Redis 인스턴스에 연결되었습니다.

Snowflake: DBeaver#

Snowflake 통합은 인증된 프록시 모드에서만 작동합니다. 아래 명령을 사용하여 Snowflake 데이터베이스로의 연결을 위한 로컬 프록시를 시작하세요:

tsh proxy db --tunnel --port 2000 snowflake

왼쪽 상단의 "add" 아이콘을 클릭하여 새 데이터베이스를 추가하세요:

열리는 "Connect to a database" 창의 검색창에 "snowflake"를 입력하고 Snowflake 드라이버를 선택한 후 "Next"를 클릭하세요:

"Host"를 localhost로, "Port"를 앞서 실행한 tsh proxy db 명령이 반환한 포트(위 예제에서는 2000)로 설정하세요. "Authentication" 섹션에서 "Username"을 --db-user로 Teleport에 전달한 데이터베이스 사용자 이름과 일치하도록 설정하고, "Password" 필드에는 임의의 값(예: "teleport")을 입력하세요(연결을 맺을 때 "Password" 값은 무시되지만 DBeaver가 데이터베이스를 등록하는 데 필요합니다):

다음으로 "Driver properties" 탭을 클릭하고 "account"를 임의의 값(예: "teleport"로 설정하세요. "Password"와 마찬가지로 "account" 값은 연결을 맺을 때 무시되지만 DBeaver가 데이터베이스를 등록하는 데 필요합니다). "User properties"에서 "ssl"을 off로 설정하세요:

Teleport는 내부적으로 데이터베이스 에이전트 구성의 값을 사용하므로, 제공된 비밀번호와 계정 이름은 무시됩니다. off로 설정된 SSL은 로컬 머신에서의 암호화만 비활성화합니다. Snowflake로의 연결은 Teleport에 의해 암호화됩니다.

이제 왼쪽 하단의 "Test Connection..."을 클릭할 수 있습니다:

축하합니다! 이제 Snowflake 인스턴스에 연결되었습니다.

Snowflake: JetBrains (IntelliJ, Goland, DataGrip, PyCharm, etc.)#

Snowflake 통합은 인증된 프록시 모드에서만 작동합니다. 아래 명령을 사용하여 Snowflake 데이터베이스로의 연결을 위한 로컬 프록시를 시작하세요:

tsh proxy db --tunnel --port 2000 snowflake

"Database Explorer"에서 "add" 버튼을 클릭하고 "Data Source"를 선택한 다음 "Snowflake"를 선택하세요:

다음으로 "Host"를 localhost로, "Port"를 앞서 실행한 tsh proxy db 명령이 반환한 포트(위 예제에서는 2000)로 설정하세요. "Username"을 Teleport를 통해 Snowflake에 연결할 때 사용하는 사용자와 일치하도록 설정하고, "Password" 필드에 임의의 값(예: "teleport")을 입력하세요("Password" 값은 무시되지만 IDE에서 데이터 소스를 생성하는 데 필요합니다):

"Advanced" 탭으로 전환하여 "account"에 임의의 값(예: "teleport")을 설정하고, 값이 off인 ssl이라는 새 레코드를 추가하세요("Password"와 마찬가지로 "account"는 연결을 맺을 때 무시되지만 IDE에서 필요합니다):

Teleport는 내부적으로 데이터베이스 에이전트 구성의 값을 사용하므로, 제공된 비밀번호와 계정 이름은 무시됩니다. "SSL"을 off로 설정하면 로컬 머신에서의 암호화만 비활성화됩니다. Snowflake로의 연결은 Teleport에 의해 암호화됩니다.

이제 "Test Connection"을 클릭하여 구성을 확인할 수 있습니다.

축하합니다! 이제 Snowflake 인스턴스에 연결되었습니다.

SQL Server DataGrip#

DataGrip 연결 구성 메뉴에서 프록시의 엔드포인트를 사용하세요. 아래 예제에서는 localhost:4242입니다. (자세한 내용은 연결 정보 가져오기를 참조하세요.)

"User & Password" 인증 옵션을 선택하고 "Password" 필드는 비워 두세요:

"OK"를 클릭하여 연결하세요.

SQL Server DBeaver#

DBeaver 연결 구성 메뉴에서 프록시의 엔드포인트를 사용하세요. 위 예제에서는 localhost:62652입니다. (자세한 내용은 연결 정보 가져오기를 참조하세요.)

SQL Server Authentication 옵션을 사용하고 Password 필드는 비워 두세요:

OK를 클릭하여 연결하세요.

Cloud Spanner DataGrip#

Cloud Spanner 통합은 로컬 프록시 터널 모드에서만 동작합니다. 아래 명령을 사용하여 Spanner 데이터베이스에 대한 연결을 위한 로컬 프록시 터널을 시작합니다.

$ tsh proxy db --tunnel --port 1443 spanner --db-user=<service-account-name> --db-name=<spanner database name>

--db-user에 지정하는 데이터베이스 사용자는 Spanner 데이터베이스에 접근할 수 있는 GCP 서비스 계정의 이름이어야 합니다. 서비스 계정의 이름은 서비스 계정 이메일 주소의 "@" 앞부분 전체여야 합니다. 예를 들어 llama@example-project-123456.iam.gserviceaccount.com의 이름은 "llama"입니다.

DataGrip 메뉴에서 "File > New > Data Source from URL"을 클릭한 다음, tsh proxy db가 출력한 JDBC URL을 복사하여 붙여넣으세요:

"Google Cloud Spanner" 드라이버가 자동으로 선택됩니다. "Ok"를 클릭하세요.

DataGrip은 GCP 자격 증명이 필요하지 않습니다 - 이미 Teleport가 제공합니다. 새 데이터 소스의 "General" 탭에서 "Authentication" 드롭다운 설정을 선택하고 "No auth"를 선택하세요:

"Test connection"을 클릭하여 연결이 올바르게 구성되었는지 확인한 다음 "Ok"를 클릭하여 데이터 소스를 생성하세요.

나중에 이 데이터 소스를 재사용하려면 동일한 tsh 로컬 포트(이 예시에서는
1443)를 사용하거나, tsh 로컬 프록시가 수신 대기 중인 포트와 일치하도록 드라이버
URL을 편집해야 합니다.

Cloud Spanner DBeaver#

Cloud Spanner 통합은 로컬 프록시 터널 모드에서만 동작합니다. 아래 명령을 사용하여 Spanner 데이터베이스에 대한 연결을 위한 로컬 프록시 터널을 시작합니다.

$ tsh proxy db --tunnel --port 1443 spanner --db-user=<service-account-name> --db-name=<spanner database name>

--db-user에 지정하는 데이터베이스 사용자는 Spanner 데이터베이스에 접근할 수 있는 GCP 서비스 계정의 이름이어야 합니다. 서비스 계정의 이름은 서비스 계정 이메일 주소의 "@" 앞부분 전체여야 합니다. 예를 들어 llama@example-project-123456.iam.gserviceaccount.com의 이름은 "llama"입니다.

메뉴에서 "Database > Driver Manager"를 클릭하세요:

"Google Cloud Spanner" 드라이버를 검색하여 선택하고 "Copy" 버튼을 클릭하여 사용자 지정 드라이버 구성을 만드세요:

사용자 지정 드라이버에 "Teleport Spanner"와 같은 이름을 지정한 다음, "URL Template"을 다음 패턴 문자열로 설정하세요:

jdbc:cloudspanner://127.0.0.1:{port}/projects/{server}/instances/{host}/databases/{database};usePlainText=true

"Ok"를 클릭한 다음 "Close"를 클릭하세요

메뉴에서 "Database > New Connection from JDBC URL"을 클릭하세요:

이제 tsh proxy db가 출력한 JDBC URL을 복사하여 붙여넣으세요:

"Proceed"를 클릭한 다음 "Finish"를 클릭하세요.

나중에 이 데이터 소스를 재사용하려면 동일한 tsh 로컬 포트(이 예시에서는
1443)를 사용하거나, tsh 로컬 프록시가 수신 대기 중인 포트와 일치하도록 드라이버
URL을 편집해야 합니다.

Oracle graphical clients#

Oracle 통합은 인증된 프록시 모드에서만 작동합니다. 아래 명령을 사용하여 Oracle 데이터베이스로의 연결을 위한 로컬 프록시를 시작하세요:

> tsh proxy db --tunnel --port 11555 --db-user=<user> --db-name=<db-name> oracle

Started authenticated tunnel for the Oracle database "oracle" in cluster "teleport.example.com" on 127.0.0.1:11555.

로컬 프록시는 TCP 및 TCPS 모드를 지원합니다. 클라이언트마다 선호하는 모드가 다릅니다.

TCP:

• 사용자 이름이나 비밀번호가 필요 없음
• 일반적으로 구성이 더 쉬움

TCPS:

• 사용자 이름이나 비밀번호가 필요 없음
• 자동으로 생성된 지갑(wallet)에 의존함
• 구성에 JDBC URL을 사용함

Oracle SQL Developer (standalone)#

"Connections"에서 "+" 버튼을 클릭하여 새 데이터베이스 연결을 만드세요:

다음으로 --db-user 매개변수에서 이름과 사용자 이름을 설정하세요. 연결 유형을 "Custom JDBC"로 설정하고 tsh proxy db 명령의 출력값으로 "Custom JDBC URL"을 설정하세요.

이제 "Test"를 클릭하여 구성을 확인할 수 있습니다.

Oracle SQL Developer (VS Code extension)#

VS Code Marketplace에서 확장 프로그램을 설치하세요.

TCP와 TCPS 모드를 모두 사용할 수 있습니다.

Toad#

로그인 대화 상자에서 새 로그인 레코드를 추가하세요.

"Direct" 탭에서 연결 세부 정보를 입력하세요:

연결을 테스트하여 설정을 확인하세요.

새로 추가된 로그인이 로그인 목록에 나타납니다.

DBeaver#

"New Database Connection" 버튼을 클릭하세요.

드라이버 목록에서 "Oracle"을 선택하세요. 검색 도구 모음을 사용하여 목록을 좁힐 수 있습니다.

"Custom" 연결 유형을 선택하고 tsh proxy db가 출력한 JDBC 연결 문자열을 붙여넣으세요.

연결을 테스트하여 설정을 확인하세요. "Finish"를 클릭하여 마무리하세요.