Teleport는 Teleport Database Service를 통해 CockroachDB에 대한 안전한 접근을 제공할 수 있습니다. 이를 통해 Teleport RBAC 시스템을 사용한 세분화된 접근 제어가 가능합니다.

Teleport Database Service는 데이터베이스 클라이언트의 트래픽을 인프라에 있는 자체 호스팅 데이터베이스로 프록시합니다. Teleport는 데이터베이스 클라이언트를 위한 인증 기관(CA)을 유지합니다. 데이터베이스가 Teleport 데이터베이스 클라이언트 CA를 신뢰하도록 구성하면, Teleport Database Service는 사용자 트래픽을 프록시할 때 이 CA로 서명된 인증서를 제시합니다. 이러한 설정을 사용하면 자체 호스팅 데이터베이스에 대한 장기 자격 증명을 저장할 필요가 없습니다.

한편 Teleport Database Service는 자체 호스팅 데이터베이스의 TLS 인증서를 Teleport 데이터베이스 CA 또는 데이터베이스에 사용되는 사용자 지정 CA와 대조하여 데이터베이스를 검증합니다.

이 가이드에서는 다음을 수행합니다.

1. Teleport 접근을 위해 CockroachDB 데이터베이스를 구성합니다.
2. 데이터베이스를 Teleport 클러스터에 추가합니다.
3. Teleport를 통해 데이터베이스에 연결합니다.

작동 방식#

Teleport Database Service는 상호 TLS(mutual TLS)를 사용하여 자체 호스팅된 CockroachDB 데이터베이스에 인증합니다. CockroachDB는 데이터베이스 클라이언트에 대한 Teleport 인증 기관(CA)을 신뢰하며, Teleport 데이터베이스 CA 또는 커스텀 CA가 서명한 인증서를 제시합니다. 사용자가 데이터베이스 세션을 시작하면 Teleport Database Service는 Teleport가 서명한 인증서를 제시합니다. 이후 인증된 연결이 사용자의 클라이언트 트래픽을 프록시합니다.

사전 요구사항#

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

• tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     

  2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 

• CockroachDB 클러스터.

• Teleport 데이터베이스 서비스를 실행할 호스트(예: Amazon EC2 인스턴스).

Teleport cluster에 연결할 수 있는지 확인하려면 tsh login으로 로그인한 다음, 현재 자격 증명으로 tctl 명령을 실행할 수 있는지 확인합니다.

예를 들어, teleport.example.com에 cluster 내 Teleport Proxy Service의 도메인 이름을, email@example.com에 Teleport 사용자 이름을 지정하여 다음 명령을 실행합니다:

$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

cluster에 연결하여 tctl status 명령을 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 이후의 tctl 명령을 실행할 수 있습니다. 자체 Teleport cluster를 호스팅하는 경우, 전체 권한을 얻기 위해 Teleport Auth Service를 호스팅하는 컴퓨터에서 tctl 명령을 실행할 수도 있습니다.

• CockroachDB 클러스터 내 노드용 CockroachDB 인증서를 발급할 인증 기관.

1/4단계. Teleport 데이터베이스 서비스 설정#

Database Service가 Teleport 클러스터에 조인하려면 유효한 조인 토큰이 필요합니다. 다음 tctl 명령을 실행하고 Database Service를 실행할 서버에서 토큰 출력을 /tmp/token에 저장합니다:

$ tctl tokens add --type=db --format=text
(=presets.tokens.first=)

Teleport 데이터베이스 서비스를 실행할 위치에 Teleport를 설치 및 구성합니다.

$ sudo teleport db configure create \
   -o file \
   --token=/tmp/token \
   --proxy=teleport.example.com:443 \
   --name=roach \
   --protocol=cockroachdb \
   --uri=roach.example.com:26257 \
   --labels=env=dev 

$ sudo teleport db configure create \
   -o file \
   --token=/tmp/token \
   --proxy=mytenant.teleport.sh:443 \
   --name=roach \
   --protocol=cockroachdb \
   --uri=roach.example.com:26257 \
   --labels=env=dev

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

$ sudo teleport install systemd -o /etc/systemd/system/teleport.service
$ sudo systemctl enable teleport
$ sudo systemctl start teleport

$ helm repo add teleport (=teleport.helm_repo_url=)

$ helm repo update

$ JOIN_TOKEN=$(cat /tmp/token)
$ helm install teleport-kube-agent teleport/teleport-kube-agent \
  --create-namespace \
  --namespace teleport-agent \
  --set roles=db \
  --set proxyAddr=teleport.example.com:443 \
  --set authToken=${JOIN_TOKEN?} \
  --set "databases[0].name=roach" \
  --set "databases[0].uri=roach.example.com:26257" \
  --set "databases[0].protocol=cockroachdb" \
  --set "databases[0].static_labels.env=dev" \
  --version (=teleport.version=)

