Added docs for terraform credential/inventory source (#15004)

* Added docs for terraform credential/inventory source

* Updated screen captures for inventories and source to match wfjt example

* Added docs for terraform credential/inventory source

* Updated screen captures for inventories and source to match wfjt example

* Update docs/docsite/rst/userguide/inventories.rst

Co-authored-by: Aoki <lucasaoki@users.noreply.github.com>

* Revised per review feedback.

* Update docs/docsite/rst/userguide/inventories.rst

Co-authored-by: Helen Bailey <hakbailey@gmail.com>

---------

Co-authored-by: Aoki <lucasaoki@users.noreply.github.com>
Co-authored-by: Helen Bailey <hakbailey@gmail.com>

4 files changed, 69 insertions, 0 deletions

diff --git a/docs/docsite/rst/common/images/credentials-create-terraform-credential.png b/docs/docsite/rst/common/images/credentials-create-terraform-credential.png
new file mode 100644
index 0000000000..ddd9547d60
--- /dev/null
+++ b/docs/docsite/rst/common/images/credentials-create-terraform-credential.png
diff --git a/docs/docsite/rst/common/images/inventories-create-source-terraform-example.png b/docs/docsite/rst/common/images/inventories-create-source-terraform-example.png
new file mode 100644
index 0000000000..0ade0c3fa5
--- /dev/null
+++ b/docs/docsite/rst/common/images/inventories-create-source-terraform-example.png
diff --git a/docs/docsite/rst/userguide/credentials.rst b/docs/docsite/rst/userguide/credentials.rst
index b5b9112d69..1b2cfbe81b 100644
--- a/docs/docsite/rst/userguide/credentials.rst
+++ b/docs/docsite/rst/userguide/credentials.rst
@@ -646,6 +646,39 @@ Source Control credentials have several attributes that may be configured:
     If you are using a GitHub account for a Source Control credential and you have 2FA (Two Factor Authentication) enabled on your account, you will need to use your Personal Access Token in the password field rather than your account password. 
 
 
+.. _ug_credentials_terraform:
+
+Terraform backend configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. index::
+   pair: credential types; Terraform
+   pair: backend configuration; Terraform
+
+
+Terraform is a HashiCorp tool used to automate various infrastructure tasks. Select this credential type to enable synchronization with the Terraform inventory source.
+
+The Terraform credential requires the **Backend configuration** attribute which should contain the data from a `Terraform backend block <https://developer.hashicorp.com/terraform/language/settings/backends/configuration>`_. You can paste, drag a file, browse to upload a file, or click the (|key icon|) button to populate the field from an external :ref:`ug_credential_plugins`. An example configuration for an S3 backend:
+
+.. |key icon| image:: ../common/images/key-mgmt-button.png
+    :alt: Credentials - create Terraform backend configuration credential form
+
+::
+
+    bucket = "my-terraform-state-bucket"
+    key = "path/to/terraform-state-file"
+    region = "us-east-1"
+    access_key = "my-aws-access-key"
+    secret_key = "my-aws-secret-access-key"
+
+|Credentials - create terraform credential|
+
+.. |Credentials - create terraform credential| image:: ../common/images/credentials-create-terraform-credential.png
+    :alt: Credentials - create Terraform backend configuration credential form
+
+Saving it stores the file path to the backend configuration in an environment variable ``TF_BACKEND_CONFIG_FILE`` that is made available to any job with the credential attached.
+
+
 Thycotic DevOps Secrets Vault
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This is considered part of the secret management capability. See :ref:`ug_credentials_thycoticvault` for more detail.
diff --git a/docs/docsite/rst/userguide/inventories.rst b/docs/docsite/rst/userguide/inventories.rst
index a5a9e5df56..2807177d3f 100644
--- a/docs/docsite/rst/userguide/inventories.rst
+++ b/docs/docsite/rst/userguide/inventories.rst
@@ -481,6 +481,7 @@ Inventory updates use dynamically-generated YAML files which are parsed by their
 - :ref:`ug_source_openstack`
 - :ref:`ug_source_rhv`
 - :ref:`ug_source_rhaap`
+- :ref:`ug_source_terraform`
 
 
 Newly created configurations for inventory sources will contain the default plugin configuration values. If you want your newly created inventory sources to match the output of legacy sources, you must apply a specific set of configuration values for that source. To ensure backward compatibility, AWX uses "templates" for each of these sources to force the output of inventory plugins into the legacy format. Refer to :ref:`ir_inv_plugin_templates_reference` section of this guide for each source and their respective templates to help you migrate to the new style inventory plugin output.
@@ -1084,6 +1085,41 @@ Red Hat Ansible Automation Platform
 
 4. Use the **Source Variables** field to override variables used by the ``controller`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. 
 
+
+.. _ug_source_terraform:
+
+Terraform State
+~~~~~~~~~~~~~~~~
+
+.. index::
+   pair: inventories; Terraform
+   pair: inventory source; Terraform state
+
+
+This inventory source uses the `terraform_state <https://github.com/ansible-collections/cloud.terraform/blob/main/plugins/inventory/terraform_state.py>`_ inventory plugin from the `cloud.terraform <https://github.com/ansible-collections/cloud.terraform>`_ collection. The plugin will parse a terraform state file and add hosts for AWS EC2, GCE, and Azure instances.
+
+1. To configure this type of sourced inventory, select **Terraform State** from the Source field.
+
+2. The Create new source window expands with the required **Credential** field. Choose from an existing Terraform backend Credential. For more information, refer to :ref:`ug_credentials`.
+
+3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. For Terraform, enable **Overwrite** and **Update on launch** options.  
+
+4. Use the **Source Variables** field to override variables used by the ``controller`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For more information on these variables, see the `terraform_state <https://github.com/ansible-collections/cloud.terraform/blob/main/plugins/inventory/terraform_state.py>`_ file for detail.
+
+  The ``backend_type`` variable is required by the Terraform state inventory plugin. This should match the remote backend configured in the Terraform backend credential, here is an example for an Amazon S3 backend:
+
+  ::
+
+    ---
+    backend_type: s3
+
+5. Enter an |ee| in the **Execution Environment** field that contains a Terraform binary. This is required for the inventory plugin to run the Terraform commands that read inventory data from the Terraform state file. Refer to the `Terraform EE readme <https://github.com/ansible-cloud/terraform_ee>`_ that contains an example |ee| configuration with a Terraform binary.
+
+  .. image:: ../common/images/inventories-create-source-terraform-example.png
+
+6. To add hosts for AWS EC2, GCE, and Azure instances, the Terraform state file in the backend must contain state for resources already deployed to EC2, GCE, or Azure. Refer to each of the Terraform providers' respective documentation to provision instances.
+
+
 .. _ug_customscripts:
 
 Export old inventory scripts