From f865fa0f6e2b9dfcd1ec314f6c818aa93dedf3dc Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Wed, 27 May 2026 16:28:54 -0400 Subject: [PATCH] docs: Update db docs (#67141) * docs: Update db docs * docs: Fix formatting * docs: fix formatting Co-authored-by: Tener --------- Co-authored-by: Tener --- .../auto-user-provisioning/postgres.mdx | 3 +-- .../enrollment/azure/azure-sql-server-ad.mdx | 16 ++++++++-------- .../enrollment/google-cloud/alloydb.mdx | 2 +- .../self-hosted/clickhouse-self-hosted.mdx | 4 ++-- .../enrollment/self-hosted/redis-cluster.mdx | 1 - .../database-access/guides/health-checks.mdx | 12 ++++++------ .../database-access/reference/cli.mdx | 2 +- .../database-access/reference/labels.mdx | 2 +- .../database-access/troubleshooting.mdx | 4 ++-- .../connection-timeout-troubleshooting.mdx | 2 +- 10 files changed, 23 insertions(+), 25 deletions(-) diff --git a/docs/pages/enroll-resources/database-access/auto-user-provisioning/postgres.mdx b/docs/pages/enroll-resources/database-access/auto-user-provisioning/postgres.mdx index 3181f96d20f..cf9eb47bfc0 100644 --- a/docs/pages/enroll-resources/database-access/auto-user-provisioning/postgres.mdx +++ b/docs/pages/enroll-resources/database-access/auto-user-provisioning/postgres.mdx @@ -46,8 +46,7 @@ GRANT rds_iam TO "teleport-admin" WITH ADMIN OPTION; Note that the RDS database must have IAM authentication enabled. -Refer to the [AWS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html) to make sure you are using the `rds_iam` role correctly. -for more information. +Refer to the [AWS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html) to make sure you are using the `rds_iam` role correctly for more information. If the admin user needs to grant the `rds_superuser` role to auto-provisioned users, the admin user must also be a `rds_superuser`: diff --git a/docs/pages/enroll-resources/database-access/enrollment/azure/azure-sql-server-ad.mdx b/docs/pages/enroll-resources/database-access/enrollment/azure/azure-sql-server-ad.mdx index 07fffeec03f..9f76d8c8820 100644 --- a/docs/pages/enroll-resources/database-access/enrollment/azure/azure-sql-server-ad.mdx +++ b/docs/pages/enroll-resources/database-access/enrollment/azure/azure-sql-server-ad.mdx @@ -1,7 +1,7 @@ --- title: Database Access with Azure SQL Server sidebar_label: SQL Server -description: How to configure Teleport database access with Azure SQL Server using Microsoft Entra authentication. +description: How to configure Teleport database access with Azure SQL Server using Microsoft Entra ID authentication. tags: - how-to - zero-trust @@ -22,10 +22,10 @@ forwards user traffic to the database. -![Access Azure SQL Server Microsoft Entra Self-Hosted](../../../../../img/database-access/guides/sqlserver/sql-aad.png) +![Access Azure SQL Server Microsoft Entra ID Self-Hosted](../../../../../img/database-access/guides/sqlserver/sql-aad.png) -![Access Azure SQL Server Microsoft Entra Cloud](../../../../../img/database-access/guides/sqlserver/cloud-sql-aad.png) +![Access Azure SQL Server Microsoft Entra ID Cloud](../../../../../img/database-access/guides/sqlserver/cloud-sql-aad.png) @@ -44,12 +44,12 @@ forwards user traffic to the database. (!docs/pages/includes/database-access/create-user.mdx!) -## Step 2/8. Enable the Microsoft Entra authentication +## Step 2/8. Enable the Microsoft Entra ID authentication If you have it enabled, you can go to the next step. Go to the [Azure Portal](https://portal.azure.com/), select **Database -servers**, and select the database you wish to enable the Microsoft Entra +servers**, and select the database you wish to enable the Microsoft Entra ID authentication. Select **Microsoft Entra ID** under "Settings" in the left-hand column. @@ -57,7 +57,7 @@ Select **Microsoft Entra ID** under "Settings" in the left-hand column. Select **Set Admin**, and choose an account that will be added as an admin login to SQL Server. -![Azure SQL Server Microsoft Entra admin page](../../../../../img/database-access/guides/sqlserver/azure-set-ad-admin.png) +![Azure SQL Server Microsoft Entra ID admin page](../../../../../img/database-access/guides/sqlserver/azure-set-ad-admin.png) ## Step 3/8. Configure IAM permissions for Teleport @@ -167,7 +167,7 @@ The Microsoft Entra ID SQL Server integration uses database-level authentication database we want to access. To create contained users for the identities, connect to your SQL server using -its Activity Directory Admin and execute the query: +its Active Directory Admin and execute the query: ```sql USE MyDatabase; @@ -288,4 +288,4 @@ To check if the VM has access, you can do the following on the VM: (!docs/pages/includes/database-access/guides-next-steps.mdx!) ## Further reading -- [Microsoft Entra authentication for Azure SQL](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-overview?view=azuresql) +- [Microsoft Entra ID authentication for Azure SQL](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-overview?view=azuresql) diff --git a/docs/pages/enroll-resources/database-access/enrollment/google-cloud/alloydb.mdx b/docs/pages/enroll-resources/database-access/enrollment/google-cloud/alloydb.mdx index 090f754d6fd..67a8c6bc8c4 100644 --- a/docs/pages/enroll-resources/database-access/enrollment/google-cloud/alloydb.mdx +++ b/docs/pages/enroll-resources/database-access/enrollment/google-cloud/alloydb.mdx @@ -287,7 +287,7 @@ endpoint instead, set `endpoint_type` in the config: ```yaml db_service: - resources: + databases: - name: alloydb protocol: postgres uri: alloydb://projects/PROJECT-ID/locations/REGION/clusters/CLUSTER/instances/INSTANCE diff --git a/docs/pages/enroll-resources/database-access/enrollment/self-hosted/clickhouse-self-hosted.mdx b/docs/pages/enroll-resources/database-access/enrollment/self-hosted/clickhouse-self-hosted.mdx index a770542c3c1..93084ec619d 100644 --- a/docs/pages/enroll-resources/database-access/enrollment/self-hosted/clickhouse-self-hosted.mdx +++ b/docs/pages/enroll-resources/database-access/enrollment/self-hosted/clickhouse-self-hosted.mdx @@ -196,8 +196,8 @@ databases: - name: example-clickhouse uri: clickhouse.example.com:8443 protocol: -tags: - env: dev + static_labels: + env: dev ``` To configure the Teleport Database Service to trust a custom CA: diff --git a/docs/pages/enroll-resources/database-access/enrollment/self-hosted/redis-cluster.mdx b/docs/pages/enroll-resources/database-access/enrollment/self-hosted/redis-cluster.mdx index 074ffaabbdd..74337bcfc0c 100644 --- a/docs/pages/enroll-resources/database-access/enrollment/self-hosted/redis-cluster.mdx +++ b/docs/pages/enroll-resources/database-access/enrollment/self-hosted/redis-cluster.mdx @@ -183,7 +183,6 @@ returns the `ERR Teleport: command not supported` error. - `PSUBSCRIBE` - `PSYNC` - `PUNSUBSCRIBE` -- `PUNSUBSCRIBE` - `READONLY` - `READWRITE` - `REPLCONF` diff --git a/docs/pages/enroll-resources/database-access/guides/health-checks.mdx b/docs/pages/enroll-resources/database-access/guides/health-checks.mdx index 0c056662541..42b3387d635 100644 --- a/docs/pages/enroll-resources/database-access/guides/health-checks.mdx +++ b/docs/pages/enroll-resources/database-access/guides/health-checks.mdx @@ -156,19 +156,19 @@ You can use `tctl` to view target health information in `db_server.status.target $ tctl get db_server/example-postgres-db | yq -y .status target_health: # address is the database address. - address: "localhost:5432", + address: "localhost:5432" # message is additional information meant for a user. message: "1 health check failed" # protocol is the health check connection protocol, such as "TCP". - protocol: "TCP", + protocol: "TCP" # status is the health status, one of "unknown", "healthy", or "unhealthy". - status: "unhealthy", + status: "unhealthy" # transition_reason is a unique reason for the last transition: one of "initialized", "disabled", "threshold_reached", or "internal_error". - transition_reason: "threshold_reached", + transition_reason: "threshold_reached" # transition_timestamp is the time that the last status transition occurred. - transition_timestamp: "2025-06-09T22:40:24.147753Z", + transition_timestamp: "2025-06-09T22:40:24.147753Z" # transition_error shows the health check error observed when the transition to "unhealthy" happened. - transition_error: "dial tcp 127.0.0.1:5432: connect: connection refused", + transition_error: "dial tcp 127.0.0.1:5432: connect: connection refused" ``` ## Troubleshooting diff --git a/docs/pages/enroll-resources/database-access/reference/cli.mdx b/docs/pages/enroll-resources/database-access/reference/cli.mdx index 5165b648b20..f18188d3a3c 100644 --- a/docs/pages/enroll-resources/database-access/reference/cli.mdx +++ b/docs/pages/enroll-resources/database-access/reference/cli.mdx @@ -66,7 +66,7 @@ $ teleport db start \ | `--fips` | Start Teleport in FedRAMP/FIPS mode. | | `--name` | Name of the proxied database. | | `--description` | Description of the proxied database. | -| `--protocol` | Proxied database protocol. Supported are: `postgres` and `mysql`. | +| `--protocol` | Proxied database protocol. Supported are: `postgres`, `mysql`, `mongodb`, `oracle`, `cockroachdb`, `redis`, `snowflake`, `sqlserver`, `cassandra`, `elasticsearch`, `opensearch`, `dynamodb`, `clickhouse`, `clickhouse-http` and `spanner`. | | `--uri` | Address the proxied database is reachable at. | | `--ca-cert` | Database CA certificate path. | | `--aws-region` | (Only for RDS, Aurora or Redshift) AWS region RDS, Aurora or Redshift database instance is running in. | diff --git a/docs/pages/enroll-resources/database-access/reference/labels.mdx b/docs/pages/enroll-resources/database-access/reference/labels.mdx index 36b19f2c3b1..425cfa781d3 100644 --- a/docs/pages/enroll-resources/database-access/reference/labels.mdx +++ b/docs/pages/enroll-resources/database-access/reference/labels.mdx @@ -19,7 +19,7 @@ of the following values: | Label Value | Description | | - | - | | `cloud` | database resources created by auto-discovery. | -| `config` | database resources manually defined in the `database_service.databases` section of `teleport.yaml`. | +| `config` | database resources manually defined in the `db_service.databases` section of `teleport.yaml`. | | `dynamic` | database resources created through [dynamic registration](../../../enroll-resources/database-access/guides/dynamic-registration.mdx) like `tctl create` command. | ## Auto-discovery diff --git a/docs/pages/enroll-resources/database-access/troubleshooting.mdx b/docs/pages/enroll-resources/database-access/troubleshooting.mdx index fdd6b33c855..f2efba0a956 100644 --- a/docs/pages/enroll-resources/database-access/troubleshooting.mdx +++ b/docs/pages/enroll-resources/database-access/troubleshooting.mdx @@ -125,7 +125,7 @@ We can update a user's roles from the command-line by using either `tctl users u $ tctl users update alice@example.com --set-roles=access ``` - + Open Alice's user resource in your text editor: @@ -159,7 +159,7 @@ access see the [RBAC](../database-access/rbac.mdx) documentation. ### Connection to MySQL database results in "Unknown system variable 'query_cache_size'" error -When TLS Routing is disable by default, the Teleport Proxy Service returns `8.0.0-Teleport` as the MySQL server version. In some cases, like connecting with a GUI Client, this can result in obtaining an `Unknown system variable 'query_cache_size'` error that indicates that MySQL capabilities were not properly negotiated between the MySQL client and server. +When TLS Routing is disabled by default, the Teleport Proxy Service returns `8.0.0-Teleport` as the MySQL server version. In some cases, like connecting with a GUI Client, this can result in obtaining an `Unknown system variable 'query_cache_size'` error that indicates that MySQL capabilities were not properly negotiated between the MySQL client and server. One way to solve this issue is to [use the TLS Routing feature](../../zero-trust-access/management/tls-routing.mdx), where the Teleport Proxy diff --git a/docs/pages/includes/database-access/connection-timeout-troubleshooting.mdx b/docs/pages/includes/database-access/connection-timeout-troubleshooting.mdx index 11863643c11..08d26cdf19b 100644 --- a/docs/pages/includes/database-access/connection-timeout-troubleshooting.mdx +++ b/docs/pages/includes/database-access/connection-timeout-troubleshooting.mdx @@ -31,7 +31,7 @@ For deployments in AWS, it may be helpful to use [AWS Reachability Analyzer](htt If your database is registered dynamically or via auto-discovery, repeat the -above connectivity test for *every** Teleport Database Service instance that +above connectivity test for **every** Teleport Database Service instance that proxies this database. To list all Teleport Database Service instances associated with a given database, run the `tctl get db_server/` command. For example: