You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/artemis/rollouts/index.md
+22-20Lines changed: 22 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,17 +8,19 @@ You may set up a **Rollout** to automate the rollout of one or more [guardrails]
8
8
9
9
A rollout provides a predictable, ordered mechanism for deploying guardrails to your organization. When you create a rollout, you choose one or more guardrails that you would like to deploy, select the accounts to deploy them to, and set a deployment and communication schedule for promoting the guardrails through phases.
10
10
11
-
Rollout allow you to control the deployment schedule as well as communications with application team, for example:
11
+
Rollouts allow you to control the deployment schedule as well as communications with application teams, for example:
12
12
- Schedule automatic transitions from one [phase](guardrails#phases) to another.
13
13
- Automatically enforce guardrails once there are no alarms.
14
14
- Send email notices to account teams on a schedule or when phase change events occur.
15
15
16
16
17
17
## Examples
18
-
The following examples use terraform to illustrate the capabilities of a rollout, but you can create a rollout from the console if you prefer.
18
+
The following examples use Terraform to illustrate the capabilities of a rollout, but you can create a rollout from the console if you prefer.
19
19
20
20
### Rollout Basics
21
-
A rollout should include at least one guardrail. Once the rollout starts, you cannot be subsequently add, remove, or change the guardrails. You may add or remove accounts after the rollout starts, but you will usually want to include all the accounts before you move beyond the `draft` phase.
21
+
A rollout should include at least one guardrail. Once the rollout starts, you cannot subsequently add, remove, or change the guardrails.
22
+
23
+
You may add or remove accounts after the rollout starts, but be careful when doing so. Adding an account to a rollout will move the guardrail directly to the current rollout phase.
22
24
23
25
```hcl
24
26
resource "rollout" "foo" {
@@ -150,7 +152,7 @@ resource "rollout" "foo" {
150
152
151
153
### Relative Dates
152
154
153
-
All dates are "absolute" in the rollout, but you can use HCL functions to make them relative. This makes it easier to manage the plan if dates change in the future since they tend to be related to each other.
155
+
All dates are "absolute" in the rollout, but you can use HCL functions to make them relative. This makes it easier to manage the plan if dates change in the future, since they tend to be related to each other.
154
156
155
157
```hcl
156
158
locals {
@@ -186,7 +188,7 @@ resource "rollout" "foo" {
186
188
187
189
### Transitioning as soon as there are no alerts
188
190
189
-
If you want, you may use `start_early_if = "no_alerts"` automatically enter a phase when there are no alerts, regardless of the schedule. For example, accounts could go straight to enforceif they don't have any alarms for the controls in the rollout.
191
+
If you want, you can configure a rollout to automatically move accounts to a phase when there are no alerts, regardless of the schedule. For example, accounts could go straight to the `enforce` phase if they don't have any alarms for the guardrails in the rollout. To do set, set `start_early_if = "no_alerts"` in the phase block.
190
192
191
193
```hcl
192
194
resource "rollout" "foo" {
@@ -239,9 +241,9 @@ resource "rollout" "bar" {
239
241
}
240
242
```
241
243
242
-
Note that by using the data source in the terraform plan, the account list will ONLY be updated if you re-run the plan; The list of accounts is resolved in the plan phase of the terraform run. If you want to update the list, you have to re-run the plan. The UI also makes it possible to add accounts by tag, even though they are stored internally as IDs.
244
+
Note that by using the data source in the Terraform plan, the account list will ONLY be updated if you re-run the plan; The list of accounts is resolved in the plan phase of the Terraform run. If you want to update the list, you have to re-run the plan. The UI also makes it possible to add accounts by tag, even though they are stored internally as IDs.
243
245
244
-
Guardrails, on the other hand, cannot be added or removed once the rollout has started. If guardrails are added or removed that match the tag, then subsequent terraform runs will fail - the list of guardrails no longer match the current state, but you are not allowed to update them. To avoid this situation, you can use an `ignore_changes` lifecycle policy.
246
+
Guardrails, on the other hand, cannot be added or removed once the rollout has started. If guardrails are added or removed that match the tag, then subsequent Terraform runs will fail - the list of guardrails no longer matches the current state, but you are not allowed to update them. To avoid this situation, you can use an `ignore_changes` lifecycle policy.
Rollouts provide a predictable way to roll out your guardrails. How to deploy them is up to you; many customer prefer to deploy small, incremental changes frequently, while others prefer larger, less frequent changes. Both options are possible with guardrails.
293
+
Rollouts provide a predictable way to roll out your guardrails. How to deploy them is up to you; many customers prefer to deploy small, incremental changes frequently, while others prefer larger, less frequent changes. Both options are possible with guardrails.
292
294
293
-
In either case, your policy posture is dynamic, and will change over time. As new guardrails are rolled out to existing accounts, they also need to be applied to new accounts, or existing accounts that are newly imported. You can use `tags` on guardrails to help define baselines and manage to a known set of guardrails.
295
+
In either case, your policy posture is dynamic and will change over time. As new guardrails are rolled out to existing accounts, they also need to be applied to new accounts or existing accounts that are newly imported. You can use `tags` on guardrails to help define baselines and manage to a known set of guardrails.
294
296
295
297
The process is simple; define a [tag](#dynamic-attachments-via-tags) for your baseline, and as you deploy guardrails, tag them with any baseline that you want them to be included in.
296
298
297
299
This can simplify managing a consistent posture:
298
-
- When *brand new accounts* are added, you can deploy the baseline by creating a rollout that includes all guardrails with the baseline tag(s). Since the accounts are new, you can probably move them straight to enforce (or use `start_early_if` to allow a relaxed scheduled but progress faster if there are no alarms).
299
-
- When *existing account are newly imported*, you may choose to deploy the baseline to bring them "up to standards". Alternatively, deploy guardrails iteratively in priority order until the baseline has been reached.
300
-
- You can *manage drift* and ensure accounts have the baseline installed. Because guardrails that are already in `enforce` will not be re-applied, simply create a deployment plan to apply the baseline and attach any accounts. Any "missing" guardrails will be deployed on the rollout schedule. Accounts that already meet the baseline will be unaffected, and will not receive any notices.
300
+
- When *brand new accounts* are added, you can deploy the baseline by creating a rollout that includes all guardrails with the baseline tag(s). Since the accounts are new, you can probably move them straight to enforce (or use `start_early_if` to allow a relaxed schedule but progress faster if there are no alarms).
301
+
- When *existing accounts are newly imported*, you may choose to deploy the baseline to bring them "up to standards". Alternatively, deploy guardrails iteratively in priority order until the baseline has been reached.
302
+
- You can *manage drift* and ensure accounts have the baseline installed. Because guardrails that are already in `enforce` will not be re-applied, simply create a deployment plan to apply the baseline and attach any accounts. Any "missing" guardrails will be deployed on the rollout schedule. Accounts that already meet the baseline will be unaffected, and no notices will be sent for them.
301
303
302
304
303
305
### Detaching guardrails
@@ -326,8 +328,8 @@ A guardrail may be included in more than one rollout, and an account may be a me
326
328
- Rollout `bar` also includes the `S3 Bucket Encryption at Rest` guardrail. Account `111111111111` is also included in this rollout. Currently, this rollout is in `Check` phase, scheduled to go to `Enforce` in 3 weeks.
327
329
- As a result:
328
330
- For account `111111111111`, the `S3 Bucket Encryption at Rest` is currently in `Check` phase.
329
-
- There should be no warning or welcome notices from the `foo` for the `111111111111` account, because it is already in the `Check` phase. It would have already been sent warnings and/or welcome notices from the `bar` rollout.
330
-
- Warnings and welcome for the `Enforce` phase will be sent to `111111111111` from the the `foo` rollout, because `foo` rollout is scheduled to transition the account to `enforce` before `bar` will.
331
+
- There should be no warning or welcome notices from the `foo`rollout for the `111111111111` account, because it is already in the `Check` phase. It would have already been sent warnings and/or welcome notices from the `bar` rollout.
332
+
- Warnings and welcome for the `Enforce` phase will be sent to `111111111111` from the `foo` rollout, because `foo` rollout is scheduled to transition the account to `enforce` before `bar` will.
331
333
332
334
333
335
The schedule is the same for all accounts in a rollout. Rollouts only move forward, from `draft` -> `preview` -> `check` -> `enforce`.
@@ -339,7 +341,7 @@ You can manually move an account through the phases for a guardrail, or for a ro
339
341
340
342
## Starting, Stopping, and Pausing a Rollout
341
343
342
-
The guardrails for a rollout are set when the rollout starts, and cannot be subsequently changed
344
+
The guardrails for a rollout are set when the rollout starts, and cannot be subsequently changed.
343
345
344
346
Accounts can be attached after the rollout starts, and they will immediately proceed to the "current" phase of the rollout. They will not receive any missed notices, but they will receive the "welcome" message for the current phase if they are transitioned due to the rollout.
345
347
@@ -349,7 +351,7 @@ You may change the dates in the rollout after it has started.
349
351
350
352
You can pause a rollout. While paused, no state transitions will occur and no notices will be sent. If you subsequently resume the rollout, any "missed" notices will not be sent, but accounts will be moved to whatever state the rollout dictates, and they will receive the "welcome" notice for that phase if they are transitioned due to the rollout.
351
353
352
-
Likewise, you can pause a single account to "pin" it to its current phase. The behavior is the same as when the rollout is paused: While paused, no state transitions will occur and no notices will be sent. If you subsequently resume the rollout, any "missed" notices will not be sent, but the account will be moved to whatever state the rollout dictates, and will receive the "welcome" notice for that phase if it is transitioned due to the rollout.
354
+
Likewise, you can pause a single account to "pin" it to its current phase. The behavior is the same as when the rollout is paused: While paused, no state transitions will occur, and no notices will be sent. If you subsequently resume the rollout, any "missed" notices will not be sent, but the account will be moved to whatever state the rollout dictates, and will receive the "welcome" notice for that phase if it is transitioned due to the rollout.
353
355
354
356
A rollout is "complete" once all the accounts in it are at the final phase, or you choose to mark it "complete".
355
357
@@ -359,7 +361,7 @@ Updating policies on a guardrail would be done via a new rollout. Either:
359
361
360
362
Removing a guardrail "uninstalls it". You cannot delete a guardrail that is part of an active rollout.
361
363
362
-
If you attempt to delete a guardrail, or to edit a policy setting for a guardrail that is in `check` or `enforce` for any account, it will fail unless "forced". You must either:
364
+
If you attempt to delete a guardrail or to edit a policy setting for a guardrail that is in `check` or `enforce` for any account, it will fail unless "forced". You must either:
363
365
- move the guardrail back to `preview` or `draft` for all accounts first or
0 commit comments