Teleport는 Teleport Database Service를 통해 PostgreSQL on Google Cloud SQL에 대한 안전한 접근을 제공할 수 있습니다. 이는 Teleport의 RBAC를 통해 세부적인 접근 제어를 가능하게 합니다.

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

1. PostgreSQL on Google Cloud SQL 데이터베이스 with a service account를 구성합니다.
2. 데이터베이스를 Teleport 클러스터에 추가합니다.
3. Teleport를 통해 데이터베이스에 연결합니다.

작동 원리

Teleport 데이터베이스 서비스는 IAM 인증을 사용하여 PostgreSQL와 통신합니다. 사용자가 Teleport를 통해 데이터베이스에 연결하면, Teleport 데이터베이스 서비스는 Google Cloud 자격 증명을 얻고 데이터베이스에 접근할 수 있는 권한을 가진 IAM 주체로 Google Cloud에 인증합니다.

• 셀프 호스팅
• 클라우드 호스팅

전제 조건

• 실행 중인 Teleport 클러스터 버전 이상. Teleport를 시작하려면, 가입하기 위해 무료 평가판에 등록하거나 데모 환경 설정하기를 참조하세요.

• tctl 관리 도구와 tsh 클라이언트 도구.

  tctl과 tsh 다운로드에 대한 지침은 설치를 방문하세요.

• Google Cloud 계정
• 명령줄 클라이언트 psql이 설치되어 시스템의 PATH 환경 변수에 추가되어 있어야 합니다.
• Teleport 데이터베이스 서비스를 실행할 호스트, 예를 들어 Compute Engine 인스턴스
• 당신의 Teleport 클러스터에 연결할 수 있는지 확인하려면, tsh login으로 로그인한 다음 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  클러스터  teleport.example.com
  버전  16.2.0
  CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  클러스터에 연결하고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 작업대에서 후속 tctl 명령어를 실행할 수 있습니다. 자신의 Teleport 클러스터를 호스팅하는 경우, Teleport 인증 서비스를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

1단계/9. Teleport 데이터베이스 서비스용 서비스 계정 생성

Google Cloud Platform(GCP)에서 Teleport Database Service가 다른 GCP 서비스 계정을 대신하여 임시 액세스 토큰을 생성할 수 있도록 하기 위해 서비스 계정을 생성하는 방법에 대한 절차는 다음과 같습니다.

서비스 계정 생성하기

Google Cloud 콘솔에 로그인하고 서비스 계정 페이지로 이동합니다:

(선택 사항) 권한 부여

Teleport 데이터베이스 서비스가 Cloud SQL 인스턴스의 루트 CA 인증서를 자동으로 다운로드하고 임시 클라이언트 인증서를 생성하기 위해서는 권한이 필요합니다.

CA 인증서를 수동으로 다운로드할 계획이고 Cloud SQL 인스턴스의 SSL 모드가 "신뢰할 수 있는 클라이언트 인증서 필요"가 아니라면, 이 단계를 건너뛸 수 있습니다.

그렇지 않다면, 서비스 계정 생성 대화 상자의 두 번째 단계에서 서비스 계정에 사전 정의된 GCP IAM 역할 "Cloud SQL Client"를 할당하고 "완료"를 클릭하세요.

# 인스턴스의 루트 CA 인증서를 자동으로 다운로드하고 SSL 모드를 확인하는 데 사용됩니다.
cloudsql.instances.get
# 임시 클라이언트 인증서를 생성하는 데 사용됩니다.
cloudsql.instances.connect

2단계/9. 데이터베이스 사용자용 서비스 계정 생성

Teleport는 서비스 계정을 사용하여 Cloud SQL 데이터베이스에 연결합니다.

서비스 계정 생성

IAM & Admin의 서비스 계정 페이지로 이동하여 "cloudsql-user"라는 이름의 새로운 서비스 계정을 생성하세요:

"생성 및 계속"을 클릭합니다.

권한 부여

두 번째 단계에서 이 서비스 계정에 "Cloud SQL Instance User" 역할을 부여하여 IAM 토큰을 사용한 인증으로 Cloud SQL 인스턴스에 연결할 수 있도록 합니다.

"완료"를 클릭하세요.

서비스 계정에 액세스 권한 부여

Teleport Database Service가 이 서비스 계정을 가장할 수 있어야 합니다. "cloudsql-user" 서비스 계정 개요 페이지로 이동하여 "권한" 탭을 선택하세요:

"액세스 권한 부여"를 클릭하고 "teleport-db-service" 주체 ID를 추가합니다. "Service Account Token Creator" 역할을 선택하고 변경 사항을 저장하세요:

# Used to generate IAM auth tokens when connecting to a database instance.
iam.serviceAccounts.getAccessToken

3단계/9. Cloud SQL 데이터베이스 구성

Teleport는 Cloud SQL PostgreSQL 인스턴스에서 IAM 데이터베이스 인증을 사용합니다.

새로운 PostgreSQL 인스턴스를 생성할 때, "인스턴스 맞춤설정 / 플래그" 섹션에서 cloudsql.iam_authentication 데이터베이스 플래그를 추가해야 합니다.

