InfoGrab DocsInfoGrab Docs

GCP 데이터베이스 디스커버리

요약

이 가이드를 완료하면 Teleport가 Cloud SQL for PostgreSQL 및 MySQL 인스턴스를 자동으로 탐색하여 등록하고, 해당 인스턴스로의 연결을 프록시합니다. Cloud Spanner와 AlloyDB를 포함한 수동 등록 가이드는 Google Cloud 데이터베이스 등록을 참조합니다.

이 가이드를 완료하면 Teleport가 Cloud SQL for PostgreSQL 및 MySQL 인스턴스를 자동으로 탐색하여 등록하고, 해당 인스턴스로의 연결을 프록시합니다. Teleport RBAC와 데이터베이스 권한은 별도로 구성합니다.

Cloud Spanner와 AlloyDB를 포함한 수동 등록 가이드는 Google Cloud 데이터베이스 등록을 참조합니다.

작동 방식#

Teleport database 자동 디스커버리는 두 가지 구성 요소로 이루어집니다:

  1. 새로운 database 또는 이전에 디스커버리된 database의 변경 사항을 감시하는 Teleport Discovery Service. 디스커버리된 각 database를 Teleport 클러스터의 db 리소스로 동적으로 등록합니다. 디스커버리하는 database에 대한 연결이 필요하지 않습니다.
  2. Discovery Service가 등록한 동적 db 리소스를 모니터링하는 Teleport Database Service. 사용자와 database 간의 통신을 프록시합니다.

사전 요구사항#

  • 실행 중인 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` 파일을 더블 클릭하여 설치를 시작합니다.
 
     
Warning
       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
     ```
   

 
  • Cloud SQL 인스턴스가 하나 이상 있는 Google Cloud 프로젝트.
  • 해당 프로젝트에서 서비스 계정을 생성하고 IAM 역할을 부여할 수 있는 권한.
  • Teleport Discovery Service를 실행할 호스트.
  • Teleport Database Service를 실행할 호스트(예: Compute Engine 인스턴스). 이 호스트는 퍼블릭 IP, 프라이빗 IP(PSA) 또는 Private Service Connect 엔드포인트를 통해 Cloud SQL 인스턴스에 연결할 수 있어야 합니다. Discovery Service는 인스턴스에 대한 연결이 필요하지 않습니다. 퍼블릭 IP의 승인된 네트워크 등 각 옵션의 요구사항은 Google Cloud 문서의 Cloud SQL에 연결하는 방법 선택을 참조합니다.
  • 두 호스트 모두 HTTPS를 통해 Teleport 프록시와 Google Cloud API에 연결할 수 있어야 합니다.
  • Discovery Service용 Google Cloud 서비스 계정. 이 계정에는 사전 정의된 Cloud SQL Viewer 역할(roles/cloudsql.viewer)을 부여해야 합니다.
  • Database Service용 Google Cloud 서비스 계정. 이 계정에는 사전 정의된 Cloud SQL Client 역할(roles/cloudsql.client)을 부여해야 합니다.
  • 각 호스트는 Application Default Credentials를 사용하여 해당 서비스 계정으로 Google Cloud에 인증할 수 있어야 합니다.

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 명령을 실행할 수도 있습니다.

1/6단계. Teleport 설치#

Teleport Discovery Service와 Teleport Database Service를 실행할 호스트에 Teleport를 설치합니다.

Linux 서버에 Teleport Agent를 설치하려면:

권장 설치 방법은 클러스터 설치 스크립트입니다. 이 스크립트는 클러스터에 맞는 올바른 버전, 에디션, 설치 모드를 선택합니다.

  1. teleport.example.com:443에 Teleport 클러스터의 호스트명과 포트를 할당하되, 스킴(https://)은 포함하지 마십시오.

  2. 클러스터의 설치 스크립트를 실행하십시오:

    $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
    

2/6단계. Discovery Service 배포#

Teleport 구성 파일 생성#

다음 구성은 공유 시크릿 조인 토큰을 사용합니다. Google Compute Engine VM에서 Discovery Service를 실행하는 경우, 공유 시크릿 없이 조인할 수 있는 GCP 조인 방식을 대신 사용할 수 있습니다.

Discovery Service를 실행할 호스트에 teleport.yaml 구성 파일을 생성합니다.

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "teleport.example.com:443"
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
discovery_service:
  enabled: true
  discovery_group: "gcp-prod"

이 구성은 discovery_service를 활성화하고 Teleport 클러스터에 조인시킵니다.

Warning

Discovery Service는 검색된 리소스를 서로 다른 집합으로 그룹화할 수 있게 하는 구성 파라미터 discovery_service.discovery_group을 제공합니다. 이 파라미터는 서로 다른 클라우드 리소스 집합을 감시하는 Discovery Agent들이 서로 충돌하여 다른 서비스가 생성한 리소스를 삭제하는 것을 방지하는 데 사용됩니다.

여러 개의 Discovery Service를 실행할 때, 동일한 클라우드 리소스를 감시하는 경우에는 각 서비스가 동일한 discovery_group 값으로 구성되어 있는지 확인해야 하며, 서로 다른 클라우드 리소스를 감시하는 경우에는 서로 다른 값으로 구성해야 합니다.

동일한 Teleport 클러스터에서 구성을 혼합하여 실행할 수 있습니다. 즉 일부 Discovery Service는 동일한 클라우드 리소스를 감시하도록 구성하고 다른 서비스는 서로 다른 리소스를 감시하도록 구성할 수 있습니다. 예를 들어, 서로 다른 두 개의 클라우드 계정에서 데이터를 분석하는 4개 에이전트 고가용성 구성은 다음과 같은 구성으로 실행됩니다.

  • Production 계정에서 데이터를 폴링하는 discovery_group: "prod"로 구성된 Discovery Service 2개.
  • Staging 계정에서 데이터를 폴링하는 discovery_group: "staging"로 구성된 Discovery Service 2개.

조인 토큰 생성#

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

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

Discovery Service 시작#

systemd 서비스를 생성하여 호스트가 부팅될 때 the Discovery Service이 자동으로 시작되도록 구성합니다. 지침은 the Discovery Service을 어떻게 설치했는지에 따라 다릅니다.

Package Manager

the Discovery Service을 실행할 호스트에서 Teleport를 활성화하고 시작합니다:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

TAR Archive

the Discovery Service을 실행할 호스트에서 Teleport용 systemd 서비스 구성을 생성하고, Teleport 서비스를 활성화한 후 Teleport를 시작합니다:

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

systemctl status teleport로 the Discovery Service의 상태를 확인하고 journalctl -fu teleport로 로그를 볼 수 있습니다.

3/6단계. Cloud SQL 디스커버리 구성#

위에서 구성한 것과 동일한 discovery_group을 사용하여 discovery-cloudsql.yaml 파일을 생성합니다.

kind: discovery_config
version: v1
metadata:
  name: discovery-cloudsql
spec:
  discovery_group: "gcp-prod"
  gcp:
    - types: ["cloudsql"]
      # The Google Cloud projects to search. Use ["*"] to search every project
      # the Discovery Service service account can access.
      project_ids: ["my-project"]
      # The Google Cloud regions to search. Use ["*"] to search all regions.
      # For Cloud SQL, locations must be regions (e.g. "us-central1"), not zones.
      locations: ["us-central1"]
      # Optional selector matched against imported user labels and Cloud SQL
      # metadata such as engine, region, and endpoint type. Defaults to a
      # wildcard that matches every instance.
      labels:
        "*": "*"

discovery_config를 생성합니다.

$ tctl create -f discovery-cloudsql.yaml

디스커버리는 기본적으로 5분마다 실행되므로, 일치하는 인스턴스가 Teleport db 리소스로 나타나기까지 최대 5분이 걸릴 수 있습니다. Discovery Service는 지원되지 않거나 사용할 수 없는 인스턴스, 또는 사용 가능한 연결 엔드포인트가 없는 인스턴스를 건너뜁니다.

4/6단계. 등록된 데이터베이스 나열#

Info

이 단계에서 tctl get db는 탐색된 데이터베이스 리소스를 나열합니다. 데이터베이스는 Database Service가 일치시킨 후에야 tsh db ls 또는 tctl db ls에 나타납니다.

Discovery Service가 예상한 인스턴스에 대한 db 리소스를 생성했는지 확인합니다.

$ tctl get db

특정 데이터베이스를 확인하려면 다음 명령을 실행합니다. database-name에는 해당 데이터베이스의 Teleport 리소스 이름을 지정합니다.

$ tctl get db/database-name

예상한 데이터베이스가 보이지 않으면 Discovery Service 문제 해결을 참조합니다.

탐색된 데이터베이스 이름

탐색된 데이터베이스의 이름은 <instance>-cloudsql-<region>-<project-id> 형식이며, 예를 들면 my-postgres-cloudsql-us-central1-my-project입니다. 인스턴스 이름에 이미 포함된 접미사 부분은 Teleport가 제외합니다.

전체 이름과 인스턴스 이름 모두 tsh 및 tctl 명령에서 사용할 수 있습니다. tsh db ls와 tctl db ls는 --verbose를 지정하지 않으면 인스턴스 이름을 표시합니다. 인스턴스 이름이 둘 이상의 데이터베이스와 일치하면 전체 이름을 사용합니다.

인스턴스에 teleport-database-name 사용자 라벨을 적용하면 이름이 재정의됩니다. Teleport는 접미사 없이 해당 값을 그대로 사용하며, 인스턴스 이름은 더 이상 그 이름의 별칭으로 작동하지 않습니다. 이 값은 유효하고 고유한 Teleport 데이터베이스 이름이어야 하며, 유효하지 않은 값이 있는 인스턴스는 Teleport가 건너뜁니다.

탐색된 데이터베이스에 적용되는 라벨은 Google Cloud 데이터베이스 라벨 레퍼런스를 참조합니다.

엔드포인트 선택

인스턴스에 엔드포인트가 여러 개 있으면 Teleport는 퍼블릭, 프라이빗(PSA), PSC 순서로 사용 가능한 첫 번째 엔드포인트를 등록합니다. 이 선택을 재정의하려면 Cloud SQL 인스턴스의 teleport-database-endpoint-type 사용자 라벨을 public, private 또는 psc로 설정합니다. 재정의가 설정되어 있으면 Teleport는 다른 엔드포인트 유형을 시도하지 않습니다.

Database Service 호스트는 Teleport가 등록하는 엔드포인트에 연결할 수 있어야 합니다. 퍼블릭 IP라면 호스트의 송신 IP 주소도 인스턴스의 승인된 네트워크에 포함되어야 합니다.

5/6단계. Database Service 배포#

Teleport 구성 파일 생성#

다음 구성은 공유 시크릿 조인 토큰을 사용합니다. Google Compute Engine VM에서 Database Service를 실행하는 경우, 공유 시크릿 없이 조인할 수 있는 GCP 조인 방식을 대신 사용할 수 있습니다.

Database Service를 실행할 호스트에 teleport.yaml 구성 파일을 생성합니다.

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "teleport.example.com:443"
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
db_service:
  enabled: true
  resources:
    - labels:
        "teleport.dev/origin": "cloud"
        "teleport.dev/cloud": "GCP"
        "teleport.dev/discovery-type": "cloudsql"
        "project-id": "my-project"
        "region": "us-central1"

Discovery Service는 등록하는 모든 데이터베이스에 teleport.dev/origin: cloud 라벨을 추가합니다. 이 예시에서 db_service.resources는 해당 라벨과 다른 셀렉터를 사용하여 my-project 및 us-central1에서 자동으로 탐색된 Cloud SQL 데이터베이스를 일치시킵니다. 일치하는 각 db 리소스에 대해 Database Service는 수명이 짧은 db_server 리소스를 생성하며, 이 리소스는 해당 db에 대한 연결을 프록시할 준비가 되었음을 Teleport 클러스터에 알립니다.

Warning

Database Service 인스턴스가 실제로 도달할 수 있는 데이터베이스에만 매칭되도록, 필요한 경우 더 구체적인 레이블 셀렉터를 사용하십시오. 광범위한 셀렉터는 도달할 수 없는 데이터베이스가 등록되게 하여 연결 실패로 이어질 수 있습니다.

조인 토큰 생성#

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

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

Database Service 시작#

systemd 서비스를 생성하여 호스트가 부팅될 때 the Database Service이 자동으로 시작되도록 구성합니다. 지침은 the Database Service을 어떻게 설치했는지에 따라 다릅니다.

Package Manager

the Database Service을 실행할 호스트에서 Teleport를 활성화하고 시작합니다:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

TAR Archive

the Database Service을 실행할 호스트에서 Teleport용 systemd 서비스 구성을 생성하고, Teleport 서비스를 활성화한 후 Teleport를 시작합니다:

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

systemctl status teleport로 the Database Service의 상태를 확인하고 journalctl -fu teleport로 로그를 볼 수 있습니다.

6/6단계. 데이터베이스 서버 나열#

Database Service가 탐색된 데이터베이스에 대한 서버를 등록했는지 확인합니다.

$ tctl db ls teleport.dev/origin=cloud,teleport.dev/cloud=GCP,teleport.dev/discovery-type=cloudsql,project-id=my-project,region=us-central1

예상한 데이터베이스가 없으면 Database Service 문제 해결을 참조합니다.

문제 해결#

Discovery Service 문제 해결#

먼저 database가 검색되었는지 확인합니다. 이를 위해 tctl get db 명령을 사용하여 예상되는 database가 이미 Teleport 클러스터에 등록되었는지 확인할 수 있습니다.

일부 database가 목록에 나타나지 않는다면, Discovery Service 셀렉터 레이블이 누락된 database 태그와 일치하는지 확인하거나 Discovery Service 로그에서 권한 오류를 살펴보십시오.

Discovery Service가 올바른 AWS 계정의 자격 증명으로 실행되고 있는지 확인합니다. 다른 AWS 계정의 리소스를 검색할 수 있지만, 그런 경우에는 해당 다른 AWS 계정에서 역할을 assume하도록 구성되어 있어야 합니다.

둘 이상의 Discovery Service가 실행 중인지 확인합니다:

$ tctl inventory status --connected

여러 Discovery Service를 실행하는 경우, 동일한 클라우드 database를 감시하는 서비스들은 모두 동일한 discovery_group 값으로 구성하고, 서로 다른 클라우드 database를 감시하는 서비스들은 서로 다른 값으로 구성해야 합니다. 이것이 올바르게 구성되지 않으면, 일반적인 증상으로 db 리소스가 Teleport 클러스터의 레지스트리에서 간헐적으로 삭제됩니다.

Database Service 문제 해결#

tctl db ls에 데이터베이스가 나타나지 않음#

tctl get db 명령이 예상한 검색된 데이터베이스를 반환하지만 tctl db ls 명령에는 포함되지 않는 경우, db_service.resources 섹션이 올바르게 설정되어 있는지 확인하세요. 예를 들면 다음과 같습니다:

db_service:
  enabled: true
  resources:
  - labels:
      "env": "prod"

섹션이 올바르게 구성되어 있는데도 데이터베이스가 여전히 나타나지 않는다면, Teleport에서 데이터베이스를 나열할 올바른 권한이 있는지 확인하세요. 데이터베이스 레이블과 일치하고 db 및 db_server 오브젝트에 대해 "read" 및 "list" verb를 허용하는 Teleport 역할이 있어야 합니다. 다음은 클러스터의 모든 데이터베이스에 대해 해당 권한을 부여하는 예시입니다:

kind: role
version: v6
metadata:
  name: view-all-databases
spec:
  allow:
    db_labels:
      '*': '*'
    rules:
      - resources: [db_server, db]
        verbs: [read, list]

데이터베이스에 연결할 때 오류 발생#

Note

이 섹션에서는 Enroll AWS Databases의 특정 가이드를 따라 이미 데이터베이스 사용자를 프로비저닝하고 해당 데이터베이스 사용자에 대한 Teleport RBAC를 구성했다고 가정합니다.

데이터베이스에 연결하려고 할 때 연결 오류가 발생하면, 먼저 대상 데이터베이스에 대해 여러 개의 db_server 하트비트 리소스가 있는지 확인하세요: tctl get db_server/yourDatabaseName. 여러 개가 있다면 여러 Teleport Database Service 인스턴스가 데이터베이스를 프록시하고 있다는 의미이며, 이는 문제 해결을 복잡하게 만드는 HA 구성입니다. Teleport는 연결을 프록시할 Database Service 인스턴스 중 하나를 무작위로 선택하며, 그중 하나가 데이터베이스 엔드포인트에 연결할 수 없거나 권한이 부족한 경우 무작위 연결 오류가 발생합니다.

연결 오류가 일관되게 발생하더라도, 오류를 해결하는 동안에는 대상 db와 일치하는 인스턴스가 하나만 남도록 Teleport Database Service 인스턴스를 축소하거나 재구성해야 합니다. tctl get db_server/yourDatabaseName으로 db_server가 하나만 있는지 확인한 다음 다시 연결을 시도하세요.

DEBUG 레벨 로깅을 활성화한 상태에서 Teleport Database Service 로그를 확인하고 네트워크 또는 권한 오류를 찾아보세요.

보다 일반적인 문제 해결 단계는 Database Service 문제 해결 가이드를 참고하세요.

또한 Enroll AWS Databases에서 데이터베이스 유형에 특화된 가이드에 더 구체적인 문제 해결 정보가 있을 수 있습니다.

다음 단계#

GCP 데이터베이스 디스커버리

Teleport v18.11
원문 보기

요약

이 가이드를 완료하면 Teleport가 Cloud SQL for PostgreSQL 및 MySQL 인스턴스를 자동으로 탐색하여 등록하고, 해당 인스턴스로의 연결을 프록시합니다. Cloud Spanner와 AlloyDB를 포함한 수동 등록 가이드는 Google Cloud 데이터베이스 등록을 참조합니다.

이 가이드를 완료하면 Teleport가 Cloud SQL for PostgreSQL 및 MySQL 인스턴스를 자동으로 탐색하여 등록하고, 해당 인스턴스로의 연결을 프록시합니다. Teleport RBAC와 데이터베이스 권한은 별도로 구성합니다.

Cloud Spanner와 AlloyDB를 포함한 수동 등록 가이드는 Google Cloud 데이터베이스 등록을 참조합니다.

작동 방식#

Teleport database 자동 디스커버리는 두 가지 구성 요소로 이루어집니다:

  1. 새로운 database 또는 이전에 디스커버리된 database의 변경 사항을 감시하는 Teleport Discovery Service. 디스커버리된 각 database를 Teleport 클러스터의 db 리소스로 동적으로 등록합니다. 디스커버리하는 database에 대한 연결이 필요하지 않습니다.
  2. Discovery Service가 등록한 동적 db 리소스를 모니터링하는 Teleport Database Service. 사용자와 database 간의 통신을 프록시합니다.

사전 요구사항#

  • 실행 중인 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` 파일을 더블 클릭하여 설치를 시작합니다.
 
     
Warning
       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
     ```
   

 
  • Cloud SQL 인스턴스가 하나 이상 있는 Google Cloud 프로젝트.
  • 해당 프로젝트에서 서비스 계정을 생성하고 IAM 역할을 부여할 수 있는 권한.
  • Teleport Discovery Service를 실행할 호스트.
  • Teleport Database Service를 실행할 호스트(예: Compute Engine 인스턴스). 이 호스트는 퍼블릭 IP, 프라이빗 IP(PSA) 또는 Private Service Connect 엔드포인트를 통해 Cloud SQL 인스턴스에 연결할 수 있어야 합니다. Discovery Service는 인스턴스에 대한 연결이 필요하지 않습니다. 퍼블릭 IP의 승인된 네트워크 등 각 옵션의 요구사항은 Google Cloud 문서의 Cloud SQL에 연결하는 방법 선택을 참조합니다.
  • 두 호스트 모두 HTTPS를 통해 Teleport 프록시와 Google Cloud API에 연결할 수 있어야 합니다.
  • Discovery Service용 Google Cloud 서비스 계정. 이 계정에는 사전 정의된 Cloud SQL Viewer 역할(roles/cloudsql.viewer)을 부여해야 합니다.
  • Database Service용 Google Cloud 서비스 계정. 이 계정에는 사전 정의된 Cloud SQL Client 역할(roles/cloudsql.client)을 부여해야 합니다.
  • 각 호스트는 Application Default Credentials를 사용하여 해당 서비스 계정으로 Google Cloud에 인증할 수 있어야 합니다.

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 명령을 실행할 수도 있습니다.

1/6단계. Teleport 설치#

Teleport Discovery Service와 Teleport Database Service를 실행할 호스트에 Teleport를 설치합니다.

Linux 서버에 Teleport Agent를 설치하려면:

권장 설치 방법은 클러스터 설치 스크립트입니다. 이 스크립트는 클러스터에 맞는 올바른 버전, 에디션, 설치 모드를 선택합니다.

  1. teleport.example.com:443에 Teleport 클러스터의 호스트명과 포트를 할당하되, 스킴(https://)은 포함하지 마십시오.

  2. 클러스터의 설치 스크립트를 실행하십시오:

    $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
    

2/6단계. Discovery Service 배포#

Teleport 구성 파일 생성#

다음 구성은 공유 시크릿 조인 토큰을 사용합니다. Google Compute Engine VM에서 Discovery Service를 실행하는 경우, 공유 시크릿 없이 조인할 수 있는 GCP 조인 방식을 대신 사용할 수 있습니다.

Discovery Service를 실행할 호스트에 teleport.yaml 구성 파일을 생성합니다.

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "teleport.example.com:443"
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
discovery_service:
  enabled: true
  discovery_group: "gcp-prod"

이 구성은 discovery_service를 활성화하고 Teleport 클러스터에 조인시킵니다.

Warning

Discovery Service는 검색된 리소스를 서로 다른 집합으로 그룹화할 수 있게 하는 구성 파라미터 discovery_service.discovery_group을 제공합니다. 이 파라미터는 서로 다른 클라우드 리소스 집합을 감시하는 Discovery Agent들이 서로 충돌하여 다른 서비스가 생성한 리소스를 삭제하는 것을 방지하는 데 사용됩니다.

여러 개의 Discovery Service를 실행할 때, 동일한 클라우드 리소스를 감시하는 경우에는 각 서비스가 동일한 discovery_group 값으로 구성되어 있는지 확인해야 하며, 서로 다른 클라우드 리소스를 감시하는 경우에는 서로 다른 값으로 구성해야 합니다.

동일한 Teleport 클러스터에서 구성을 혼합하여 실행할 수 있습니다. 즉 일부 Discovery Service는 동일한 클라우드 리소스를 감시하도록 구성하고 다른 서비스는 서로 다른 리소스를 감시하도록 구성할 수 있습니다. 예를 들어, 서로 다른 두 개의 클라우드 계정에서 데이터를 분석하는 4개 에이전트 고가용성 구성은 다음과 같은 구성으로 실행됩니다.

  • Production 계정에서 데이터를 폴링하는 discovery_group: "prod"로 구성된 Discovery Service 2개.
  • Staging 계정에서 데이터를 폴링하는 discovery_group: "staging"로 구성된 Discovery Service 2개.

조인 토큰 생성#

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

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

Discovery Service 시작#

systemd 서비스를 생성하여 호스트가 부팅될 때 the Discovery Service이 자동으로 시작되도록 구성합니다. 지침은 the Discovery Service을 어떻게 설치했는지에 따라 다릅니다.

Package Manager

the Discovery Service을 실행할 호스트에서 Teleport를 활성화하고 시작합니다:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

TAR Archive

the Discovery Service을 실행할 호스트에서 Teleport용 systemd 서비스 구성을 생성하고, Teleport 서비스를 활성화한 후 Teleport를 시작합니다:

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

systemctl status teleport로 the Discovery Service의 상태를 확인하고 journalctl -fu teleport로 로그를 볼 수 있습니다.

3/6단계. Cloud SQL 디스커버리 구성#

위에서 구성한 것과 동일한 discovery_group을 사용하여 discovery-cloudsql.yaml 파일을 생성합니다.

kind: discovery_config
version: v1
metadata:
  name: discovery-cloudsql
spec:
  discovery_group: "gcp-prod"
  gcp:
    - types: ["cloudsql"]
      # The Google Cloud projects to search. Use ["*"] to search every project
      # the Discovery Service service account can access.
      project_ids: ["my-project"]
      # The Google Cloud regions to search. Use ["*"] to search all regions.
      # For Cloud SQL, locations must be regions (e.g. "us-central1"), not zones.
      locations: ["us-central1"]
      # Optional selector matched against imported user labels and Cloud SQL
      # metadata such as engine, region, and endpoint type. Defaults to a
      # wildcard that matches every instance.
      labels:
        "*": "*"

discovery_config를 생성합니다.

$ tctl create -f discovery-cloudsql.yaml

디스커버리는 기본적으로 5분마다 실행되므로, 일치하는 인스턴스가 Teleport db 리소스로 나타나기까지 최대 5분이 걸릴 수 있습니다. Discovery Service는 지원되지 않거나 사용할 수 없는 인스턴스, 또는 사용 가능한 연결 엔드포인트가 없는 인스턴스를 건너뜁니다.

4/6단계. 등록된 데이터베이스 나열#

Info

이 단계에서 tctl get db는 탐색된 데이터베이스 리소스를 나열합니다. 데이터베이스는 Database Service가 일치시킨 후에야 tsh db ls 또는 tctl db ls에 나타납니다.

Discovery Service가 예상한 인스턴스에 대한 db 리소스를 생성했는지 확인합니다.

$ tctl get db

특정 데이터베이스를 확인하려면 다음 명령을 실행합니다. database-name에는 해당 데이터베이스의 Teleport 리소스 이름을 지정합니다.

$ tctl get db/database-name

예상한 데이터베이스가 보이지 않으면 Discovery Service 문제 해결을 참조합니다.

탐색된 데이터베이스 이름

탐색된 데이터베이스의 이름은 <instance>-cloudsql-<region>-<project-id> 형식이며, 예를 들면 my-postgres-cloudsql-us-central1-my-project입니다. 인스턴스 이름에 이미 포함된 접미사 부분은 Teleport가 제외합니다.

전체 이름과 인스턴스 이름 모두 tsh 및 tctl 명령에서 사용할 수 있습니다. tsh db ls와 tctl db ls는 --verbose를 지정하지 않으면 인스턴스 이름을 표시합니다. 인스턴스 이름이 둘 이상의 데이터베이스와 일치하면 전체 이름을 사용합니다.

인스턴스에 teleport-database-name 사용자 라벨을 적용하면 이름이 재정의됩니다. Teleport는 접미사 없이 해당 값을 그대로 사용하며, 인스턴스 이름은 더 이상 그 이름의 별칭으로 작동하지 않습니다. 이 값은 유효하고 고유한 Teleport 데이터베이스 이름이어야 하며, 유효하지 않은 값이 있는 인스턴스는 Teleport가 건너뜁니다.

탐색된 데이터베이스에 적용되는 라벨은 Google Cloud 데이터베이스 라벨 레퍼런스를 참조합니다.

엔드포인트 선택

인스턴스에 엔드포인트가 여러 개 있으면 Teleport는 퍼블릭, 프라이빗(PSA), PSC 순서로 사용 가능한 첫 번째 엔드포인트를 등록합니다. 이 선택을 재정의하려면 Cloud SQL 인스턴스의 teleport-database-endpoint-type 사용자 라벨을 public, private 또는 psc로 설정합니다. 재정의가 설정되어 있으면 Teleport는 다른 엔드포인트 유형을 시도하지 않습니다.

Database Service 호스트는 Teleport가 등록하는 엔드포인트에 연결할 수 있어야 합니다. 퍼블릭 IP라면 호스트의 송신 IP 주소도 인스턴스의 승인된 네트워크에 포함되어야 합니다.

5/6단계. Database Service 배포#

Teleport 구성 파일 생성#

다음 구성은 공유 시크릿 조인 토큰을 사용합니다. Google Compute Engine VM에서 Database Service를 실행하는 경우, 공유 시크릿 없이 조인할 수 있는 GCP 조인 방식을 대신 사용할 수 있습니다.

Database Service를 실행할 호스트에 teleport.yaml 구성 파일을 생성합니다.

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "teleport.example.com:443"
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
db_service:
  enabled: true
  resources:
    - labels:
        "teleport.dev/origin": "cloud"
        "teleport.dev/cloud": "GCP"
        "teleport.dev/discovery-type": "cloudsql"
        "project-id": "my-project"
        "region": "us-central1"

Discovery Service는 등록하는 모든 데이터베이스에 teleport.dev/origin: cloud 라벨을 추가합니다. 이 예시에서 db_service.resources는 해당 라벨과 다른 셀렉터를 사용하여 my-project 및 us-central1에서 자동으로 탐색된 Cloud SQL 데이터베이스를 일치시킵니다. 일치하는 각 db 리소스에 대해 Database Service는 수명이 짧은 db_server 리소스를 생성하며, 이 리소스는 해당 db에 대한 연결을 프록시할 준비가 되었음을 Teleport 클러스터에 알립니다.

Warning

Database Service 인스턴스가 실제로 도달할 수 있는 데이터베이스에만 매칭되도록, 필요한 경우 더 구체적인 레이블 셀렉터를 사용하십시오. 광범위한 셀렉터는 도달할 수 없는 데이터베이스가 등록되게 하여 연결 실패로 이어질 수 있습니다.

조인 토큰 생성#

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

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

Database Service 시작#

systemd 서비스를 생성하여 호스트가 부팅될 때 the Database Service이 자동으로 시작되도록 구성합니다. 지침은 the Database Service을 어떻게 설치했는지에 따라 다릅니다.

Package Manager

the Database Service을 실행할 호스트에서 Teleport를 활성화하고 시작합니다:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

TAR Archive

the Database Service을 실행할 호스트에서 Teleport용 systemd 서비스 구성을 생성하고, Teleport 서비스를 활성화한 후 Teleport를 시작합니다:

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

systemctl status teleport로 the Database Service의 상태를 확인하고 journalctl -fu teleport로 로그를 볼 수 있습니다.

6/6단계. 데이터베이스 서버 나열#

Database Service가 탐색된 데이터베이스에 대한 서버를 등록했는지 확인합니다.

$ tctl db ls teleport.dev/origin=cloud,teleport.dev/cloud=GCP,teleport.dev/discovery-type=cloudsql,project-id=my-project,region=us-central1

예상한 데이터베이스가 없으면 Database Service 문제 해결을 참조합니다.

문제 해결#

Discovery Service 문제 해결#

먼저 database가 검색되었는지 확인합니다. 이를 위해 tctl get db 명령을 사용하여 예상되는 database가 이미 Teleport 클러스터에 등록되었는지 확인할 수 있습니다.

일부 database가 목록에 나타나지 않는다면, Discovery Service 셀렉터 레이블이 누락된 database 태그와 일치하는지 확인하거나 Discovery Service 로그에서 권한 오류를 살펴보십시오.

Discovery Service가 올바른 AWS 계정의 자격 증명으로 실행되고 있는지 확인합니다. 다른 AWS 계정의 리소스를 검색할 수 있지만, 그런 경우에는 해당 다른 AWS 계정에서 역할을 assume하도록 구성되어 있어야 합니다.

둘 이상의 Discovery Service가 실행 중인지 확인합니다:

$ tctl inventory status --connected

여러 Discovery Service를 실행하는 경우, 동일한 클라우드 database를 감시하는 서비스들은 모두 동일한 discovery_group 값으로 구성하고, 서로 다른 클라우드 database를 감시하는 서비스들은 서로 다른 값으로 구성해야 합니다. 이것이 올바르게 구성되지 않으면, 일반적인 증상으로 db 리소스가 Teleport 클러스터의 레지스트리에서 간헐적으로 삭제됩니다.

Database Service 문제 해결#

tctl db ls에 데이터베이스가 나타나지 않음#

tctl get db 명령이 예상한 검색된 데이터베이스를 반환하지만 tctl db ls 명령에는 포함되지 않는 경우, db_service.resources 섹션이 올바르게 설정되어 있는지 확인하세요. 예를 들면 다음과 같습니다:

db_service:
  enabled: true
  resources:
  - labels:
      "env": "prod"

섹션이 올바르게 구성되어 있는데도 데이터베이스가 여전히 나타나지 않는다면, Teleport에서 데이터베이스를 나열할 올바른 권한이 있는지 확인하세요. 데이터베이스 레이블과 일치하고 db 및 db_server 오브젝트에 대해 "read" 및 "list" verb를 허용하는 Teleport 역할이 있어야 합니다. 다음은 클러스터의 모든 데이터베이스에 대해 해당 권한을 부여하는 예시입니다:

kind: role
version: v6
metadata:
  name: view-all-databases
spec:
  allow:
    db_labels:
      '*': '*'
    rules:
      - resources: [db_server, db]
        verbs: [read, list]

데이터베이스에 연결할 때 오류 발생#

Note

이 섹션에서는 Enroll AWS Databases의 특정 가이드를 따라 이미 데이터베이스 사용자를 프로비저닝하고 해당 데이터베이스 사용자에 대한 Teleport RBAC를 구성했다고 가정합니다.

데이터베이스에 연결하려고 할 때 연결 오류가 발생하면, 먼저 대상 데이터베이스에 대해 여러 개의 db_server 하트비트 리소스가 있는지 확인하세요: tctl get db_server/yourDatabaseName. 여러 개가 있다면 여러 Teleport Database Service 인스턴스가 데이터베이스를 프록시하고 있다는 의미이며, 이는 문제 해결을 복잡하게 만드는 HA 구성입니다. Teleport는 연결을 프록시할 Database Service 인스턴스 중 하나를 무작위로 선택하며, 그중 하나가 데이터베이스 엔드포인트에 연결할 수 없거나 권한이 부족한 경우 무작위 연결 오류가 발생합니다.

연결 오류가 일관되게 발생하더라도, 오류를 해결하는 동안에는 대상 db와 일치하는 인스턴스가 하나만 남도록 Teleport Database Service 인스턴스를 축소하거나 재구성해야 합니다. tctl get db_server/yourDatabaseName으로 db_server가 하나만 있는지 확인한 다음 다시 연결을 시도하세요.

DEBUG 레벨 로깅을 활성화한 상태에서 Teleport Database Service 로그를 확인하고 네트워크 또는 권한 오류를 찾아보세요.

보다 일반적인 문제 해결 단계는 Database Service 문제 해결 가이드를 참고하세요.

또한 Enroll AWS Databases에서 데이터베이스 유형에 특화된 가이드에 더 구체적인 문제 해결 정보가 있을 수 있습니다.

다음 단계#