generated from ansible-collections/collection_template
-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #45 from hakbailey/add-backup-plan-role
Add backup plan role
- Loading branch information
Showing
23 changed files
with
680 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,67 @@ | ||
backup_create_plan | ||
================== | ||
|
||
A role to create a backup plan and optionally a vault. A set of variables for plan rules is included for use as-is or as examples for modification. This role can be combined with the backup_select_resources role to back up a selection of resources. | ||
|
||
Requirements | ||
------------ | ||
|
||
AWS User Account with the following permission: | ||
|
||
* backup:CreateBackupVault | ||
* backup:CreateBackupPlan | ||
* backup:DescribeBackupVault | ||
* backup:ListBackupPlans | ||
* backup:ListTags | ||
* backup-storage:MountCapsule | ||
* kms:CreateGrant | ||
* kms:GenerateDataKey | ||
* kms:Decrypt | ||
* kms:RetireGrant | ||
* kms:DescribeKey | ||
|
||
Role Variables | ||
-------------- | ||
|
||
* **plan_name**: (Required) The name of the backup plan you want to create | ||
* **plan_rules**: (Required) A set of rules for the backup, as a list of dicts | ||
* **plan_windows_vss_settings**: Optional settings for Windows VSS backup, see [AdvancedBackupSetting object in the AWS Backup API documentation](https://docs.aws.amazon.com/aws-backup/latest/devguide/API_AdvancedBackupSetting.html) for details | ||
* **plan_tags**: Optional tags to apply to all backups created with the plan | ||
* **vault_name**: The name of the vault you want to use or create. If not provided, the role will use (and create if needed) the AWS default vault for the account, named Default. | ||
* **vault_encryption_key_arn**: Optional ARN of key to use for vault encryption | ||
* **vault_tags**: Optional tags to apply to the vault | ||
|
||
### Included sample plan rules variables | ||
These are included in vars/main.yaml for use as-is or as examples for modification. | ||
|
||
* **hourly_backup**: Rules specifying hourly continous backup at :15 UTC with 7-day retention | ||
* **daily_backup**: Rules specifying daily backup at 5am UTC with Amazon defaults for all other settings | ||
* **weekly_backup**: Rules specifying weekly backup on Mondays at 5am UTC with 90 day retention after quick transition to cold storage | ||
* **monthly_backup**: Rules specifying monthly backup at 5am UTC on 1st of month with copy to additional vault (requires an additional variable **copy_vault_name** be set with the name of the vault to copy to) | ||
|
||
|
||
Dependencies | ||
------------ | ||
|
||
* role: [aws_setup_credentials](../aws_setup_credentials/README.md) | ||
|
||
Example Playbook | ||
---------------- | ||
|
||
- hosts: localhost | ||
roles: | ||
- role: cloud.aws_ops.backup_create_plan | ||
plan_name: my-backup-plan | ||
plan_rules: "{{ daily_backup }}" | ||
|
||
License | ||
------- | ||
|
||
GNU General Public License v3.0 or later | ||
|
||
See [LICENCE](https://github.com/ansible-collections/cloud.aws_ops/blob/main/LICENSE) to see the full text. | ||
|
||
Author Information | ||
------------------ | ||
|
||
* Ansible Cloud Content Team |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
--- | ||
vault_name: Default |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
--- | ||
dependencies: | ||
- role: cloud.aws_ops.aws_setup_credentials |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,53 @@ | ||
--- | ||
- name: Verify required variables | ||
block: | ||
- name: Fail when plan variables are not defined | ||
ansible.builtin.fail: | ||
msg: "Required variable {{ item }} has not been defined" | ||
when: vars[item] is undefined | ||
loop: | ||
- plan_name | ||
- plan_rules | ||
|
||
- name: Run backup_create_plan_role | ||
module_defaults: | ||
group/aws: "{{ aws_setup_credentials__output }}" | ||
block: | ||
- name: Create or update backup vault | ||
block: | ||
- name: Create or update backup vault | ||
amazon.aws.backup_vault: | ||
state: present | ||
backup_vault_name: "{{ vault_name }}" | ||
encryption_key_arn: "{{ vault_encryption_key_arn | default(omit) }}" | ||
tags: "{{ vault_tags | default(omit) }}" | ||
register: backup_create_plan_backup_vault_result | ||
|
||
- name: Verify that vault has been created/updated | ||
ansible.builtin.debug: | ||
msg: Vault '{{ vault_name }}' successfully created/updated. | ||
when: backup_create_plan_backup_vault_result is changed | ||
|
||
- name: Verify that vault already exists | ||
ansible.builtin.debug: | ||
msg: Vault '{{ vault_name }}' exists, no updates needed. | ||
when: backup_create_plan_backup_vault_result is not changed | ||
|
||
- name: Create or update backup plan | ||
amazon.aws.backup_plan: | ||
state: present | ||
backup_plan_name: "{{ plan_name }}" | ||
rules: "{{ plan_rules }}" | ||
advanced_backup_settings: "{{ plan_windows_vss_settings | default(omit) }}" | ||
tags: "{{ plan_tags | default(omit) }}" | ||
register: backup_create_plan_backup_plan_result | ||
|
||
- name: Verify that plan has been created/updated | ||
ansible.builtin.debug: | ||
msg: Plan '{{ plan_name }}' successfully created/updated. | ||
when: backup_create_plan_backup_plan_result is changed | ||
|
||
- name: Verify that plan already exists | ||
ansible.builtin.debug: | ||
msg: Plan '{{ plan_name }}' exists, no updates needed. | ||
when: backup_create_plan_backup_plan_result is not changed |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,30 @@ | ||
--- | ||
hourly_backup: # Hourly continous backup at :15 with 7-day retention | ||
rule_name: hourly | ||
target_backup_vault_name: "{{ vault_name }}" | ||
schedule_expression: "cron(15 * ? * * *)" | ||
start_window_minutes: 60 | ||
completion_window_minutes: 120 | ||
enable_continuous_backup: true | ||
lifecycle: | ||
delete_after_days: 7 | ||
|
||
daily_backup: # Daily backup at 5am UTC with Amazon defaults for all other settings | ||
rule_name: daily | ||
target_backup_vault_name: "{{ vault_name }}" | ||
schedule_expression: "cron(0 5 ? * * *)" | ||
|
||
weekly_backup: # Weekly backup on Mondays at 5am UTC with 90 day retention after quick transition to cold storage | ||
rule_name: weekly | ||
target_backup_vault_name: "{{ vault_name }}" | ||
schedule_expression: "cron(0 5 ? * MON *)" | ||
lifecycle: | ||
delete_after_days: 91 | ||
move_to_cold_storage_after_days: 1 | ||
|
||
monthly_backup: # Monthly backup at 5am UTC on 1st of month with copy to additional vault | ||
rule_name: monthly | ||
target_backup_vault_name: "{{ vault_name }}" | ||
schedule_expression: "cron(0 5 1 * ? *)" | ||
copy_actions: | ||
- destination_backup_vault_name: "{{ copy_vault_name }}" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,83 @@ | ||
backup_select_resources | ||
================== | ||
|
||
A role to configure backups for selected resources. The role requires an existing backup vault and plan, and adds selected resources to the provided plan. A set of variables for resource selections is included for use as-is or as examples for modification. This role can be combined with the `backup_create_plan` role to create or update a backup plan if one does not already exist. (see [example playbook](#create-backup-plan-and-select-resources)). | ||
|
||
Requirements | ||
------------ | ||
|
||
AWS User Account with the following permission: | ||
|
||
* backup:CreateBackupSelection | ||
* backup:DeleteBackupSelection | ||
* backup:GetBackupPlan | ||
* backup:GetBackupSelection | ||
* backup:ListBackupSelections | ||
* iam:GetRole | ||
|
||
Role Variables | ||
-------------- | ||
|
||
* **plan_name**: (Required) The name of the backup plan you want to use for the selected resources. | ||
* **selection_name**: (Required) The display name of the resource selection you want to back up. | ||
* **selection_resources**: (Required) List of resources selected for backup. Can use wild cards and/or combine with selection options below to precisely restrict resources based on various conditions. See included vars for examples. | ||
* **selection_excluded_resources**: List of resources to exclude from backup | ||
* **selection_tags**: List of resource tags selected for backup | ||
* **selection_conditions**: Conditions for resources to back up | ||
* **backup_role_name**: (Required) The name of an IAM role with permissions to perform all needed backup actions for the selected resources. Alternatively, provide a new for a new IAM role which will be created with the same permissions as the AWSBackupDefaultServiceRole (note: these permissions allow backups and restores for all resources). | ||
|
||
### Included sample resource selection variables | ||
These are included in vars/main.yaml for use as-is or as examples for modification. | ||
|
||
* **all_resources**: All AWS resources | ||
* **all_s3_buckets** All S3 buckets | ||
* **all_rds_db_instances**: All RDS database instances | ||
* **tag_list_backup_or_prod**: Resources tagged {"backup": "true"} OR {"env": "prod"}, for use with the **selection_tags** role variable | ||
* **conditions_tagged_backup_and_prod**: Resources tagged {"backup": "true"} AND {"env": "prod"}, for use with the **selection_conditions** role variable | ||
|
||
Dependencies | ||
------------ | ||
|
||
* role: [aws_setup_credentials](../aws_setup_credentials/README.md) | ||
|
||
Example Playbooks | ||
---------------- | ||
|
||
### Select resources | ||
- hosts: localhost | ||
roles: | ||
- role: cloud.aws_ops.backup_select_resources | ||
vars: | ||
plan_name: my-backup-plan | ||
selection_name: s3_buckets | ||
selection_resources: | ||
- "{{ all_s3_buckets }}" | ||
|
||
### Create backup plan and select resources | ||
|
||
- hosts: localhost | ||
roles: | ||
- role: cloud.aws_ops.backup_create_plan | ||
plan_name: my-backup-plan | ||
plan_rules: "{{ daily_backup }}" | ||
|
||
- hosts: localhost | ||
roles: | ||
- role: cloud.aws_ops.backup_select_resources | ||
vars: | ||
plan_name: my-backup-plan | ||
selection_name: s3_buckets | ||
selection_resources: | ||
- "{{ all_s3_buckets }}" | ||
|
||
License | ||
------- | ||
|
||
GNU General Public License v3.0 or later | ||
|
||
See [LICENCE](https://github.com/ansible-collections/cloud.aws_ops/blob/main/LICENSE) to see the full text. | ||
|
||
Author Information | ||
------------------ | ||
|
||
* Ansible Cloud Content Team |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,12 @@ | ||
{ | ||
"Version": "2012-10-17", | ||
"Statement":[ | ||
{ | ||
"Effect": "Allow", | ||
"Principal": { | ||
"Service": "backup.amazonaws.com" | ||
}, | ||
"Action": "sts:AssumeRole" | ||
} | ||
] | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
--- | ||
dependencies: | ||
- role: cloud.aws_ops.aws_setup_credentials |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,75 @@ | ||
--- | ||
- name: Fail when name, role, and resource variables are not defined | ||
ansible.builtin.fail: | ||
msg: "Required variable {{ item }} has not been defined" | ||
when: vars[item] is undefined | ||
loop: | ||
- backup_role_name | ||
- plan_name | ||
- selection_name | ||
- selection_resources | ||
|
||
- name: Run backup_select_resources role | ||
module_defaults: | ||
group/aws: "{{ aws_setup_credentials__output }}" | ||
block: | ||
- name: Get plan info | ||
amazon.aws.backup_plan_info: | ||
backup_plan_names: | ||
- "{{ plan_name }}" | ||
register: backup_select_resources_backup_plan_info | ||
|
||
- name: Fail when backup plan does not exist | ||
ansible.builtin.fail: | ||
msg: Backup plan {{ plan_name }} does not exist, please create or confirm plan name is correct. | ||
when: backup_select_resources_backup_plan_info.backup_plans | length == 0 | ||
|
||
- name: Get provided IAM role info | ||
community.aws.iam_role_info: | ||
name: "{{ backup_role_name }}" | ||
register: backup_select_resources_role_info | ||
|
||
- name: Create new role when IAM role does not exist | ||
block: | ||
- name: Create role | ||
when: backup_select_resources_role_info.iam_roles | length == 0 | ||
community.aws.iam_role: | ||
name: "{{ backup_role_name }}" | ||
state: present | ||
assume_role_policy_document: '{{ lookup("file", "backup-policy.json") }}' | ||
create_instance_profile: false | ||
description: "AWS Backup Role" | ||
managed_policy: | ||
- arn:aws:iam::aws:policy/service-role/AWSBackupServiceRolePolicyForBackup | ||
wait: true | ||
register: backup_select_resources_new_role_info | ||
|
||
- name: Wait for role to be created | ||
ansible.builtin.pause: | ||
seconds: 8 | ||
|
||
- name: Set backup role ARN | ||
ansible.builtin.set_fact: | ||
backup_select_resources_backup_role_arn: "{{ backup_select_resources_role_info.iam_roles[0].arn if backup_select_resources_new_role_info is skipped else backup_select_resources_new_role_info.arn }}" | ||
|
||
- name: Create or update backup selection | ||
amazon.aws.backup_selection: | ||
state: present | ||
backup_plan_name: "{{ plan_name }}" | ||
selection_name: "{{ selection_name }}" | ||
iam_role_arn: "{{ backup_select_resources_backup_role_arn }}" | ||
resources: "{{ selection_resources }}" | ||
list_of_tags: "{{ selection_tags | default(omit) }}" | ||
not_resources: "{{ selection_excluded_resources | default(omit) }}" | ||
conditions: "{{ selection_conditions | default(omit) }}" | ||
register: backup_select_resources_selection_result | ||
|
||
- name: Verify that selection has been created/updated | ||
ansible.builtin.debug: | ||
msg: Backup selection '{{ selection_name }}' successfully created/updated. | ||
when: backup_select_resources_selection_result is changed | ||
|
||
- name: Verify that selection already exists | ||
ansible.builtin.debug: | ||
msg: Backup selection '{{ selection_name }}' exists, no updates needed. | ||
when: backup_select_resources_selection_result is not changed |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
--- | ||
all_resources: "*" | ||
all_s3_buckets: "arn:aws:s3:::*" | ||
all_rds_db_instances: "arn:aws:rds:*:*:db:*" | ||
|
||
tag_list_backup_or_prod: # Resources tagged {"backup": "true"} OR {"env": "prod"} | ||
- condition_type: "STRINGEQUALS" | ||
condition_key: "backup" | ||
condition_value: "true" | ||
- condition_type: "StringEquals" | ||
condition_key: "env" | ||
condition_value: "prod" | ||
|
||
conditions_tagged_backup_and_prod: # Resources tagged {"backup": "true"} AND {"env": "prod"} | ||
string_equals: | ||
- condition_key: "aws:ResourceTag/backup" | ||
condition_value: "true" | ||
- condition_key: "aws:ResourceTag/env" | ||
condition_value: "prod" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
# Specifically run tests against the oldest versions that we support | ||
boto3==1.22.0 | ||
botocore==1.25.0 | ||
|
||
# AWS CLI has `botocore==` dependencies, provide the one that matches botocore | ||
# to avoid needing to download over a years worth of awscli wheels. | ||
awscli==1.23.0 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# Our code is based on the AWS SDKs | ||
boto3 | ||
botocore |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
cloud/aws | ||
role/backup_create_plan | ||
time=3m |
2 changes: 2 additions & 0 deletions
2
tests/integration/targets/test_backup_create_plan/defaults/main.yml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
--- | ||
aws_security_token: '{{ security_token | default(omit) }}' |
Oops, something went wrong.