Skip to content

Introduce centralized ansible configuration section and simplify init command#4509

Merged
cidrblock merged 3 commits intoansible:mainfrom
cidrblock:ansible_as_root_key
Aug 13, 2025
Merged

Introduce centralized ansible configuration section and simplify init command#4509
cidrblock merged 3 commits intoansible:mainfrom
cidrblock:ansible_as_root_key

Conversation

@cidrblock
Copy link
Copy Markdown

@cidrblock cidrblock commented Aug 10, 2025 •
edited
Loading

Summary

This change introduces a new top-level ansible: section to molecule.yml that centralizes all Ansible-related configuration previously scattered across multiple sections. The enhancement maintains full backward compatibility while providing a cleaner, more intuitive configuration experience.

Background

Currently, Ansible configuration is distributed across several sections (provisioner.ansible_args, provisioner.config_options, executor.backend, etc.), creating confusion and inconsistency. This change consolidates these settings into a single, logical location while supporting modern Ansible tooling patterns.

Key Changes

New ansible: Configuration Section:

  • ansible.cfg: Centralized ansible.cfg configuration options
  • ansible.env: Environment variables for Ansible execution
  • ansible.executor: Backend selection (ansible-playbook/ansible-navigator) with dedicated argument structures
  • ansible.playbooks: Playbook path definitions

Enhanced User Experience:

  • Simplified molecule init scenario command (removed unnecessary options)
  • Comprehensive template with practical defaults and examples
  • Better support for ansible-navigator and execution environments
  • Clear separation between config file settings and CLI arguments

Backward Compatibility:

  • Automatic migration of legacy keys to new ansible: section
  • Mutual exclusion validation prevents conflicting configurations
  • Existing molecule.yml files continue to work unchanged

Technical Implementation

  • Schema validation: Enhanced JSON schema with conditional requirements and conflict detection
  • Runtime migration: Transparent conversion of legacy configuration keys
  • Template improvements: Modern, comprehensive molecule.yml generation
  • CLI simplification: Streamlined init command interface

Complete Per-File Changes (17 files, +1716/-300 lines)

details

Core Implementation Files

src/molecule/data/molecule.json (+198/-9 lines)

  • Added complete AnsibleModel schema definition with nested cfg, executor, env, playbooks
  • Implemented conditional validation: platforms optional if ansible: present, mandatory otherwise
  • Added mutual exclusion rules preventing conflicts between legacy and new keys
  • Enhanced ProvisionerModel to include ansible_args for validation
  • Removed legacy root executor schema

src/molecule/config.py (+138/-113 lines)

  • Replaced legacy migration functions with centralized _get_config_with_migration()
  • Added comprehensive debug logging for migration guidance
  • Implemented _migrate_user_config() with support for ansible_args, config_options, env, playbooks
  • Enhanced configuration loading flow: defaults → user config → migration → merge
  • Added _get_ansible_key_mapping() helper for debug messages

src/molecule/constants.py (+123/-1 lines)

  • Added complete DEFAULT_CONFIG with new ansible section defaults
  • Centralized all default configuration in single location
  • Provides sensible defaults for ansible.cfg, ansible.env, ansible.executor, ansible.playbooks

src/molecule/types.py (+73/-14 lines)

  • Added AnsibleData TypedDict with nested configuration structures
  • Enhanced DefaultConfigData to include ansible section
  • Updated type definitions to support new schema structure

Runtime Integration Files

src/molecule/provisioner/ansible.py (+46/-38 lines)

  • Updated ansible_args, config_options, env properties to use ansible section
  • Modified inventory property to handle empty platforms gracefully
  • Enhanced _verify_inventory with context-aware validation
  • Maintained backward compatibility while accessing new configuration paths

src/molecule/provisioner/ansible_playbooks.py (+11/-4 lines)

  • Updated _get_playbook and _get_bundled_driver_playbook to access ansible.playbooks
  • Maintained existing playbook resolution logic with new configuration source

src/molecule/model/schema_v3.py (+17/-14 lines)

  • Enhanced validate function to handle optional driver properties
  • Improved error handling for missing configuration sections
  • Maintained existing validation interface while supporting new schema

Command Interface Files

