Skip to content

Commit c32ad98

Browse files
authored
Merge pull request #570 from redis/DOC-4137
Merging original work to clear pull request.
2 parents 903735e + 5ff8b8b commit c32ad98

29 files changed

+422
-0
lines changed
Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
Title: Data Integration
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rc
8+
description: Use Redis Data Integration with Redis Cloud.
9+
hideListLinks: true
10+
weight: 99
11+
---
12+
13+
Redis Cloud now supports [Redis Data Integration (RDI)]({{<relref "integrate/redis-data-integration">}}), a fast and simple way to bring your data into Redis from other types of primary databases.
14+
15+
A relational database usually handles queries much more slowly than a Redis database. If your application uses a relational database and makes many more reads than writes (which is the typical case) then you can improve performance by using Redis as a cache to handle the read queries quickly. Redis Cloud uses [ingest]({{<relref "/integrate/redis-data-integration/">}}) to help you offload all read queries from the application database to Redis automatically.
16+
17+
Using a data pipeline lets you have a cache that is always ready for queries. RDI Data pipelines ensure that any changes made to your primary database are captured in your Redis cache within a few seconds, preventing cache misses and stale data within the cache.
18+
19+
RDI helps Redis customers sync Redis Cloud with live data from their primary databases to:
20+
- Meet the required speed and scale of read queries and provide an excellent and predictable user experience.
21+
- Save resources and time when building pipelines and coding data transformations.
22+
- Reduce the total cost of ownership by saving money on expensive database read replicas.
23+
24+
Using RDI with Redis Cloud simplifies managing your data integration pipeline. No need to worry about hardware or underlying infrastructure, as Redis Cloud manages that for you. Creating the data flow from source to target is much easier, and there are validations in place to reduce errors.
25+
26+
## Data pipeline architecture
27+
28+
An RDI data pipeline sits between your source database and your target Redis database. Initially, the pipeline reads all of the data and imports it into the target database during the *initial sync* phase. After this initial sync is complete, the data pipeline enters the *streaming* phase, where changes are captured as they happen. Changes in the source database are added to the target within a few seconds of capture. The data pipeline translates relational database rows to Redis hashes or JSON documents.
29+
30+
For more info on how RDI works, see [RDI Architecture]({{<relref "/integrate/redis-data-integration/architecture">}}).
31+
32+
### Pipeline security
33+
34+
Data pipelines are set up to ensure a high level of data security. Source database credentials and TLS secrets are stored in AWS secret manager and shared using the Kubernetes CSI driver for secrets. See [Share source database credentials]({{<relref "/operate/rc/databases/rdi/setup#share-source-database-credentials">}}) to learn how to share your source database credentials and TLS certificates with Redis Cloud.
35+
36+
Connections to the source database use Java Database Connectivity (JDBC) through [AWS PrivateLink](https://aws.amazon.com/privatelink/), ensuring that the data pipeline is only exposed to the specific database endpoint. See [Set up connectivity]({{<relref "/operate/rc/databases/rdi/setup#set-up-connectivity">}}) to learn how to connect your PrivateLink to the Redis Cloud VPC.
37+
38+
RDI encrypts all network connections with TLS. The pipeline will process data from the source database in-memory and write it to the target database using a TLS connection. There are no external connections to your data pipeline except from Redis Cloud management services.
39+
40+
## Prerequisites
41+
42+
Before you can create a data pipeline, you must have:
43+
44+
- A [Redis Cloud Pro database]({{< relref "/operate/rc/databases/create-database/create-pro-database-new" >}}) hosted on Amazon Web Services (AWS). This will be the target database.
45+
- One supported source database, also hosted on AWS and connected to [AWS PrivateLink](https://aws.amazon.com/privatelink/):
46+
- MySQL
47+
- Oracle
48+
- SQL Server
49+
- PostgreSQL
50+
- mariaDB
51+
- Amazon Aurora
52+
53+
{{< note >}}
54+
Please be aware of the following limitations:
55+
56+
- The target database must be a Redis Cloud Pro database hosted on Amazon Web Services (AWS). Redis Cloud Essentials databases and databases hosted on Google Cloud do not support Data Integration.
57+
- The target database must use multi-zone [high availability]({{< relref "/operate/rc/databases/configuration/high-availability" >}}).
58+
- The target database can use TLS, but can not use mutual TLS.
59+
- The target database cannot be in the same subscription as another database that has a data pipeline.
60+
- Source databases must also be hosted on AWS.
61+
- One source database can only be synced to one target database.
62+
{{< /note >}}
63+
64+
## Get started
65+
66+
To create a new data pipeline, you need to:
67+
68+
1. [Prepare your source database]({{<relref "/operate/rc/databases/rdi/setup">}}) and any associated credentials.
69+
2. [Define the source connection and data pipeline]({{<relref "/operate/rc/databases/rdi/define">}}) by selecting which tables to sync.
70+
71+
Once your data pipeline is defined, you can [view and edit]({{<relref "/operate/rc/databases/rdi/view-edit">}}) it.
Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
Title: Define data pipeline
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rc
8+
description: Define the source connction and data pipeline.
9+
hideListLinks: true
10+
weight: 2
11+
---
12+
13+
After you have [prepared your source database]({{<relref "/operate/rc/databases/rdi/setup">}}) and connection information, you can set up your new pipeline. To do this:
14+
15+
1. [Define the source connection](#define-source-connection) by entering all required source database information.
16+
2. [Define the data pipeline](#define-data-pipeline) by selecting the data that you want to sync from your source database to the target database.
17+
18+
## Define source connection
19+
20+
1. In the [Redis Cloud console](https://cloud.redis.io/), go to your target database and select the **Data Pipeline** tab.
21+
1. Select **Define source database**.
22+
{{<image filename="images/rc/rdi/rdi-define-source-database.png" alt="The define source database button." width=200px >}}
23+
1. Enter a **Pipeline name**. This pipeline name will be the prefix to all keys generated by this pipeline in the target database.
24+
{{<image filename="images/rc/rdi/rdi-define-pipeline-cidr.png" alt="The pipeline name and deployment CIDR fields." >}}
25+
1. Enter the **Deployment CIDR** for your pipeline, or use the one generated for you. This CIDR should not conflict with your apps or other databases.
26+
1. In the **Source database connectivity** section, enter the **PrivateLink service name** of the [PrivateLink connected to your source database]({{< relref "/operate/rc/databases/rdi/setup#set-up-connectivity" >}}).
27+
{{<image filename="images/rc/rdi/rdi-define-connectivity.png" alt="The Source database connectivity section, with database connection details and connectivity options." >}}
28+
1. Enter your database details. This depends on your database type, and includes:
29+
- **Port**: The database's port
30+
- **Database**: Your database's name, or the root database *(PostgreSQL, Oracle only)*, or a comma-separated list of one or more databases you want to connect to *(SQL Server only)*
31+
- **Database Server ID**: Unique ID for the replication client. Leave as default if you don't use replication *(mySQL and mariaDB only)*
32+
- **PDB**: Name of the Oracle pluggable database *(Oracle only)*
33+
1. Enter the ARN of your [database credentials secret]({{< relref "/operate/rc/databases/rdi/setup#share-source-database-credentials" >}}) in the **Source database secrets ARN** field.
34+
1. Select **Start pipeline setup**.
35+
{{<image filename="images/rc/rdi/rdi-start-pipeline-setup.png" alt="The start pipeline setup button." width=200px >}}
36+
1. Redis Cloud will attempt to connect to PrivateLink. If your PrivateLink does not allow automatic acceptance of incoming connections, accept the incoming connection on AWS PrivateLink to proceed. See [Accept or Reject PrivateLink connection requests](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#accept-reject-connection-requests).
37+
38+
If Redis Cloud can't find your PrivateLink connection, make sure that the PrivateLink service name is correct and that Redis Cloud is listed as an Allowed Principal for your VPC. See [Set up connectivity]({{<relref "/operate/rc/databases/rdi/setup#set-up-connectivity">}}) for more info.
39+
40+
At this point, Redis Cloud will provision the pipeline infrastructure that will allow you to define your data pipeline.
41+
42+
{{<image filename="images/rc/rdi/rdi-pipeline-setup-in-progress.png" alt="The Pipeline setup in progress screen." width=75% >}}
43+
44+
Pipelines are provisioned in the background. You aren't allowed to make changes to your data pipeline or to your database during provisioning. This process will take a long time, so you can close the window and come back later.
45+
46+
When your pipeline is provisioned, select **Complete setup**. You will then [define your data pipeline](#define-data-pipeline).
47+
48+
{{<image filename="images/rc/rdi/rdi-complete-setup.png" alt="The complete setup button." width=200px >}}
49+
50+
## Define data pipeline
51+
52+
After your pipeline is provisioned, you will be able to define your pipeline. You will select the database schemas, tables, and columns that you want to import and synchronize with your primary database.
53+
54+
### Configure a new pipeline
55+
56+
1. In the [Redis Cloud console](https://cloud.redis.io/), go to your target database and select the **Data Pipeline** tab. If your pipeline is already provisioned, select **Complete setup** to go to the **Pipeline definition** section.
57+
{{<image filename="images/rc/rdi/rdi-complete-setup.png" alt="The complete setup button." width=200px >}}
58+
1. For the **Configure a new pipeline** option, select the Redis data type to write keys to the target. You can choose **Hash** or **JSON** if the target database supports JSON.
59+
{{<image filename="images/rc/rdi/rdi-configure-new-pipeline.png" alt="The Pipeline definition screen. Configure a new pipeline is selected." width=75% >}}
60+
Select **Continue**.
61+
{{<image filename="images/rc/rdi/rdi-continue-button.png" alt="The continue button." width=150px >}}
62+
1. Select the Schema and Tables you want to migrate to the target database from the **Source data selection** list.
63+
{{<image filename="images/rc/rdi/rdi-select-source-data.png" alt="The select source data section. " width=75% >}}
64+
65+
You can select any number of columns from a table.
66+
67+
{{<image filename="images/rc/rdi/rdi-select-columns.png" alt="The select source data section. A table is expanded with a few columns selected." width=75% >}}
68+
69+
If any tables are missing a unique constraint, the **Missing unique constraint** list will appear. Select the columns that define a unique constraint for those tables from the list.
70+
71+
{{<image filename="images/rc/rdi/rdi-missing-unique-constraint.png" alt="The missing unique constraint list." width=75% >}}
72+
73+
{{<image filename="images/rc/rdi/rdi-select-constraints.png" alt="The missing unique constraint list with columns selected." width=75% >}}
74+
75+
Select **Add schema** to add more database schemas.
76+
77+
{{<image filename="images/rc/rdi/rdi-add-schema.png" alt="The add schema button." width=150px >}}
78+
79+
Select **Delete** to delete a schema. You must have at least one schema to continue.
80+
81+
{{<image filename="images/rc/rdi/rdi-delete-schema.png" alt="The delete schema button." width=50px >}}
82+
83+
After you've selected the schemas and tables you want to sync, select **Continue**.
84+
85+
{{<image filename="images/rc/rdi/rdi-continue-button.png" alt="The continue button." width=150px >}}
86+
87+
1. Review the tables you selected in the **Summary**. If everything looks correct, select **Start ingest** to start ingesting data from your source database.
88+
89+
{{<image filename="images/rc/rdi/rdi-start-ingest.png" alt="The start ingest button." width=175px >}}
90+
91+
At this point, the data pipeline will ingest data from the source database to your target Redis database. This process will take time, especially if you have a lot of records in your source database.
92+
93+
After this initial sync is complete, the data pipeline enters the *change streaming* phase, where changes are captured as they happen. Changes in the source database are added to the target within a few seconds of capture.
94+
95+
You can view the status of your data pipeline in the **Data pipeline** tab of your database. See [View and edit data pipeline]({{<relref "/operate/rc/databases/rdi/view-edit">}}) to learn more.
Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
Title: Prepare source database
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rc
8+
description: Prepare your source database and database credentials for Data integration.
9+
hideListLinks: true
10+
weight: 1
11+
---
12+
13+
## Create new data pipeline
14+
15+
1. In the [Redis Cloud console](https://cloud.redis.io/), go to your target database and select the **Data Pipeline** tab.
16+
1. Select **Create data pipeline**.
17+
{{<image filename="images/rc/rdi/rdi-create-data-pipeline.png" alt="The create data pipeline button." width=200px >}}
18+
1. Select your source database type. The following database types are supported:
19+
- MySQL
20+
- mariaDB
21+
- Oracle
22+
- SQL Server
23+
- PostgreSQL
24+
{{<image filename="images/rc/rdi/rdi-select-source-db.png" alt="The select source database type list." width=500px >}}
25+
1. If you know the size of your source database, enter it into the **Source dataset size** field.
26+
{{<image filename="images/rc/rdi/rdi-source-dataset-size.png" alt="Enter the amount of source data you plan to ingest." width=400px >}}
27+
1. Under **Setup connectivity**, save the provided ARN and extract the AWS account ID for the account associated with your Redis Cloud cluster from it.
28+
29+
{{<image filename="images/rc/rdi/rdi-setup-connectivity-arn.png" alt="The select source database type list." width=80% >}}
30+
31+
The AWS account ID is the string of numbers after `arn:aws:iam::` in the ARN. For example, if the ARN is `arn:aws:iam::123456789012:role/redis-data-pipeline`, the AWS account ID is `123456789012`.
32+
33+
## Prepare source database
34+
35+
Before using the pipeline, you must first prepare your source database to use the Debezium connector for change data capture (CDC).
36+
37+
See [Prepare source databases]({{<relref "/integrate/redis-data-integration/data-pipelines/prepare-dbs/">}}) to find steps for your database type:
38+
- [MySQL and mariaDB]({{<relref "/integrate/redis-data-integration/data-pipelines/prepare-dbs/my-sql-mariadb">}})
39+
- [Oracle]({{<relref "/integrate/redis-data-integration/data-pipelines/prepare-dbs/oracle">}})
40+
- [SQL Server]({{<relref "/integrate/redis-data-integration/data-pipelines/prepare-dbs/sql-server">}})
41+
- [PostgreSQL]({{<relref "/integrate/redis-data-integration/data-pipelines/prepare-dbs/postgresql">}})
42+
43+
See the [RDI architecture overview]({{< relref "/integrate/redis-data-integration/architecture#overview" >}}) for more information about CDC.
44+
45+
## Share source database credentials
46+
47+
You need to share your source database credentials and certificates in an Amazon secret with Redis Cloud so that the pipeline can connect to your database.
48+
49+
To do this, you need to:
50+
1. [Create an encryption key](#create-encryption-key) using AWS Key Management Service with the right permissions.
51+
1. [Create a secret](#create-database-credentials-secret) containing the source database credentials encrypted using that key.
52+
53+
### Create encryption key
54+
55+
In the [AWS Management Console](https://console.aws.amazon.com/), use the **Services** menu to locate and select **Security, Identity, and Compliance** > **Key Management Service**. [Create an encryption key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) with the following settings:
56+
57+
1. In **Step 1 - Configure key**:
58+
- **Key type**: Select **Symmetric**.
59+
- **Key usage**: Select **Encrypt and decrypt**.
60+
- Under **Advanced options**, set the following:
61+
- **Key material origin**: Select **KMS - recommended**.
62+
- **Regionality**: Select **Single-Region key**.
63+
1. In **Step 2 - Add labels**, add an alias and description for the key.
64+
1. In **Step 3 - Define key administrative permissions**, under **Key deletion**, select **Allow key administrators to delete this key**.
65+
1. In **Step 4 - Define key usage permissions**, under **Other AWS accounts**, select **Add another AWS account**. Enter the AWS account ID for the Redis Cloud cluster that you saved earlier.
66+
67+
### Create database credentials secret
68+
69+
In the [AWS Management Console](https://console.aws.amazon.com/), use the **Services** menu to locate and select **Security, Identity, and Compliance** > **Secrets Manager**. [Create a secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) of type **Other type of secret** with the following settings:
70+
71+
- **Key/value pairs**: Enter the following key/value pairs.
72+
73+
- `username`: Database username
74+
- `password`: Database password
75+
- `trust_certificate`: Server certificate in PEM format *(TLS only)*
76+
- `client_public_key`: [X.509 client certificate](https://en.wikipedia.org/wiki/X.509) or chain in PEM format *(mTLS only)*
77+
- `client_private_key`: Key for the client certificate or chain in PEM format *(mTLS only)*
78+
- `client_private_key_passphrase`: Passphrase or password for the client certificate or chain in PEM format *(mTLS only)*
79+
80+
{{<note>}}
81+
If your source database has TLS or mTLS enabled, we recommend that you enter the `trust_certificate`, `client_public_key`, and `client_private_key` into the secret editor using the **Key/Value** input method instead of the **JSON** input method. Pasting directly into the JSON editor may cause an error.
82+
{{</note>}}
83+
84+
- **Encryption key**: Select the [encryption key](#create-encryption-key) you created earlier.
85+
86+
- **Resource permissions**: Add the following permissions to your secret to allow the Redis data pipeline to access your secret. Replace `<AWS ACCOUNT ID>` with the AWS account ID for the Redis Cloud cluster that you saved earlier.
87+
88+
```json
89+
{
90+
"Version" : "2012-10-17",
91+
"Statement" : [ {
92+
"Sid" : "RedisDataIntegrationRoleAccess",
93+
"Effect" : "Allow",
94+
"Principal" : "*",
95+
"Action" : [ "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret" ],
96+
"Resource" : "*",
97+
"Condition" : {
98+
"StringLike" : {
99+
"aws:PrincipalArn" : "arn:aws:iam::<AWS ACCOUNT ID>:role/redis-data-pipeline-secrets-role"
100+
}
101+
}
102+
} ]
103+
}
104+
```
105+
106+
After you store this secret, you can view and copy the [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#iam-resources) of your secret on the secret details page.
107+
108+
## Set up connectivity
109+
110+
To expose your source database to Redis, you need to add Redis Cloud as an Allowed Principal on the [AWS PrivateLink VPC permissions](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) for the PrivateLink connected to your source database.
111+
112+
1. Copy the Amazon Resource Name (ARN) provided in the **Setup connectivity** section.
113+
1. Open the [Amazon VPC console](https://console.aws.amazon.com/vpc/) and select **Endpoint services**.
114+
1. Navigate to **Allow principals** tab.
115+
1. Add the Redis Cloud ARN and choose **Allow principals**.
116+
1. Copy your PrivateLink service name for later.
117+
118+
For more details on AWS PrivateLink, see [Share your services through AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html).
119+
120+
121+
## Next steps
122+
123+
After you have set up your source database and prepared connectivity and credentials, select **Define source database** to [define your source connection and data pipeline]({{<relref "/operate/rc/databases/rdi/define">}}).
124+
125+
{{<image filename="images/rc/rdi/rdi-define-source-database.png" alt="ADD ALT TEXT" width=200px >}}

0 commit comments

Comments
 (0)