Teleport는 AlloyDB 인스턴스에 IAM 데이터베이스 인증을 사용합니다.

인스턴스가 IAM 인증을 사용하도록 구성되어 있는지 확인합니다. 인스턴스 설정으로 이동하여 고급 구성 옵션 섹션에서 alloydb.iam_authentication 플래그가 있는지 확인합니다.

또는 해당 서비스 계정의 키 탭으로 이동하여 새 키를 생성합니다.

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

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

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

teleport.yaml에서 데이터베이스를 구성하는 대신 동적 데이터베이스 리소스를 생성할 수 있습니다. 이를 통해 Database Service를 재시작하지 않고 데이터베이스를 추가하거나 업데이트할 수 있습니다.

다음 내용으로 alloydb.yaml이라는 파일을 생성합니다:

kind: db
version: v3
metadata:
  name: alloydb-dynamic
  labels:
    env: dev
spec:
  protocol: "postgres"
  uri: "alloydb://


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

5/5단계: 데이터베이스에 연결#
데이터베이스에 대한 액세스 권한 부여#
Note
다음 명령은 새 Teleport 사용자와 역할을 생성합니다. env: dev 레이블이 있는 리소스에 대한 액세스 권한을 부여하는 기존 Teleport 사용자와 역할이 있는 경우 이 단계를 건너뛸 수 있습니다.









Flag
Description




--roles
List of roles to assign to the user. The builtin access role allows them to connect to any database server registered with Teleport.


--db-users
List of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user.


--db-names
List of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database.




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

연결#
Database Service가 클러스터에 연결된 후 사용 가능한 데이터베이스를 보려면 로그인합니다:
$ tsh login --proxy=teleport.example.com --user=alice
$ tsh db ls
# Name    Description Labels
# ------- ----------- -------
# alloydb GCP AlloyDB env=dev

Note
Teleport 역할이 액세스할 수 있는 데이터베이스만 볼 수 있습니다. 자세한 내용은 RBAC 가이드를 참고하세요.

데이터베이스에 연결할 때 IAM 데이터베이스 사용자로 추가한 데이터베이스 서비스 계정의 이름을 사용하고,
.gserviceaccount.com 접미사를 뺍니다. 데이터베이스 사용자 이름은 AlloyDB 인스턴스의 사용자 페이지에 표시됩니다.
아래 명령에서 를 Google Cloud 프로젝트 ID로 교체합니다. alloydb 예시 데이터베이스의 자격 증명을 검색하고 연결합니다:
$ tsh db connect --db-user=alloydb-user@.iam --db-name=postgres alloydb

Tip
버전 17.1부터 웹 UI를 통해 PostgreSQL 데이터베이스에 액세스할 수 있습니다.

데이터베이스에서 로그아웃하고 자격 증명을 제거하려면:
# 특정 데이터베이스 인스턴스의 자격 증명을 제거합니다:
$ tsh db logout alloydb
# 또는 모든 데이터베이스의 자격 증명을 제거합니다:
$ tsh db logout

선택 사항: 최소 권한 액세스#
가능한 경우 필요한 권한만 부여하는 사용자 지정 IAM 역할을 정의하여 최소 권한을 적용합니다.
Teleport Database Service를 위한 사용자 지정 역할#
teleport-db-service 서비스 계정으로 실행되는 Teleport Database Service는 AlloyDB 인스턴스에 액세스하기 위한 권한이 필요합니다.
다음 권한으로 사용자 지정 역할을 생성합니다:
# 클라이언트 인증서 생성에 사용됨
alloydb.clusters.generateClientCertificate
# 연결 정보 가져오기에 사용됨
alloydb.instances.connect

alloydb-user 서비스 계정을 가장하기 위해 기본 제공 "서비스 계정 토큰 생성자" IAM 역할은 필요 이상으로 광범위합니다. 해당 서비스 계정에 대한 권한을 제한하려면 다음만 포함하는 사용자 지정 역할을 생성합니다:
iam.serviceAccounts.getAccessToken

데이터베이스 사용자를 위한 사용자 지정 역할#
데이터베이스 액세스에 사용되는 alloydb-user 서비스 계정은 인스턴스에 연결하고 데이터베이스 사용자로 인증하기 위한 권한이 필요합니다. 다음을 포함하는 사용자 지정 역할을 생성합니다:
alloydb.instances.connect
alloydb.users.login
serviceusage.services.use

문제 해결#

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.


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.


SSL SYSCALL error#
You may encounter the following error when your local psql is not compatible
with newer versions of 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

Please upgrade your local psql to the latest version.

다음 단계#



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.





AlloyDB의 IAM 인증 관리에 대해 자세히 알아보세요.


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


AlloyDB Auth Proxy에 대해 자세히 알아보세요.