Update return block of Backup modules (#2106)

Update return block of Backup modules SUMMARY Updated return block of following modules, tried to ensure consistency across their return blocks 1. backup_plan 2. backup_plan_info 3. backup_vault 4. backup_selection ISSUE TYPE Docs Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Alina Buzachis Reviewed-by: Mandar Kulkarni <[email protected]> Reviewed-by: Bikouo Aubin Reviewed-by: Mike Graves <[email protected]>
ansible-collections · Jun 7, 2024 · 7c888ce · 7c888ce
1 parent 7c1d8aa
commit 7c888ce
Show file tree

Hide file tree

Showing 5 changed files with 250 additions and 37 deletions.
diff --git a/changelogs/fragments/update_return_block_backup_modules.yml b/changelogs/fragments/update_return_block_backup_modules.yml
@@ -0,0 +1,3 @@
+---
+trivial:
+  - Update return block in the module documentation for backup_plan, backup_plan_info, backup_vault, backup_selection (https://github.com/ansible-collections/amazon.aws/pull/2106).
diff --git a/plugins/modules/backup_plan.py b/plugins/modules/backup_plan.py
@@ -213,7 +213,7 @@
   description: ID of the backup plan.
   returned: always
   type: str
-  sample: 1111f877-1ecf-4d79-9718-a861cd09df3b
+  sample: "1111f877-1ecf-4d79-9718-a861cd09df3b"
 backup_plan_name:
   description: Name of the backup plan.
   returned: always
@@ -240,7 +240,7 @@
   type: dict
   contains:
     backup_plan_name:
-      description: Name of the backup plan.
+      description: The display name of a backup plan.
       returned: always
       type: str
       sample: elastic
@@ -260,7 +260,7 @@
           description: The name of a logical container where backups are stored.
           returned: always
           type: str
-          sample: 09da67966fd5-backup-vault"
+          sample: "09da67966fd5-backup-vault"
         schedule_expression:
           description: A cron expression in UTC specifying when Backup initiates a backup job.
           returned: always
@@ -271,25 +271,34 @@
             - A value in minutes after a backup is scheduled before a job will be canceled if it
               doesn't start successfully.
           type: int
+          returned: always
           sample: 480
         completion_window_minutes:
           description:
             - A value in minutes after a backup job is successfully started before it must be
               completed or it will be canceled by Backup.
           type: int
+          returned: always
           sample: 10080
         lifecycle:
           description:
-            - The lifecycle defines when a protected resource is transitioned to cold storage and when
-              it expires.
+            - Defines when a protected resource is transitioned to cold storage and when it expires.
           type: dict
-          sample: {}
+          returned: when configured.
+          sample: {
+                    "delete_after_days": 100,
+                    "move_to_cold_storage_after_days": 10
+                  }
         recovery_point_tags:
           description:
             - An array of key-value pair strings that are assigned to resources that are associated with
               this rule when restored from backup.
           type: dict
-          sample: {}
+          returned: when configured.
+          sample: {
+                    "Tagkey1": "TagValue1",
+                    "Tagkey2": "TagValue2"
+                  }
         rule_id:
           description:
             - Uniquely identifies a rule that is used to schedule the backup of a selection of resources.
@@ -298,9 +307,18 @@
           sample: "973621ef-d863-41ef-b5c3-9e943a64ad0c"
         copy_actions:
           description: An array of CopyAction objects, which contains the details of the copy operation.
+          returned: when configured.
           type: list
-          returned: always
-          sample: []
+          elements: dict
+          sample: [
+                    {
+                      "destination_backup_vault_arn": "arn:aws:backup:us-west-2:123456789012:backup-vault:my-test-vault",
+                      "lifecycle": {
+                          "delete_after_days": 100,
+                          "move_to_cold_storage_after_days": 10
+                      }
+                    }
+                  ]
         enable_continous_backup:
           description: Specifies whether Backup creates continuous backups.
           type: bool
@@ -316,20 +334,36 @@
           version_added: 7.3.0
     advanced_backup_settings:
       description: Advanced backup settings of the backup plan.
-      returned: when configured
+      returned: when configured.
       type: list
       elements: dict
+      sample: [
+                {
+                  "backup_options": {
+                      "windows_vss": "enabled"
+                  },
+                  "resource_type": "EC2"
+                }
+              ]
       contains:
         resource_type:
           description: Resource type of the advanced settings.
           type: str
+          sample: "EC2"
         backup_options:
           description: Backup options of the advanced settings.
           type: dict
+          sample: {
+                    "windows_vss": "enabled"
+                  }
     tags:
       description: Tags of the backup plan.
       returned: on create/update
       type: str
+      sample: {
+                "TagKey1": "TagValue1",
+                "TagKey2": "TagValue2"
+              }
 """
 
 import json

diff --git a/plugins/modules/backup_plan_info.py b/plugins/modules/backup_plan_info.py
@@ -41,37 +41,49 @@
 
 RETURN = r"""
 backup_plans:
-    description: List of backup plan objects. Each element consists of a dict with all the information related to that backup plan.
+    description: List of backup plan objects. List elements are dict with the information about backup plan.
     type: list
     elements: dict
     returned: always
     contains:
         backup_plan_arn:
-            description: ARN of the backup plan.
+            description: An Amazon Resource Name (ARN) that uniquely identifies a backup plan.
+            returned: always
             type: str
             sample: arn:aws:backup:eu-central-1:111122223333:backup-plan:1111f877-1ecf-4d79-9718-a861cd09df3b
         backup_plan_id:
             description: Id of the backup plan.
+            returned: always
             type: str
-            sample: 1111f877-1ecf-4d79-9718-a861cd09df3b
+            sample: "1111f877-1ecf-4d79-9718-a861cd09df3b"
         backup_plan_name:
-            description: Name of the backup plan.
+            description: The display name of a backup plan.
+            returned: always
             type: str
             sample: elastic
         creation_date:
             description: Creation date of the backup plan.
+            returned: always
             type: str
             sample: '2023-01-24T10:08:03.193000+01:00'
         last_execution_date:
             description: Last execution date of the backup plan.
+            returned: always
             type: str
             sample: '2023-03-24T06:30:08.250000+01:00'
         tags:
             description: Tags of the backup plan
+            returned: always
             type: str
+            sample: {
+                      "TagKey1": "TagValue1",
+                      "TagKey2": "TagValue2"
+                    }
         version_id:
-            description: Version id of the backup plan.
+            description: Version id of the backup plan
+            returned: always
             type: str
+            sample: 'A2AiAAAmAAAtAxAxAA00AAa0AAAxAxAtA0AmAAA4NDY1ZTZl'
         backup_plan:
             returned: always
             description: Detailed information about the backup plan.
@@ -80,12 +92,22 @@
             contains:
                 backup_plan_name:
                     description: Name of the backup plan.
+                    returned: always
                     type: str
                     sample: elastic
                 advanced_backup_settings:
                     description: Advanced backup settings of the backup plan.
+                    returned: when configured
                     type: list
                     elements: dict
+                    sample: [
+                              {
+                                "backup_options": {
+                                    "windows_vss": "enabled"
+                                },
+                                "resource_type": "EC2"
+                              }
+                            ]
                     contains:
                         resource_type:
                             description: Resource type of the advanced setting.
@@ -95,8 +117,84 @@
                             type: dict
                 rules:
                     description:
-                    - An array of BackupRule objects, each of which specifies a scheduled task that is used to back up a selection of resources.
+                      - An array of BackupRule objects, each of which specifies a scheduled task that is used to back up a selection of resources.
+                    returned: always
                     type: list
+                    elements: dict
+                    contains:
+                      rule_name:
+                          description: A display name for a backup rule.
+                          returned: always
+                          type: str
+                          sample: "daily"
+                      target_backup_vault_name:
+                          description: The name of a logical container where backups are stored.
+                          returned: always
+                          type: str
+                          sample: "09da67966fd5-backup-vault"
+                      schedule_expression:
+                          description: A cron expression in UTC specifying when Backup initiates a backup job.
+                          returned: always
+                          type: str
+                          sample: "cron(0 5 ? * * *)"
+                      start_window_minutes:
+                          description:
+                            - A value in minutes after a backup is scheduled before a job will be canceled if it
+                              doesn't start successfully.
+                          type: int
+                          returned: always
+                          sample: 480
+                      completion_window_minutes:
+                          description:
+                            - A value in minutes after a backup job is successfully started before it must be
+                              completed or it will be canceled by Backup.
+                          type: int
+                          returned: always
+                          sample: 10080
+                      lifecycle:
+                          description:
+                            - Defines when a protected resource is transitioned to cold storage and when it expires.
+                          type: dict
+                          returned: when configured.
+                          sample: {
+                                    "delete_after_days": 100,
+                                    "move_to_cold_storage_after_days": 10
+                                  }
+                      recovery_point_tags:
+                          description:
+                            - An array of key-value pair strings that are assigned to resources that are associated with
+                              this rule when restored from backup.
+                          type: dict
+                          returned: when configured.
+                          sample: {
+                                    "Tagkey1": "TagValue1",
+                                    "Tagkey2": "TagValue2"
+                                  }
+                      rule_id:
+                          description:
+                            - Uniquely identifies a rule that is used to schedule the backup of a selection of resources.
+                          type: str
+                          returned: always
+                          sample: "973621ef-d863-41ef-b5c3-9e943a64ad0c"
+                      copy_actions:
+                          description: An array of CopyAction objects, which contains the details of the copy operation.
+                          returned: when configured.
+                          type: list
+                          elements: dict
+                          sample: [
+                                    {
+                                      "destination_backup_vault_arn": "arn:aws:backup:us-west-2:123456789012:backup-vault:my-test-vault",
+                                      "lifecycle": {
+                                          "delete_after_days": 100,
+                                          "move_to_cold_storage_after_days": 10
+                                      }
+                                    }
+                                  ]
+                      enable_continous_backup:
+                          description: Specifies whether Backup creates continuous backups.
+                          type: bool
+                          returned: always
+                          sample: false
 """
 
 try: