The Asyncening

.github/workflows/build.yml

@@ -0,0 +1,79 @@
+---
+
+name: Test and release 'main'
+on:
+  push:
+    branches:
+      - main
+      - devel
+  pull_request:
+    branches:
+      - main
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 4
+      matrix:
+        python-version: ["3.12"]
+        molecule-scenario:
+          - default
+          - ec2_platform
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          pip install molecule ansible-lint requests boto3[crt]
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+
+      - name: Build and install collection
+        run: |
+          ansible-galaxy collection build --force
+          ansible-galaxy collection install --force syndr-molecule-*.tar.gz
+
+      - name: Log into AWS
+        if: ${{ matrix.molecule-scenario == 'ec2_platform' }}
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-2
+
+      - name: Test with molecule
+        env:
+          # Make molecule output colored content (easier to read via GH UI)
+          PY_COLORS: 1
+          ANSIBLE_FORCE_COLOR: 1
+        run: |
+          molecule test -s ${{ matrix.molecule-scenario }}
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create and Push Tag
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          TAG_NAME=${{ github.ref_name }}
+          echo "Creating tag $TAG_NAME"
+          # Configure Git user
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          # Create the tag
+          git tag "$TAG_NAME"
+          # Push the tag to the repository
+          git push origin "refs/tags/$TAG_NAME" --force
+

.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+---
+
+name: Deploy Collection
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: |
+      github.event.release.prerelase == false
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Tag latest release
+        uses: EndBug/latest-tag@latest
+        with:
+          ref: latest
+          description: This tag is automatically generated on new releases.
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and Deploy Collection
+        uses: artis3n/ansible_galaxy_collection@v2
+        with:
+          api_key: '${{ secrets.GALAXY_API_KEY }}'
+

.gitignore

@@ -1 +1 @@
-syndr-molecule-*.tar.gz
+*-molecule-*.tar.gz

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 syndr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -8,8 +8,55 @@ It provides tooling to create Molecule testing scenarios via the `init` role, an
 
 When utilizing an image with systemd support (systemd packages are installed, etc.), the `docker_platform` role supports the creation of Docker containers with a functional Systemd implementation, which can be used to test Ansible code that makes use of Systemd services or related functionality.
 
+# Table of Contents
+
+- [Ansible Collection - syndr.molecule](#ansible-collection---syndrmolecule)
+- [What is Molecule?](#what-is-molecule)
+- [Using this collection](#using-this-collection)
+  - [Host Requirements](#host-requirements)
+  - [Project requirements](#project-requirements)
+    - [Standalone roles](#standalone-roles)
+    - [Collections](#collections)
+    - [Monoliths](#monoliths)
+      - [Testing roles and playbooks within a monolithic project](#testing-roles-and-playbooks-within-a-monolithic-project)
+    - [Playbooks](#playbooks)
+- [Using Molecule](#using-molecule)
+  - [Ansible Tags](#ansible-tags)
+- [Contributing](#contributing)
+
+# What is Molecule?
+
+> Molecule project is designed to aid in the development and testing of Ansible roles.
+
+Molecule is a testing platform for your Ansible projects that enables testing of your code both during development and after release via CI infrastructure.
+
+Some resources on Molecule can be found here:
+* [Developing and Testing Ansible Roles with Molecule and Podman - Part 1](https://www.ansible.com/blog/developing-and-testing-ansible-roles-with-molecule-and-podman-part-1)
+* [Testing your Ansible roles with Molecule](https://www.jeffgeerling.com/blog/2018/testing-your-ansible-roles-molecule)
+* [Ansible Collections: Role Tests with Molecule](https://ericsysmin.com/2020/04/30/ansible-collections-role-tests-with-molecule/)
+* [Introducing Ansible Molecule with Ansible Automation Platform](https://developers.redhat.com/articles/2023/09/13/introducing-ansible-molecule-ansible-automation-platform#an_automation_testing_framework_built_for_the_enterprise)
+
+> [!WARNING]  
+> Some [fairly significant changes](https://ansible.readthedocs.io/projects/molecule/next/) have been made in Molecule v6. Most noticable among these are likely to be that `ansible` is now the only driver included by default (previously called `delegated`), and that the `molecule init` command now only supports creation of scenarios, not Ansible roles. 
+>
+> This [RedHat article](https://developers.redhat.com/articles/2023/09/13/introducing-ansible-molecule-ansible-automation-platform#) has some more information on this change.
+>
+> When reading the above referenced articles, keep in mind their publishing dates, and that there may have been breaking changes to Molecule's functionality since that time!
+
+More tips on using Molecule can be found [below](#using-molecule).
+
 # Using this collection
 
+The following roles are provided:
+
+* [init](roles/init) - Initialize the Molecule testing framework for a project
+* [platform](roles/platform) - Deploy a Molecule platform for testing
+* [docker_platform](roles/docker_platform) - Used by the `platform` role to create a Docker-based test platform
+* [ec2_platform](roles/ec2_platform) - Used by the `platform` role to create an EC2-based test platform
+* [prepare_controller](roles/prepare_controller) - Prepare a molecule controller to run local code tests
+
+The recommended way to use this collection is to provision Molecule scenarios using the [init role](roles/init). The `init` role provides template configurations that will work in various project types.
+
 ## Host Requirements
 
 The host from which this collection is run (workstation, CI instance, etc.) must meet the following requirements:
@@ -35,12 +82,13 @@ Docker CE can be installed by following the appropriate [installation instructio
 
 ## Project requirements
 
-Roles within this collection will attempt to discover what type of project they are being utilized in. This is enabled by setting the appropriate `project_type` configuration variable to `auto`. The project type can also be explicitly specified if this is desired.
+The `init` role from this collection will attempt to discover what type of project it is being utilized in. This is enabled by setting the `init_project_type` configuration variable to `auto`. The project type can also be explicitly specified if this is desired.
 
 Supported project types:  
-* `role`
 * `collection`
 * `monolith`
+* `playbook`
+* `role`
 
 When used with a role or collection, the Galaxy meta information for the role must be configured!
 
@@ -146,9 +194,11 @@ or if your `collections/requirements.yml` includes this collection:
 ansible-galaxy collection install -p ./collections -r ./collections/requirements.yml
 ```
 
-#### Testing roles within a monolithic project
+#### Testing roles and playbooks within a monolithic project
 
-When configuring molecule testing for individual roles within a monolithic project (creating a `roles/<role_name>/molecule` directory), take care _not_ to name the scenario "default", as there is already a "default" scenario for the monolithic project itself if you have created `molecule/default` as described above! Instead, name your role scenario with a unique name.
+When configuring molecule testing for individual roles or playbooks within a monolithic project (creating a `roles/<role_name>/molecule` or `playbooks/<playbook_name>/molecule` directory), take care _not_ to name the scenario "default", as there is already a "default" scenario for the monolithic project itself if you have created `molecule/default` as described above! Instead, name your role scenario with a unique name.
+
+For example (role):
 
 ```bash
 ROLE_NAME=your_role
@@ -157,6 +207,93 @@ wget -P molecule/role-$ROLE_NAME https://raw.githubusercontent.com/syndr/ansible
 ansible-playbook molecule/role-$ROLE_NAME/init.yml
 ```
 
+Note that in this circumstance, you will need to specify the scenario name in order to run molecule against it (as it is not named `default`).
+
+Running the `molecule list` command will provide you an overview of the available scenarios
+
+```bash
+❯ molecule list                     
+INFO     Running pb-example_playbook > list
+                     ╷             ╷                  ╷                     ╷         ╷            
+  Instance Name      │ Driver Name │ Provisioner Name │ Scenario Name       │ Created │ Converged  
+╶────────────────────┼─────────────┼──────────────────┼─────────────────────┼─────────┼───────────╴
+  docker-rockylinux9 │ default     │ ansible          │ pb-example_playbook │ false   │ false      
+                     ╵             ╵                  ╵                     ╵         ╵
+```
+
+
+And running the full test suite for this playbook would be done as:
+
+```bash
+molecule test -s pb-example_playbook
+```
+
+While running just the "converge" steps (IE: during development) would be:
+
+```bash
+molecule converge -s pb-example_playbook
+```
+
+> [!TIP]  
+> The `molecule list` command will show multiple scenarios when run in the root of a monolithic project that also has molecule configured on individual playbooks or roles contained within it. Note that you will, however, still need to be in the appropriate role or playbook directory in order to successfully run these!
+
+### Playbooks
+
+Playbook configurations are similar to the `monolith` project type noted above, and are typically contained within monolithic projects. A project directory is considered a playbook if it contains a `tasks/` folder, but no role `meta/main.yml` configuration, and no `playbooks/` subdirectory.
+
+A playbook project configuration may look like:
+
+```
+playbooks
+├── your_playbook
+│   ├── main.yml
+│   ├── README.md
+│   ├── tasks
+│   │   ├── asserts.yml
+│   │   ├── main.yml
+│   │   └── standard.yml
+│   └── vars
+└── [...]
+```
+
+Playbook configuration adds the following directories to the role path configuration (paths relative to the playbook `main.yml` or equivilant file):
+
+* `./roles`
+* `./../roles`
+* `./../../roles`
+
+It also adds the following directories to the collection path configuration (paths relative to the playbook `main.yml` or equivilant file):
+* `./collections`
+* `./../collections`
+* `./../../collections`
+
+# Using Molecule
+
+The most common Molecule commands that you will likely use are:
+
+```bash
+molecule create     # Create the test infrastructure, as defined in molecule.yml
+molecule converge   # Run the plays from converge.yml (launch your role/playbook)
+molecule verify     # Run the plays from verify.yml (test for desired state)
+molecule test       # Run the full test sequence
+```
+
+## Ansible Tags
+
+If [tags](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_tags.html) are used in your code to enable/disable certian functionality, they must be specified on the command line when running Molecule commands. To do so, use the `--` [command line option](https://ansible.readthedocs.io/projects/molecule/usage/#test-sequence-commands) to pass commands through to `ansible-playbook`.
+
+For example:
+
+```bash
+molecule test -- --tags the-cheese
+```
+
+Or running `converge` using a non-default scenario:
+
+```bash
+molecule converge -s pb-the_toaster -- --tags sourdough
+```
+
 # Contributing
 
 Pull requests are welcomed!

galaxy.yml

@@ -8,7 +8,7 @@ namespace: syndr
 name: molecule
 
 # The version of the collection. Must be compatible with semantic versioning
-version: 1.2.1
+version: 2.0.0
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md
@@ -56,7 +56,7 @@ repository: https://github.com/syndr/ansible-collection-molecule
 #homepage: http://example.com
 
 # The URL to the collection issue tracker
-issues: https://github.com/syndr/ansible-collection-molecule/issues
+#issues: https://github.com/syndr/ansible-collection-molecule/issues
 
 # A list of file glob-like patterns used to filter any files or directories that should not be included in the build
 # artifact. A pattern is matched from the relative path of the file or directory of the collection directory. This

molecule/default/collections.yml

@@ -0,0 +1 @@
+../resources/collections.yml