이 가이드는 인기 있는 그래픽 데이터베이스 클라이언트를 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 Database Service. 데이터베이스에 맞는 Teleport Database Service 설정 방법은 가이드를 참조하세요.

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

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

GUI 클라이언트는 Teleport Database Service에 인증서를 제출하고 Teleport로 보호된 데이터베이스가 발급한 데이터베이스 서버 인증서를 확인해야 합니다. 이를 위한 세 가지 방법이 있습니다:

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

GUI 클라이언트로 Teleport로 보호된 데이터베이스에 접근하려면 클라이언트에 전달할 연결 정보를 검색해야 합니다.

연결할 수 있는 데이터베이스를 나열하여 접근할 데이터베이스를 결정하세요:

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

을 연결하려는 데이터베이스 이름으로 바꾸세요.

인증된 터널#

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

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

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

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

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

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

로컬 프록시 서버#

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

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

$ tsh proxy db 
Started DB proxy on 127.0.0.1:61740

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

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

원격 호스트 및 포트#

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

# View configuration for the database you're logged in to.
$ tsh db config
# View configuration for the specific database when you're logged into multiple.
$ 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 파일은 mutual TLS 인증을 지원하는 pgAdmin 4, MySQL Workbench 및 기타 그래픽 데이터베이스 클라이언트를 통해 연결하는 데 사용됩니다.

MongoDB Compass#

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

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

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

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

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입니다. (자세한 내용은 연결 정보 가져오기 참조)

Azure Data Studio를 사용한 SQL Server#

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를 클릭하여 연결하세요.

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 명령이 출력한 포트를 사용하세요.

Redis 사용자명을 Username으로, 비밀번호를 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")을 설정하고 ssl 이름과 off 값의 새 레코드를 추가하세요 ("Password"와 마찬가지로 "account"는 연결 설정 시 무시되지만 IDE에서 데이터베이스를 등록하는 데 필요합니다). "User properties"에서 "ssl"을 off로 설정하세요:

Teleport는 내부적으로 Database Agent 설정의 값을 사용하므로 제공된 비밀번호와 계정 이름을 무시합니다. SSL을 off로 설정하면 로컬 머신의 암호화만 비활성화됩니다. Snowflake에 대한 연결은 Teleport에 의해 암호화됩니다.

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

축하합니다! Snowflake 인스턴스에 성공적으로 연결되었습니다.

Snowflake: JetBrains (IntelliJ, Goland, DataGrip, PyCharm 등)#

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

tsh proxy db --tunnel --port 2000 snowflake

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

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

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

Teleport는 내부적으로 Database Agent 설정의 값을 사용하므로 제공된 비밀번호와 계정 이름을 무시합니다. "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#

The Cloud Spanner integration works only in the local proxy tunnel mode. Start a local proxy tunnel for connections to your Spanner database by using the command below:

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

The database user specified in --db-user should be the name of a GCP service account that can access the Spanner database. The name of the service account should be everything before the "@" of the service account email address, e.g. the name for llama@example-project-123456.iam.gserviceaccount.com is just "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"를 클릭하여 데이터 소스를 생성하세요.

Cloud Spanner DBeaver#

The Cloud Spanner integration works only in the local proxy tunnel mode. Start a local proxy tunnel for connections to your Spanner database by using the command below:

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

The database user specified in --db-user should be the name of a GCP service account that can access the Spanner database. The name of the service account should be everything before the "@" of the service account email address, e.g. the name for llama@example-project-123456.iam.gserviceaccount.com is just "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"를 클릭하세요.

Oracle 그래픽 클라이언트#

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 (독립 실행형)#

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

다음으로 --db-user 파라미터에서 이름과 사용자명을 설정하세요. 연결 유형을 "Custom JDBC"로 설정하고 tsh proxy db 명령에서 "Custom JDBC URL"을 설정하세요.

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

Oracle SQL Developer (VS Code 확장)#

VS Code Marketplace에서 확장을 설치하세요.

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

Toad#

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

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

설정을 확인하기 위해 연결을 테스트하세요.

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

DBeaver#

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

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

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

설정을 확인하기 위해 연결을 테스트하세요. "Finish"를 클릭하여 완료하세요.