azure mysql postgres auto discovery docs

docs/pages/database-access/guides/azure-postgres-mysql.mdx

@@ -10,8 +10,8 @@ description: How to configure Teleport Database Access with Azure Database for P
   scopeOnly={true}
   min="8.1"
 >
-  Database access for Azure PostgreSQL/MySQL is available starting from Teleport
-  `8.1`.
+  Static configuration of database access for Azure PostgreSQL/MySQL is available starting from Teleport
+  `8.1` and Azure database auto-discovery is available starting from Teleport `10.2`.
 </Details>
 
 This guide will help you to:
@@ -44,7 +44,7 @@ This guide will help you to:
 
 (!docs/pages/includes/user-client-prereqs.mdx!)
 
-## Step 1/4. Install and configure Teleport
+## Step 1/5. Install and configure Teleport
 
 ### Set up the Teleport Auth and Proxy Services
 
@@ -58,36 +58,30 @@ Install Teleport on the host where you will run the Teleport Database Service:
 
 (!docs/pages/includes/install-linux.mdx!)
 
-<ScopedBlock scope={["oss", "enterprise"]}>
+Create the Database Service configuration, specifying a region like this:
 
-Start the Teleport Database Service. Make sure to update `--auth-server` to point to
-your Teleport Proxy Service address and `--uri` to the Azure database server
-endpoint.
+<ScopedBlock scope={["oss", "enterprise"]}>
 
 <Tabs>
 <TabItem label="PostgreSQL">
 
   ```code
-  $ teleport db start \
+  $ teleport db configure create \
+    -o file \
+    --proxy=tele.example.com:443 \
     --token=/tmp/token \
-    --auth-server=teleport.example.com:3080 \
-    --name=azure-db \
-    --protocol=postgres \
-    --uri=example.postgres.database.azure.com:5321 \
-    --labels=env=dev
+    --azure-postgres-discovery=eastus
   ```
 
 </TabItem>
 <TabItem label="MySQL">
 
   ```code
-  $ teleport db start \
+  $ teleport db configure create \
+    -o file \
+    --proxy=teleport.example.com:3080 \
     --token=/tmp/token \
-    --auth-server=teleport.example.com:3080 \
-    --name=azure-db \
-    --protocol=mysql \
-    --uri=example.mysql.database.azure.com:3306 \
-    --labels=env=dev
+    --azure-mysql-discovery=eastus
   ```
 
 </TabItem>
@@ -96,51 +90,42 @@ endpoint.
 </ScopedBlock>
 <ScopedBlock scope={["cloud"]}>
 
-Start the Teleport Database Service. Make sure to update `--auth-server` to point to
-your Teleport Cloud tenant address and `--uri` to the Azure database server
-endpoint.
-
 <Tabs>
 <TabItem label="PostgreSQL">
 
   ```code
-  $ teleport db start \
+  $ teleport db configure create \
+    -o file \
+    --proxy=teleport.example.com:3080 \
     --token=/tmp/token \
-    --auth-server=mytenant.teleport.sh:443 \
-    --name=azure-db \
-    --protocol=postgres \
-    --uri=example.postgres.database.azure.com:5321 \
-    --labels=env=dev
+    --azure-postgres-discovery=eastus
   ```
 
 </TabItem>
 <TabItem label="MySQL">
 
   ```code
-  $ teleport db start \
+  $ teleport db configure create \
+    -o file \
+    --proxy=teleport.example.com:3080 \
     --token=/tmp/token \
-    --auth-server=mytenant.teleport.sh:443 \
-    --name=azure-db \
-    --protocol=mysql \
-    --uri=example.mysql.database.azure.com:3306 \
-    --labels=env=dev
+    --azure-mysql-discovery=eastus
   ```
 
 </TabItem>
 </Tabs>
 
 </ScopedBlock>
 
-<Admonition type="tip">
-  You can start the Teleport Database Service using a configuration file instead of
-  CLI flags. See the [YAML reference](../reference/configuration.mdx).
-</Admonition>
+The 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 user
 
 (!docs/pages/includes/database-access/create-user.mdx!)
 
-## Step 2/4. Configure Azure service principal
+## Step 2/5. Configure Azure service principal
 
 To authenticate with PostgreSQL or MySQL databases, Teleport Database Service
 needs to obtain access tokens from Azure AD. There are a couple of ways to
@@ -203,7 +188,7 @@ achieve that:
   ![Registered app secrets](../../../img/database-access/guides/azure/registered-app-secrets@2x.png)
 
   The Teleport Database Service uses Azure SDK's default credential provider chain to
-  look for credentials. Refer to [Authentication methods](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authorization)
+  look for credentials. Refer to [Azure SDK Authorization](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authorization)
   to pick a method suitable for your use-case. For example, to use
   environment-based authentication with a client secret, the Database Service should
   have the following environment variables set:
@@ -216,10 +201,88 @@ achieve that:
 </TabItem>
 </Tabs>
 
-## Step 3/4. Create Azure database users
+## Step 3/5. Configure IAM permissions for Teleport
+
+### Create a custom role
+
+Teleport needs Azure IAM permissions to discover and register MySQL and PostgreSQL databases.
+Create a role with assignable scope(s) that include all databases that Teleport should discover. For example:
+
+```json
+{
+    "properties": {
+        "roleName": "TeleportDiscovery",
+        "description": "Allows Teleport to discover MySQL and PostgreSQL databases",
+        "assignableScopes": [
+            "/subscriptions/11111111-2222-3333-4444-555555555555"
+        ],
+        "permissions": [
+            {
+                "actions": [
+                    "Microsoft.DBforMySQL/servers/read",
+                    "Microsoft.DBforPostgreSQL/servers/read"
+                ],
+                "notActions": [],
+                "dataActions": [],
+                "notDataActions": []
+            }
+        ]
+    }
+}
+```
+
+This role definition allows Teleport to discover MySQL and PostgreSQL databases, but Teleport only needs 
+permissions for the database types you have. The assignable scopes include a subscription, so
+the role can be assigned at any resource scope within that subscription, or assigned using the
+subscription scope itself.
+
+<Admonition type="note" title="Custom role assignable scope">
+Custom roles, unlike
+[Azure built-in roles](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles),
+can not have a root assignable scope. The highest assignable scope that
+can be used in a custom role is subscription scope. Using a management group scope is currently an Azure
+preview feature, and only allows for a single management group in the "assignableScopes" of a role 
+definition.
+See [Azure RBAC custom roles](https://docs.microsoft.com/en-us/azure/role-based-access-control/custom-roles) for
+more information.
+</Admonition>
+
+Go to the [Subscriptions](https://portal.azure.com/#view/Microsoft_Azure_Billing/SubscriptionsBlade) page and select a subscription.
+
+Click on *Access control (IAM)* in the subscription and select *Add > Add custom role*:
+<Figure align="left">
+![IAM custom role](../../../img/database-access/guides/azure/add-custom-role@2x.png)
+</Figure>
+
+In the custom role creation page, click the *JSON* tab and click *Edit*, then paste the JSON example
+and replace the subscription in "assignableScopes" with your own subscription id:
+<Figure align="left">
+![Create JSON role](../../../img/database-access/guides/azure/create-role-from-json@2x.png)
+</Figure>
+
+### Create a role assignment for the Teleport Database Service principal.
+
+To grant Teleport permissions, the custom role you created must be assigned to the Teleport service principal -
+either the managed identity or the app registration you created earlier.
+
+Navigate to the resource scope where you want to make the role assignment. Click *Access control (IAM)* and 
+select *Add > Add role assignment*. Choose the custom role you created as the role and the Teleport
+service principal as a member.
+
+<Figure align="left">
+![Assign role](../../../img/database-access/guides/azure/create-role-assignment@2x.png)
+</Figure>
+
+<Admonition type="note" title="Azure Role Assignments">
+The role assignment should be at a high enough scope to allow the Teleport Database Service to discover
+all matching databases. See
+[Identify the needed scope](https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-steps#step-3-identify-the-needed-scope)
+for more information about Azure scopes and creating role assignments.
+</Admonition>
+## Step 4/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 for that principal in the database.
+principal, you need to create Azure AD users authenticated by that principal in the database.
 
 ### Assign Azure AD administrator
 
@@ -229,7 +292,13 @@ and set the AD admin using the *Set admin* button:
 
 ![Set AD admin](../../../img/database-access/guides/azure/set-ad-admin@2x.png)
 
-Note that only one AD user can be set as an admin for the database.
+<Admonition type="note" title="Azure AD Admin">
+Only one Azure user (or group) can be set as an Azure AD admin for the database.
+If the Azure AD admin is removed from the server, all Azure AD logins will be disabled for the server.
+Adding a new Azure AD admin from the same tenant will re-enable Azure AD logins.
+Refer to [Use Azure Active Directory for authenticating with PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/concepts-azure-ad-authentication)
+for more information.
+</Admonition>
 
 ### Connect to the database as an AD admin
 
@@ -280,12 +349,19 @@ registrations:
   mysql> CREATE AADUSER 'teleport' IDENTIFIED BY '11111111-2222-3333-4444-555555555555';
   Query OK, 0 rows affected (0.92 sec)
   ```
+
+  The created user may not have access to anything by default so let's grant it
+  some permissions:
+
+  ```sql
+  GRANT ALL ON `%`.* TO 'teleport'@'%';
+  ```
 </TabItem>
 </Tabs>
 
-You can create multiple database users for the same service principal.
+You can create multiple database users identified by the same service principal.
 
-## Step 4/4. Connect
+## Step 5/5. Connect
 
 Log in to your Teleport cluster. Your Azure database should appear in the list of
 available databases:
@@ -330,6 +406,10 @@ To log out of the database and remove credentials:
 $ tsh db logout azure-db
 ```
 
+## Troubleshooting
+
+(!docs/pages/includes/database-access/azure-troubleshooting.mdx!)
+
 ## Next steps
 
 (!docs/pages/includes/database-access/guides-next-steps.mdx!)

docs/pages/includes/database-access/azure-troubleshooting.mdx

@@ -0,0 +1,19 @@
+### No credential providers error
+
+If you see the error `DefaultAzureCredential: failed to acquire a token.` in Database Service logs then Teleport
+is not detecting the required credentials to connect to the Azure SDK. Check whether
+the credentials have been applied in the machine running the Teleport Database Service and restart
+the Teleport Database Service.
+Refer to [Azure SDK Authorization](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authorization)
+for more information.
+
+### Timeout errors
+
+The Teleport Database Service needs connectivity to your database endpoints. That may require
+enabling inbound traffic on the database from the Database Service on the same VPC or routing rules from another VPC. Using the `nc`
+program you can verify connections to databases:
+
+```code
+$ nc -zv server-name.postgres.database.azure.com 5432
+# Connection to server-name.postgres.database.azure.com 5432 port [tcp/postgresql] succeeded!
+```

docs/pages/includes/database-access/database-config.yaml

@@ -21,6 +21,26 @@ db_service:
     tags:
       "*": "*"
 
+  # Matchers for registering Azure-hosted databases.
+  azure:
+    # Database types. Valid options are:
+    # 'mysql' - discovers and registers Azure MySQL single-server databases.
+    # 'postgres' - discovers and registers Azure PostgreSQL single-server databases.
+  - types: ["mysql", "postgres"]
+    # Azure regions to register databases from. Valid options are:
+    # '*' - discovers databases in all regions (default).
+    # Any valid Azure region name. List all valid regions using the Azure "az" cli: `az account list-locations -o table`
+    regions: ["eastus", "westus"]
+    # Azure subscription IDs to register databases from. Valid options are:
+    # '*' - discovers databases in all subscriptions (default).
+    subscriptions: ["11111111-2222-3333-4444-555555555555"]
+    # Azure resource groups to register databases from. Valid options are:
+    # '*' - discovers databases in all resource groups within configured subscription(s) (default).
+    resource_groups: ["group1", "group2"]
+    # Azure resource tags to match when registering databases.
+    tags:
+      "*": "*"
+
   # Lists statically registered databases proxied by this agent.
   databases:
     # Name of the database proxy instance, used to reference in CLI.