AWS organizations documentation change
Summary
Restructured backup policy documentation with simplified syntax explanations, added sections for considerations, IAM roles, backup vaults, quotas, and examples. Removed detailed JSON examples in favor of tabular format and condensed explanations.
Security assessment
The changes emphasize IAM role requirements (permissions to access resources and perform backups) and backup vault pre-requisites, which are security best practices. However, there's no evidence of addressing a specific vulnerability or incident. The documentation improvements focus on proper configuration rather than patching security flaws.
Diff
diff --git a/organizations/latest/userguide/orgs_manage_policies_backup_syntax.md b/organizations/latest/userguide/orgs_manage_policies_backup_syntax.md index 9c9ede05d..3611a435d 100644 --- a//organizations/latest/userguide/orgs_manage_policies_backup_syntax.md +++ b//organizations/latest/userguide/orgs_manage_policies_backup_syntax.md @@ -5 +5 @@ -Syntax for backup policiesBackup policy examples +Syntax for backup policiesConsiderationsBackup syntax: OverviewBackup syntax: rulesBackup syntax: regionsBackup syntax: selectionsBackup syntax: advanced backup settingsBackup syntax: backup plan tagsBackup policy examples @@ -13 +13 @@ This page describes backup policy syntax and provides examples. -A backup policy is a plaintext file that is structured according to the rules of [JSON](http://json.org). The syntax for backup policies follows the syntax for all management policy types. For a complete discussion of that syntax, see [Policy syntax and inheritance for management policy types](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_inheritance_mgmt.html). This topic focuses on applying that general syntax to the specific requirements of the backup policy type. +A backup policy is a plaintext file that is structured according to the rules of [JSON](http://json.org). The syntax for backup policies follows the syntax for all management policy types. For more information, see [Policy syntax and inheritance for management policy types](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_inheritance_mgmt.html). This topic focuses on applying that general syntax to the specific requirements of the backup policy type. @@ -15 +15 @@ A backup policy is a plaintext file that is structured according to the rules of -The bulk of a backup policy is the backup plan and its rules. The syntax for the backup plan within an AWS Organizations backup policy is structurally identical to the syntax used by AWS Backup, but the key names are different. In the descriptions of the policy key names below, each includes the equivalent AWS Backup plan key name. For more information about AWS Backup plans, see [CreateBackupPlan](https://docs.aws.amazon.com/aws-backup/latest/devguide/API_CreateBackupPlan.html) in the _AWS Backup Developer Guide_. +For more information about AWS Backup plans, see [CreateBackupPlan](https://docs.aws.amazon.com/aws-backup/latest/devguide/API_CreateBackupPlan.html) in the _AWS Backup Developer Guide_. @@ -17 +17 @@ The bulk of a backup policy is the backup plan and its rules. The syntax for the -###### Note +## Considerations @@ -19 +19 @@ The bulk of a backup policy is the backup plan and its rules. The syntax for the -When using JSON, duplicate key names will be rejected. If you want to include multiple plans, rules, or selections in a single policy, make sure the name of each key is unique. +**Policy syntax** @@ -21 +21 @@ When using JSON, duplicate key names will be rejected. If you want to include mu -To be complete and functional, an [effective backup policy](./orgs_manage_policies_effective.html) must include more than just a backup plan with its schedule and rules. The policy must also identify the AWS Regions and the resources to be backed up, and the AWS Identity and Access Management (IAM) role that AWS Backup can use to perform the backup. +Duplicate key names will be rejected in JSON. @@ -23 +23 @@ To be complete and functional, an [effective backup policy](./orgs_manage_polici -###### Important +Policies must specify the AWS Regions and resources to be backed up. @@ -25 +25 @@ To be complete and functional, an [effective backup policy](./orgs_manage_polici -Using the `@@assign` operator at the same level or in the organization hierarchy may introduce risk of the backup policy not creating expected backup plans. The `@@assign` operator overwrites any existing policy settings with the new values specified in the final effective policy. +Policies must specify the IAM role that AWS Backup assumes. @@ -27 +27 @@ Using the `@@assign` operator at the same level or in the organization hierarchy -The following functionally complete policy shows the basic backup policy syntax. If this example was attached directly to an account, AWS Backup would back up all resources for that account in the `us-east-1` and `eu-north-1` Regions that have the tag `dataType` with a value of either `PII` or `RED` . It backs up those resources daily at 5:00 AM to `My_Backup_Vault` and also stores a copy in `My_Secondary_Vault`. Both of those vaults are in the same account as the resource. It also stores a copy of the backup in the `My_Tertiary_Vault` in a different, explicitly specified account. The vaults must already exist in each of the specified AWS Regions for each AWS account that receives the effective policy. If any of the backed up resources are EC2 instances, then support for Microsoft Volume Shadow Copy Service (VSS) is enabled for the backups on those instances. The backup applies the tag `Owner:Backup` to each recovery point. +Using `@@assign` operator at the same level can overwrite existing settings. For more information, see A child policy overrides settings in a parent policy. @@ -28,0 +29 @@ The following functionally complete policy shows the basic backup policy syntax. +Inheritance operators control how inherited policies and account policies merge into the account's effective policy. These operators include value-setting operators and child control operators. @@ -30,145 +31 @@ The following functionally complete policy shows the basic backup policy syntax. - { - "plans": { - "PII_Backup_Plan": { - "rules": { - "My_Hourly_Rule": { - "schedule_expression": {"@@assign": "cron(0 5 ? * * *)"}, - "start_backup_window_minutes": {"@@assign": "60"}, - "complete_backup_window_minutes": {"@@assign": "604800"}, - "enable_continuous_backup": {"@@assign": false}, - "target_backup_vault_name": {"@@assign": "My_Backup_Vault"}, - "recovery_point_tags": { - "Owner": { - "tag_key": {"@@assign": "Owner"}, - "tag_value": {"@@assign": "Backup"} - } - }, - "lifecycle": { - "move_to_cold_storage_after_days": {"@@assign": "180"}, - "delete_after_days": {"@@assign": "270"}, - "opt_in_to_archive_for_supported_resources": {"@@assign": false} - }, - "copy_actions": { - "arn:aws:backup:us-west-2:$account:backup-vault:My_Secondary_Vault": { - "target_backup_vault_arn": { - "@@assign": "arn:aws:backup:us-west-2:$account:backup-vault:My_Secondary_Vault" - }, - "lifecycle": { - "move_to_cold_storage_after_days": {"@@assign": "180"}, - "delete_after_days": {"@@assign": "270"}, - "opt_in_to_archive_for_supported_resources": {"@@assign": false} - } - }, - "arn:aws:backup:us-east-1:111111111111:backup-vault:My_Tertiary_Vault": { - "target_backup_vault_arn": { - "@@assign": "arn:aws:backup:us-east-1:111111111111:backup-vault:My_Tertiary_Vault" - }, - "lifecycle": { - "move_to_cold_storage_after_days": {"@@assign": "180"}, - "delete_after_days": {"@@assign": "270"}, - "opt_in_to_archive_for_supported_resources": {"@@assign": false} - } - } - } - } - }, - "regions": { - "@@append": [ - "us-east-1", - "eu-north-1" - ] - }, - "selections": { - "tags": { - "My_Backup_Assignment": { - "iam_role_arn": {"@@assign": "arn:aws:iam::$account:role/MyIamRole"}, - "tag_key": {"@@assign": "dataType"}, - "tag_value": { - "@@assign": [ - "PII", - "RED" - ] - } - } - } - }, - "advanced_backup_settings": { - "ec2": { - "windows_vss": {"@@assign": "enabled"} - } - }, - "backup_plan_tags": { - "stage": { - "tag_key": {"@@assign": "Stage"}, - "tag_value": {"@@assign": "Beta"} - } - } - } - } - } - -Backup policy syntax includes the following components: - - * `$account` variables – In certain text strings in the policies, you can use the `$account` variable to represent the current AWS account. When AWS Backup runs a plan in the effective policy, it automatically replaces this variable with the current AWS account in which the effective policy and its plans are running. - -###### Important - -You can use the `$account` variable only in policy elements that can include an Amazon Resource Name (ARN), such as those that specify the backup vault to store the backup in, or the IAM role with permissions to perform the backup. - -For example, the following requires that a vault named `My_Vault` exist in each AWS account that the policy applies to. - - arn:aws:backup:us-west-2:**_$account_** :backup-vault:My_Vault" - -We recommend that you use AWS CloudFormation stack sets and its integration with Organizations to automatically create and configure backup vaults and IAM roles for each member account in the organization. For more information, see [Create a stack set with self-managed permissions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-getting-started-create.html#create-stack-set-service-managed-permissions) in the _AWS CloudFormation User Guide_. - - * Inheritance operators – Backup policies can use both the inheritance [value-setting operators](./policy-operators.html#value-setting-operators) and the [child control operators](./policy-operators.html#child-control-operators). - - * `plans` - -At the top level key of the policy is the `plans` key. A backup policy must always start with this fixed key name at the top of the policy file. You can have one or more backup plans under this key. - - * Each plan under the `plans` top level key has a key name that consists of the backup plan name assigned by the user. In the preceding example, the backup plan name is `PII_Backup_Plan`. You can have multiple plans in a policy, each with its own `rules`, `regions`, `selections`, and `tags`. - -This backup plan key name in a backup policy maps to the value of the `BackupPlanName` key in an AWS Backup plan. - -Each plan can contain the following elements: - - * `rules` – This key contains a collection of rules. Each rule translates to a scheduled task, with a start time and window in which to back up the resources identified by the `selections` and `regions` elements in the effective backup policy. - - * `regions` – This key contains an array list of AWS Regions whose resources can be backed up by this policy. - - * `selections` – This key contains one or more collections of resources (within the specified `regions`) that are backed up by the specified `rules`. - - * `advanced_backup_settings` – This key contains settings specific to backups running on certain resources. - - * `backup_plan_tags` – This specifies tags that are attached to the backup plan itself. - - * `rules` - -The `rules` policy key maps to the `Rules` key in an AWS Backup plan. You can have one or more rules under the `rules` key. Each rule becomes a scheduled task to perform a backup of the selected resources. - -Each rule contains a key whose name is the name of the rule. In the previous example, the rule name is "My_Hourly_Rule". The value of the rule key is the following collection of rule elements: - - * `schedule_expression` – This policy key maps to the `ScheduleExpression` key in an AWS Backup plan. - -Specifies the start time of the backup. This key contains the [@@assign inheritance value operator](./policy-operators.html#value-setting-operators) and a string value with a [CRON expression](https://www.wikipedia.org/wiki/Cron#CRON_expression) that specifies when AWS Backup is to initiate a backup job. The general format of the CRON string is: "cron( )". Each is a number or wildcard. For example, `cron(0 5 ? * 1,3,5 *)` starts the backup at 5 AM every Monday, Wednesday, and Friday. `cron(0 0/1 ? * * *)` starts the backup every hour on the hour, every day of the week. - - * `target_backup_vault_name` – This policy key maps to the `TargetBackupVaultName` key in an AWS Backup plan. - -Specifies the name of the backup vault in which to store the backup. You create the value by using AWS Backup. This key contains the [@@assign inheritance value operator](./policy-operators.html#value-setting-operators) and a string value with a vault name. - -###### Important - -The vault must already exist when the backup plan is launched the first time. We recommend that you use AWS CloudFormation stack sets and its integration with Organizations to automatically create and configure backup vaults and IAM roles for each member account in the organization. For more information, see [Create a stack set with self-managed permissions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-getting-started-create.html#create-stack-set-service-managed-permissions) in the _AWS CloudFormation User Guide_. - - * `start_backup_window_minutes` – This policy key maps to the `StartWindowMinutes` key in an AWS Backup plan. - -(Optional) Specifies the number of minutes to wait before canceling a job that does not start successfully. This key contains the [@@assign inheritance value operator](./policy-operators.html#value-setting-operators) and a value with an integer number of minutes. - - * `complete_backup_window_minutes` – This policy key maps to the `CompletionWindowMinutes` key in an AWS Backup plan. - -(Optional) Specifies the number of minutes after a backup job successfully starts before it must complete or it is canceled by AWS Backup. This key contains the [@@assign inheritance value operator](./policy-operators.html#value-setting-operators) and a value with an integer number of minutes. - - * `enable_continuous_backup` – This policy key maps to the `EnableContinuousBackup` key in an AWS Backup plan. - -(Optional) Specifies whether AWS Backup creates continuous backups. `True` causes AWS Backup to create continuous backups capable of point-in-time restore (PITR). `False` (or not specified) causes AWS Backup to create snapshot backups. +For more information, see [Inheritance operators](./policy-operators.html) and Backup policy examples. @@ -176 +33 @@ The vault must already exist when the backup plan is launched the first time. We -###### Note +**IAM roles** @@ -178 +35 @@ The vault must already exist when the backup plan is launched the first time. We -Because PITR-enabled backups can be retained for a maximum of 35 days, you must either choose `False` or don't specify a value **_if_** you set either of the following options: +The IAM role must exist when creating a backup plan for the first time. @@ -180 +37 @@ Because PITR-enabled backups can be retained for a maximum of 35 days, you must - * Set `delete_after_days` to greater than 35. +The IAM role must have permission to access resources identified by tag query. @@ -182 +39 @@ Because PITR-enabled backups can be retained for a maximum of 35 days, you must - * Set `move_to_cold_storage_after_days` to any value. +The IAM role must have permission to perform the backup. @@ -184 +41 @@ Because PITR-enabled backups can be retained for a maximum of 35 days, you must -For more information about continuous backups, see [Point-in-time recovery](https://docs.aws.amazon.com/aws-backup/latest/devguide/point-in-time-recovery.html) in the _AWS Backup Developer Guide_. +**Backup vaults** @@ -186 +43 @@ For more information about continuous backups, see [Point-in-time recovery](http - * `lifecycle` – This policy key maps to the `Lifecycle` key in an AWS Backup plan. +Vaults must exist in each specified AWS Regions before a backup plan can run. @@ -188 +45 @@ For more information about continuous backups, see [Point-in-time recovery](http -(Optional) Specifies when AWS Backup transitions this backup to cold storage and when it expires.