Teleport can provide secure access to CockroachDB via the Teleport Database Service. This allows for fine-grained access control through the Teleport RBAC system.

The Teleport Database Service proxies traffic from database clients to self-hosted databases in your infrastructure. Teleport maintains a certificate authority (CA) for database clients. You configure your database to trust the Teleport database client CA, and the Teleport Database Service presents certificates signed by this CA when proxying user traffic. With this setup, there is no need to store long-lived credentials for self-hosted databases.

Meanwhile, the Teleport Database Service verifies self-hosted databases by checking their TLS certificates against either the Teleport database CA or a custom CA used with the database.

In this guide, you will:

1. Configure your CockroachDB database for Teleport access.
2. Add the database to your Teleport cluster.
3. Connect to the database via Teleport.

작동 방식#

The Teleport Database Service authenticates to your self-hosted CockroachDB database using mutual TLS. CockroachDB trusts the Teleport certificate authority for database clients, and presents a certificate signed by either the Teleport database CA or a custom CA. When a user initiates a database session, the Teleport Database Service presents a certificate signed by Teleport. The authenticated connection then proxies client traffic from the user.

사전 조건#

• A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace with the web address of your Teleport Proxy Service:

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

  2. Follow the instructions for your platform to install tctl and tsh clients:

• CockroachDB 클러스터.

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

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:

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

If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

• CockroachDB 클러스터의 노드에 대해 CockroachDB 인증서를 발급하는 인증 기관.

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

The Database Service requires a valid join token to join your Teleport cluster. Run the following tctl command and save the token output in /tmp/token on the server that will run the Database Service:

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

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

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

$ helm repo update

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

(!docs/pages/includes/database-access/multiple-instances-tip.mdx !)

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

For more detailed information about database access controls and how to restrict access see RBAC documentation.

3/4단계. CockroachDB 구성#

CockroachDB 사용자 생성#

Teleport는 CockroachDB와 상호 TLS 인증을 사용합니다. 클라이언트 인증서 인증은 모든 CockroachDB 사용자에게 사용 가능합니다. 아직 없는 경우 Cockroach 클러스터에 연결하여 생성합니다:

CREATE USER alice WITH PASSWORD NULL;

WITH PASSWORD NULL 절은 사용자가 패스워드 인증을 사용하지 못하게 하고 클라이언트 인증서 인증을 의무화합니다.

데이터베이스 클러스터 내에서 사용자에게 적절한 권한을 할당해야 합니다. 자세한 정보는 CockroachDB 문서의 사용자 생성을 참조하세요.

상호 TLS 설정#

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

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

CockroachDB 노드는 Teleport 사용자가 클라이언트로서 CockroachDB 클러스터에 인증할 수 있도록 Teleport db_client CA를 신뢰해야 합니다.

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

$ CERTS_DIR=
$ cp "${CERTS_DIR}/ca.crt" "${CERTS_DIR}/ca-client.crt"

$ tctl auth export --type=db-client >> /ca-client.crt

  databases:
  - name: "example-cockroachdb"
    protocol: "cockroachdb"
    uri: "cockroachdb.example.com:26257"
    static_labels:
      "env": "example"
    tls:
      ca_cert_file: ""

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

$ tctl auth sign \
    --format=cockroachdb \
    --host=roach.example.com \
    --out= \
    --ttl=2190h

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

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

$ cockroach start \
    --certs-dir= \
    # 다른 플래그들...

또는 노드가 이미 --certs-dir=으로 시작된 경우, 노드를 재시작하지 않고 cockroach 프로세스에 SIGHUP 신호를 보내 인증서를 다시 로드할 수 있습니다. cockroach 프로세스를 시작한 것과 동일한 사용자로 SIGHUP을 보내야 합니다:

$ 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

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

$ tsh db logout roach

문제 해결#

구현되지 않은 클라이언트 인코딩 오류#

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

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

export PGCLIENTENCODING='utf-8'

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

Unable to cancel a query#

If you use a PostgreSQL cli client like psql, and you try to cancel a query with Ctrl+C, but it doesn't cancel the query, then you need to connect using a tsh local proxy instead. When psql cancels a query, it establishes a new connection without TLS certificates, however Teleport requires TLS certificates not only for authentication, but also to route database connections.

If you enable TLS Routing in Teleport then tsh db connect will automatically start a local proxy for every connection. Alternatively, you can connect via Teleport Connect which also uses a local proxy. Otherwise, you need to start a tsh local proxy manually using tsh proxy db and connect via the local proxy.

If you have already started a long-running query in a psql session that you cannot cancel with Ctrl+C, you can start a new client session to cancel that query manually:

First, find the query's process identifier (PID):

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

Next, gracefully cancel the query using its PID. This will send a SIGINT signal to the postgres backend process for that query:

SELECT pg_cancel_backend(<PID>);

You should always try to gracefully terminate a query first, but if graceful cancellation is taking too long, then you can forcefully terminate the query instead. This will send a SIGTERM signal to the postgres backend process for that query:

SELECT pg_terminate_backend(<PID>);

See the PostgreSQL documentation on admin functions for more information about the pg_cancel_backend and pg_terminate_backend functions.

다음 단계#

• Learn how to restrict access to certain users and databases.

• View the High Availability (HA) guide.

• Take a look at the YAML configuration reference.

• See the full CLI reference.

• CockroachDB 클라이언트 인증
• 분할 CA 인증서를 사용하는 CockroachDB