|
| 1 | +--- |
| 2 | +Title: Create Active-Active databases with crdb-cli |
| 3 | +alwaysopen: false |
| 4 | +categories: |
| 5 | +- docs |
| 6 | +- operate |
| 7 | +- kubernetes |
| 8 | +description: This section shows how to set up an Active-Active Redis Enterprise database |
| 9 | + on Kubernetes using the Redis Enterprise Software operator. |
| 10 | +linkTitle: Create Active-Active with crdb-cli |
| 11 | +weight: 99 |
| 12 | +--- |
| 13 | +{{<note>}} Versions 6.4.2 and later support the Active-Active database controller. This controller allows you to create Redis Enterprise Active-Active databases (REAADB) and Redis Enterprise remote clusters (RERC) with custom resources. We recommend using the [REAADB method for creating Active-Active databases]({{< relref "/operate/kubernetes/7.8.6/active-active/create-reaadb.md" >}}).{{</note>}} |
| 14 | + |
| 15 | +On Kubernetes, Redis Enterprise [Active-Active]({{< relref "/operate/rs/databases/active-active/" >}}) databases provide read-and-write access to the same dataset from different Kubernetes clusters. For more general information about Active-Active, see the [Redis Enterprise Software docs]({{< relref "/operate/rs/databases/active-active/" >}}). |
| 16 | + |
| 17 | +Creating an Active-Active database requires routing [network access]({{< relref "/operate/kubernetes/7.8.6/networking/" >}}) between two Redis Enterprise clusters residing in different Kubernetes clusters. Without the proper access configured for each cluster, syncing between the databases instances will fail. |
| 18 | + |
| 19 | +This process consists of: |
| 20 | + |
| 21 | +1. Documenting values to be used in later steps. It's important these values are correct and consistent. |
| 22 | +1. Editing the Redis Enterprise cluster (REC) spec file to include the `ActiveActive` section. This will be slightly different depending on the K8s distribution you are using. |
| 23 | +1. Creating the database with the `crdb-cli` command. These values must match up with values in the REC resource spec. |
| 24 | + |
| 25 | +## Prerequisites |
| 26 | + |
| 27 | +Before creating Active-Active databases, you'll need admin access to two or more working Kubernetes clusters that each have: |
| 28 | + |
| 29 | +- Routing for external access with an [ingress resources]({{< relref "/operate/kubernetes/7.8.6/networking/ingress.md" >}}) (or [route resources]({{< relref "/operate/kubernetes/7.8.6/networking/routes.md" >}}) on OpenShift). |
| 30 | +- A working [Redis Enterprise cluster (REC)]({{< relref "/operate/kubernetes/7.8.6/reference/redis_enterprise_cluster_api" >}}) with a unique name. |
| 31 | +- Enough memory resources available for the database (see [hardware requirements]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/hardware-requirements.md" >}})). |
| 32 | + |
| 33 | +{{<note>}} The `activeActive` field and the `ingressOrRouteSpec` field cannot coexist in the same REC. If you configured your ingress via the `ingressOrRouteSpec` field in the REC, create your Active-Active database with the RedisEnterpriseActiveActiveDatabase (REAADB) custom resource.{{</note>}} |
| 34 | + |
| 35 | +## Document required parameters |
| 36 | + |
| 37 | +The most common mistake when setting up Active-Active databases is incorrect or inconsistent parameter values. The values listed in the resource file must match those used in the crdb-cli command. |
| 38 | + |
| 39 | +- **Database name** `<db-name>`: |
| 40 | + - Description: Combined with ingress suffix to create the Active-Active database hostname |
| 41 | + - Format: string |
| 42 | + - Example value: `myaadb` |
| 43 | + - How you get it: you choose |
| 44 | + - The database name requirements are: |
| 45 | + - Maximum of 63 characters |
| 46 | + - Only letter, number, or hyphen (-) characters |
| 47 | + - Starts with a letter; ends with a letter or digit. |
| 48 | + - Database name is not case-sensitive |
| 49 | + |
| 50 | +You'll need the following information for each participating Redis Enterprise cluster (REC): |
| 51 | + |
| 52 | +{{<note>}} |
| 53 | +You'll need to create DNS aliases to resolve your API hostname `<api-hostname>`,`<ingress-suffix>`, `<replication-hostname>` to the IP address for the ingress controller’s LoadBalancer (or routes in Openshift) for each database. To avoid entering multiple DNS records, you can use a wildcard in your alias (such as *.ijk.example.com). |
| 54 | +{{</note>}} |
| 55 | + |
| 56 | +- **REC hostname** `<rec-hostname>`: |
| 57 | + - Description: Hostname used to identify your Redis Enterprise cluster in the `crdb-cli` command. This MUST be different from other participating clusters. |
| 58 | + - Format: `<rec-name>.<namespace>.svc.cluster.local` |
| 59 | + - Example value: `rec01.ns01.svc.cluster.local` |
| 60 | + - How to get it: List all your Redis Enterprise clusters |
| 61 | + ```bash |
| 62 | + kubectl get rec |
| 63 | + ``` |
| 64 | +- **API hostname** `<api-hostname>`: |
| 65 | + - Description: Hostname used to access the Redis Enterprise cluster API from outside the K8s cluster |
| 66 | + - Format: string |
| 67 | + - Example value: `api.ijk.example.com` |
| 68 | +- **Ingress suffix** `<ingress-suffix>`: |
| 69 | + - Description: Combined with database name to create the Active-Active database hostname |
| 70 | + - Format: string |
| 71 | + - Example value: `-cluster.ijk.example.com` |
| 72 | +- [**REC admin credentials**]({{< relref "/operate/kubernetes/7.8.6/security/manage-rec-credentials.md" >}}) `<username> <password>`: |
| 73 | + - Description: Admin username and password for the REC stored in a secret |
| 74 | + - Format: string |
| 75 | + - Example value: username: `[email protected]`, password: `something` |
| 76 | + - How to get them: |
| 77 | + ```sh |
| 78 | + kubectl get secret <rec-name> \ |
| 79 | + -o jsonpath='{.data.username}' | base64 --decode |
| 80 | + kubectl get secret <rec-name> \ |
| 81 | + -o jsonpath='{.data.password}' | base64 --decode |
| 82 | + ``` |
| 83 | +- **Replication hostname** `<replication-hostname>`: |
| 84 | + - Description: Hostname used inside the ingress for the database |
| 85 | + - Format: `<db-name><ingress-suffix>` |
| 86 | + - Example value: `myaadb-cluster.ijk.example.com` |
| 87 | + - How to get it: Combine `<db-name>` and `<ingress-suffix`> values you documented above. |
| 88 | +- **Replication endpoint** `<replication-endpoint>`: |
| 89 | + - Description: Endpoint used externally to contact the database |
| 90 | + - Format: `<db-name><ingress-suffix>:443` |
| 91 | + - Example value: `myaadb-cluster.ijk.example.com:443` |
| 92 | + - How to get it:`<replication-hostname>:443` |
| 93 | + |
| 94 | +## Add `activeActive` section to the REC resource file |
| 95 | + |
| 96 | +From inside your K8s cluster, edit your Redis Enterprise cluster (REC) resource to add the following to the `spec` section. Do this for each participating cluster. |
| 97 | + |
| 98 | + The operator uses the API hostname (`<api-hostname>`) to create an ingress to the Redis Enterprise cluster's API; this only happens once per cluster. Every time a new Active-Active database instance is created on this cluster, the operator creates a new ingress route to the database with the ingress suffix (`<ingress-suffix>`). The hostname for each new database will be in the format <nobr>`<db-name><ingress-suffix>`</nobr>. |
| 99 | +
|
| 100 | +### Using ingress controller |
| 101 | +
|
| 102 | +1. If your cluster uses an [ingress controller]({{< relref "/operate/kubernetes/7.8.6/networking/ingress.md" >}}), add the following to the `spec` section of your REC resource file. |
| 103 | +
|
| 104 | + Nginx: |
| 105 | +
|
| 106 | + ```sh |
| 107 | + activeActive: |
| 108 | + apiIngressUrl: <api-hostname> |
| 109 | + dbIngressSuffix: <ingress-suffix> |
| 110 | + ingressAnnotations: |
| 111 | + kubernetes.io/ingress.class: nginx |
| 112 | + nginx.ingress.kubernetes.io/backend-protocol: HTTPS |
| 113 | + nginx.ingress.kubernetes.io/ssl-passthrough: "true" |
| 114 | + method: ingress |
| 115 | + ``` |
| 116 | +
|
| 117 | +HAproxy: |
| 118 | +
|
| 119 | + ```sh |
| 120 | + activeActive: |
| 121 | + apiIngressUrl: <api-hostname> |
| 122 | + dbIngressSuffix: <ingress-suffix> |
| 123 | + ingressAnnotations: |
| 124 | + kubernetes.io/ingress.class: haproxy |
| 125 | + ingress.kubernetes.io/ssl-passthrough: "true" |
| 126 | + method: ingress |
| 127 | + ``` |
| 128 | +
|
| 129 | +2. After the changes are saved and applied, you can verify a new ingress was created for the API. |
| 130 | +
|
| 131 | + ```sh |
| 132 | + $ kubectl get ingress |
| 133 | + NAME HOSTS ADDRESS PORTS AGE |
| 134 | + rec01 api.abc.cde.example.com 225161f845b278-111450635.us.cloud.com 80 24h |
| 135 | + ``` |
| 136 | +
|
| 137 | +3. Verify you can access the API from outside the K8s cluster. |
| 138 | +
|
| 139 | + ```sh |
| 140 | + curl -k -L -i -u <username>:<password> https://<api-hostname>/v1/cluster |
| 141 | + ``` |
| 142 | +
|
| 143 | + If the API call fails, create a DNS alias that resolves your API hostname (`<api-hostname>`) to the IP address for the ingress controller's LoadBalancer. |
| 144 | + |
| 145 | +4. Make sure you have DNS aliases for each database that resolve your API hostname `<api-hostname>`,`<ingress-suffix>`, `<replication-hostname>` to the IP address of the ingress controller’s LoadBalancer. To avoid entering multiple DNS records, you can use a wildcard in your alias (such as `*.ijk.example.com`). |
| 146 | + |
| 147 | +#### If using Istio Gateway and VirtualService |
| 148 | + |
| 149 | +No changes are required to the REC spec if you are using [Istio]({{< relref "/operate/kubernetes/7.8.6/networking/istio-ingress.md" >}}) in place of an ingress controller. The `activeActive` section added above creates ingress resources. The two custom resources used to configure Istio (Gateway and VirtualService) replace the need for ingress resources. |
| 150 | + |
| 151 | +{{<warning>}} |
| 152 | +These custom resources are not controlled by the operator and will need to be configured and maintained manually. |
| 153 | +{{</warning>}} |
| 154 | + |
| 155 | +For each cluster, verify the VirtualService resource has two `- match:` blocks in the `tls` section. The hostname under `sniHosts:` should match your `<replication-hostname>`. |
| 156 | + |
| 157 | +### Using OpenShift routes |
| 158 | + |
| 159 | +1. Make sure your Redis Enterprise cluster (REC) has a different name (`<rec-name.namespace>`) than any other participating clusters. If not, you'll need to manually rename the REC or move it to a different namespace. |
| 160 | + You can check your new REC name with: |
| 161 | + ```sh |
| 162 | + oc get rec -o jsonpath='{.items[0].metadata.name}' |
| 163 | + ``` |
| 164 | +
|
| 165 | + If the rec name was modified, reapply [scc.yaml](https://github.com/RedisLabs/redis-enterprise-k8s-docs/blob/master/openshift/scc.yaml) to the namespace to reestablish security privileges. |
| 166 | + |
| 167 | + ```sh |
| 168 | + oc apply -f scc.yaml |
| 169 | + oc adm policy add-scc-to-group redis-enterprise-scc-v2 system:serviceaccounts:<namespace> |
| 170 | + ``` |
| 171 | +
|
| 172 | + Releases before 6.4.2-6 use the earlier version of the SCC, named `redis-enterprise-scc`. |
| 173 | +
|
| 174 | +1. Make sure you have DNS aliases for each database that resolve your API hostname `<api-hostname>`,`<ingress-suffix>`, `<replication-hostname>` to the route IP address. To avoid entering multiple DNS records, you can use a wildcard in your alias (such as `*.ijk.example.com`). |
| 175 | +
|
| 176 | +1. If your cluster uses [OpenShift routes]({{< relref "/operate/kubernetes/7.8.6/networking/routes.md" >}}), add the following to the `spec` section of your Redis Enterprise cluster (REC) resource file. |
| 177 | +
|
| 178 | + ```sh |
| 179 | + activeActive: |
| 180 | + apiIngressUrl: <api-hostname> |
| 181 | + dbIngressSuffix: <ingress-suffix> |
| 182 | + method: openShiftRoute |
| 183 | + ``` |
| 184 | +
|
| 185 | +1. Make sure you have DNS aliases that resolve to the routes IP for both the API hostname (`<api-hostname>`) and the replication hostname (`<replication-hostname>`) for each database. To avoid entering each database individually, you can use a wildcard in your alias (such as `*.ijk.example.com`). |
| 186 | +
|
| 187 | +1. After the changes are saved and applied, you can see that a new route was created for the API. |
| 188 | +
|
| 189 | + ```sh |
| 190 | + $ oc get route |
| 191 | + NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD |
| 192 | + rec01 api-openshift.apps.abc.example.com rec01 api passthrough None |
| 193 | + ``` |
| 194 | +
|
| 195 | +## Create an Active-Active database with `crdb-cli` |
| 196 | +
|
| 197 | +The `crdb-cli` command can be run from any Redis Enterprise pod hosted on any participating K8s cluster. You'll need the values for the [required parameters]({{< relref "/operate/kubernetes/7.8.6/active-active/create-aa-crdb-cli#document-required-parameters" >}}) for each Redis Enterprise cluster. |
| 198 | + |
| 199 | +```sh |
| 200 | +crdb-cli crdb create \ |
| 201 | + --name <db-name> \ |
| 202 | + --memory-size <mem-size> \ |
| 203 | + --encryption yes \ |
| 204 | + --instance fqdn=<rec-hostname-01>,url=https://<api-hostname-01>,username=<username-01>,password=<password-01>,replication_endpoint=<replication-endpoint-01>,replication_tls_sni=<replication-hostname-01> \ |
| 205 | + --instance fqdn=<rec-hostname-02>,url=https://<api-hostname-02>,username=<username-02>,password=<password-02>,replication_endpoint=<replication-endpoint-02>,replication_tls_sni=<replication-hostname-02> |
| 206 | +``` |
| 207 | + |
| 208 | +To create a database that syncs between more than two instances, add additional `--instance` arguments. |
| 209 | + |
| 210 | +See the [`crdb-cli` reference]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}}) for more options. |
| 211 | + |
| 212 | +## Test your database |
| 213 | + |
| 214 | +The easiest way to test your Active-Active database is to set a key-value pair in one database and retrieve it from the other. |
| 215 | + |
| 216 | +You can connect to your databases with the instructions in [Manage databases]({{< relref "/operate/kubernetes/7.8.6/re-databases/db-controller#connect-to-a-database" >}}). Set a test key with `SET foo bar` in the first database. If your Active-Active deployment is working properly, when connected to your second database, `GET foo` should output `bar`. |
0 commit comments