From 357112e3e82be2c0b320bd64db641cc94e2a2cca Mon Sep 17 00:00:00 2001 From: stevenGravy Date: Sat, 9 Nov 2024 07:02:18 -0500 Subject: [PATCH 1/4] docs: update azure postgres mysql --- .../azure-postgres-mysql.mdx | 260 +++++++++--------- 1 file changed, 137 insertions(+), 123 deletions(-) diff --git a/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx b/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx index 464041d58c8d1..b12d3baa097df 100644 --- a/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx +++ b/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx @@ -35,135 +35,15 @@ database. Service. - (!docs/pages/includes/tctl.mdx!) -## Step 1/5. Install the Teleport Database Service -(!docs/pages/includes/tctl-token.mdx serviceName="Database" tokenType="db" tokenFile="/tmp/token"!) - -Install Teleport on the host where you will run the Teleport Database Service: - -(!docs/pages/includes/install-linux.mdx!) - -Create the Database Service configuration. - - - - -- Specify the region for your database(s) in `--azure-postgres-discovery`. - -- Replace the `--proxy` value with your Teleport proxy address or Teleport cloud - URI (e.g. `mytenant.teleport.sh:443`): - - ```code - $ sudo teleport db configure create \ - -o file \ - --proxy=teleport.example.com:443 \ - --token=/tmp/token \ - --azure-postgres-discovery=eastus - ``` - - - - -- Specify the region for your database(s) in `--azure-mysql-discovery`. - -- Replace the `--proxy` value with your Teleport proxy address or Teleport cloud - URI (e.g. `mytenant.teleport.sh:443`): - - ```code - $ sudo teleport db configure create \ - -o file \ - --proxy=teleport.example.com:443 \ - --token=/tmp/token \ - --azure-mysql-discovery=eastus - ``` - - - - - -Run the following command on your Database Service host: - - ```code - $ sudo teleport db configure create \ - -o file \ - --proxy=teleport.example.com:443 \ - --token=/tmp/token \ - --azure-mysql-discovery=eastus \ - --azure-postgres-discovery=eastus - ``` - - -This will create two `types` entities in `teleport.yaml`, one for each database -type. This is useful if you want different regions, tags, or labels for each -database type. - -Alternatively, you can edit `teleport.yaml` to include both database types in a -single entry: - -```yaml -db_service: - azure: - - types: ["mysql", "postgres"] - ... -``` - - - - - - - -This command will generate a Database Service configuration with Azure MySQL/Postgres -database auto-discovery enabled in the `eastus` region and place it at the -`/etc/teleport.yaml` location. - -### Create a Teleport role - -On your workstation logged in to your Teleport cluster with `tsh`, define a new -role to provide access to your Azure database. Create a file called `azure-database-role.yaml` with the following content: - -```yaml -version: v7 -kind: role -metadata: - name: azure-database-access -spec: - allow: - db_labels: - 'engine': - - "Microsoft.DBforMySQL/servers" - - "Microsoft.DBforMySQL/flexibleServers" - - "Microsoft.DBforPostgreSQL/servers" - - "Microsoft.DBforPostgreSQL/flexibleServers" - db_names: - - '*' - db_users: - - teleport -``` - -| Flag | Description | -|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------| -| `--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. | -| `--db-labels` | List of labels assigned to the database the user will be able to access. A wildcard entry allows any database. | - -Save this file and apply it to your Teleport cluster: - -```code -$ tctl create -f azure-database-role.yaml -role 'azure-database-role.yaml' has been created -``` - -(\!docs/pages/includes/add-role-to-user.mdx role="azure-database-access" \!) - -## Step 2/5. Configure Azure service principal +## Step 1/5. Configure Azure service principal To authenticate with PostgreSQL or MySQL databases, Teleport Database Service needs to obtain access tokens from Azure AD. (!docs/pages/includes/database-access/azure-configure-service-principal.mdx!) -## Step 3/5. Configure IAM permissions for Teleport +## Step 2/5. Configure IAM permissions for Teleport ### Create a custom role @@ -228,7 +108,7 @@ and replace the subscription in "assignableScopes" with your own subscription id (!docs/pages/includes/database-access/azure-assign-service-principal.mdx!) -## Step 4/5. Create Azure database users +## Step 3/5. Create Azure database users To let Teleport connect to your Azure database authenticating as a service principal, you need to create Azure AD users authenticated by that principal in the database. @@ -367,6 +247,140 @@ GRANT ALL ON `%`.* TO 'teleport'@'%'; You can create multiple database users identified by the same service principal. +## Step 4/5. Install the Teleport Database Service + +(!docs/pages/includes/tctl-token.mdx serviceName="Database" tokenType="db" tokenFile="/tmp/token"!) + +Install Teleport on the host where you will run the Teleport Database Service: + +(!docs/pages/includes/install-linux.mdx!) + +Create the Database Service configuration. + + + + +- Specify the region for your database(s) in `--azure-postgres-discovery`. + +- Replace the `--proxy` value with your Teleport proxy address or Teleport cloud + URI (e.g. `mytenant.teleport.sh:443`): + + ```code + $ sudo teleport db configure create \ + -o file \ + --proxy=teleport.example.com:443 \ + --token=/tmp/token \ + --azure-postgres-discovery=eastus + ``` + + + + +- Specify the region for your database(s) in `--azure-mysql-discovery`. + +- Replace the `--proxy` value with your Teleport proxy address or Teleport cloud + URI (e.g. `mytenant.teleport.sh:443`): + + ```code + $ sudo teleport db configure create \ + -o file \ + --proxy=teleport.example.com:443 \ + --token=/tmp/token \ + --azure-mysql-discovery=eastus + ``` + + + + + +Run the following command on your Database Service host: + + ```code + $ sudo teleport db configure create \ + -o file \ + --proxy=teleport.example.com:443 \ + --token=/tmp/token \ + --azure-mysql-discovery=eastus \ + --azure-postgres-discovery=eastus + ``` + + +This will create two `types` entities in `teleport.yaml`, one for each database +type. This is useful if you want different regions, tags, or labels for each +database type. + +Alternatively, you can edit `teleport.yaml` to include both database types in a +single entry: + +```yaml +db_service: + azure: + - types: ["mysql", "postgres"] + ... +``` + + + + + + + +This command will generate a Database Service configuration with Azure MySQL/Postgres +database auto-discovery enabled in the `eastus` region and place it at the +`/etc/teleport.yaml` location. + +### Create a Teleport role + +On your workstation logged in to your Teleport cluster with `tsh`, define a new +role to provide access to your Azure database. Create a file called `azure-database-role.yaml` with the following content: + +```yaml +version: v7 +kind: role +metadata: + name: azure-database-access +spec: + allow: + db_labels: + 'engine': + - "Microsoft.DBforMySQL/servers" + - "Microsoft.DBforMySQL/flexibleServers" + - "Microsoft.DBforPostgreSQL/servers" + - "Microsoft.DBforPostgreSQL/flexibleServers" + db_names: + - '*' + db_users: + - teleport +``` + +| Flag | Description | +|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| `--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. | +| `--db-labels` | List of labels assigned to the database the user will be able to access. A wildcard entry allows any database. | + +Save this file and apply it to your Teleport cluster: + +```code +$ tctl create -f azure-database-role.yaml +role 'azure-database-role.yaml' has been created +``` + +(\!docs/pages/includes/add-role-to-user.mdx role="azure-database-access" \!) + +### Start Teleport Database Service + +(!docs/pages/includes/start-teleport.mdx service="the Teleport Database Service"!) + + + A single Teleport process can run multiple different services, for example + multiple Database Service agents as well as the SSH Service or Application + Service. + + ## Step 5/5. Connect Log in to your Teleport cluster. Your Azure database should appear in the list of From 85b33db90813d25e657dd8f99627f1f858c06b86 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Mon, 11 Nov 2024 15:14:00 -0500 Subject: [PATCH 2/4] docs: azure postgres mysql verbiage update Co-authored-by: Paul Gottschling --- .../enroll-azure-databases/azure-postgres-mysql.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx b/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx index b12d3baa097df..81edaa8058e5a 100644 --- a/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx +++ b/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx @@ -262,8 +262,8 @@ Create the Database Service configuration. - Specify the region for your database(s) in `--azure-postgres-discovery`. -- Replace the `--proxy` value with your Teleport proxy address or Teleport cloud - URI (e.g. `mytenant.teleport.sh:443`): +- Replace the `--proxy` value with your Teleport Proxy Service address or Teleport Enterprise (Cloud) + URI (e.g. `example.teleport.sh:443`): ```code $ sudo teleport db configure create \ @@ -278,8 +278,8 @@ Create the Database Service configuration. - Specify the region for your database(s) in `--azure-mysql-discovery`. -- Replace the `--proxy` value with your Teleport proxy address or Teleport cloud - URI (e.g. `mytenant.teleport.sh:443`): +- Replace the `--proxy` value with your Teleport Proxy Service address or Teleport Enterprise (Cloud) + URI (e.g. `example.teleport.sh:443`): ```code $ sudo teleport db configure create \ From edaffc4c2bc6cff3738de376775d269f56e4a4a6 Mon Sep 17 00:00:00 2001 From: Steven Martin Date: Mon, 11 Nov 2024 15:15:26 -0500 Subject: [PATCH 3/4] docs: remove admonition wrapper on instrs --- .../enroll-azure-databases/azure-postgres-mysql.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx b/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx index 81edaa8058e5a..b639ab2a0673a 100644 --- a/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx +++ b/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx @@ -304,7 +304,6 @@ Run the following command on your Database Service host: --azure-postgres-discovery=eastus ``` - This will create two `types` entities in `teleport.yaml`, one for each database type. This is useful if you want different regions, tags, or labels for each database type. @@ -319,8 +318,6 @@ db_service: ... ``` - - From 45a5a8a4db3130a374bb8194e975d3e28dd1c4fa Mon Sep 17 00:00:00 2001 From: stevenGravy Date: Mon, 11 Nov 2024 16:52:21 -0500 Subject: [PATCH 4/4] update links for generated content --- .../helm-reference/zz_generated.teleport-kube-agent.mdx | 2 +- examples/chart/teleport-kube-agent/values.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/includes/helm-reference/zz_generated.teleport-kube-agent.mdx b/docs/pages/includes/helm-reference/zz_generated.teleport-kube-agent.mdx index 175e6693b56fb..1ebd25154c1f9 100644 --- a/docs/pages/includes/helm-reference/zz_generated.teleport-kube-agent.mdx +++ b/docs/pages/includes/helm-reference/zz_generated.teleport-kube-agent.mdx @@ -266,7 +266,7 @@ annotations: `azureDatabases` configures Azure database auto-discovery. - For Azure database auto-discovery to work, your Database Service pods will need to have appropriate IAM permissions as per the [database documentation](../../enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx#step-35-configure-iam-permissions-for-teleport). + For Azure database auto-discovery to work, your Database Service pods will need to have appropriate IAM permissions as per the [database documentation](../../enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx#step-25-configure-iam-permissions-for-teleport). After configuring a service principal with appropriate IAM permissions, you must pass credentials to the pods. The easiest way is to use an Azure client secret. diff --git a/examples/chart/teleport-kube-agent/values.yaml b/examples/chart/teleport-kube-agent/values.yaml index beb0d284b1efe..0286db419342f 100644 --- a/examples/chart/teleport-kube-agent/values.yaml +++ b/examples/chart/teleport-kube-agent/values.yaml @@ -219,7 +219,7 @@ awsDatabases: [] # azureDatabases(list) -- configures Azure database auto-discovery. # -# For Azure database auto-discovery to work, your Database Service pods will need to have appropriate IAM permissions as per the [database documentation](../../enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx#step-35-configure-iam-permissions-for-teleport). +# For Azure database auto-discovery to work, your Database Service pods will need to have appropriate IAM permissions as per the [database documentation](../../enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx#step-25-configure-iam-permissions-for-teleport). # # After configuring a service principal with appropriate IAM permissions, you must pass credentials to the pods. # The easiest way is to use an Azure client secret.