Teleport can provide secure access to MySQL on Google Cloud SQL via the Teleport Database Service. This allows for fine-grained access control through Teleport's RBAC.

In this guide, you will:

1. Configure your MySQL on Google Cloud SQL database with a service account.
2. Add the database to your Teleport cluster.
3. Connect to the database via Teleport.

작동 방식#

The Teleport Database Service uses IAM authentication to communicate with MySQL. When a user connects to the database via Teleport, the Teleport Database Service obtains Google Cloud credentials and authenticates to Google Cloud as an IAM principal with permissions to access the database.

사전 요구 사항#

• 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:

• Google Cloud 계정
• Teleport Database Service를 실행할 호스트(예: Compute Engine 인스턴스)

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.

1/9단계. Teleport Database Service를 위한 서비스 계정 생성#

(!docs/pages/includes/database-access/cloudsql-create-service-account-for-db-service.mdx !)

(선택 사항) 권한 부여#

The Teleport Database Service needs permissions to automatically download your Cloud SQL instance's root CA certificate and to general an ephemeral client certificate.

If you intend to download the CA certificate manually and your Cloud SQL instance SSL mode is not "require trusted client certificates", then you can skip this step.

Otherwise, in the second step of the service account creation dialogue, assign the service account the pre-defined GCP IAM role "Cloud SQL Client", then click "Done".

# Used to auto-download the instance's root CA certificate and check SSL mode.
cloudsql.instances.get
# Used to generate an ephemeral client certificate
cloudsql.instances.connect

(선택 사항) 사용자 유형 확인 권한 부여#

사용자가 Teleport를 통해 Cloud SQL 데이터베이스에 연결할 때 데이터베이스 사용자로 사용할 서비스 계정의 이름을 지정해야 합니다. 서비스 계정의 짧은 이름 또는 전체 이메일을 사용할 수 있습니다. 예를 들어 계정 이메일이 cloudsql-user@project.iam.gserviceaccount.com인 경우 전체 이메일 대신 "cloudsql-user"를 사용할 수 있습니다.

그러나 서비스 계정의 짧은 이름을 사용하는 경우 Teleport는 사용해야 할 인증 종류를 결정하기 위한 권한이 필요합니다: IAM 인증 또는 레거시 일회용 비밀번호 인증. 이 권한이 없으면 기본적으로 일회용 비밀번호 사용을 시도합니다. 서비스 계정의 짧은 이름으로 IAM 인증을 지원하려면 다음 권한이 필요합니다:

# 데이터베이스 사용자 유형 확인에 사용됨.
cloudsql.users.get

미리 정의된 "Cloud SQL 뷰어" 역할에 이 권한이 있지만 필요하지 않은 다른 권한도 있습니다. 최소 권한 원칙을 따르려면 서비스 계정에 사용자 지정 역할을 정의하고 바인딩합니다.

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

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

Create a service account#

Go to the IAM & Admin Service Accounts page and create a new service account named "cloudsql-user":

Click "Create and continue".

Grant permissions#

On the second step grant this service account the "Cloud SQL Instance User" role which will allow it to connect to Cloud SQL instances using an IAM token for authentication:

Click "Done".

Grant access to the service account#

The Teleport Database Service must be able to impersonate this service account. Navigate to the "cloudsql-user" service account overview page and select the "permissions" tab:

Click "Grant Access" and add the "teleport-db-service" principal ID. Select the "Service Account Token Creator" role and save the change:

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

Cloud SQL IAM 인증 활성화#

Teleport는 Cloud SQL MySQL 인스턴스에 IAM 인증을 사용합니다.

If you're creating a new MySQL instance, make sure to add the cloudsql.iam_authentication database flag under "Customize your instance / Flags" section:

To check whether IAM authentication is enabled for an existing Cloud SQL instance, look for the flag on the Configuration panel on the instance's Overview page:

If it isn't enabled, you can add this flag using the "Edit configuration" dialog at the bottom of the Configuration panel. Changing this setting may require a database instance reboot.

(선택 사항) SSL 모드 "신뢰할 수 있는 클라이언트 인증서 요구"#

Cloud SQL MySQL에서 "신뢰할 수 있는 클라이언트 인증서 요구"를 활성화하여 사용하는 경우 Teleport는 기본 Cloud SQL MySQL 리스너가 생성된 임시 인증서를 신뢰하지 않으므로 기본 포트 3306 대신 Cloud SQL Proxy 포트 3307을 통해 데이터베이스에 연결합니다. 이러한 이유로 "신뢰할 수 있는 클라이언트 인증서 요구"를 사용할 때 포트 3307을 허용해야 합니다.

데이터베이스 사용자 생성#

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

"추가"를 누릅니다. 자세한 내용은 Google Cloud 문서의 IAM 사용자 생성 및 관리를 참고하세요.

4/9단계. Teleport 설치#

To install a Teleport Agent on your Linux server:

The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

1. Assign to your Teleport cluster hostname and port, but not the scheme (https://).

2. Run your cluster's install script:

   $ curl "https:///scripts/install.sh" | sudo bash
   

5/9단계. Teleport Database Service 구성#

조인 토큰 생성#

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=)

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

The Cloud SQL instance's root CA certificate is required so that the Teleport Database Service can validate the certificate presented by the database instance.

The Teleport Database Service can automatically download the instance's root CA certificate if it is granted the "cloudsql.instances.get" permission.

Alternatively, you can download the instance's CA certificate file from the "Connections" tab under the "Security" section:

Teleport 구성 생성#

This command will generate a Teleport Database Service configuration file and save it to /etc/teleport.yaml.

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

The Teleport Database Service must have credentials for the "teleport-db-service" GCP service account.

If the Teleport Database Service is hosted on a GCE instance, you can change the attached service account. For non-GCE deployments of Teleport, we recommend using workload identity.

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

7/9단계. Teleport Database Service 시작#

Configure the Teleport Database Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport Database Service.

You can check the status of the Teleport Database Service with systemctl status teleport and view its logs with journalctl -fu teleport.

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

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

9/9단계. 연결#

Teleport Database Service가 클러스터에 연결된 후 사용 가능한 데이터베이스를 보려면 로그인합니다:

$ tsh login --proxy=teleport.example.com --user=alice
$ tsh db ls
# Name     Description         Labels
# -------- ------------------- --------
# cloudsql GCP Cloud SQL MySQL env=dev

$ tsh login --proxy=mytenant.teleport.sh --user=alice
$ tsh db ls
# Name     Description         Labels
# -------- ------------------- --------
# cloudsql GCP Cloud SQL MySQL env=dev

데이터베이스에 연결할 때 데이터베이스 사용자 이름 또는 서비스 계정의 이메일 ID를 사용합니다. 사용자 이름과 서비스 계정의 이메일 ID는 Cloud SQL 인스턴스의 사용자 페이지에 표시됩니다. "cloudsql" 예시 데이터베이스의 자격 증명을 검색하고 연결합니다. 를 Google Cloud 프로젝트 ID로 할당합니다:

# 데이터베이스 사용자 서비스 계정의 짧은 이름으로 연결:
$ tsh db connect --db-user=cloudsql-user --db-name=mysql cloudsql
# 또는 전체 이메일 ID로 연결:
$ tsh db connect --db-user=cloudsql-user@.iam.gserviceaccount.com --db-name=mysql cloudsql

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

# 특정 데이터베이스 인스턴스의 자격 증명을 제거합니다:
$ tsh db logout cloudsql
# 또는 모든 데이터베이스의 자격 증명을 제거합니다:
$ tsh db logout

문제 해결#

복제본 인스턴스에 연결할 때 오류#

복제본 인스턴스에 연결할 때 다음 오류가 발생할 수 있습니다:

$ tsh db connect --db-user=cloudsql-user --db-name=test cloudsql-replica
ERROR 1105 (HY000): Could not update Cloud SQL user "<username>" password:

  The requested operation is not valid for a replica instance.

...

비밀번호가 있는 기본 제공 데이터베이스 사용자로의 연결은 Cloud SQL 복제본 인스턴스에서 지원되지 않습니다. 대신 IAM 인증을 사용하려면 이 가이드를 따르세요.

Could not find default credentials#

This error can come from either your client application or Teleport.

For a client application, ensure that you disable GCP credential loading. Your client should not attempt to load credentials because GCP credentials will be provided by the Teleport Database Service.

If you see the credentials error message in the Teleport Database Service logs (at DEBUG log level), then the Teleport Database Service does not have GCP credentials configured correctly.

If you are using a service account key, then ensure that the environment variable GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json is set and restart your Teleport Database Service to ensure that the env var is available to teleport. For example, if your Teleport Database Service runs as a systemd service:

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

See authentication in the Google Cloud documentation for more information about service account authentication methods.

다음 단계#

• 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.

• Google Cloud에서 서비스 계정으로 인증하기에 대해 자세히 알아보세요.