src/molecule/command/init/scenario.py (+1/-64 lines)

  • Removed deprecated CLI options: --dependency-name, --driver-name, --provisioner-name
  • Simplified function signature to only accept scenario_name
  • Removed driver validation logic (no longer needed)
  • Updated CommandArgs TypedDict for cleaner interface

src/molecule/data/init-scenario.yml (-4 lines)

  • Removed conditional template logic based on driver type
  • Simplified template processing for consistent generation

src/molecule/data/templates/scenario/molecule.yml.j2 (+57/-12 lines)

  • Complete rewrite with comprehensive ansible: section example
  • Educational comments explaining each configuration option
  • Examples for both ansible-playbook and ansible-navigator
  • Production-ready defaults and best practices

Test Files

tests/unit/test_migration_logic.py (+810 lines) - NEW FILE

  • Comprehensive test suite for migration logic
  • 10 test cases covering positive and negative migration scenarios
  • Schema validation tests with before/after configurations
  • Debug logging verification for migration guidance

tests/unit/provisioner/test_ansible.py (+141/-17 lines)

  • Updated test fixtures to use new ansible section format
  • Enhanced tests for new configuration access patterns
  • Maintained test coverage for backward compatibility

tests/unit/provisioner/test_ansible_playbook.py (+33/-3 lines)

  • Updated fixtures and tests for new ansible.executor path
  • Enhanced test coverage for argument handling

tests/unit/test_config.py (+47/-1 lines)

  • Added tests for new ansible section defaults and validation
  • Enhanced configuration loading tests

tests/unit/conftest.py (+15/-2 lines)

  • Updated test fixtures to support new schema structure
  • Enhanced test configuration setup

Integration Test Fixtures

tests/fixtures/integration/test_command/molecule/test-scenario*/molecule.yml (+3/-2 lines each)

  • Updated integration test fixtures to use new format
  • Maintained test compatibility with enhanced configuration

Migration Path

Users can gradually adopt the new ansible: section while legacy configurations remain functional. Debug logging assists with migration by identifying which legacy keys can be moved to the centralized section.

Future Direction

This change encourages the use of Ansible-native inventory management rather than Molecule-managed inventory through legacy keys, aligning with modern Ansible practices and improving integration with existing Ansible toolchains.

Testing

  • Comprehensive unit tests for migration logic and schema validation
  • Integration tests verify backward compatibility
  • All existing tests continue to pass (143 passed, 3 skipped)

Example Usage

Before (legacy):

provisioner:
  name: ansible
  ansible_args:
    - --diff
  config_options:
    defaults:
      host_key_checking: false
executor:
  backend: ansible-playbook

After (centralized):

ansible:
  cfg:
    defaults:
      host_key_checking: false
  executor:
    backend: ansible-playbook
    args:
      ansible_playbook:
        - --diff

Both configurations work, but the new format provides better organization and modern tooling support.

Documentation

Due to the breadth of changes needed, documentation updates will be in a future PR.

@cidrblock cidrblock requested a review from a team as a code owner August 10, 2025 14:21
@cidrblock cidrblock removed the feature label Aug 11, 2025
@cidrblock cidrblock changed the title feat: Introduce centralized ansible configuration section and simplify init command Introduce centralized ansible configuration section and simplify init command Aug 11, 2025
@cidrblock cidrblock force-pushed the ansible_as_root_key branch from 9aafdab to 1877493 Compare August 12, 2025 15:39
@cidrblock cidrblock requested a review from a team August 12, 2025 20:22

This comment was marked as outdated.

Sign in to view

@cidrblock cidrblock mentioned this pull request Aug 12, 2025
Closed
shatakshiiii
shatakshiiii approved these changes Aug 13, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor

@shatakshiiii shatakshiiii left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great! 🎉

@cidrblock cidrblock merged commit 4735afc into ansible:main Aug 13, 2025
21 checks passed
@smbd smbd mentioned this pull request Dec 3, 2025
Closed
7 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@shatakshiiii shatakshiiii shatakshiiii approved these changes

@Qalthos Qalthos Awaiting requested review from Qalthos

@ssbarnea ssbarnea Awaiting requested review from ssbarnea

Assignees

No one assigned

Labels

enhancement

Projects

🧰 devtools project board
Archived in project

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@cidrblock @shatakshiiii