Skip to content

Ansible Waldur Module Generator

This project is a code generator designed to automate the creation of a self-contained Ansible Collection for the Waldur API. By defining a module's behavior and its API interactions in a simple YAML configuration file, you can automatically generate robust, well-documented, and idempotent Ansible modules, perfectly packaged for distribution and use.

The primary goal is to eliminate boilerplate code, enforce consistency, and dramatically speed up the development process for managing Waldur resources with Ansible. The official Waldur Ansible Collection generated by this tool is published on Ansible Galaxy.

Core Concept

The generator works by combining three main components:

  1. OpenAPI Specification: The single source of truth for all available Waldur API endpoints.
  2. Generator Configuration (generator_config.yaml): A user-defined YAML file where you describe the Ansible Collection and the modules you want to create.
  3. Plugins: The engine of the generator. Each plugin understands a specific workflow (e.g., fetching facts, simple CRUD, or complex marketplace orders) and contains the logic to build the corresponding Ansible module code.

Getting Started

Prerequisites

  • Python 3.11+
  • Poetry
  • Ansible Core (ansible-core >= 2.14)

Installation

  1. Clone the repository and navigate into the directory.

  2. Install dependencies:

    1
    poetry install

Running the Generator

To generate the Ansible Collection(s) as defined in inputs/generator_config.yaml, run:

1
poetry run ansible-waldur-generator

The generated collections will be placed in the outputs/ directory.

Documentation Guides

This project's documentation is split into guides tailored for different audiences. Find the one that best describes your goal.

For Ansible Users (Using Generated Collections)

Audience: Users who want to manage Waldur resources using a pre-built Ansible collection like waldur.openstack or waldur.structure.

This guide covers everything you need to know to write effective and clean playbooks.

  • Installing collections from Ansible Galaxy.
  • Writing playbooks to create, update, and delete resources.
  • Reducing boilerplate with module_defaults.
  • Using _facts modules for dynamic resource lookups.
  • Mapping terms from the Waldur UI to Ansible parameters.

➡️ See the full Best Practices Guide for detailed examples.

For Module Authors (Using the Generator)

Audience: Developers who want to use this generator to create a new Ansible Collection or add new modules to an existing one.

This guide provides a deep dive into the generator's configuration and plugin system.

  • Understanding the generator's workflow.
  • Configuring collections and modules in generator_config.yaml.
  • Detailed explanations of each plugin (facts, crud, order, actions, link).
  • Using YAML anchors to keep your configuration DRY.
  • Testing and publishing a generated collection.

➡️ Dive into the Module Author Guide to get started.

For Generator Developers (Contributing to this Project)

Audience: Contributors who want to extend the generator's core functionality, such as by adding a new plugin or improving the testing framework.

These guides explain the internal architecture and testing strategy of the generator itself.

  • Plugin Author Guide: Explains the internal architecture, the "Plan and Execute" runtime model, the powerful resolver system, and provides a step-by-step tutorial for creating a new plugin from scratch.
  • Test Author Guide: Details our end-to-end testing strategy using pytest and VCR.py, explaining how to run tests and how to record new "cassettes" for new or modified tests.

➡️ Start with the Plugin Author Guide and the Test Author Guide.

License

This project is licensed under the MIT License. See the LICENSE file for details.