Update documentation #3985
Update documentation #3985
Conversation
audgirka
force-pushed
the
fix/update_docs
branch
from
0c098d3 to
58d8e13
Compare
|
Can we drop the use of docker here and maybe just have the getting started run against localhost? This might necessitate the need for a follw on docs about "standing up infrastructure for a molecule scenario" guide but it might be easier to demonstate the capabilities of molecule agains localhost |
audgirka
force-pushed
the
fix/update_docs
branch
from
c69c9e7 to
d8d039c
Compare
audgirka
force-pushed
the
fix/update_docs
branch
from
d8d039c to
50548b3
Compare
audgirka
force-pushed
the
fix/update_docs
branch
from
50548b3 to
4d6ac19
Compare
| !!! note | ||
| Molecule aims to test your Ansible roles and playbooks in isolation | ||
| as it launches an environment to run your playbook and then performs tests over it. | ||
| You can then run your playbook over different instance types and versions to verify if it still runs. | ||
|
|
There was a problem hiding this comment.
Coming in late with a few general comments. A getting started guide should allow the reader to 'get something quick and easy done'. Most of these changes do adhere to that which is great! But it might be good in a future PR to add a sentence or two here. Something like :
"This Getting Started guide will walk you through creating a simple collection with a role and playbook, and then use Molecule to test that collection."
|
|
||
| ## The Scenario Layout | ||
|
|
||
| Within the `molecule/default` folder, we find a number of files and | ||
| Within the `molecule/default` folder, we find several files and |
There was a problem hiding this comment.
This particular part starts to talk about files that from the reader perspective, don't exist yet. So in the perfect world, these file descriptions for molecule/default and molecule.yml would move to a reference page and this Getting Started would just go right into creating the example collection etc.
| driver. | ||
| The following guide will step through an example of developing and | ||
| testing a new Ansible collection. After reading this guide, you should be | ||
| familiar with the basics of how to use Molecule and what it can offer. |
There was a problem hiding this comment.
This is the sentence that should near the top of the getting started. It tells the reader immediately what to expect from this guide.
| Now, we can tell Molecule to create an instance with: | ||
| To create a collection, use the `ansible-galaxy` tool. | ||
| `ansible-galaxy collection init <namespace>.<collection_name>` | ||
| Example: `ansible-galaxy collection init foo.bar` |
There was a problem hiding this comment.
Consider an alternate way to write these sections. Each of these are steps in this procedure of creating a new collection and testing it with molecule. So for this one, it could be written as:
- Create a collection.
`ansible-galaxy collection init foo.bar`
There was a problem hiding this comment.
Also notice -this Getting Started is focused on molecule, so we can skip some of the background details about ..well anything that isn't molecule :-) like the naming of collections in this instance.
| ``` | ||
| To initialize a role inside a collection we can again use `ansible-galaxy` tool under the `roles` directory. | ||
| `ansible-galaxy role init <namespace>.<collection_name>` | ||
| Example: `ansible-galaxy collection init my_role` | ||
|
|
There was a problem hiding this comment.
If we were to continue converting this into a series of steps in a procedure, this section would lose it title, and just become:
- cd to the
rolesdirectory in your new collection. - Initialize a new role for this collection.
`ansible-galaxy collection init my_role`
- Add a task under
my_role_tasks/main.yml.
(and then keep the task as you have it below)
| and initialize `molecule scenario` under this directory using | ||
| the command: `molecule init scenario <scenario_name>` | ||
| `scenario_name` is optional, if not provided, will create | ||
| a `default` scenario. |
There was a problem hiding this comment.
I'd keep this as a section like it is, but convert the steps here to.. steps. Something like:
- Create a new directory in your collection called
extensions. - Initialize a new default molecule scenario in this directory.
`molecule init scenario`
| $ molecule destroy | ||
| ``` | ||
| Also, create an ansible configuration `ansible.cfg` file under the `extensions` directory. | ||
| Add the `collections_path` to this configuration file. | ||
|
|
There was a problem hiding this comment.
- Create an ansible configuration...
- Add the
collections_path...
| ├── side_effect | ||
| ├── verify | ||
| ├── cleanup | ||
| └── destroy | ||
| ``` |
There was a problem hiding this comment.
I find it a bit confusing between this section (running all tests) and the section below (running just playbook tests). Consider if it's better to just run the playbook tests first and then show the command to run everything? I'm guessing the everything test wouldn't run in this example because we've only had the reader modify converge.yml?
| - name: Include a playbook from a collection | ||
| ansible.builtin.import_playbook: foo.bar.my_playbook | ||
|
|
||
| ``` |
There was a problem hiding this comment.
At this point we haven't edited the default converge.yml - is there a step missing or will this work with whatever was created by the init command?
| ``` | ||
|
|
||
| Similarly, if we want to test only the role instead of a playbook in `converge.yml` file: | ||
|
|
There was a problem hiding this comment.
is the following supposed to be in converge.yml or in tasks/main.yml in the role?
Update documentation for molecule.