$ JOIN_TOKEN=$(cat /tmp/token)
$ helm install teleport-kube-agent teleport/teleport-kube-agent \
  --create-namespace \
  --namespace teleport-agent \
  --set roles=db \
  --set proxyAddr=mytenant.teleport.sh:443 \
  --set authToken=${JOIN_TOKEN?} \
  --set "databases[0].name=roach" \
  --set "databases[0].uri=roach.example.com:26257" \
  --set "databases[0].protocol=cockroachdb" \
  --set "databases[0].static_labels.env=dev" \
  --version (=cloud.version=)

$ kubectl -n teleport-agent get pods
NAME                    READY   STATUS    RESTARTS   AGE
teleport-kube-agent-0   1/1     Running   0          32s

2/4단계. Teleport 사용자 생성#

Teleport Community Edition

내장 access 역할을 가진 로컬 Teleport 사용자를 생성합니다:

$ tctl users add \
  --roles=access \
  --db-users="*" \
  --db-names="*" \
  alice

Teleport Enterprise/Enterprise Cloud

내장 access 및 requester 역할을 가진 로컬 Teleport 사용자를 생성합니다:

$ tctl users add \
  --roles=access,requester \
  --db-users="*" \
  --db-names="*" \
  alice

데이터베이스 접근 제어 및 접근 제한 방법에 대한 자세한 정보는 RBAC 문서를 참조하십시오.

3/4단계. CockroachDB 구성#

CockroachDB 사용자 생성#

Teleport는 CockroachDB에 대해 상호 TLS 인증을 사용합니다. 클라이언트 인증서 인증은 모든 CockroachDB 사용자가 사용할 수 있습니다. 아직 사용자가 없다면 Cockroach 클러스터에 접속하여 생성합니다.

CREATE USER alice WITH PASSWORD NULL;

WITH PASSWORD NULL 절은 해당 사용자가 비밀번호 인증을 사용하지 못하도록 하고 클라이언트 인증서 인증을 강제합니다.

데이터베이스 클러스터 내에서 사용자에게 적절한 권한을 반드시 할당해야 합니다. 자세한 내용은 CockroachDB 문서의 Create User를 참조하세요.

상호 TLS 설정#

상호 TLS 인증을 설정하려면 다음 사항을 확인해야 합니다.

• Teleport가 CockroachDB 노드에서 제시하는 인증서를 신뢰해야 합니다.
• CockroachDB 노드가 여러분의 CockroachDB CA와 Teleport 클러스터의 db_client CA 양쪽 모두에 의해 서명된 클라이언트 인증서를 신뢰해야 합니다.

CockroachDB 노드는 Teleport db_client CA를 신뢰해야 하며, 이를 통해 Teleport 사용자가 클라이언트로서 여러분의 CockroachDB 클러스터에 인증할 수 있습니다.

CockroachDB CA는 각 CockroachDB 노드에서 신뢰되어야 하며, 이를 통해 노드가 CockroachDB 클러스터 내 다른 노드에 대해 클라이언트로서 스스로를 인증할 수 있습니다. 이는 CockroachDB가 노드 간 통신에 mTLS를 사용하기 때문입니다.

$ CERTS_DIR=/path/to/cockroachdb/certs/dir
$ cp "${CERTS_DIR}/ca.crt" "${CERTS_DIR}/ca-client.crt"

$ tctl auth export --type=db-client >> /path/to/cockroachdb/certs/dir/ca-client.crt

  databases:
  - name: "example-cockroachdb"
    protocol: "cockroachdb"
    uri: "cockroachdb.example.com:26257"
    static_labels:
      "env": "example"
    tls:
      ca_cert_file: "/path/to/your/ca.crt"

allow:
  impersonate:
    users: ["Db"]
    roles: ["Db"]

$ tctl auth sign \
    --format=cockroachdb \
    --host=roach.example.com \
    --out=/path/to/cockroachdb/certs/dir \
    --ttl=2190h

$ cockroach cert create-client node \
  --certs-dir=/path/to/cockroachdb/certs/dir \
  --ca-key=ca-secrets/ca-client.key

--certs-dir 플래그를 통해 생성된 시크릿이 담긴 디렉터리를 전달하여 CockroachDB 노드를 재시작합니다.

$ cockroach start \
    --certs-dir=/path/to/cockroachdb/certs/dir \
    # other flags...

