Configuration

Prerun

In order 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 role or a collection. The destination is project_dir/.cache and the code itself is reused from ansible-lint, which has to do the same actions.

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 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 still disable it by adding prerun: false inside the configuration file.

Keep in mind that you can add this value to .config/molecule/config.yml file in order to avoid adding it to each scenario.

Variable Substitution

class molecule.interpolation.Interpolator

Configuration options may contain environment variables.

For example, suppose the shell contains VERIFIER_NAME=testinfra and the following molecule.yml is supplied.

verifier:
  - name: ${VERIFIER_NAME}

Molecule will substitute $VERIFIER_NAME with the value of the VERIFIER_NAME environment variable.

Warning

If an environment variable is not set, Molecule substitutes with an empty string.

Both $VARIABLE and ${VARIABLE} syntax are supported. Extended shell-style features, such as ${VARIABLE-default} and ${VARIABLE:-default} are also supported. Even the default as another environment variable is supported like ${VARIABLE-$DEFAULT} or ${VARIABLE:-$DEFAULT}. An empty string is returned when both variables are undefined.

If a literal dollar sign is needed in a configuration, use a double dollar sign ($$).

Molecule will substitute special MOLECULE_ environment variables defined in molecule.yml.

Important

Remember, the MOLECULE_ namespace is reserved for Molecule. Do not prefix your own variables with MOLECULE_.

A file may be placed in the root of the project as .env.yml, and Molecule will read variables when rendering molecule.yml. See command usage.

Construct Interpolator.

There are following environment variables available in molecule.yml:

Variable

Description

MOLECULE_DEBUG

If debug is turned on or off

MOLECULE_FILE

Path to molecule config file

MOLECULE_ENV_FILE

Path to molecule environment file

MOLECULE_STATE_FILE

?

MOLECULE_INVENTORY_FILE

Path to generated inventory file

MOLECULE_EPHEMERAL_DIRECTORY

Path to generated directory, usually ~/.cache/molecule/<scenario-name>

MOLECULE_SCENARIO_DIRECTORY

Path to scenario directory

MOLECULE_PROJECT_DIRECTORY

Path to your project directory

MOLECULE_INSTANCE_CONFIG

?

MOLECULE_DEPENDENCY_NAME

Dependency type name, usually ‘galaxy’

MOLECULE_DRIVER_NAME

Name of the molecule scenario driver

MOLECULE_PROVISIONER_NAME

Name of the provisioner tool (usually ‘ansible’)

MOLECULE_REPORT

Name of HTML file where to dump execution report.

MOLECULE_SCENARIO_NAME

Name of the scenario

MOLECULE_VERBOSITY

Determine Ansible verbosity level.

MOLECULE_VERIFIER_NAME

Name of the verifier tool (usually ‘ansible’)

MOLECULE_VERIFIER_TEST_DIRECTORY

?

Dependency

Testing roles may rely upon additional dependencies. Molecule handles managing these dependencies by invoking configurable dependency managers.

Ansible Galaxy

Shell

Driver

Molecule uses Ansible to manage instances to operate on. Molecule supports any provider Ansible supports. This work is offloaded to the provisioner.

The driver’s name is specified in molecule.yml, and can be overridden on the command line. Molecule will remember the last successful driver used, and continue to use the driver for all subsequent subcommands, or until the instances are destroyed by Molecule.

Important

The verifier must support the Ansible provider for proper Molecule integration.

The driver’s python package requires installation.

Delegated

Lint

Starting with v3, Molecule handles project linting by invoking and external lint commands as exemplified below.

The decision to remove the complex linting support was not easily taken as we do find it very useful. The issue was that molecule runs on scenarios and linting is usually performed at repository level.

It makes little sense to perform linting in more than one place per project. Molecule was able to use up to three linters and while it was aimed to flexible about them, it ended up creating more confusions to the users. We decided to maximize flexibility by just calling an external shell command.

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

The older format is no longer supported and you have to update the molecule.yml when you upgrade. If you don’t want to do any linting, it will be enough to remove all lint related sections from the file.

# old v2 format, no longer supported
lint:
  name: yamllint
  enabled: true
provisioner:
  lint:
    name: ansible-lint
  options: ...
  env: ...
verifier:
  lint:
    name: flake8

Platforms

Provisioner

Molecule handles provisioning and converging the role.

Ansible

Scenario

Molecule treats scenarios as a first-class citizens, with a top-level configuration syntax.

State

An internal bookkeeping mechanism.

Verifier

Molecule handles role testing by invoking configurable verifiers.

Ansible

Testinfra