Molecule: Migrating to molecule v3 checklist

[ssbarnea]

How to migrate to molecule v3 (3.0a9 or newer)

Only delegated, docker and podman providers are ready, so if you use others, delay till they are updated or preferably give a hand with that.

• remove scenario.name from molecule.yaml, from now on, only folder name determines the scenario name
• remove lint: sections from molecule.yaml or replace them with newer syntax from documentation
• if you use testinfra, add it as a pip dependency, is no longer installed by default
• if you use linters, you need to add them as pip dependencies
• (optional) rename playbook.yml to converge.yml to avoid a deprecation message

Known regressions with v3

• TBH

When not to migrate to v3

If you use one of:

• non-core providers like Azure, EC2, DigitalOcean, GCE, HetznerCloud, Linode, LXD, OpenStack or Vagrant, you probably do want to delay migration until they are updated. Keep in mind that as well as molecule, they are fully community supported, so if nobody steps in to help, they will be affected by bit rot and become unusable.

• you are using goss verifier which was removed. It can still be re-implemented as a plugin, if anyone is willing to help.

[zeitounator]

@ssbarnea. Shouldn't playbook.yml be renamed to converge.yml? I guess it's a typo...

[ssbarnea]

@zeitounator Thanks, fixed. That is the proof that most people TLDR, really happy to get corrections.

[geerlingguy]

Can you add a little more detail to the lint: section? E.g. maybe a link to the relevant documentation page(s)?

[hswong3i]

@ssbarnea as per https://github.com/ansible-community/molecule-vagrant/issues/2, could I give a hand for molecule-vagrant?

[SirUli]

@ssbarnea The "lint" - example from the documentation with ansible-lint leads to errors, could you elaborate a little on this? Behaviour before was that if a role doesn't contain any playbook.yml then it at least verified the playbook.yml in the molecule directory of the scenario (at least that is my impression).

So configuration as this:

lint: |
    yamllint .
    ansible-lint
    flake8

ansible-lint now just shows the help since it doesn't get any parameters (this example is from a role that doesn't have a playbook.yml in the root directory). Before assuming anything: How is that planned to be? Thanks in advance!

[geerlingguy]

Heh, I just started seeing new failures today as Molecule 3.0 arrived and I install via pip install molecule:

ERROR: Failed to pre-validate.

{'lint': ['must be of string type']}

Luckily for this project I already had the updated molecule.yml ready to go, but it looks like I'll need to quickly get my other projects up to speed to prevent a CI-pocalypse! See fix: https://github.com/ansible-collections/kubernetes/pull/32/files

Note that a quick fix if you _don't_ want Molecule 3 yet (e.g. wait to migrate your tests to it), change your pip install to:

pip3 install molecule===2.22

[mrlesmithjr]

I too am getting hammered with issues from v3 today! As @geerlingguy mentioned, CI nightmare but all is good. Working through numerous projects as well.

[geerlingguy]

Here's the script I used to convert all my active geerlingguy.* roles: https://gist.github.com/geerlingguy/19aace82f94b2d07a0dfb23db7345a57 (just posting in case anyone else wants a quick example and has a bunch of roles to use—it is not a generic script in any way).

[zeitounator]

@SirUli I was able to "fix" ansible-lint error with the following

(Edit: this is only necessary if you use an outdated ansible-lint version. Running pip install --upgrade ansible-lint should wipe the error out)

lint: |
  yamllint .
  ansible-lint .
  flake8

Meanwhile, although this is correctly checking the role's files, it does not check the molecule's test playbooks. This can be mitigated with the following (taking into account you renamed playbook.yml to converge.yml)

