Add docs guide to collection usage in AAP

[hakbailey]

SUMMARY

This adds a scenario guide to the docs for using this collection in AAP. Highlights include creating an execution environment that can run Terraform, remote state, and handling credentials.

ISSUE TYPE

• Docs Pull Request

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 79.55%. Comparing base (8c52bf2) to head (5404fe2). Report is 12 commits behind head on main.

:exclamation: Current head 5404fe2 differs from pull request most recent head 518b0a9. Consider uploading reports for the commit 518b0a9 to get more accurate results

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #122 +/- ## ========================================== + Coverage 73.00% 79.55% +6.55% ========================================== Files 16 23 +7 Lines 1015 1438 +423 Branches 182 253 +71 ========================================== + Hits 741 1144 +403 - Misses 243 252 +9 - Partials 31 42 +11 ``` | [Flag](https://app.codecov.io/gh/ansible-collections/cloud.terraform/pull/122/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=ansible-collections) | Coverage Δ | | |---|---|---| | [sanity](https://app.codecov.io/gh/ansible-collections/cloud.terraform/pull/122/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=ansible-collections) | `?` | | | [units](https://app.codecov.io/gh/ansible-collections/cloud.terraform/pull/122/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=ansible-collections) | `79.55% <ø> (+6.94%)` | :arrow_up: | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=ansible-collections#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[softwarefactory-project-zuul[bot]]

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/da8f2fd45032487d951fbdf002008b8c

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 5m 20s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 31s

[GomathiselviS]

Great job on making it clear and detailed. For some reason, the yaml code blocks appear underlined.

[hakbailey]

Great job on making it clear and detailed. For some reason, the yaml code blocks appear underlined.

I think that's just Github's preview rendering. When building the docs it looks as expected in the HTML files.

[softwarefactory-project-zuul[bot]]

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/5cb09412c4be4ab7a78ee9c615e606be

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 5m 09s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 46s

[softwarefactory-project-zuul[bot]]

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/30b2e8e37d9746d88b1fe945a8a2942a

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 14s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 21s

[softwarefactory-project-zuul[bot]]

Build succeeded (gate pipeline). https://ansible.softwarefactory-project.io/zuul/buildset/f7eed2b7745b42c88a10ae2123c3ba5f

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 47s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 39s

[patchback[bot]]

Backport to stable-2: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-2/05781aae1e5899659da4093c63e289c17252b9d5/pr-122

Backported as https://github.com/ansible-collections/cloud.terraform/pull/129

🤖 @patchback I'm built with octomachinery and my source is open — https://github.com/sanitizers/patchback-github-app.

[patchback[bot]]

Backport to stable-2: 💔 cherry-picking failed — could not push

❌ Current GitHub App installation does not grant sufficient privileges for pushing to https://github.com/ansible-collections/cloud.terraform.git. Lacking Contents: write or Workflows: write permissions are known to cause this.

the underlying command output was:

$ git --git-dir /tmp/ansible-collections--cloud.terraform---stable-2---p8kk7udq---PR-122.git/.git --work-tree /tmp/ansible-collections--cloud.terraform---stable-2---p8kk7udq---PR-122.git -c user.email=45432694+patchback[bot]@users.noreply.github.com -c user.name=patchback[bot] -c diff.algorithm=histogram push --force-with-lease origin HEAD

[RETURN CODE]: 1

[OUTPUT]:

[STDERR]:

Backporting merged PR #122 into main

1. Ensure you have a local repo clone of your fork. Unless you cloned it from the upstream, this would be your origin remote.
2. Make sure you have an upstream repo added as a remote too. In these instructions you'll refer to it by the name upstream. If you don't have it, here's how you can add it:

   $ git remote add upstream https://github.com/ansible-collections/cloud.terraform.git

3. Ensure you have the latest copy of upstream and prepare a branch that will hold the backported code:

   $ git fetch upstream
   $ git checkout -b patchback/backports/stable-2/05781aae1e5899659da4093c63e289c17252b9d5/pr-122 upstream/stable-2

4. Now, cherry-pick PR #122 contents into that branch:

   $ git cherry-pick -x 05781aae1e5899659da4093c63e289c17252b9d5

   If it'll yell at you with something like fatal: Commit 05781aae1e5899659da4093c63e289c17252b9d5 is a merge but no -m option was given., add -m 1 as follows instead:

   $ git cherry-pick -m1 -x 05781aae1e5899659da4093c63e289c17252b9d5

5. At this point, you'll probably encounter some merge conflicts. You must resolve them in to preserve the patch from PR #122 as close to the original as possible.
6. Push this branch to your fork on GitHub:

   $ git push origin patchback/backports/stable-2/05781aae1e5899659da4093c63e289c17252b9d5/pr-122

7. Create a PR, ensure that the CI is green. If it's not — update it so that the tests and any other checks pass. This is it! Now relax and wait for the maintainers to process your pull request when they have some cycles to do reviews. Don't worry — they'll tell you if any improvements are necessary when the time comes!

🤖 @patchback I'm built with octomachinery and my source is open — https://github.com/sanitizers/patchback-github-app.