Add playbook docs

README.md

@@ -1,17 +1,17 @@
-# cloud.aws_ops roles/playbooks to demo Ansible on AWS
+# cloud.aws_ops roles/playbooks/rulebooks to demo Ansible on AWS
 
 This repository hosts the `cloud.aws_ops` Ansible Collection.
 
-The collection includes a variety of Ansible roles and playbooks to help automate the management of resources on AWS.
+The collection includes a variety of Ansible roles, playbooks, and rulebooks to help automate the management of resources on AWS.
 
 <!--start requires_ansible-->
 ## Ansible version compatibility
 
-This collection has been tested against following Ansible versions: **>=2.12.0**.
+This collection has been tested against following Ansible versions: **>=2.13.0**.
 
 ## Included content
 
-Click on the name of a role to view that content's documentation:
+Click on the name of a role, playbook, or rulebook to view that content's documentation:
 
 <!--start collection content-->
 ### Roles
@@ -29,11 +29,16 @@ Name | Description
 [cloud.aws_ops.moving_objects_between_buckets](https://github.com/ansible-collections/cloud.aws_ops/blob/main/roles/moving_objects_between_buckets/README.md)|A role to move objects from one bucket to another bucket.
 [cloud.aws_ops.awsconfig_apigateway_with_lambda_integration](https://github.com/ansible-collections/cloud.aws_ops/blob/main/roles/awsconfig_apigateway_with_lambda_integration/README.md)|A role to create/delete an API gateway with lambda function integration.
 
-
 ### Playbooks
 Name | Description
 --- | ---
-cloud.aws_ops.webapp|A playbook to create a webapp on AWS.
+[cloud.aws_ops.eda](https://github.com/ansible-collections/cloud.aws_ops/blob/main/playbooks/README.md)|A set of playbooks to restore AWS Cloudtrail configurations, created for use with the [cloud.aws_manage_cloudtrail_encryption rulebook](https://github.com/ansible-collections/cloud.aws_ops/blob/main/extensions/eda/rulebooks/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md).
+[cloud.aws_ops.webapp](https://github.com/ansible-collections/cloud.aws_ops/blob/main/playbooks/webapp/README.md)|A set of playbooks to create, delete, or migrate a webapp on AWS.
+
+### Rulebooks
+Name | Description
+--- | ---
+[cloud.aws_ops.aws_manage_cloudtrail_encryption](https://github.com/ansible-collections/cloud.aws_ops/blob/main/extensions/eda/rulebooks/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md)|An Event-Driven Ansible rulebook to ensure that an existing encrypted AWS Cloudtrail trail will not be deleted or have its encryption removed.
 <!--end collection content-->
 
 ## Installation and Usage
@@ -42,6 +47,7 @@ cloud.aws_ops.webapp|A playbook to create a webapp on AWS.
 
 The [amazon.aws](https://github.com/ansible-collections/amazon.aws) and [community.aws](https://github.com/ansible-collections/amazon.aws) collections MUST be installed in order for this collection to work.
 
+To run rulebooks, [ansible-rulebook](https://ansible.readthedocs.io/projects/rulebook/en/latest/) must be installed.
 
 ### Installation
 Clone the collection repository.
@@ -70,7 +76,7 @@ Once installed, you can reference the cloud.aws_ops collection content by its fu
 ### See Also
 
 * [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details.
-
+* [Ansible Rulebook documentation](https://ansible.readthedocs.io/projects/rulebook/en/stable/index.html) for information on using rulebooks.
 
 ## Contributing to this collection
 

changelogs/fragments/20230822-docs_and_bugfixes.yml

@@ -0,0 +1,17 @@
+---
+breaking_changes:
+  - cloud.aws_ops.migrate_webapp - replace variable name `do_not_delete_source` with `delete_source` to make intent clearer and fix reversed default value logic (https://github.com/redhat-cop/cloud.aws_ops/pull/86).
+
+bugfixes:
+  - cloud.aws_ops.aws_restore_cloudtrail - provide `key_prefix` default so it doesn't error if not present (https://github.com/redhat-cop/cloud.aws_ops/pull/86).
+  - cloud.aws_ops.aws_restore_kms_key - fix conditional value to properly retrieve KMS key ARN from ansible-rulebook event variable (https://github.com/redhat-cop/cloud.aws_ops/pull/86).
+  - cloud.aws_ops.webapp - update webapp create task to use provided variables instead of hard-coding values in some places (https://github.com/redhat-cop/cloud.aws_ops/pull/86).
+  - cloud.aws_ops.webapp - update RDS engine from deprecated version (https://github.com/redhat-cop/cloud.aws_ops/pull/86).
+  - cloud.aws_ops.enable_cloudtrail_encryption_with_kms - fix incorrect fact name for retrieved trail info and provide `s3_key_prefix` default so it doesn't error if not present (https://github.com/redhat-cop/cloud.aws_ops/pull/86).
+  - cloud.aws_ops.aws_manage_cloudtrail_encryption - fix condition logic to match expected Cloudtrail events and add extra_vars to pass rulebook variables to playbooks called in actions (https://github.com/redhat-cop/cloud.aws_ops/pull/86).
+
+trivial:
+  - Move EDA rulebook to recommended extensions/eda/rulebooks folder (https://github.com/redhat-cop/cloud.aws_ops/pull/86).
+  - Move EDA playbooks to top-level playbooks directory so they can be called from ansible-rulebook by FQCN (https://github.com/redhat-cop/cloud.aws_ops/pull/86).
+  - Add documentation for playbooks and rulebooks (https://github.com/redhat-cop/cloud.aws_ops/pull/86).
+  - Add AWS account permissions to enable_cloudtrail_encryption_with_kms role README (https://github.com/redhat-cop/cloud.aws_ops/pull/86).

extensions/eda/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md

@@ -0,0 +1,71 @@
+# cloud.aws_ops.aws_manage_cloudtrail_encryption
+
+A rulebook to ensure continuously running and encrypted Cloudtrail trails using Event Driven Ansible.
+
+This rulebook includes four rules:
+
+1. A rule that matches Cloudtrail events indicating the provided KMS key was deleted or disabled, and re-enables it.
+2. A rule that matches Cloudtrail events indicating the provided trail was deleted, and recreates it with encryption using the provided KMS key.
+3. A rule that matches Cloudtrail events indicating the provided trail encryption was disabled, and re-enables it with the provided KMS key.
+4. A rule that matches Cloudtrail events indicating the provided S3 bucket was deleted, and prints the full event data.
+
+## Requirements
+
+AWS User Account with the following permissions:
+
+* cloudtrail:CreateTrail
+* cloudtrail:DescribeTrails
+* cloudtrail:GetTrail
+* cloudtrail:GetTrailStatus
+* cloudtrail:ListTags
+* cloudtrail:StartLogging
+* cloudtrail:UpdateTrail
+* kms:CancelKeyDeletion
+* kms:DescribeKey
+* kms:EnableKey
+* kms:GetKeyPolicy
+* kms:GetKeyRotationStatus
+* kms:ListAliases
+* kms:ListGrants
+* kms:ListKeyPolicies
+* kms:ListResourceTags
+* s3:PutObject
+* s3:GetBucketAcl
+* s3:PutBucketLogging
+* s3:ListBucket
+
+## Rulebook Variables
+
+* **cloudtrail_name** (str): (Required) Name of the Cloudtrail trail to monitor.
+* **kms_key_alias** (str): (Required) Alias for the KMS key used to encrypt the trail.
+* **s3_bucket_name** (str): (Required) Name of the s3 bucket used to store trail logs.
+* **s3_key_prefix** (str): Optional s3 key prefix for trail logs.
+
+## Example Usage
+
+Create an `inventory.yaml` file with the following contents:
+
+```yaml
+---
+all:
+  hosts:
+    localhost:
+      ansible_connection: local
+```
+
+Create a `vars.yaml` file with the required variables:
+
+```yaml
+---
+cloudtrail_name: your-trail-name
+kms_key_alias: your-kms-key
+s3_bucket_name: your-s3-bucket
+```
+
+With AWS credentials set via ENV or AWS config, run:
+
+```bash
+ansible-rulebook -r cloud.aws_ops.aws_manage_cloudtrail_encryption -i inventory.yml -e vars.yml -vv
+```
+
+Perform one of the above monitored actions in the AWS console or via CLI or API (delete or disable the KMS key, delete the trail, disable trail encryption, or delete the S3 bucket) and observe the ansible-rulebook runner output to see that the corrective action is taken. Note: it can take some time, up to a few minutes, for the matching Cloudtrail event to be received and processed by the queue.

extensions/eda/rulebooks/aws_manage_cloudtrail_encryption.yml

@@ -0,0 +1,49 @@
+- name: Rules for cloud.aws_ops to ensure a CloudTrail trail remains active and encrypted
+  hosts: all
+
+  sources:
+    - ansible.eda.aws_cloudtrail:
+        connection:
+          region_name: vars.region_name
+        delay: 5
+  rules:
+    - name: Cancel deletion or disabling of the KMS key
+      condition: event.CloudTrailEvent.eventName=="ScheduleKeyDeletion" or event.CloudTrailEvent.eventName=="DisableKey"
+      action:
+        run_playbook:
+          name: cloud.aws_ops.aws_restore_kms_key
+          extra_vars:
+            kms_key_alias: "{{ kms_key_alias }}"
+
+    - name: Re-create the deleted trail
+      condition: >
+        event.CloudTrailEvent.eventName=="DeleteTrail"
+        and event.CloudTrailEvent.requestParameters.name is search(vars.cloudtrail_name)
+      action:
+        run_playbook:
+          name: cloud.aws_ops.aws_restore_cloudtrail
+          extra_vars:
+            cloudtrail_name: "{{ cloudtrail_name }}"
+            kms_key_alias: "{{ kms_key_alias }}"
+            s3_bucket_name: "{{ s3_bucket_name }}"
+            s3_key_prefix: "{{ s3_key_prefix | default('') }}"
+
+    - name: Re-enable trail encryption
+      condition: >
+        event.CloudTrailEvent.eventName == "UpdateTrail"
+        and event.CloudTrailEvent.responseElements.name == vars.cloudtrail_name
+        and event.CloudTrailEvent.requestParameters.kmsKeyId == ""
+      action:
+        run_playbook:
+          name: cloud.aws_ops.aws_restore_cloudtrail_encryption
+          extra_vars:
+            cloudtrail_name: "{{ cloudtrail_name }}"
+            kms_key_alias: "{{ kms_key_alias }}"
+
+    - name: Print when Cloudtrail log S3 bucket is deleted
+      condition: >
+        event.CloudTrailEvent.eventName == "DeleteBucket"
+        and event.CloudTrailEvent.bucketName == vars.s3_bucket_name
+      action:
+        print_event:
+          pretty: true

playbooks/README.md

@@ -0,0 +1,13 @@
+# cloud.aws_ops playbooks
+
+## EDA playbooks
+
+Playbooks to restore canceled or deleted cloudtrail resources, intended for use with the EDA [aws_manage_cloudtrail_encryption rulebook](https://github.com/ansible-collections/cloud.aws_ops/blob/main/extensions/eda/rulebooks/AWS_MANAGE_CLOUDTRAIL_ENCRYPTION.md)
+
+* **aws_restore_cloudtrail_encryption**: Playbook to restore encryption to an existing AWS Cloudtrail trail using the [enable_cloudtrail_encryption_with_kms role](https://github.com/ansible-collections/cloud.aws_ops/blob/main/roles/enable_cloudtrail_encryption_with_kms/README.md).
+* **aws_restore_cloudtrail**: Playbook to re-create and encrypt a deleted AWS Cloudtrail trail using the [awsconfig_multiregion_cloudtrail](https://github.com/ansible-collections/cloud.aws_ops/blob/main/roles/awsconfig_multiregion_cloudtrail/README.md) and [enable_cloudtrail_encryption_with_kms](https://github.com/ansible-collections/cloud.aws_ops/blob/main/roles/enable_cloudtrail_encryption_with_kms/README.md) roles.
+* **aws_restore_kms_key**: Playbook to cancel deletion of a KMS key and re-enable it.
+
+## Webapp playbooks
+
+Playbooks to create, delete, or migrate a webapp on AWS. See [webapp playbooks README](https://github.com/ansible-collections/cloud.aws_ops/blob/main/playbooks/webapp/README.md) for details and usage.

playbooks/eda/aws_restore_cloudtrail.yml → playbooks/aws_restore_cloudtrail.yml

@@ -9,7 +9,7 @@
       vars:
         operation: create
         bucket_name: "{{ s3_bucket_name }}"
-        key_prefix: "{{ s3_key_prefix }}"
+        key_prefix: "{{ s3_key_prefix | default(omit) }}"
         trail_name: "{{ cloudtrail_name }}"
 
     - name: Include 'cloud.aws_ops.enable_cloudtrail_encryption_with_kms' role

playbooks/eda/aws_restore_kms_key.yml → playbooks/aws_restore_kms_key.yml

@@ -13,7 +13,7 @@
         kms_key_arn: "{{ __kms_key_info.kms_keys.0.key_arn }}"
 
     - name: Cancel the deletion of the KMS key and re-enable the KMS key
-      when: event.CloudTrailEvent.requestParameters.keyId == kms_key_arn
+      when: ansible_eda.event.CloudTrailEvent.responseElements.keyId == kms_key_arn
       block:
         - name: Cancel the deletion of the KMS key and re-enable the KMS key
           amazon.aws.kms_key:
@@ -22,7 +22,7 @@
             enabled: true
           register: __kms_key_restore
 
-        - name: Assert that trail has been re-enabled
+        - name: Assert that key has been re-enabled
           ansible.builtin.assert:
             that:
               - __kms_key_restore is changed