Skip to content

Commit

Permalink
Split Redis docs (#11702)
Browse files Browse the repository at this point in the history 
* Split Redis docs to Redis Standalone and Cluster for better readability.

Backport of #11246

Co-authored-by: Paul Gottschling <[email protected]>
  • Loading branch information
@jakule @ptgott
jakule and ptgott authored Apr 4, 2022
1 parent d3a7fca commit 9d01de4
Show file tree
Hide file tree
Showing 6 changed files with 331 additions and 299 deletions.
4 changes: 4 additions & 0 deletions docs/config.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -472,6 +472,10 @@
"title": "Self-Hosted Redis",
"slug": "/database-access/guides/redis/"
},
{
"title": "Self-Hosted Redis Cluster",
"slug": "/database-access/guides/redis-cluster/"
},
{
"title": "SQL Server (Preview)",
"slug": "/database-access/guides/sql-server-ad/"
Expand Down
190 changes: 190 additions & 0 deletions docs/pages/database-access/guides/redis-cluster.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,190 @@
---
title: Database Access with Redis Cluster
description: How to configure Teleport Database Access with Redis Cluster.
---

<Details
title="Version warning"
opened={true}
scope={["oss", "enterprise"]}
scopeOnly={true}
min="9.0"
>
Database Access for Redis is available starting from Teleport `9.0`.
</Details>

If you want to configure Redis Standalone, please read [Database Access with Redis](redis.mdx).

This guide will help you to:

- Install and configure Teleport.
- Configure mutual TLS authentication between Teleport and Redis Cluster.
- Connect to Redis through Teleport.

## Prerequisites

- Teleport version `9.0` or newer.
- Redis version `6.0` or newer.
- `redis-cli` installed and added to your system's `PATH` environment variable.

<Admonition type="note" title="Note">
Redis `7.0` and RESP3 (REdis Serialization Protocol) are currently not supported.
</Admonition>

## Step 1/6. Set up Teleport Auth and Proxy

(!docs/pages/includes/database-access/start-auth-proxy.mdx!)

## Step 2/6. Create a Teleport user

(!docs/pages/includes/database-access/create-user.mdx!)

## Step 3/6. Create Redis users

(!docs/pages/includes/database-access/redis-create-users.mdx!)

## Step 4/6. Set up mutual TLS

(!docs/pages/includes/database-access/tctl-auth-sign.mdx!)

We will show you how to use the `tctl auth sign` command below.


When connecting to Redis Cluster, sign certificates for each member
using their hostnames and IP addresses.
For example, if the first member is accessible at `redis1.example.com` with IP `10.0.0.1` and
the second at `redis2.example.com` with IP `10.0.0.2`, run:
```code
$ tctl auth sign --format=redis --host=redis1.example.com,10.0.0.1 --out=redis1 --ttl=2190h
$ tctl auth sign --format=redis --host=redis2.example.com,10.0.0.2 --out=redis2 --ttl=2190h
```

(!docs/pages/includes/database-access/ttl-note.mdx!)

The command will create three files:
- `server.cas` with Teleport's certificate authority
- `server.key` with a generated private key
- `server.crt` with a generated user certificate

You will need these files to enable mutual TLS on your Redis server.

(!docs/pages/includes/database-access/rotation-note.mdx!)

Use the generated secrets to enable mutual TLS in your `redis.conf` configuration
file and restart the database:

```ini
tls-port 7001
port 0
cluster-enabled yes
tls-replication yes
tls-cluster yes
aclfile /path/to/users.acl
masterauth GENERATED_STRONG_PASSWORD
masteruser replica-user
tls-cert-file /usr/local/etc/redis/certs/server.crt
tls-key-file /usr/local/etc/redis/certs/server.key
tls-ca-cert-file /usr/local/etc/redis/certs/server.cas
tls-protocols "TLSv1.2 TLSv1.3"
```

Once mutual TLS has been enabled, you will no longer be able to connect to
the cluster without providing a valid client certificate. You can use the
`tls-auth-clients optional` setting to allow connections
from clients that do not present a certificate.

See [TLS Support](https://redis.io/topics/encryption)
in the Redis documentation for more details.

## Step 5/6. Create cluster

Use the following command to create the cluster. Please note `redis-cli --cluster create` accepts only IP addresses.
```sh
export REDISCLI_AUTH=STRONG_GENERATED_PASSWORD
export CERTS_DIR=/path/to/certs/
export IP1=10.0.0.1 # update with the real node 1 IP
export IP2=10.0.0.2 # update with the real node 2 IP
export IP3=10.0.0.3 # update with the real node 3 IP
export IP4=10.0.0.4 # update with the real node 4 IP
export IP5=10.0.0.5 # update with the real node 5 IP
export IP6=10.0.0.6 # update with the real node 6 IP
redis-cli --user alice --cluster-replicas 1 --tls --cluster-yes \
--cluster create ${IP1}:7001 ${IP2}:7002 ${IP3}:7003 ${IP4}:7004 ${IP5}:7005 ${IP6}:7006 \
--cacert ${CERTS_DIR}/server.cas --key ${CERTS_DIR}/server.key --cert ${CERTS_DIR}/server.crt
```

## Step 6/6. Connect

To enable Redis cluster mode in Teleport, add the `mode=cluster` parameter to the connection URI in
your Teleport Database Service config file.
```yaml
databases:
- name: "redis-cluster"
uri: "rediss://redis.example.com:6379?mode=cluster"
```
(!docs/pages/includes/database-access/redis-connect.mdx!)
### Supported Redis Cluster commands
Redis in cluster mode does not support the following commands. If one of the listed commands above is called Teleport
returns the <nobr>`ERR Teleport: command not supported`</nobr> error.

<Details title="Unsupported commands" opened={false}>
- `ACL`
- `ASKING`
- `CLIENT`
- `CLUSTER`
- `CONFIG`
- `DEBUG`
- `EXEC`
- `HELLO`
- `INFO`
- `LATENCY`
- `MEMORY`
- `MIGRATE`
- `MODULE`
- `MONITOR`
- `MULTI`
- `PFDEBUG`
- `PFSELFTEST`
- `PSUBSCRIBE`
- `PSYNC`
- `PUNSUBSCRIBE`
- `PUNSUBSCRIBE`
- `READONLY`
- `READWRITE`
- `REPLCONF`
- `REPLICAOF`
- `ROLE`
- `SCAN`
- `SCRIPT DEBUG`
- `SCRIPT KILL`
- `SHUTDOWN`
- `SLAVEOF`
- `SLOWLOG`
- `SSUBSCRIBE`
- `SUNSUBSCRIBE`
- `SYNC`
- `TIME`
- `WAIT`
- `WATCH`
</Details>

Teleport conducts additional processing on the following commands before
communicating with Redis Cluster:

| Command | Description |
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `DBSIZE` | Sends the query to all nodes and returns the number of keys in the whole cluster. |
| `KEYS` | Sends the query to all nodes and returns a list of all keys in the whole cluster. |
| `MGET` | Translates the commands to multiple `GET`s and sends them to multiple nodes. Result is merged in Teleport and returned back to the client. If Teleport fails to fetch at least one key an error is returned. |
| `FLUSHDB` | Sends the query to all nodes. |
| `FLUSHALL` | Works the same as `FLUSHDB`. |
| <nobr>`SCRIPT EXISTS`</nobr> | Sends the query to all nodes. `1` is returned only if script exists on all nodes. |
| <nobr>`SCRIPT LOAD`</nobr> | Sends the script to all nodes. |
| <nobr>`SCRIPT FLUSH`</nobr> | Sends the query to all nodes. `ASYNC` parameter is ignored. |

## Next steps

(!docs/pages/includes/database-access/guides-next-steps.mdx!)
Loading

0 comments on commit 9d01de4

Please sign in to comment.