From 94199acc9278cedff64fc75e9c47bf27ee10955d Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 7 Apr 2022 11:16:54 -0400 Subject: [PATCH] Edit the Database Access GUI guide for Cloud users See #10637 - Add a Prerequisites section with tabs for different scopes - Use a ScopedBlock so the "Get connection information" section only shows connection options that are relevant to a particular scope. - Where the guide refers to a particular "tsh" command that doesn't apply to all scopes, refer to the "Get connection information" section instead. - Light copy-edits for style, clarity, and grammar --- .../database-access/guides/gui-clients.mdx | 176 ++++++++++++++---- 1 file changed, 142 insertions(+), 34 deletions(-) diff --git a/docs/pages/database-access/guides/gui-clients.mdx b/docs/pages/database-access/guides/gui-clients.mdx index 9e881f6b6bb51..876d7edc1922a 100644 --- a/docs/pages/database-access/guides/gui-clients.mdx +++ b/docs/pages/database-access/guides/gui-clients.mdx @@ -3,12 +3,80 @@ title: Database Access GUI Clients description: How to configure graphical database clients for Teleport Database Access. --- -# Graphical Database Clients - -This article describes how to configure popular graphical database clients to +This guide describes how to configure popular graphical database clients to work with Teleport Database Access. -## Get connection information +## Setting up your Teleport environment + +### Prerequisites + +Ensure that your environment includes the following: + + + + +- A running Teleport cluster. For details on how to set this up, see one of our + [Getting Started](/docs/getting-started) guides. + +- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + $ tsh version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + See [Installation](/docs/installation.mdx) for details. + + + + +- A running Teleport cluster. For details on how to set this up, see our Enterprise + [Getting Started](/docs/enterprise/getting-started) guide. + +- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=), + which you can download by visiting the + [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + + + +- A Teleport Cloud account. If you do not have one, visit the + [sign up page](https://goteleport.com/signup/) to begin your free trial. + +- The `tctl` admin tool and `tsh` client tool version >= (=cloud.version=). + To download these tools, visit the [Downloads](/docs/cloud/downloads) page. + + ```code + $ tctl version + # Teleport v(=cloud.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=cloud.version=) go(=teleport.golang=) + ``` + + + + +- The Teleport Database Service configured to access a database. See one of our + [guides](../guides.mdx) for how to set up Teleport Database Access for your + database. + + +### Get connection information + + @@ -61,6 +129,28 @@ TLS authentication. + + + +Use the following command to start a local TLS proxy your GUI database client +will be connecting to: + +```code +$ tsh proxy db +Started DB proxy on 127.0.0.1:61740 + +Use following credentials to connect to the proxy: + ca_file=/Users/r0mant/.tsh/keys/root.gravitational.io/certs.pem + cert_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice-db/root/-x509.pem + key_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice +``` + +Use the displayed local proxy host/port and credentials paths when configuring +your GUI client below. When entering the hostname, use `localhost` rather than +`127.0.0.1`. + + + ## PostgreSQL pgAdmin 4 [pgAdmin 4](https://www.pgadmin.org/) is a popular graphical client for @@ -90,17 +180,19 @@ for password, leave the password field empty and click OK. ## MySQL Workbench -[MySQL Workbench](https://www.mysql.com/products/workbench/) is a visual tool -that provides comprehensive MySQL administration and SQL development tools. +[MySQL Workbench](https://www.mysql.com/products/workbench/) is a GUI +application that provides comprehensive MySQL administration and SQL development +tools. -In MySQL Workbench "Setup New Connection" dialog, fill out "Connection Name", -"Hostname", "Port", and "Username": +In the MySQL Workbench "Setup New Connection" dialog, fill out "Connection +Name", "Hostname", "Port", and "Username": ![MySQL Workbench Parameters](../../../img/database-access/workbench-parameters@2x.png) -In the "SSL" tab, set "Use SSL" to `Require and Verify Identity` and enter paths -to your CA, certificate, and private key files from `tsh db config` command: +In the "SSL" tab, set "Use SSL" to `Require and Verify Identity` and enter the +paths to your CA, certificate, and private key files (see +[Get connection information](./gui-clients.mdx#get-connection-information)): ![MySQL Workbench SSL](../../../img/database-access/workbench-ssl@2x.png) @@ -108,39 +200,49 @@ Optionally, click "Test Connection" to verify connectivity: ![MySQL Workbench Test](../../../img/database-access/workbench-test@2x.png) -Save the connection, and connect to the database. +Save the connection and connect to the database. ## MySQL DBeaver - Teleport's DBeaver MySQL integration only supports MySQL server (=mysql.dbeaver_min_ver=) or older. + + Teleport's DBeaver MySQL integration only supports MySQL server + (=mysql.dbeaver_min_ver=) or older. + Right-click in the "Database Navigator" menu in the main view and select Create > Connection: ![DBeaver Add Server](../../../img/database-access/dbeaver-add-server.png) -In the search bar of the "Connect to a database" window that opens up type "mysql", select the MySQL driver, and click "Next": +In the search bar of the "Connect to a database" window that opens up, type "mysql", select the MySQL driver, and click "Next": ![DBeaver Select Driver](../../../img/database-access/dbeaver-select-driver.png) -In the newly-opened "Connection Settings" Main tab copy the `Server Host` and `Port` from the `tsh db config` output into the DBeaver config fields: +In the newly-opened "Connection Settings" tab, copy the `Server Host` and `Port` from the `tsh db config` output into the DBeaver config fields: ![DBeaver Select Configure Server](../../../img/database-access/dbeaver-configure-server.png) -In that same tab set the username to match the one that you are connecting to using the Teleport db certs and uncheck the 'Save password locally' box: +In that same tab, set the username to match the one that you are connecting to +using Teleport and uncheck the "Save password locally" box: ![DBeaver Select Configure User](../../../img/database-access/dbeaver-configure-user.png) -Click the "Edit Driver Settings" button on the "Main" tab, check the "No Authentication" box, and click "Ok" to save: +Click the "Edit Driver Settings" button on the "Main" tab, check the "No +Authentication" box, and click "Ok" to save: ![DBeaver Driver Settings](../../../img/database-access/dbeaver-driver-settings.png) -Once you are back in the "Connection Settings" window navigate to the "Driver Properties" tab, scroll down to find the `enabledTLSProtocols` field and enter "TLSv1.2" into the `Value` field: +Once you are back in the "Connection Settings" window, navigate to the "Driver +Properties" tab, scroll down to find the `enabledTLSProtocols` field and enter +"TLSv1.2" into the `Value` field: ![DBeaver TLS Settings](../../../img/database-access/dbeaver-tls-settings.png) -Navigate to the "SSL" tab, check the "Use SSL" box, uncheck the "Verify Server Certificates" box, and copy the `CA Certificate`, `Client Certificate`, and `Client Private Key` paths from the `tsh db config` output: +Navigate to the "SSL" tab, check the "Use SSL" box, uncheck the "Verify Server +Certificates" box, and copy the `CA Certificate`, `Client Certificate`, and +`Client Private Key` paths from the output of the `tsh` command you ran at the +beginning of this guide: ![DBeaver SSL](../../../img/database-access/dbeaver-ssl.png) @@ -155,15 +257,17 @@ On the "New Connection" panel, click on "Fill in connection fields individually" ![MongoDB Compass new connection](../../../img/database-access/compass-new-connection@2x.png) -On the "Hostname" tab, enter your Teleport proxy's hostname and port shown -by `tsh db config`. Leave "Authentication" as None. +On the "Hostname" tab, enter the hostname and port of the proxy you will use to +access the database (see +[Get connection information](./gui-clients.mdx#get-connection-information)). +Leave "Authentication" as None. ![MongoDB Compass hostname](../../../img/database-access/compass-hostname@2x.png) -On the "More Options" tab set SSL to "Client and Server Validation" and set -CA as well as client key and certificate. Note the CA path must be provided -and be able to validate certificate presented by your Teleport proxy's web -endpoint. Client key and certificate locations are shown by `tsh db config`. +On the "More Options" tab, set SSL to "Client and Server Validation" and set the +CA as well as the client key and certificate. Note that a CA path must be +provided and be able to validate the certificate presented by your Teleport +Proxy Service's web endpoint. ![MongoDB Compass more options](../../../img/database-access/compass-more-options@2x.png) @@ -171,11 +275,12 @@ Click on the "Connect" button. ## SQL Server DBeaver -(!docs/pages/includes/database-access/sql-server-local-proxy.mdx!) +In the DBeaver connection configuration menu, use your proxy's endpoint. This is +`localhost:4242` in the example above. (See +[Get connection information](./gui-clients.mdx#get-connection-information) for +more information.) -In DBeaver connection configuration use the local proxy's endpoint (`localhost:4242` -in the example above) as host/port. Use SQL Server Authentication option and keep -the Password field empty: +Use the SQL Server Authentication option and keep the Password field empty: ![DBeaver connection options](../../../img/database-access/guides/sqlserver/dbeaver-connection@2x.png) @@ -183,15 +288,17 @@ Click OK to connect. ## SQL Server DataGrip -(!docs/pages/includes/database-access/sql-server-local-proxy.mdx!) +In the DataGrip connection configuration menu, use your proxy's endpoint. This +is `localhost:4242` in the example below. (See +[Get connection information](./gui-clients.mdx#get-connection-information) for +more information.) -In DataGrip connection configuration use the local proxy's endpoint (`localhost:4242` -in the example above) as host/port. Use Use & Password authentication option and -keep the Password field empty: +Select the "User & Password" authentication option and keep the "Password" field +empty: ![DataGrip connection options](../../../img/database-access/guides/sqlserver/datagrip-connection@2x.png) -Click OK to connect. +Click "OK" to connect. ## Redis Insight @@ -207,7 +314,8 @@ Log in to your Redis instance with a Redis user first by using: `tsh db login --db-user=alice redis-db-name`. -Click `Add Database Manually`. Use `127.0.0.1` as the `Host` and port printed by `tsh proxy db` as described [here](#get-connection-information). +Click `Add Database Manually`. Use `127.0.0.1` as the `Host`. Use the port printed by +the `tsh` command you ran in [Get connection information](#get-connection-information). Provide your Redis username as `Username` and password as `Password`.