기존 Cloud SQL 인스턴스에 대해 IAM 인증이 활성화되어 있는지 확인하려면, 인스턴스의 개요 페이지의 구성 패널에서 해당 플래그를 찾아보세요.

활성화되어 있지 않다면, 구성 패널 하단의 "구성 수정" 대화 상자를 사용하여 이 플래그를 추가할 수 있습니다. 이 설정을 변경하면 데이터베이스 인스턴스를 재부팅해야 할 수도 있습니다.

데이터베이스 사용자 생성

이제 Cloud SQL 인스턴스의 사용자 페이지로 돌아가서 새 사용자 계정을 추가하십시오. 사이드바에서 "Cloud IAM" 인증 유형을 선택하고 두 번째 단계에서 생성한 "cloudsql-user" 서비스 계정을 추가합니다:

"추가"를 누르면 사용자 테이블은 다음과 비슷하게 표시됩니다:

Google Cloud 문서에서 IAM 사용자 생성 및 관리에 대한 더 많은 정보를 확인하세요.

4단계/9. Teleport 설치

Linux 서버에 Teleport 설치하기:

1. Teleport 에디션에 따라 edition을(를) 다음 중 하나로 지정합니다:

   에디션	값
   Teleport Enterprise Cloud	cloud
   Teleport Enterprise (자체 호스팅)	enterprise
   Teleport Community Edition	oss

2. 설치할 Teleport의 버전을 확인합니다. 클러스터에서 자동 에이전트 업데이트가 활성화되어 있는 경우, 업데이터와 호환되는 최신 Teleport 버전을 쿼리합니다:

   TELEPORT_DOMAIN=example.teleport.com
   TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

   그렇지 않으면, Teleport 클러스터의 버전을 확인합니다:

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

3. Linux 서버에 Teleport를 설치합니다:

   curl https://cdn.teleport.dev/install-v16.2.0.sh | bash -s ${TELEPORT_VERSION} edition

   설치 스크립트는 Linux 서버에서 패키지 관리자를 감지하고 이를 사용하여 Teleport 바이너리를 설치합니다. 설치를 사용자 지정하려면 설치 가이드에서 Teleport 패키지 리포지토리에 대해 알아보세요.

5단계/9. Teleport 데이터베이스 서비스 구성

조인 토큰 생성

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

tctl tokens add --type=db --format=text
abcd123-insecure-do-not-use-this  

(선택 사항) Cloud SQL CA 인증서 다운로드

Teleport 데이터베이스 서비스가 데이터베이스 인스턴스에서 제시한 인증서를 검증할 수 있도록 Cloud SQL 인스턴스의 루트 CA 인증서가 필요합니다.

Teleport 데이터베이스 서비스는 "cloudsql.instances.get" 권한이 부여되면 인스턴스의 루트 CA 인증서를 자동으로 다운로드할 수 있습니다.

또는, "보안" 섹션의 "연결" 탭에서 인스턴스의 CA 인증서 파일을 다운로드할 수 있습니다.

Teleport 구성 생성

sudo teleport db configure create \   -o file \   --name=cloudsql \   --protocol=postgres \   --labels=env=dev \   --token=/tmp/token \   --proxy=example.teleport.sh:443  \   --uri=public-ip:5432 \   --gcp-project-id=project-id \   --gcp-instance-id=instance-id 

sudo teleport db configure create \   -o file \   --name=cloudsql \   --protocol=postgres \   --labels=env=dev \   --token=/tmp/token \   --proxy=example.teleport.sh:443  \   --uri=public-ip:5432 \   --gcp-project-id=project-id \   --gcp-instance-id=instance-id \   --ca-cert-file=/path/to/cloudsql/instance/server-ca.pem 

이 명령은 Teleport 데이터베이스 서비스 구성 파일을 생성하고 /etc/teleport.yaml에 저장합니다.

6단계/9. GCP 자격 증명 구성

Teleport 데이터베이스 서비스는 "teleport-db-service" GCP 서비스 계정에 대한 자격 증명을 가져야 합니다.

Teleport 데이터베이스 서비스가 GCE 인스턴스에서 호스팅되는 경우, 연결된 서비스 계정을 변경할 수 있습니다. GCE가 아닌 Teleport 배포의 경우, 워크로드 아이덴티티를 사용하는 것을 권장합니다.

또는, 해당 서비스 계정의 키 탭으로 이동하여 새 키를 생성하세요:

JSON 형식을 선택해야 합니다:

파일을 저장합니다. 다운로드한 JSON 자격 증명 파일을 가리키도록 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정합니다. 예를 들어, systemd를 사용하여 teleport를 시작하는 경우, 서비스의 EnvironmentFile을 편집하여 환경 변수를 포함시켜야 합니다:

echo 'GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json' | sudo tee -a /etc/default/teleport

7단계/9. Teleport 데이터베이스 서비스 시작

호스트가 부팅될 때 the Teleport Database Service가 자동으로 시작되도록 시스템 데몬 서비스를 생성하여 구성합니다. 지침은 the Teleport Database Service를 설치한 방법에 따라 다릅니다.

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

the Teleport Database Service의 상태는 systemctl status teleport로 확인할 수 있으며, 로그는 journalctl -fu teleport로 볼 수 있습니다.

8단계/9. Teleport 사용자 생성

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

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

데이터베이스 액세스 제어와 액세스를 제한하는 방법에 대한 자세한 정보는 RBAC 문서를 참조하세요.

9단계/9. 연결

데이터베이스 서비스가 클러스터에 참여한 후, 로그인을 하여 사용 가능한 데이터베이스를 확인하세요:

tsh login --proxy=teleport.example.com --user=alice
tsh db ls
이름     설명                     레이블
-------- ----------------------- --------
cloudsql GCP Cloud SQL PostgreSQL env=dev

tsh login --proxy=mytenant.teleport.sh --user=alice
tsh db ls
이름     설명                     레이블
-------- ----------------------- --------
cloudsql GCP Cloud SQL PostgreSQL env=dev

데이터베이스에 연결할 때는 위에서 추가한 IAM 데이터베이스 사용자로서의 서비스 계정의 이름을 사용하세요. ".gserviceaccount.com" 접미사를 제외한 이름입니다. 데이터베이스 사용자 이름은 Cloud SQL 인스턴스의 사용자 페이지에 표시됩니다. "cloudsql" 예제 데이터베이스의 자격 증명을 검색하고 연결하세요:

tsh db connect --db-user=cloudsql-user@project-id.iam --db-name=postgres cloudsql

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

특정 데이터베이스 인스턴스에 대한 자격 증명 제거:
tsh db logout cloudsql
또는 모든 데이터베이스에 대한 자격 증명 제거:
tsh db logout

문제 해결

기본 자격 증명을 찾을 수 없습니다

"기본 자격 증명을 찾을 수 없습니다"라는 오류는 클라이언트 애플리케이션이나 Teleport에서 발생할 수 있습니다.

클라이언트 애플리케이션의 경우

• GCP 자격 증명 로딩을 비활성화해야 합니다. 클라이언트가 자격 증명을 로드하려고 시도해서는 안 되며, GCP 자격 증명은 Teleport Database Service에 의해 제공될 것입니다.

Teleport Database Service 로그에서 오류가 발생하는 경우

• (DEBUG 로그 레벨에서) Teleport Database Service에 GCP 자격 증명이 올바르게 구성되지 않은 것입니다.
• 서비스 계정 키를 사용하는 경우, 환경 변수 GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json이 설정되어 있는지 확인하고, 이 환경 변수가 teleport에서 사용 가능하도록 Teleport Database Service를 재시작해야 합니다.

예를 들어, Teleport Database Service가 systemd 서비스로 실행되는 경우:

echo 'GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json' | sudo tee -a /etc/default/teleportsudo systemctl restart teleport

서비스 계정 인증 방법에 대한 자세한 내용은 Google Cloud 문서의 인증을 참조하세요.

쿼리를 취소할 수 없습니다

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

만약 당신이 Teleport에서 TLS 라우팅을 활성화하면 tsh db connect는 모든 연결에 대해 자동으로 로컬 프록시를 시작합니다. 대안으로, 로컬 프록시를 사용하는 Teleport Connect를 통해 연결할 수 있습니다. 그렇지 않으면 tsh proxy db를 사용하여 수동으로 tsh 로컬 프록시를 시작하고 로컬 프록시를 통해 연결해야 합니다.

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

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

{{ PIDQuery }}

다음으로, PID를 사용하여 쿼리를 정상적으로 취소합니다. 이것은 해당 쿼리에 대한 postgres 백엔드 프로세스에 SIGINT 신호를 보냅니다:

SELECT pg_cancel_backend(<PID>);

항상 먼저 쿼리를 정상 종료하려고 시도해야 하지만, 정상 취소가 너무 오래 걸리는 경우, 대신 쿼리를 강제로 종료할 수 있습니다. 이것은 해당 쿼리에 대한 postgres 백엔드 프로세스에 SIGTERM 신호를 보냅니다:

SELECT pg_terminate_backend(<PID>);

pg_cancel_backend 및 pg_terminate_backend 함수에 대한 더 많은 정보는 PostgreSQL 문서의 관리자 함수를 참조하십시오.

SSL SYSCALL error

다음은 로컬 psql이 최신 버전의 OpenSSL과 호환되지 않을 때 발생할 수 있는 오류 메시지입니다:

$ tsh db connect --db-user postgres --db-name postgres postgres
psql: error: connection to server at "localhost" (::1), port 12345 failed: Connection refused
    Is the server running on that host and accepting TCP/IP connections?
connection to server at "localhost" (127.0.0.1), port 12345 failed: SSL SYSCALL error: Undefined error: 0

이 문제를 해결하려면 로컬 psql을 최신 버전으로 업그레이드하세요.

다음 단계

• 특정 사용자와 데이터베이스에 대한 액세스를 제한하는 방법을 알아보세요.

• 고가용성(HA) 가이드를 확인하세요.

• YAML 구성 참조를 살펴보세요.

• 전체 CLI 참조를 확인하세요.

• Google Cloud에서 서비스 계정으로 인증하는 방법에 대해 더 알아보세요.