DOCSEARCHbyAlgolia
Submit Docs

Ansible Molecule

repository·main·Indexed 26 days ago

https://github.com/ansible/molecule

A testing framework for Ansible used to develop and validate collections, playbooks, and roles. Molecule supports testing across various platforms, including containers, virtual machines, cloud infrastructure, APIs, and network devices. It utilizes standard Ansible features like inventory and playbooks to enable flexible testing workflows and supports the latest two major versions of Ansible.

Tokens
36.3K
Snippets
104
Records
199
Agent score
87%

What's inside Molecule

  1. Overview of Ansible Molecule

    main

    Molecule is an Ansible testing framework used for developing and testing Ansible collections, playbooks, and roles. It utilizes standard Ansible features like inventory, playbooks, and collections to enable flexible testing workflows.

    Key capabilities include:

    • Testing against containers, virtual machines, cloud infrastructure, hyperscaler services, APIs, databases, and network devices.
    • Validating inventory configurations and dynamic inventory sources.
    • Supporting the latest two major versions of Ansible (N/N-1).

  2. Overview of Ansible Molecule capabilities

    main

    Molecule leverages standard Ansible features (inventory, playbooks, and collections) to provide flexible testing workflows. It can target any system or service reachable from Ansible, including:

    • Containers and virtual machines
    • Cloud infrastructure and hyperscaler services
    • APIs, databases, and network devices

    It can also be used to validate inventory configurations and dynamic inventory sources.

  3. Requirements for lifecycle management in testing

    main

    Effective lifecycle management involves four key capabilities:

    • Environment provisioning: Creating environments that reflect production conditions (networking, storage, service dependencies) using template-based provisioning.
    • State management: Managing state across test phases, including checkpointing infrastructure, preserving application configurations, and providing rollback capabilities.
    • Cleanup and resource recovery: Tracking all created resources to prevent leaks and ensuring cleanup occurs even during failures. This includes cloud resources, services, and database states.
    • Observability and debugging: Providing detailed logs (provisioning, deployment, API traces), artifact collection (logs, state dumps), and state snapshots to facilitate root cause analysis.

  4. Leverage Ansible-native integration in Molecule

    main

    Molecule is designed to be an Ansible-centric testing solution. When using Molecule, you can benefit from several native integrations that align testing with your production automation workflows:

    • Collection Testing: Molecule provides automatic detection of Ansible collections and improved dependency resolution to streamline testing workflows for collections.
    • Inventory Integration: You can use standard Ansible inventory patterns (static files, dynamic scripts, and inventory plugins) for testing. This allows you to map test inventory structures directly to production deployment patterns.
    • Execution Environments: Molecule supports testing within modern Ansible execution environments, such as those managed by ansible-navigator, ensuring your test context matches your production containerized environments.
    • Workflow Alignment: Molecule's output is designed to align visually and functionally with standard Ansible playbook output to provide a consistent interface.

  5. Requirements for configuration flexibility in testing

    main

    To support modern development workflows, a testing framework must provide:

    • Multi-platform support: Abstracting differences between infrastructure (containers, VMs, cloud) and applications while providing unified interfaces.
    • Variable and secret management: Secure injection of secrets (API keys, credentials) and hierarchical variable override systems for different environments (dev, staging, prod).
    • Extensibility and integration: Well-defined APIs and plugin architectures to integrate with CI/CD pipelines, monitoring systems, and artifact repositories.

  6. Understand Molecule Execution Flow

    main

    Molecule execution follows a structured path from the CLI to playbook execution:

    1. CLI Entrypoint: The shell.py script uses Click to parse arguments.
    2. Argument Parsing: Subcommands parse options into MoleculeArgs, CommandArgs (TypedDicts), and ansible_args (a tuple of strings).
    3. Scenario Initialization: The execute_cmdline_scenarios() function in command/base.py packages these arguments into Scenario objects.
    4. Execution Loop: For each scenario, the relevant subcommand's execute() method is called.
    5. Provisioning: The subcommand passes details to the Provisioner, which invokes AnsiblePlaybook.execute() using ansible-playbook or ansible-navigator.
    6. Result Collection: Results are saved back through the Scenario and Scenarios objects to be presented to the user.

  7. Understand the core requirements of a testing suite

    main

    A robust testing suite for automation (like Ansible) must address four critical areas to ensure code quality and operational confidence:

    1. Resource Lifecycle Management: Precise control over creating, managing, and tearing down test environments (compute, databases, test data). It must handle dependencies and ensure cleanup even on failure.
    2. Test Isolation and Reproducibility: Tests must run in predictable, isolated environments (e.g., isolated containers or VMs) to prevent interference and ensure consistent results across different CI/CD pipelines.
    3. Flexible Execution Strategies: Support for various test sequences (syntax, unit, integration, E2E), selective execution for rapid development, and parallel processing.
    4. Configuration Adaptability: Ability to support multiple platforms (cloud, containers, bare metal), diverse provisioning strategies, and integration with existing toolchains (CI/CD, secret management).

  8. Understand Molecule supplemental inventory generation

    main

    In the Ansible-native approach, Molecule does not replace your primary inventory. Instead, it generates a supplemental inventory file containing Molecule-specific variables. These variables are made available to your playbooks and include:

    • MOLECULE_SCENARIO_DIRECTORY
    • MOLECULE_EPHEMERAL_DIRECTORY
    • Scenario metadata

    Your primary inventory is managed via the path specified in ansible.executor.args.ansible_playbook.

  9. Use Shared State in Ansible-Native Scenarios

    main

    Setting shared_state: true enables scenarios to share ephemeral state and testing resources.

    Execution Flow with Shared State:

    1. Default scenario (manages lifecycle): Executes a test_sequence (e.g., create then destroy) to set up and tear down resources.
    2. Component scenarios (runs tests): Executes a test_sequence (e.g., prepare, converge, verify, cleanup) against the resources created by the default scenario.

    This allows multiple component scenarios to run against the same persistent testing environment.

  11. Initialize a collection for testing with ansible-creator

    main

    To begin testing an Ansible collection, use ansible-creator to initialize the collection structure and then add the components (roles, plugins, etc.) you wish to test. You can then customize the Molecule directory by removing default scaffolds and creating your own structure.

    Follow these steps:

    1. Initialize the collection.
    2. Navigate to the collection directory.
    3. Remove default Molecule scaffolds.
    4. Create a custom Molecule directory.
    5. Add components to the collection.
    # Initialize the collection
ansible-creator init collection test_namespace.test_collection
cd test_namespace.test_collection

# Remove default role scaffold
rm -rf roles/run

# Clear out default molecule setup
rm -rf extensions/molecule/*

# Create custom structure
mkdir -p extensions/molecule/default/

# Add roles to test
ansible-creator add resource role role1
ansible-creator add resource role role2
ansible-creator add resource role role3

  12. Configure a non-privileged systemd container

    main

    To run services that require systemd within a non-privileged container, configure your molecule.yml platform with a systemd-compliant image, set the command to /sbin/init, mount /run and /tmp as tmpfs, and mount /sys/fs/cgroup as a read-only volume.

    platforms:
  - name: instance
    image: quay.io/centos/centos:stream8
    command: /sbin/init
    tmpfs:
      - /run
      - /tmp
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:ro