Skip to content

Commit a065767

Browse files
burythehammerburythehammer
authored
Merge pull request #639 from RedisLabs/docs/cmk-guide
CMK guide
2 parents dcc674e + a149345 commit a065767

File tree

3 files changed

+148
-3
lines changed

3 files changed

+148
-3
lines changed

‎docs/guides/cmk-guide.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
page_title: "Guide to using Customer Managed Keys (CMKs)"
3+
---
4+
5+
# Customer Managed Keys
6+
7+
Customer managed keys (CMKs) are a feature in Redis Cloud that lets users encrypt the data within their databases remotely.
8+
Redis Cloud supports two encryption options: using a Redis-managed encryption key or using a customer-managed key (CMK),
9+
where customers supply and control the key themselves.
10+
11+
Because of how subscriptions operate, the Terraform flow for CMKs is slightly different to Terraform flows you may have
12+
come across before. In this case, Terraform requires applying the resource twice. The Terraform workflow for enabling
13+
CMKs differs from standard resource provisioning due to a dependency cycle between cloud providers and the Redis Cloud API.
14+
15+
The Terraform flow looks like this:
16+
- First `terraform apply` to enable CMK and get Redis service account info.
17+
- Grant Redis service account access to your CMK in your cloud provider.
18+
- Second `terraform apply` to update the encryption information in Redis Cloud.
19+
20+
CMKs are provided at the subscription level, not at the database level. For a multi-region database (active-active)
21+
you will need to provide a key for each region. These can be the same key, but they must be specified for each region.
22+
23+
Here are examples of subscriptions which use a CMK. One is a pro RedisCloud subscription, the other is active-active:
24+
25+
## Pro Subscription:
26+
27+
```hcl
28+
resource "rediscloud_subscription" "example" {
29+
name = "..."
30+
payment_method = "credit-card"
31+
payment_method_id = "..."
32+
customer_managed_key_enabled = true
33+
34+
cloud_provider {
35+
provider = "GCP"
36+
region {
37+
region = "europe-west2"
38+
networking_deployment_cidr = "..."
39+
}
40+
}
41+
42+
# only one cmk required for pro subscriptions
43+
customer_managed_key {
44+
resource_name = "..."
45+
}
46+
47+
creation_plan {
48+
dataset_size_in_gb = 1
49+
quantity = 1
50+
replication = false
51+
support_oss_cluster_api = false
52+
throughput_measurement_by = "operations-per-second"
53+
throughput_measurement_value = 10000
54+
}
55+
}
56+
57+
output "customer_managed_key_redis_service_account" {
58+
value = rediscloud_subscription.example.customer_managed_key_redis_service_account
59+
}
60+
```
61+
62+
## Active-Active Subscription:
63+
64+
```hcl
65+
resource "rediscloud_active_active_subscription" "example" {
66+
name = "..."
67+
payment_method = "credit-card"
68+
payment_method_id = "..."
69+
customer_managed_key_enabled = true
70+
cloud_provider = "GCP"
71+
72+
73+
# multiple keys required for active active subscriptions
74+
customer_managed_key {
75+
resource_name = "..."
76+
region = "europe-west1"
77+
}
78+
79+
customer_managed_key {
80+
resource_name = "..."
81+
region = "europe-west2"
82+
}
83+
84+
# creation plan is to show how the regions line up with the keys
85+
creation_plan {
86+
memory_limit_in_gb = 1
87+
quantity = 1
88+
region {
89+
region = "europe-west1"
90+
networking_deployment_cidr = "..."
91+
write_operations_per_second = 1000
92+
read_operations_per_second = 1000
93+
}
94+
region {
95+
region = "europe-west2"
96+
networking_deployment_cidr = "..."
97+
write_operations_per_second = 1000
98+
read_operations_per_second = 1000
99+
}
100+
}
101+
102+
output "customer_managed_key_redis_service_account" {
103+
value = rediscloud_active_active_subscription.example.customer_managed_key_redis_service_account
104+
}
105+
}
106+
```
107+
108+
109+
## How to activate CMK for your subscription
110+
111+
### 1. Create your CMK(s) in your cloud provider
112+
This can be done either using Terraform or manually creating one in the cloud provider console.
113+
114+
### 2. Activate the `customer_managed_key_enabled` flag
115+
116+
The setup is relatively similar between the two kinds of subscriptions, and is enabled by activation of the
117+
`customer_managed_key_enabled` flag on the subscription.
118+
119+
Run `terraform apply` with this flag enabled on your subscription.
120+
121+
The subscription is put into a `encryption_key_pending` state - and will output the
122+
`customer_managed_key_redis_service_account` information for the next step.
123+
124+
### 3. Grant your `customer_managed_key_redis_service_account` permission to use your CMK(s)
125+
126+
Now your redis service account is created with your subscription. You need to grant the CMK access to this service account.
127+
128+
A property of the subscription is `customer_managed_key_redis_service_account` - use this to grant permissions to your CMK.
129+
130+
You will need to grant the CMK permissions on the cloud provider externally. This can be done by either manually using
131+
the cloud provider console, or you can use the Terraform provider.
132+
133+
The exact permissions depend on the provider, but for a GCP account you need to grant the following:
134+
135+
- Cloud KMS CryptoKey Encrypter/Decrypter
136+
- Cloud KMS Viewer
137+
138+
### 4. Update the subscription
139+
140+
Now that you have granted access to your CMK, the subscription can be transitioned fully into an active subscription state.
141+
142+
Simply `terraform apply` again.
143+
144+
Terraform will now update the subscription with the CMK information using the `customer_managed_key` blocks. Note that
145+
if you have an active-active subscription with multiple regions, you must provide a block for each region. This is true
146+
even if the CMK is the same.

‎docs/resources/rediscloud_active_active_subscription.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ subscription, then the databases defined as separate resources will be attached
1919
the subscription. The creation_plan block can ONLY be used for provisioning new
2020
subscriptions, the block will be ignored if you make any further changes or try importing the resource (e.g. `terraform import` ...).
2121

22-
~> **Note:** The CMK (customer managed encryption key) fields require a specific flow which involves a multi step apply. Please refer to the relevant documents if using these fields.
22+
~> **Note:** The CMK (customer managed encryption key) fields require a specific flow which involves a multistep apply. Refer to [this guide](../guides/cmk-guide.md) for more information.
2323

2424
## Example Usage
2525

‎docs/resources/rediscloud_subscription.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,7 @@ subscription, then the databases defined as separate resources will be attached
2020
the subscription. The creation_plan block can ONLY be used for provisioning new
2121
subscriptions, the block will be ignored if you make any further changes or try importing the resource (e.g. `terraform import` ...).
2222

23-
~> **Note:** The CMK (customer managed encryption key) fields require a specific flow which involves a multi step apply. Please refer to the relevant documents if using these fields.
24-
23+
~> **Note:** The CMK (customer managed encryption key) fields require a specific flow which involves a multistep apply. Refer to [this guide](../guides/cmk-guide.md) for more information.
2524
## Example Usage
2625

2726
```hcl

0 commit comments

Comments
 (0)