Prepare Release 2.1.0

CHANGELOG.rst

@@ -4,6 +4,26 @@ The cloud.terraform collection Release Notes
 
 .. contents:: Topics
 
+v2.1.0
+======
+
+Release Summary
+---------------
+
+The cloud.terraform 2.1.0 release includes a new module to ``plan_stash`` and a new inventory plugin ``terraform_state``.
+
+New Plugins
+-----------
+
+Inventory
+~~~~~~~~~
+
+- terraform_state - Builds an inventory from resources created by cloud providers.
+
+New Modules
+-----------
+
+- plan_stash - Handle the base64 encoding or decoding of a terraform plan file
 
 v2.0.0
 ======
@@ -13,33 +33,31 @@ Breaking Changes / Porting Guide
 
 - Remove support for ansible-core < 2.14 (https://github.com/ansible-collections/cloud.terraform/pull/102).
 
-
 Major Changes
 -------------
 
-- terraform_provider - Added ``search_child_modules`` option (https://github.com/ansible-collections/cloud.terraform/pull/55).
 - terraform_provider  - Allow ``project_path`` in terraform_provider inventory plugin to accept a list of paths (https://github.com/ansible-collections/cloud.terraform/pull/55).
+- terraform_provider - Added ``search_child_modules`` option (https://github.com/ansible-collections/cloud.terraform/pull/55).
 
 Minor Changes
 -------------
 
 - Removed integration tests workaround in terrform_provider. (https://github.com/ansible-collections/cloud.terraform/pull/84)
 - Set default of ``state_file`` in terraform_provider inventory plugin to a blank string (https://github.com/ansible-collections/cloud.terraform/pull/55).
-- terraform  - add support for ``workspace`` when running ``terraform output`` (https://github.com/ansible-collections/cloud.terraform/issues/85). 
+- terraform  - add support for ``workspace`` when running ``terraform output`` (https://github.com/ansible-collections/cloud.terraform/issues/85).
+- terraform - cleanup temporary file create during module execution. (https://github.com/ansible-collections/cloud.terraform/issues/2)
 - terraform_output -  add support for ``workspace`` when running ``terraform output`` (https://github.com/ansible-collections/cloud.terraform/issues/85).
 - tf_output - add support for ``workspace`` when running ``terraform output`` (https://github.com/ansible-collections/cloud.terraform/issues/85).
-- terraform - cleanup temporary file create during module execution. (https://github.com/ansible-collections/cloud.terraform/issues/2)
-
 
 Bugfixes
 --------
 
 - module_utils - Accept Terraform executables present on PATH passed in as ``binary_path`` without specifying their absolute path. (https://github.com/ansible-collections/cloud.terraform/issues/49)
 - module_utils - Allow ``nested_type`` attribute in terraform schema. (https://github.com/ansible-collections/cloud.terraform/issues/93)
 - module_utils - Fix AWS SQS queue creation. The ``values`` attribute in terraform output is optional. SQS is one of (rare) cases where ``values`` is absent. (https://github.com/ansible-collections/cloud.terraform/issues/86)
-- terraform - fix spaces between characters in command field in result (https://github.com/ansible-collections/cloud.terraform/pull/76).
 - move test requirements out of the requirements.txt file (https://github.com/ansible-collections/cloud.terraform/pull/67).
 - terraform - fix issue with ``plan_file`` option specified with ``check_mode=true`` and ``state`` set to one of ``present`` and ``absent``, the module is enable now to generate a Terraform file to the specified location (https://github.com/ansible-collections/cloud.terraform/issues/87).
+- terraform - fix spaces between characters in command field in result (https://github.com/ansible-collections/cloud.terraform/pull/76).
 
 v1.1.0
 ======

README.md

@@ -30,6 +30,7 @@ This collection requires Ansible Core 2.14 or later and thus Python 3.9 or later
 Name | Description
 --- | ---
 [cloud.terraform.terraform_provider](https://github.com/ansible-collections/cloud.terraform/blob/main/docs/cloud.terraform.terraform_provider_inventory.rst)|Builds an inventory from Terraform state file.
+[cloud.terraform.terraform_state](https://github.com/ansible-collections/cloud.terraform/blob/main/docs/cloud.terraform.terraform_state_inventory.rst)|Builds an inventory from resources created by cloud providers.
 
 ### Lookup plugins
 Name | Description
@@ -39,6 +40,7 @@ Name | Description
 ### Modules
 Name | Description
 --- | ---
+[cloud.terraform.plan_stash](https://github.com/ansible-collections/cloud.terraform/blob/main/docs/cloud.terraform.plan_stash_module.rst)|Handle the base64 encoding or decoding of a terraform plan file
 [cloud.terraform.terraform](https://github.com/ansible-collections/cloud.terraform/blob/main/docs/cloud.terraform.terraform_module.rst)|Manages a Terraform deployment (and plans)
 [cloud.terraform.terraform_output](https://github.com/ansible-collections/cloud.terraform/blob/main/docs/cloud.terraform.terraform_output_module.rst)|Returns Terraform module outputs.
 
@@ -132,3 +134,4 @@ ansible-doc --list | grep cloud.terraform | cut -d " " -f 1 | xargs -I {} antsib
 GNU General Public License v3.0 or later.
 
 See [LICENSE](https://github.com/ansible-collections/cloud.terraform/blob/main/LICENSE) to see the full text.
+

changelogs/changelog.yaml

@@ -75,22 +75,32 @@ releases:
       breaking_changes:
       - Remove support for ansible-core < 2.14 (https://github.com/ansible-collections/cloud.terraform/pull/102).
       bugfixes:
-      - module_utils - Accept Terraform executables present on PATH passed in as ``binary_path`` without specifying their absolute path. (https://github.com/ansible-collections/cloud.terraform/issues/49)
+      - module_utils - Accept Terraform executables present on PATH passed in as ``binary_path``
+        without specifying their absolute path. (https://github.com/ansible-collections/cloud.terraform/issues/49)
       - module_utils - Allow ``nested_type`` attribute in terraform schema. (https://github.com/ansible-collections/cloud.terraform/issues/93)
-      - module_utils - Fix AWS SQS queue creation. The ``values`` attribute in terraform output is optional. SQS is one of (rare) cases where ``values`` is absent. (https://github.com/ansible-collections/cloud.terraform/issues/86)
-      - terraform - fix spaces between characters in command field in result (https://github.com/ansible-collections/cloud.terraform/pull/76).
+      - module_utils - Fix AWS SQS queue creation. The ``values`` attribute in terraform
+        output is optional. SQS is one of (rare) cases where ``values`` is absent.
+        (https://github.com/ansible-collections/cloud.terraform/issues/86)
       - move test requirements out of the requirements.txt file (https://github.com/ansible-collections/cloud.terraform/pull/67).
-      - terraform - fix issue with ``plan_file`` option specified with ``check_mode=true`` and ``state`` set to one of ``present`` and ``absent``, the module is enable now to generate a Terraform file to the specified location (https://github.com/ansible-collections/cloud.terraform/issues/87).
+      - terraform - fix issue with ``plan_file`` option specified with ``check_mode=true``
+        and ``state`` set to one of ``present`` and ``absent``, the module is enable
+        now to generate a Terraform file to the specified location (https://github.com/ansible-collections/cloud.terraform/issues/87).
+      - terraform - fix spaces between characters in command field in result (https://github.com/ansible-collections/cloud.terraform/pull/76).
       major_changes:
+      - terraform_provider  - Allow ``project_path`` in terraform_provider inventory
+        plugin to accept a list of paths (https://github.com/ansible-collections/cloud.terraform/pull/55).
       - terraform_provider - Added ``search_child_modules`` option (https://github.com/ansible-collections/cloud.terraform/pull/55).
-      - terraform_provider  - Allow ``project_path`` in terraform_provider inventory plugin to accept a list of paths (https://github.com/ansible-collections/cloud.terraform/pull/55).
       minor_changes:
       - Removed integration tests workaround in terrform_provider. (https://github.com/ansible-collections/cloud.terraform/pull/84)
-      - Set default of ``state_file`` in terraform_provider inventory plugin to a blank string (https://github.com/ansible-collections/cloud.terraform/pull/55).
-      - terraform  - add support for ``workspace`` when running ``terraform output`` (https://github.com/ansible-collections/cloud.terraform/issues/85). 
-      - terraform_output -  add support for ``workspace`` when running ``terraform output`` (https://github.com/ansible-collections/cloud.terraform/issues/85).
-      - tf_output - add support for ``workspace`` when running ``terraform output`` (https://github.com/ansible-collections/cloud.terraform/issues/85).
+      - Set default of ``state_file`` in terraform_provider inventory plugin to a
+        blank string (https://github.com/ansible-collections/cloud.terraform/pull/55).
+      - terraform  - add support for ``workspace`` when running ``terraform output``
+        (https://github.com/ansible-collections/cloud.terraform/issues/85).
       - terraform - cleanup temporary file create during module execution. (https://github.com/ansible-collections/cloud.terraform/issues/2)
+      - terraform_output -  add support for ``workspace`` when running ``terraform
+        output`` (https://github.com/ansible-collections/cloud.terraform/issues/85).
+      - tf_output - add support for ``workspace`` when running ``terraform output``
+        (https://github.com/ansible-collections/cloud.terraform/issues/85).
     fragments:
     - 20230524-aws_integration_tests.yml
     - 20230913-add-support-for-workspace-when-running-terraform_output.yml
@@ -107,3 +117,20 @@ releases:
     - terraform-cleanup-file.yml
     - terraform_provider_remove_workaround.yml
     release_date: '2023-11-17'
+  2.1.0:
+    changes:
+      release_summary: The cloud.terraform 2.1.0 release includes a new module to
+        plan_stash and a new inventory plugin terraform_state
+    fragments:
+    - 20240217-fix-awscc-integration-test.yaml
+    - release.yaml
+    modules:
+    - description: Handle the base64 encoding or decoding of a terraform plan file
+      name: plan_stash
+      namespace: ''
+    plugins:
+      inventory:
+      - description: Builds an inventory from resources created by cloud providers.
+        name: terraform_state
+        namespace: null
+    release_date: '2024-05-21'

docs/cloud.terraform.plan_stash_module.rst

@@ -0,0 +1,186 @@
+.. _cloud.terraform.plan_stash_module:
+
+
+**************************
+cloud.terraform.plan_stash
+**************************
+
+**Handle the base64 encoding or decoding of a terraform plan file**
+
+
+Version added: 2.1.0
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+- This module performs base64-encoding of a terraform plan file and saves it into playbook execution stats similar to :ref:`ansible.builtin.set_stats <ansible.builtin.set_stats_module>` module.
+- The module also performs base64-decoding of a terraform plan file from a variable defined into ansible facts and writes them into a file specified by the user.
+
+
+
+
+Parameters
+----------
+
+.. raw:: html
+
+    <table  border=0 cellpadding=0 class="documentation-table">
+        <tr>
+            <th colspan="1">Parameter</th>
+            <th>Choices/<font color="blue">Defaults</font></th>
+            <th width="100%">Comments</th>
+        </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>binary_data</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">raw</span>
+                    </div>
+                </td>
+                <td>
+                </td>
+                <td>
+                        <div>When O(state=load), this parameter defines the base64-encoded data of the terraform plan file.</div>
+                        <div>Mutually exclusive with V(var_name).</div>
+                        <div>Ignored when O(state=stash).</div>
+                </td>
+            </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>path</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">path</span>
+                         / <span style="color: red">required</span>
+                    </div>
+                </td>
+                <td>
+                </td>
+                <td>
+                        <div>The path to the terraform plan file.</div>
+                </td>
+            </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>per_host</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">boolean</span>
+                    </div>
+                </td>
+                <td>
+                        <ul style="margin: 0; padding: 0"><b>Choices:</b>
+                                    <li><div style="color: blue"><b>no</b>&nbsp;&larr;</div></li>
+                                    <li>yes</li>
+                        </ul>
+                </td>
+                <td>
+                        <div>Whether the stats are per host or for all hosts in the run.</div>
+                        <div>Ignored when O(state=load).</div>
+                </td>
+            </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>state</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">string</span>
+                    </div>
+                </td>
+                <td>
+                        <ul style="margin: 0; padding: 0"><b>Choices:</b>
+                                    <li><div style="color: blue"><b>stash</b>&nbsp;&larr;</div></li>
+                                    <li>load</li>
+                        </ul>
+                </td>
+                <td>
+                        <div>O(state=stash): base64-encodes the terraform plan file and saves it into ansible stats like using the <span class='module'>ansible.builtin.set_stats</span> module.</div>
+                        <div>O(state=load): base64-decodes data from variable specified in O(var_name) and writes them into terraform plan file.</div>
+                </td>
+            </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>var_name</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">string</span>
+                    </div>
+                </td>
+                <td>
+                </td>
+                <td>
+                        <div>When O(state=stash), this parameter defines the variable name to be set into stats.</div>
+                        <div>When O(state=load), this parameter defines the variable from ansible facts containing the base64-encoded data of the terraform plan file.</div>
+                        <div>Variables must start with a letter or underscore character, and contain only letters, numbers and underscores.</div>
+                        <div>The module will use V(terraform_plan) as default variable name if not specified.</div>
+                </td>
+            </tr>
+    </table>
+    <br/>
+
+
+Notes
+-----
+
+.. note::
+   - For security reasons, this module should be used with *no_log=true* and *register* functionalities as the plan file can contain unencrypted secrets.
+
+
+
+Examples
+--------
+
+.. code-block:: yaml
+
+    # Encode terraform plan file into default variable 'terraform_plan'
+    - name: Encode a terraform plan file into terraform_plan variable
+      cloud.terraform.plan_stash:
+        path: /path/to/terraform_plan_file
+        state: stash
+      no_log: true
+
+    # Encode terraform plan file into variable 'stashed_plan'
+    - name: Encode a terraform plan file into terraform_plan variable
+      cloud.terraform.plan_stash:
+        path: /path/to/terraform_plan_file
+        var_name: stashed_plan
+        state: stash
+      no_log: true
+
+    # Load terraform plan file from variable 'stashed_plan'
+    - name: Load a terraform plan file data from variable 'stashed_plan' into file 'tfplan'
+      cloud.terraform.plan_stash:
+        path: tfplan
+        var_name: stashed_plan
+        state: load
+      no_log: true
+
+    # Load terraform plan file from binary data
+    - name: Load a terraform plan file data from binary data
+      cloud.terraform.plan_stash:
+        path: tfplan
+        binary_data: "{{ terraform_binary_data }}"
+        state: load
+      no_log: true
+
+
+
+
+Status
+------
+
+
+Authors
+~~~~~~~
+
+- Aubin Bikouo (@abikouo)