Add Redis docs #10693

jakule · 2022-03-01T07:34:58Z

Documentation for Redis integration, covers:

Self-hosted Redis and Redis Cluster configuration
Redis Insight GUI configuration

Related to #10053

benarent · 2022-03-02T18:57:36Z

docs/pages/database-access/guides/redis.mdx

+    hostname, run:
+
+    ```code
+    $ tctl auth sign --format=redis --host=redis.example.com --out=server --ttl=2190h


Any reason we default to 3 months? Am I correct in thinking that after 3 months the Redis integration would no longer work.

@benarent It requires you to generate a new cert, but we're using the same value in all our DB integrations, example from Mongo https://goteleport.com/docs/ver/9.0/database-access/guides/mysql-self-hosted/
If we want to change it I think we should create a separate issue and change the ttl for all integrations.

@r0mant @smallinsky Any comments?

Not sure why 2190h was picked but agree that If we want to change that we should do this be a separate PR where values for all DBs will be updated.

ptgott · 2022-03-03T20:14:45Z

docs/pages/database-access/guides/redis.mdx

+This guide will help you to:
+
+- Install and configure Teleport.
+- Configure mutual TLS authentication between Teleport and your Redis database.


I only have some brief firsthand experience with Redis, but I usually see it described as an in-memory data store rather than a database. Does "database" refer to a specific configuration of Redis, or can this guide also apply to Redis when configured as a cache (i.e. with maxmemory and eviction policies set), or even other possibilities like Redis streams?

In other words, would it make more sense to just say "Redis" or "your Redis deployment," rather than "your Redis database"?

I think that "Redis" makes sense in most places. I was thinking about using "Redis instance" as this is confusing when referring to Redis in cluster.

docs/pages/database-access/guides/redis.mdx

ptgott · 2022-03-03T20:21:28Z

docs/pages/database-access/guides/redis.mdx

+ACL GENPASS
+```
+
+or use OpenSSL if you have it installed on your machine


When do we recommend using OpenSSL vs. ACL GENPASS?

So this I think is the tricky one. Redis documentation recommends using ACL GENPASS to generate password. The problem with this is that you need a Redis running to run that command, so it's not the best advice when you're reading a guide on how to setup a Redis cluster and you're at the beginning, but I wanted to mention it somehow that Redis has such option (I don't mind removing it if you think it's confusing). The best idea that I have is to use OpenSSL to generate password, as I'd assume that now everyone knows how to create a "good password".

@r0mant @smallinsky Any objections?

no, I think that mentioning ACL GENPASS if fine.

docs/pages/database-access/guides/redis.mdx

docs/pages/database-access/guides/gui-clients.mdx

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

docs/pages/database-access/guides/redis.mdx

smallinsky · 2022-03-07T13:08:00Z

docs/pages/database-access/guides/redis.mdx

+  export CERTS_DIR=/path/to/certs/
+
+  redis-cli --user alice --cluster-replicas 1 --tls --cluster-yes \
+  --cluster create ${IP1}:7001 ${IP2}:7002 ${IP3}:7003 ${IP4}:7004 ${IP5}:7005 ${IP6}:7006 \


Don't see any IP1= bash calls so at first glance the reference to unset $IP1 var is a bit misleading.

I agree, but I've got no better idea rather than add a note with something like "export your Redis IPs as environment variables IP1...IP6". Do you think that would help or for example using some "fake" IPs in this case make more sense?

r0mant · 2022-03-09T21:16:59Z

docs/config.json

@@ -454,6 +454,10 @@
              "title": "SQL Server (Preview)",
              "slug": "/database-access/guides/sql-server-ad/"
            },
