Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 000fcbb

Browse files
committed
proofread
1 parent 4e05342 commit 000fcbb

File tree

1 file changed

+22
-20
lines changed

1 file changed

+22
-20
lines changed

docs/artemis/rollouts/index.md

Lines changed: 22 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,19 @@ You may set up a **Rollout** to automate the rollout of one or more [guardrails]
88

99
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.
1010

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:
1212
- Schedule automatic transitions from one [phase](guardrails#phases) to another.
1313
- Automatically enforce guardrails once there are no alarms.
1414
- Send email notices to account teams on a schedule or when phase change events occur.
1515

1616

1717
## 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.
1919

2020
### 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.
2224

2325
```hcl
2426
resource "rollout" "foo" {
@@ -150,7 +152,7 @@ resource "rollout" "foo" {
150152

151153
### Relative Dates
152154

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.
154156

155157
```hcl
156158
locals {
@@ -186,7 +188,7 @@ resource "rollout" "foo" {
186188

187189
### Transitioning as soon as there are no alerts
188190

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 enforce if 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.
190192

191193
```hcl
192194
resource "rollout" "foo" {
@@ -239,9 +241,9 @@ resource "rollout" "bar" {
239241
}
240242
```
241243

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.
243245

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.
245247

246248
```hcl
247249
data "turbot_resources" "guardrails" {
@@ -276,28 +278,28 @@ filter = "$.AccountAlias:morales-aaa,morales-aab"
276278
# regex of account aliases
277279
filter = "$.AccountAlias:/morales-aa.*/"
278280
279-
# GCP project ids...
281+
# GCP project IDs...
280282
filter = "$.projectId:morales-aac"
281283
282-
# Azure Sub ids...
284+
# Azure subscription IDs...
283285
filter = "$.subscriptionId:'236a078d-0292-46be-80a3-cd8a1cbccde0'"
284-
# or title and type?
286+
# or title and type?
285287
filter = "$.displayName:'morales AAA' resourceType:subscription"
286288
```
287289

288290

289291
### Baselines
290292

291-
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.
292294

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.
294296

295297
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.
296298

297299
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.
301303

302304

303305
### Detaching guardrails
@@ -326,8 +328,8 @@ A guardrail may be included in more than one rollout, and an account may be a me
326328
- 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.
327329
- As a result:
328330
- 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.
331333

332334

333335
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
339341

340342
## Starting, Stopping, and Pausing a Rollout
341343

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.
343345

344346
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.
345347

@@ -349,7 +351,7 @@ You may change the dates in the rollout after it has started.
349351

350352
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.
351353

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.
353355

354356
A rollout is "complete" once all the accounts in it are at the final phase, or you choose to mark it "complete".
355357

@@ -359,7 +361,7 @@ Updating policies on a guardrail would be done via a new rollout. Either:
359361

360362
Removing a guardrail "uninstalls it". You cannot delete a guardrail that is part of an active rollout.
361363

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:
363365
- move the guardrail back to `preview` or `draft` for all accounts first or
364366
- detach the guardrail from all accounts or
365367
- resubmit the request with a 'force' flag

0 commit comments

Comments
 (0)