From 7630c2c39ca30fbf9d4a0278b8e05f03cd24c390 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Fri, 28 Jun 2024 11:32:08 +0100 Subject: [PATCH 1/4] DOC-3917 added silent install docs --- .../ingest/installation/_index.md | 141 ++++++++++++++++++ 1 file changed, 141 insertions(+) diff --git a/content/integrate/redis-data-integration/ingest/installation/_index.md b/content/integrate/redis-data-integration/ingest/installation/_index.md index cd36ba3e08..aee7b7eae1 100644 --- a/content/integrate/redis-data-integration/ingest/installation/_index.md +++ b/content/integrate/redis-data-integration/ingest/installation/_index.md @@ -88,6 +88,147 @@ Once the installation is finished, RDI is ready for use. {{}}RDI gives you instructions to help you create secrets and create your pipeline.{{}} +## "Silent" installation + +You can use the +[`redis-di install`]({{< relref "/integrate/redis-data-integration/ingest/reference/cli/redis-di-install" >}}) +command with the `--file` option (or the shorter version `-f`) to supply answers +to the installer's questions automatically from a [TOML](https://toml.io/en/) file: + +```bash +redis-di install --file silent.toml +``` + +The following example shows the properties you can use: + +```toml +title = "RDI Silent Installer Config" + +high_availability = false +scaffold = false +deploy = true +db_index = 4 +deploy_directory = "/opt/rdi/config" + +[rdi.cluster] +host = "localhost" +port = 9443 +username = "username" +password = "password" + +[rdi.database] +host = "localhost" +port = 12001 +username = "username" +password = "password" +use_existing_rdi = true +ssl = true + +[rdi.database.certificates] +ca = "/home/ubuntu/rdi/certs/ca.crt" +cert = "/home/ubuntu/rdi/certs/client.crt" +key = "/home/ubuntu/rdi/certs/client.key" +passphrase = "foobar" + +# WARNING! We provide the properties below for special +# use cases. However, we *strongly* recommend that you don't +# store the source and target secrets in the clear like +# this for normal purposes! + +# [sources.default] +# username = "username" +# password = "password" +# ssl = false + +# [sources.default.certificates] +# ca = "/home/ubuntu/rdi/certs/ca.crt" +# cert = "/home/ubuntu/rdi/certs/client.crt" +# key = "/home/ubuntu/rdi/certs/client.key" +# passphrase = "foobar" + +# [targets.default] +# username = "username" +# password = "password" +# ssl = false + +# [targets.default.certificates] +# ca = "/home/ubuntu/rdi/certs/ca.crt" +# cert = "/home/ubuntu/rdi/certs/client.crt" +# key = "/home/ubuntu/rdi/certs/client.key" +# passphrase = "foobar" +``` + +The tables below describe the properties for each section in more detail: + +**Root** + +| Property | Description | +|-- |-- | +| `title` | Text to identify the file. RDI doesn't use use this, so you can use any text you like. | +| `high_availability` | Do you want to enable replication on the RDI database? (true/false) | +| `scaffold` | Do you want to enable [scaffolding]({{< relref "/integrate/redis-data-integration/ingest/reference/cli/redis-di-scaffold" >}}) during the install? (true/false) | +| `deploy` | Do you want the installer to [deploy]({{< relref "/integrate/redis-data-integration/ingest/reference/cli/redis-di-deploy" >}}) the configuration? (true/false) | +| `db_index` | Integer to specify the source database type. The options are 4 (MySQL/MariaDB), 5 (Oracle), 6 (PostgreSQL), and 8 (SQL Server). | +| `deploy_directory` | Path to the directory where you want to store the RDI configuration. | + +**rdi.cluster** + +| Property | Description | +|-- |-- | +| `host` | Hostname of the Redis cluster to use for RDI. | +| `port` | Port for the cluster. | +| `username` | Username for the cluster. | +| `password` | Password for the cluster. | + +**rdi.database** + +| Property | Description | +|-- |-- | +| `host` | Hostname for the Redis database to store RDI state. | +| `port` | Port for the RDI database. | +| `username` | Username for the RDI database. | +| `password` | Password for the RDI database. | +| `use_existing_rdi` | Do you want to use an existing RDI instance (true) or create a new one (false)? If you enable SSL (see the property below), this will be set to true, overriding the value you specify here. | +| `ssl` | Is SSL enabled for the RDI database (true/false)? If this is false then RDI will ignore the settings in the `rdi.database.certificates` section. | + +**rdi.database.certificates** + +| Property | Description | +|-- |-- | +| `ca` | Path to the CA certificate file. | +| `cert` | Path to the client certificate file. | +| `key` | Path to the key file. | +| `passphrase` | Password for the private key (string). | + +In the commented-out section of the example TOML file, you will also +notice the sections `source.default`, `target.default`, +`source.default.certificates`, and `target.default.certificates`. +For special purposes, you can use these to supply the authentication +secrets for the source and target database. However, it is normally a +major security risk to keep these secrets in the clear in +a configuration file like this. Therefore, we +*strongly recommend* that you never add these properties to +the TOML file unless you are certain that they don't need +to be kept secret. + +**source/target.default** + +| Property | Description | +|-- |-- | +| `username` | Source/target database username. | +| `password` | Source/target database password. | +| `ssl` | Do you want to enabled SSL for the connection? (true/false) | + +**source/target.default.certificates** + +| Property | Description | +|-- |-- | +| `ca` | Path to the CA certificate file. | +| `cert` | Path to the client certificate file. | +| `key` | Path to the key file. | +| `passphrase` | Password for the private key (string). | + + ## Prepare your source database You must also configure your source database to use the Debezium connector for CDC. See the From 6a81b010590f69d2ae8dcad2d583954007b428d4 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Fri, 28 Jun 2024 12:01:07 +0100 Subject: [PATCH 2/4] DOC-3917 updated CLI ref to mention TOML file rather than YAML --- .../ingest/reference/cli/redis-di-install.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/integrate/redis-data-integration/ingest/reference/cli/redis-di-install.md b/content/integrate/redis-data-integration/ingest/reference/cli/redis-di-install.md index 8b07bbe2d2..005e182b9c 100644 --- a/content/integrate/redis-data-integration/ingest/reference/cli/redis-di-install.md +++ b/content/integrate/redis-data-integration/ingest/reference/cli/redis-di-install.md @@ -30,7 +30,7 @@ Usage: redis-di install [OPTIONS] * Usage: `-f --file` - Path to a YAML configuration file for silent installation + Path to a TOML configuration file for silent installation * `online`: @@ -60,7 +60,7 @@ Usage: redis-di install [OPTIONS] Options: -l, --log-level [DEBUG|INFO|WARN|ERROR|CRITICAL] [default: WARN] - -f, --file FILE Path to a YAML configuration file for silent + -f, --file FILE Path to a TOML configuration file for silent installation --help Show this message and exit. ``` From 1426b749303dac909328c75839ed0e7ef82ab122 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Fri, 28 Jun 2024 13:31:55 +0100 Subject: [PATCH 3/4] DOC-3917 implement PR feedback --- .../ingest/installation/_index.md | 116 ++++++------------ 1 file changed, 38 insertions(+), 78 deletions(-) diff --git a/content/integrate/redis-data-integration/ingest/installation/_index.md b/content/integrate/redis-data-integration/ingest/installation/_index.md index aee7b7eae1..ca0454a9a3 100644 --- a/content/integrate/redis-data-integration/ingest/installation/_index.md +++ b/content/integrate/redis-data-integration/ingest/installation/_index.md @@ -93,29 +93,27 @@ Once the installation is finished, RDI is ready for use. You can use the [`redis-di install`]({{< relref "/integrate/redis-data-integration/ingest/reference/cli/redis-di-install" >}}) command with the `--file` option (or the shorter version `-f`) to supply answers -to the installer's questions automatically from a [TOML](https://toml.io/en/) file: +to the installer's questions automatically using properties from a +[TOML](https://toml.io/en/) file: ```bash redis-di install --file silent.toml ``` -The following example shows the properties you can use: +### Silent install example + +The following example shows the properties for a typical +silent install configuration: ```toml title = "RDI Silent Installer Config" -high_availability = false -scaffold = false -deploy = true -db_index = 4 +scaffold = true deploy_directory = "/opt/rdi/config" -[rdi.cluster] -host = "localhost" -port = 9443 -username = "username" -password = "password" - +# If you are *not* using an existing RDI database and you want +# the installer to create one then remove this section +# and uncomment the [rdi.cluster] section below. [rdi.database] host = "localhost" port = 12001 @@ -124,63 +122,41 @@ password = "password" use_existing_rdi = true ssl = true +# Uncomment this section and remove the [rdi.database] section above +# if you are *not* using an existing RDI database and you want +# the installer to create one. +# [rdi.cluster] +# host = "localhost" +# port = 9443 +# username = "username" +# password = "password" + [rdi.database.certificates] ca = "/home/ubuntu/rdi/certs/ca.crt" cert = "/home/ubuntu/rdi/certs/client.crt" key = "/home/ubuntu/rdi/certs/client.key" passphrase = "foobar" - -# WARNING! We provide the properties below for special -# use cases. However, we *strongly* recommend that you don't -# store the source and target secrets in the clear like -# this for normal purposes! - -# [sources.default] -# username = "username" -# password = "password" -# ssl = false - -# [sources.default.certificates] -# ca = "/home/ubuntu/rdi/certs/ca.crt" -# cert = "/home/ubuntu/rdi/certs/client.crt" -# key = "/home/ubuntu/rdi/certs/client.key" -# passphrase = "foobar" - -# [targets.default] -# username = "username" -# password = "password" -# ssl = false - -# [targets.default.certificates] -# ca = "/home/ubuntu/rdi/certs/ca.crt" -# cert = "/home/ubuntu/rdi/certs/client.crt" -# key = "/home/ubuntu/rdi/certs/client.key" -# passphrase = "foobar" ``` -The tables below describe the properties for each section in more detail: +The sections below describe the properties in more detail. -**Root** +### Silent install properties + +#### Root | Property | Description | |-- |-- | | `title` | Text to identify the file. RDI doesn't use use this, so you can use any text you like. | -| `high_availability` | Do you want to enable replication on the RDI database? (true/false) | +| `high_availability` | Do you want to enable replication on the RDI database (true/false)? You should only use this if you ask the installer to create the RDI database for you. | | `scaffold` | Do you want to enable [scaffolding]({{< relref "/integrate/redis-data-integration/ingest/reference/cli/redis-di-scaffold" >}}) during the install? (true/false) | -| `deploy` | Do you want the installer to [deploy]({{< relref "/integrate/redis-data-integration/ingest/reference/cli/redis-di-deploy" >}}) the configuration? (true/false) | -| `db_index` | Integer to specify the source database type. The options are 4 (MySQL/MariaDB), 5 (Oracle), 6 (PostgreSQL), and 8 (SQL Server). | +| `db_index` | Integer to specify the source database type. The options are 4 (MySQL/MariaDB), 5 (Oracle), 6 (PostgreSQL), and 8 (SQL Server). You should only use this if you ask the installer to create the RDI database for you. | | `deploy_directory` | Path to the directory where you want to store the RDI configuration. | -**rdi.cluster** - -| Property | Description | -|-- |-- | -| `host` | Hostname of the Redis cluster to use for RDI. | -| `port` | Port for the cluster. | -| `username` | Username for the cluster. | -| `password` | Password for the cluster. | +#### `rdi.database` -**rdi.database** +Use the properties in this section if you want to use an existing RDI database. +See [`rdi.cluster`](#rdicluster) below if you want the installer to create a new +RDI database. | Property | Description | |-- |-- | @@ -191,35 +167,20 @@ The tables below describe the properties for each section in more detail: | `use_existing_rdi` | Do you want to use an existing RDI instance (true) or create a new one (false)? If you enable SSL (see the property below), this will be set to true, overriding the value you specify here. | | `ssl` | Is SSL enabled for the RDI database (true/false)? If this is false then RDI will ignore the settings in the `rdi.database.certificates` section. | -**rdi.database.certificates** +#### `rdi.cluster` -| Property | Description | -|-- |-- | -| `ca` | Path to the CA certificate file. | -| `cert` | Path to the client certificate file. | -| `key` | Path to the key file. | -| `passphrase` | Password for the private key (string). | - -In the commented-out section of the example TOML file, you will also -notice the sections `source.default`, `target.default`, -`source.default.certificates`, and `target.default.certificates`. -For special purposes, you can use these to supply the authentication -secrets for the source and target database. However, it is normally a -major security risk to keep these secrets in the clear in -a configuration file like this. Therefore, we -*strongly recommend* that you never add these properties to -the TOML file unless you are certain that they don't need -to be kept secret. - -**source/target.default** +Use the properties in this section if you are *not* using an existing RDI database +and you want the installer to create one. +See [`rdi.database`](#rdidatabase) above if you want to use an existing RDI database. | Property | Description | |-- |-- | -| `username` | Source/target database username. | -| `password` | Source/target database password. | -| `ssl` | Do you want to enabled SSL for the connection? (true/false) | +| `host` | Hostname of the Redis cluster to use for RDI. | +| `port` | Port for the cluster. | +| `username` | Username for the cluster. | +| `password` | Password for the cluster. | -**source/target.default.certificates** +#### `rdi.database.certificates` | Property | Description | |-- |-- | @@ -228,7 +189,6 @@ to be kept secret. | `key` | Path to the key file. | | `passphrase` | Password for the private key (string). | - ## Prepare your source database You must also configure your source database to use the Debezium connector for CDC. See the From d865021e1cf23b2a365c83bf6d676569d5de8003 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Fri, 28 Jun 2024 14:14:35 +0100 Subject: [PATCH 4/4] DOC-3917 more feedback --- .../ingest/installation/_index.md | 37 +++++++++++++------ 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/content/integrate/redis-data-integration/ingest/installation/_index.md b/content/integrate/redis-data-integration/ingest/installation/_index.md index ca0454a9a3..a765ec6b6b 100644 --- a/content/integrate/redis-data-integration/ingest/installation/_index.md +++ b/content/integrate/redis-data-integration/ingest/installation/_index.md @@ -112,8 +112,11 @@ scaffold = true deploy_directory = "/opt/rdi/config" # If you are *not* using an existing RDI database and you want -# the installer to create one then remove this section -# and uncomment the [rdi.cluster] section below. +# the installer to create one then remove the properties in this +# section, apart from : +# - `password` +# - `use_existing_rdi` - set this to `false` +# Also, uncomment the [rdi.cluster] section below. [rdi.database] host = "localhost" port = 12001 @@ -122,8 +125,9 @@ password = "password" use_existing_rdi = true ssl = true -# Uncomment this section and remove the [rdi.database] section above -# if you are *not* using an existing RDI database and you want +# Uncomment this section and remove properties from the +# [rdi.database] section as described above if you +# are *not* using an existing RDI database and you want # the installer to create one. # [rdi.cluster] # host = "localhost" @@ -131,11 +135,14 @@ ssl = true # username = "username" # password = "password" -[rdi.database.certificates] -ca = "/home/ubuntu/rdi/certs/ca.crt" -cert = "/home/ubuntu/rdi/certs/client.crt" -key = "/home/ubuntu/rdi/certs/client.key" -passphrase = "foobar" + +# Uncomment the properties in this section only if the RDI +# database uses TLS/mTLS. +# [rdi.database.certificates] +# ca = "/home/ubuntu/rdi/certs/ca.crt" +# cert = "/home/ubuntu/rdi/certs/client.crt" +# key = "/home/ubuntu/rdi/certs/client.key" +# passphrase = "foobar" ``` The sections below describe the properties in more detail. @@ -156,7 +163,9 @@ The sections below describe the properties in more detail. Use the properties in this section if you want to use an existing RDI database. See [`rdi.cluster`](#rdicluster) below if you want the installer to create a new -RDI database. +RDI database. However, you should still supply the `password` in this +section and set `use_existing_rdi` to `false` if the installer creates the +database. | Property | Description | |-- |-- | @@ -165,7 +174,7 @@ RDI database. | `username` | Username for the RDI database. | | `password` | Password for the RDI database. | | `use_existing_rdi` | Do you want to use an existing RDI instance (true) or create a new one (false)? If you enable SSL (see the property below), this will be set to true, overriding the value you specify here. | -| `ssl` | Is SSL enabled for the RDI database (true/false)? If this is false then RDI will ignore the settings in the `rdi.database.certificates` section. | +| `ssl` | Is SSL enabled for the RDI database (true/false)? If this is false then RDI will ignore the settings in the [`rdi.database.certificates`](#rdidatabasecertificates) section. | #### `rdi.cluster` @@ -182,6 +191,12 @@ See [`rdi.database`](#rdidatabase) above if you want to use an existing RDI data #### `rdi.database.certificates` +Use these properties only if the RDI database requires +[TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) or +[mTLS](https://en.wikipedia.org/wiki/Mutual_authentication#mTLS). +You must also set `ssl` to `true` in the +[`rdi.database`](#rdidatabase) section to enable these properties. + | Property | Description | |-- |-- | | `ca` | Path to the CA certificate file. |