+            {
+              "title": "Self-Hosted Redis",


Nit: Maybe move this above SQL Server section? To keep it grouped with other self-hosted guides and also move the preview SQL Server to the bottom.

docs/pages/database-access/guides/redis.mdx

Update Redis docs

Co-authored-by: Paul Gottschling <[email protected]>

Co-authored-by: Marek Smoliński <[email protected]>

ptgott · 2022-03-10T18:11:12Z

docs/pages/database-access/guides/gui-clients.mdx

+
+Click `Add Database Manually`. Use `127.0.0.1` as the `Host` and port printed by `tsh proxy db`.
+
+<Admonition type="note">


Should this Admonition be regular text that comes before the "Click..." instruction above? Otherwise, readers will need to follow these instructions out of order.

I'll move it.

ptgott · 2022-03-10T18:15:09Z

docs/pages/database-access/guides/gui-clients.mdx

+
+![Redis Insight Startup Screen](../../../img/database-access/guides/redis/redisinsight-startup.png)
+
+Click `Add Database Manually`. Use `127.0.0.1` as the `Host` and port printed by `tsh proxy db`.


I'm not sure what the second sentence means. Does tsh proxy db return a port to include in a Redis Insight field? If so, we should change this to:

Run the following command to start a proxy that you can use to connect to your Redis instance: \`\`\`code (remove the escapes) $ tsh proxy db \`\`\` Copy the port returned from this command and use it for the `Port` field. Use `127.0.0.1` for the `Host` field.

This is not that simple. First you need to login to the database. Then call the tsh db proxy. This is explained at the top of the page https://goteleport.com/docs/database-access/guides/gui-clients/#get-connection-information. I don't think it's needed to repeat it here. I can add a link to the top of that page to make it more clear.

ptgott · 2022-03-10T18:17:22Z

docs/pages/database-access/guides/gui-clients.mdx

+
+![Redis Insight Configuration](../../../img/database-access/guides/redis/redisinsight-add-config.png)
+
+Next, check the `Use TLS` and `Verify TLS Certificates` boxes and copy the CA certificate returned by `tsh proxy db`.


We should include the instructions to copy the certificate when we first tell the reader to run tsh proxy db. Otherwise, they may have cleared the terminal at this point. (Unless the proxy runs in the foreground? I haven't run this command myself.)

Yes, tsh proxy runs in the foreground. Here is an example:

% tsh proxy db redis Started DB proxy on 127.0.0.1:51823 Use following credentials to connect to the redis proxy: ca_file=/Users/jnyckowski/.tsh/keys/example.com/cas/example.com.pem cert_file=/Users/jnyckowski/.tsh/keys/example.com/bob-db/example.com/redis-x509.pem key_file=/Users/jnyckowski/.tsh/keys/example.com/bob

That's helpful, thanks. To make this clearer, I think we should replace line 210 with something like the following (removing the code fence escapes):

Run the following command to start the Database Access proxy for your Redis instance. \`\`\`code $ tsh proxy db redis Started DB proxy on 127.0.0.1:51823 Use following credentials to connect to the redis proxy: ca_file=path/to/example.com.pem cert_file=path/to/example.com/redis-x509.pem key_file=path/to/example.com/bob \`\`\` In Redis Insight, click `Add Database Manually`. Use `127.0.0.1` as the `Host`. Copy the port printed by `tsh proxy db` and use it for the `Port` field.

docs/pages/database-access/guides/redis.mdx

ptgott · 2022-03-10T18:43:07Z

docs/pages/database-access/guides/redis.mdx

+in the Redis documentation for more details.
+
+<Admonition type="note" title="Create Redis Cluster">
+  When you're configuring Redis Cluster you need to create the cluster using `redis-cli`.


Suggested change

When you're configuring Redis Cluster you need to create the cluster using `redis-cli`.

When you're configuring Redis Cluster to use the TLS credentials we generated earlier, you need to create the cluster using `redis-cli`.

It took me a second to realize why this Admonition was being included here. I suggested linking it to the preceding text more strongly.

I don't think this sentence is correct. This step is needed as the final cluster configuration step and it's not related to the TLS keys that we generated earlier. Check my comment below about splitting the docs. I think this should help.

That sounds good to me!

ptgott · 2022-03-10T18:46:01Z

docs/pages/database-access/guides/redis.mdx

+  </TabItem>
+</Tabs>
+
+To connect to a particular database instance, first retrieve its certificate


From here until the "Supported Redis commands" header, nearly every line appears to be another box, which makes this part of the guide slightly hard to read. I think we can remove the <Admonition></Admonition> tags from the tip and the two notes while preserving the text as regular body text.

I personally think that the current version is hard to follow and it's easy to miss a step as there are many "Only Redis Cluster" blocks. What do you think about splitting this guide into two: Redis and Redis Cluster as a separate pages?

That sounds good to me! What do you think, @r0mant @smallinsky?

I have no objections. We can have "Redis Standalone" and "Redis Cluster" pages.

docs/pages/database-access/guides/redis.mdx

Co-authored-by: Paul Gottschling <[email protected]>

r0mant

@jakule Let's merge this and backport so it doesn't block the release and then split the guide in Standalone/Cluster pages as a follow up.

Add Redis documentation on how to setup Redis. Co-authored-by: Paul Gottschling <[email protected]> Co-authored-by: Marek Smoliński <[email protected]>

Add Redis documentation. Backport #10693 to branch/v9 Co-authored-by: Paul Gottschling <[email protected]> Co-authored-by: Marek Smoliński <[email protected]>

jakule added the backport-required label Mar 1, 2022

jakule marked this pull request as ready for review March 2, 2022 06:47

github-actions bot added the documentation label Mar 2, 2022

github-actions bot requested review from ptgott, r0mant, xinding33 and zmb3 March 2, 2022 06:48

jakule added the docs-new label Mar 2, 2022

jakule requested a review from smallinsky March 2, 2022 06:49

benarent mentioned this pull request Mar 2, 2022

We are missing Redis, MariaDB, Microsoft SQL Server from DB Dropdown #10757

Closed

benarent reviewed Mar 2, 2022

View reviewed changes

ptgott reviewed Mar 3, 2022

View reviewed changes

jakule mentioned this pull request Mar 3, 2022

Redis GA #10820

Open

4 tasks

smallinsky reviewed Mar 7, 2022

View reviewed changes

jakule force-pushed the jakule/redis-docs branch from e298b8d to 9e2c7c9 Compare March 8, 2022 06:51

jakule requested a review from ptgott March 8, 2022 06:51

smallinsky approved these changes Mar 9, 2022

View reviewed changes

r0mant mentioned this pull request Mar 9, 2022

Teleport 9.0 Release Plan #10447

Closed

38 tasks

r0mant approved these changes Mar 9, 2022

View reviewed changes

jakule and others added 11 commits March 9, 2022 17:33

Add Redis docs draft

533a92f

Add Redis GUI photos

50374ec

Update Redis docs

Update Redis docs.

3bbb5bd

Update Redis docs.

d0fb641

Update Redis docs.

c674ff9

Linter fixes

3e1a4b9

Apply suggestions from code review

4633f40

Co-authored-by: Paul Gottschling <[email protected]>

Fixes after review.

2e51a0f

Update docs/pages/database-access/guides/redis.mdx

870b018

Co-authored-by: Marek Smoliński <[email protected]>

Added password hash generation example.

101f9cc

Use tabled to describe processed commands in Redis Cluster

781d9ad

jakule added 2 commits March 9, 2022 17:33

Address code review comments.

e1d05f6

Address code review comments.

80117ee

jakule force-pushed the jakule/redis-docs branch from f2732bf to 80117ee Compare March 9, 2022 22:52

ptgott reviewed Mar 10, 2022

View reviewed changes

jakule and others added 2 commits March 10, 2022 14:35

Apply suggestions from code review

03d5c31

Co-authored-by: Paul Gottschling <[email protected]>

Update Redis GUI

4dcc90c

jakule requested a review from ptgott March 10, 2022 21:05

Merge branch 'master' into jakule/redis-docs

dc57790

r0mant approved these changes Mar 11, 2022

View reviewed changes

Merge branch 'master' into jakule/redis-docs

d0f3b82

jakule enabled auto-merge (squash) March 11, 2022 18:01

ptgott approved these changes Mar 11, 2022

View reviewed changes

jakule merged commit 86ad572 into master Mar 11, 2022

jakule deleted the jakule/redis-docs branch March 11, 2022 18:05

jakule added a commit that referenced this pull request Mar 11, 2022

Add Redis docs (#10693)

53398c3

Add Redis documentation on how to setup Redis. Co-authored-by: Paul Gottschling <[email protected]> Co-authored-by: Marek Smoliński <[email protected]>

jakule mentioned this pull request Mar 11, 2022

[v9] Add Redis docs #11073

Merged

jakule added a commit that referenced this pull request Mar 11, 2022

Add Redis docs (#11073)

404ff79

Add Redis documentation. Backport #10693 to branch/v9 Co-authored-by: Paul Gottschling <[email protected]> Co-authored-by: Marek Smoliński <[email protected]>

ptgott mentioned this pull request Mar 14, 2022

Split the Redis Database Access guide #11130

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Redis docs #10693

Add Redis docs #10693

jakule commented Mar 1, 2022 •

edited

Loading

benarent Mar 2, 2022

jakule Mar 3, 2022

smallinsky Mar 7, 2022

ptgott Mar 3, 2022

jakule Mar 3, 2022

ptgott Mar 3, 2022

jakule Mar 7, 2022

smallinsky Mar 9, 2022

smallinsky Mar 7, 2022

jakule Mar 7, 2022

r0mant Mar 9, 2022

ptgott Mar 10, 2022

jakule Mar 10, 2022

ptgott Mar 10, 2022

jakule Mar 10, 2022

ptgott Mar 10, 2022

jakule Mar 10, 2022

ptgott Mar 11, 2022

ptgott Mar 10, 2022

jakule Mar 10, 2022

ptgott Mar 11, 2022

ptgott Mar 10, 2022

jakule Mar 10, 2022

ptgott Mar 11, 2022

r0mant Mar 11, 2022

r0mant left a comment


		Click `Add Database Manually`. Use `127.0.0.1` as the `Host` and port printed by `tsh proxy db`.

		<Admonition type="note">


		![Redis Insight Startup Screen](../../../img/database-access/guides/redis/redisinsight-startup.png)

		Click `Add Database Manually`. Use `127.0.0.1` as the `Host` and port printed by `tsh proxy db`.


		![Redis Insight Configuration](../../../img/database-access/guides/redis/redisinsight-add-config.png)

		Next, check the `Use TLS` and `Verify TLS Certificates` boxes and copy the CA certificate returned by `tsh proxy db`.

	When you're configuring Redis Cluster you need to create the cluster using `redis-cli`.
	When you're configuring Redis Cluster to use the TLS credentials we generated earlier, you need to create the cluster using `redis-cli`.

Add Redis docs #10693

Add Redis docs #10693

Conversation

jakule commented Mar 1, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

r0mant left a comment

Choose a reason for hiding this comment

jakule commented Mar 1, 2022 •

edited

Loading