From 0e7cf0cb637a42d0feb9afcd417848aaad588425 Mon Sep 17 00:00:00 2001 From: Ajinkya Udgirkar Date: Tue, 25 Jul 2023 20:25:14 +0530 Subject: [PATCH] Update documentation (#3975) --- docs/configuration.md | 22 +++++++++++----------- docs/faq.md | 8 +++----- docs/next.md | 15 +++++++++------ 3 files changed, 23 insertions(+), 22 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 6ab64abaa..91cd5e473 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,18 +4,18 @@ ## Prerun -In order to help Ansible find used modules and roles, molecule will +To help Ansible find used modules and roles, molecule will perform a prerun set of actions. These involve installing dependencies -from `requirements.yml` specified at project level, install a standalone +from `requirements.yml` specified at the project level, installing a standalone role or a collection. The destination is `project_dir/.cache` and the code itself was reused from ansible-lint, which has to do the same actions. (Note: ansible-lint is not included with molecule.) This assures that when you include a role inside molecule playbooks, -Ansible will be able to find that role, and that the include is exactly +Ansible will be able to find that role and that the include is exactly the same as the one you are expecting to use in production. -If for some reason the prerun action does not suits your needs, you can +If for some reason the prerun action does not suit your needs, you can still disable it by adding `prerun: false` inside the configuration file. @@ -28,7 +28,7 @@ your project, in order to avoid adding it to each scenario. By default, `Molecule` will check whether the role name follows the name standard. If not, it will raise an error. -If computed fully qualified role name does not follow current galaxy +If the computed fully qualified role name does not follow current galaxy requirements, you can ignore it by adding `role_name_check:1` inside the configuration file. It is strongly recommended to follow the name standard of @@ -40,7 +40,7 @@ and ::: molecule.interpolation.Interpolator -There are following environment variables available in `molecule.yml`: +Following are the environment variables available in `molecule.yml`: MOLECULE_DEBUG @@ -57,7 +57,7 @@ MOLECULE_ENV_FILE MOLECULE_STATE_FILE -: Path to molecule state file, contains state of the instances +: The path to molecule state file contains the state of the instances (created, converged, etc.). Usually `~/.cache/molecule///state.yml` @@ -249,12 +249,12 @@ test_sequence: `provisioner.playbooks` section of molecule.yml. `side_effect` can have one or more arguments (separated by spaces) which is -a playbook (plabyooks) to execute. If the argument for `side_effect` is present, +a playbook (playbooks) to execute. If the argument for `side_effect` is present, it's executed instead. The path to the playbook is relative to the molecule.yml location. Normal side effect settings (from `provisioner.playbooks`) are ignored for action with argument. -`verify` without an argument is executing usual tests configured in the verifier section +`verify` without an argument is executing the usual tests configured in the verifier section of molecule.yml. If one or more arguments (separated by spaces) are present, each argument is treated @@ -263,9 +263,9 @@ The kind of verifier is set in the `verifier` section of molecule.yml and is app `verify` actions in the scenario. The path to tests is relative to the molecule.yml file location. The `additional_files_or_dirs` -setting for verifier is ignored if the `verify` action has an argument. +setting for the verifier is ignored if the `verify` action is provided with an argument. -Multiple `side_effect` and `verify` actions can be used to a create a combination +Multiple `side_effect` and `verify` actions can be used to create a combination of playbooks and tests, for example, for end-to-end playbook testing. Additional `converge` and `idempotence` actions can be used multiple times: diff --git a/docs/faq.md b/docs/faq.md index 69e881511..a4de683d8 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -84,12 +84,10 @@ Molecule will resolve the `INSTANCE_UUID` environment variable when creating and looking up the instance name. You can confirm all is in working order by running `molecule list`. -## Can I test Ansible Collections with Molecule? +## Where can I configure my `roles-path` and `collections-paths`? -This is not currently officially supported. Also, collections remain in -"tech preview" status. However, you can take a look at [this blog -post](https://www.jeffgeerling.com/blog/2019/how-add-integration-tests-ansible-collection-molecule) -outlining a workable DIY solution as a stop gap for now. +As of molecule v6, users are expected to make use of [`ansible.cfg`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html) file to +alter them when needed. ## Does Molecule support monorepos? diff --git a/docs/next.md b/docs/next.md index 8326e56ad..09ea39b17 100644 --- a/docs/next.md +++ b/docs/next.md @@ -7,18 +7,21 @@ reduce the amount of magic and just rely on ansible core features. # Implemented changes - `roles-path` and `collections-paths` are no longer configurable for - dependencies. Users are expected to make use of `ansible.cfg` file to + dependencies. Users are expected to make use of [`ansible.cfg`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html) file to alter them when needed. +- `molecule init` command is now only available to create a scenario + using `molecule init scenario`. + Users will no longer be able to create a role. + Instead, users can make use of [`ansible-galaxy`](https://docs.ansible.com/ansible/latest/galaxy/dev_guide.html#) to [create a role](https://docs.ansible.com/ansible/latest/galaxy/dev_guide.html#creating-roles-for-galaxy). + # Planned changes -- Removal of provisioning drivers support and documenting, with examples, how to easily migrate to a self-provisioning approach. -- Removal of testinfra verifier driver and documenting how to call testinfra from inside the converge playbook to keep using the tool. - Refactoring how dependencies are installed - Bringing ephemeral directory under scenario folder instead of the current inconvenient location under `~/.cache/molecule/...` -- Addition of a minimal `ansible.cfg` file under scenario folder that can - be used to tell ansible from where to load testing content. This is to replace +- Addition of a minimal `ansible.cfg` file under the scenario folder that can + be used to tell Ansible from where to load testing content. This is to replace current Molecule magic around roles, collections and library paths and - test inventory location. Once done you will be able to run molecule playbooks with ansible directly without + test inventory location. Once done you will be able to run molecule playbooks with Ansible directly without having to define these folders.