또는 노드가 이미 --certs-dir=<code>/path/to/cockroachdb/certs/dir</code>로 시작된 상태라면, 노드를 재시작하지 않고 인증서를 다시 로드하도록 cockroach 프로세스에 SIGHUP 신호를 보낼 수 있습니다. SIGHUP은 cockroach 프로세스를 시작한 것과 동일한 사용자로 보내야 합니다.

$ pkill -SIGHUP -x cockroach

4/4단계. 연결#

Teleport 클러스터에 로그인합니다. CockroachDB 클러스터가 사용 가능한 데이터베이스 목록에 나타나야 합니다.

$ tsh login --proxy=teleport.example.com --user=alice
$ tsh db ls
# Name  Description         Labels
# ----- ------------------- -------
# roach Example CockroachDB env=dev

$ tsh login --proxy=mytenant.teleport.sh --user=alice
$ tsh db ls
# Name  Description         Labels
# ----- ------------------- -------
# roach Example CockroachDB env=dev

데이터베이스에 대한 자격 증명을 조회하고 연결하려면:

$ tsh db connect roach

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

$ tsh db connect --db-user=alice roach

[Web UI를 사용하여 CockroachDB 데이터베이스에 접근](../../connect-your-client/teleport-clients/web-ui.mdx#starting-a-database-session)할 수도 있습니다.

데이터베이스에서 로그아웃하고 자격 증명을 제거하려면:

$ tsh db logout roach

트러블슈팅#

Unimplemented client encoding 오류#

psql이 SQL_ASCII 인코딩을 사용하는 경우, CockroachDB 데이터베이스에 연결할 때 unimplemented client encoding: "sqlascii" 오류가 발생할 수 있습니다.

CockroachDB는 UTF8 클라이언트 인코딩만 지원합니다. 이 인코딩을 강제하려면 tsh db connect를 실행하는 셸에서 다음 환경 변수를 설정하세요.

export PGCLIENTENCODING='utf-8'

Teleport Connect로 CockroachDB 데이터베이스에 연결하는 경우, 셸 시작 스크립트에 이 환경 변수를 추가하고 Teleport Connect 앱을 재시작하세요.

쿼리를 취소할 수 없음#

psql과 같은 PostgreSQL CLI 클라이언트를 사용하여 Ctrl+C로 쿼리를 취소하려고 했으나 쿼리가 취소되지 않는다면, 대신 tsh 로컬 프록시를 사용하여 연결해야 합니다. psql이 쿼리를 취소할 때는 TLS 인증서 없이 새 연결을 설정하지만, Teleport는 인증 뿐만 아니라 데이터베이스 연결을 라우팅하는 데에도 TLS 인증서를 필요로 합니다.

Teleport에서 TLS Routing을 활성화 하면 tsh db connect가 모든 연결에 대해 로컬 프록시를 자동으로 시작합니다. 또는 마찬가지로 로컬 프록시를 사용하는 Teleport Connect를 통해 연결할 수도 있습니다. 그 외의 경우에는 tsh proxy db를 사용하여 tsh 로컬 프록시를 수동으로 시작하고 로컬 프록시를 통해 연결해야 합니다.

Ctrl+C로 취소할 수 없는 장기 실행 쿼리를 psql 세션에서 이미 시작한 경우, 새 클라이언트 세션을 시작하여 해당 쿼리를 수동으로 취소할 수 있습니다:

먼저 쿼리의 프로세스 식별자(PID)를 찾습니다:

SELECT pid,usename,backend_start,query FROM pg_stat_activity WHERE state = 'active';

다음으로, PID를 사용하여 쿼리를 정상적으로 취소합니다. 이는 해당 쿼리의 postgres 백엔드 프로세스에 SIGINT 시그널을 보냅니다:

SELECT pg_cancel_backend(<PID>);

항상 먼저 쿼리를 정상적으로 종료하려고 시도해야 하지만, 정상적인 취소가 너무 오래 걸린다면 대신 쿼리를 강제로 종료할 수 있습니다. 이는 해당 쿼리의 postgres 백엔드 프로세스에 SIGTERM 시그널을 보냅니다:

SELECT pg_terminate_backend(<PID>);

pg_cancel_backend 및 pg_terminate_backend 함수에 대한 자세한 내용은 PostgreSQL 문서의 관리 함수를 참조하십시오.

다음 단계#

• 특정 사용자 및 데이터베이스에 대한 접근을 제한하는 방법을 알아보십시오.

• 고가용성 (HA) 가이드를 확인하십시오.

• YAML 구성 레퍼런스를 살펴보십시오.

• 전체 CLI 레퍼런스를 참조하십시오.

• CockroachDB client authentication

• CockroachDB using split CA certificates