lint: |
  yamllint .
  ansible-lint .
  ansible-lint ./molecule/*/converge.yml
  flake8

But I'm not really happy with hardcoding a path like that just for checking the test playbooks. I' like to get a return from de dev team (@ssbarnea or someone else ?). Did I miss something in the doc/PRs to make this more straightforward ?

[zeitounator]

@SirUli I had to do the above this morning because the machine I was on apparently had an old version of ansible-lint. The referenced lint string works like a charm if your previously pip install --upgrade ansible-lint. Meanwhile my remark concerning testing the molecule playbook themselves still stands.

[zeitounator]

if you use linters, you need to add them as pip dependencies

yamllint is still listed as a molecule dependency, therefore installed by default with molecule.

$ pip show molecule                                                                                                                                                                                                                    on fix/nexus3.21_molecule3.0| ✔ 
Name: molecule
Version: 3.0.1
Summary: Molecule aids in the development and testing of Ansible roles
Home-page: https://github.com/ansible-community/molecule
Author: Ansible by Red Hat
Author-email: [email protected]
License: MIT
Location: /usr/local/lib/python3.6/dist-packages
Requires: sh, tree-format, colorama, yamllint, pexpect, cookiecutter, click, paramiko, PyYAML, click-completion, ansible, python-gilt, six, tabulate, click-help-colors, Jinja2, pre-commit, pluggy, cerberus
Required-by: 

[hswong3i]

In case of Travis CI + Molecule + Vagrant + Libvirt + KVM + CentOS/openSUSE/Ubuntu setup, you may reference my initial changes for upgrade from 2.22.0 to 3.0.1:

• https://github.com/alvistack/ansible-role-virtualbox/commit/4e414fc2731b23c6008de1266f6fc16c10dd7c25
• https://travis-ci.org/alvistack/ansible-role-virtualbox/jobs/653456732

[karcaw]

I suggest you spell molecule properly in the tile of the issue?
mocule => molecule

[hswong3i]

@ssbarnea the new lint syntax SHOULD BE something like:

lint: |
  yamllint . && ansible-lint && flake8

But NOT:

lint: |
  yamllint .
  ansible-lint
  flake8

Else if yamllint or ansible-lint return error code BUT flake8 return successful, the overall lint validation will result as successful (because we just check the final return code).

[ssbarnea]

@hswong3i Not sure which shell are you using because set -e should be used anyway, so you would avoid the need to chain the commands, as it will fail at first.

I am glad to review a PR that adds set -e in the documentation example, to assure that it fails at first error. I prefer that approach to chaining as is easier to read, and maintain.

[juanje]

@ssbarnea I found the same issue here. I don't know if new behavior from ansible-lint, but you need to pass a playbook or path, otherwise it will fail.
As @SirUli mentioned before, it will show the help, but also it will exit with 1, which raise the error from the set -e:

$ molecule lint
--> Test matrix

└── default
    ├── dependency
    └── lint
[...]

Dependency completed successfully.
--> Scenario: 'default'
--> Action: 'lint'
--> Executing: set -e
yamllint .
ansible-lint
Usage: ansible-lint [options] playbook.yml [playbook2 ...]

Options:
  --version             show program's version number and exit
[...]
  -c C                  Specify configuration file to use.  Defaults to
                        ".ansible-lint"
ERROR: Lint failed: Command 'set -e
yamllint .
ansible-lint
' returned non-zero exit status 1.: Command 'set -e
yamllint .
ansible-lint
' returned non-zero exit status 1.

You can test it:

$ ansible-lint
Usage: ansible-lint [options] playbook.yml [playbook2 ...]

Options:
  --version             show program's version number and exit
[...]
  -c C                  Specify configuration file to use.  Defaults to
                        ".ansible-lint"
$ echo $?
1

I found that if you put a dot as the PATH (like in the yamllint) it works as expected. So, this instead of the current version at the templates and documentation:

lint: |
  set -e
  yamllint .
  ansible-lint .

I tested this on several roles with the following versions:

• molecule: 3.0.2
• ansible-lint: 4.1.0

[juanje]

Sorry, I didn't realize that there was a superior version with this change reverted.
I just update the package to the version 4.2.0 and worked just fine without the dot.
Sorry for the noise and thanks for your hard work.

[ssbarnea]

@juanje I added https://github.com/ansible-community/molecule/pull/2659 to address this.

[decentral1se]

molecule-hetznercloud plugin supports molecule 3.x now.

[malodie]

With the updated syntax, the docker container run in the documentation no longer works.
If this issue needs to be moved to the docker container itself, I can certainly comment there.

docker run --rm -it \ -v "$(pwd)":/tmp/$(basename "${PWD}"):ro \ -v /var/run/docker.sock:/var/run/docker.sock \ -w /tmp/$(basename "${PWD}") \ quay.io/ansible/molecule:latest \ molecule test ERROR: Failed to validate. {'lint': ['must be of dict type']}

https://molecule.readthedocs.io/en/latest/examples.html

I'm finding that no matter what I try, nothing works under the lint, since it isn't qualifying as the dict type.

The docker container also doesn't recognize 'ansible' as a verifier.

This is my molecule.yml file. Ignore the extra ` at the end, it wouldn't format as code:

```---
dependency:
name: galaxy
driver:
name: docker
platforms:

• name: genericansible
  image: retr0h/centos7-systemd-ansible:latest
  privileged: True
  command: /usr/sbin/init
  lint: |
  set -e
  yamllint .
  ansible-lint
  provisioner:
  name: ansible
  verifier:
  name: ansible```