DOCSEARCHbyAlgolia
Submit Docs

ansible-creator

repository·main·Indexed 41 days ago

https://github.com/ansible/ansible-creator

A CLI tool and Python API designed to scaffold Ansible content, providing a fast way to initialize and expand Ansible projects. It supports initializing new projects, adding resources, and specifically scaffolding Execution Environment (EE) projects with integrated CI/CD workflows for GitHub Actions and GitLab CI. It also integrates with the VS Code Ansible extension for a GUI-based content creation experience.

Tokens
16.1K
Snippets
53
Records
81
Agent score
98%

What's inside ansible-creator

  1. Overview of ansible-creator

    main
    The ansible-creator is a Command-Line Interface (CLI) tool used for scaffolding Ansible content. It is designed to automate the creation of Ansible Collections and the framework for specific plugins, ensuring precision and efficiency based on user requirements.

  2. Use the ansible-creator Python API (Internal)

    main

    The ansible_creator.api module provides a programmatic Python interface to ansible-creator's scaffolding capabilities. This is intended for internal Ansible ecosystem tooling (such as the ansible-dev-tools server, VS Code extensions, or MCP servers) rather than general end-users.

    The API is dynamic and schema-driven, meaning it introspects the command tree at runtime. When new subcommands or resources are added to the CLI, they are automatically available via the API without requiring code changes in the consuming tool.

    from ansible_creator.api import V1

api = V1(verbosity=1)

# Scaffold a collection
result = api.run("init", "collection", collection="testns.testcol")
print(result.status)  # "success"
print(result.path)    # Path to temp dir with scaffolded content

  3. Understand the Schema Structure and Parameter Types

    main

    The API schema follows a JSON Schema-like structure. Each node in the tree contains a name, description, parameters, and optionally subcommands.

    Parameter Types

    Types are inferred from the underlying argparse actions:

    • "string": Default for most arguments.
    • "boolean": For store-true/store-false flags and BooleanOptionalAction.
    • "integer": For count actions (e.g., verbosity).
    • "int" / "float": When a type converter is specified.
    • "array": For nargs + or *.

    Validation Keywords

    The schema includes standard JSON Schema keywords for client-side validation:

    • minLength / maxLength: String length constraints.
    • pattern: Regex for format validation.
    • format: Semantic hints like path, url, or fqcn.
    • minimum / maximum: Numeric range constraints.
    • minItems / maxItems: Array length constraints.
    • items: Schema for individual array elements.

    Note: Routing parameters (like subcommand, project, type, resource_type, plugin_type) are excluded from the schema as they are implicit in the command path.

  4. How Galaxy server tokens are handled in CI

    main

    When a Galaxy server is marked with token_required: true, the scaffolded CI workflow (GitHub Actions or GitLab CI) performs the following:

    1. Verifies that the environment variable ANSIBLE_GALAXY_SERVER_<ID>_TOKEN is configured as a repository secret or CI/CD variable.
    2. Passes the token as a --build-arg to the container build command (podman build or buildah bud).
    3. Declares a matching ARG directive in the EE definition's prepend_galaxy section.

    Security Note: Tokens are never written to ansible.cfg or persisted in any OCI layer. The multi-stage build ensures tokens only exist in the intermediate galaxy stage and are not present in the final image.

  5. Understand token security in EE builds

    main

    The scaffolding implements several security measures to ensure secrets do not leak into the final OCI image:

    1. Galaxy Server Tokens: Passed as --build-arg values. When using buildah >= 1.24 or podman 4+, these ARG values are not stored in the image history or metadata.
    2. SCM Tokens: Resolved via envsubst into the build context after ansible-builder create. A multi-stage build is used so that tokens only exist in intermediate stages and never in the final image.
    3. Configuration Files: The ansible.cfg file (which contains server URLs but never tokens) is volume-mounted into the build and never enters any OCI layer.

  6. Core functionalities of ansible-creator: init and add

    main

    The ansible-creator tool operates primarily through two core functional patterns:

    1. init: Used to initialize a brand new Ansible project (such as a new Collection).
    2. add: Used to add new resources or components to an existing Ansible project.

  7. Create Ansible content using the VS Code Ansible extension GUI

    main

    If you prefer a graphical interface over the command line, ansible-creator integrates with Visual Studio Code (VS Code) and the Ansible extension.

    To use the GUI:

    1. Open VS Code.
    2. Navigate to the Ansible section in the VS Code activity bar.
    3. Select "Ansible Development Tools".
    4. Use the menu-driven interface and interactive forms to manage your Ansible content without using CLI commands.

  8. Configure CI/CD for Execution Environment builds

    main

    The scaffolded pipelines allow you to build and publish Execution Environment (EE) images using either GitHub Actions (via buildah) or GitLab CI (via podman). Both systems use an envsubst model to inject secrets into the build process.

    GitHub Actions (ee-build.yml)

    Triggers:

    • Pull requests to main/master: Performs a build only.
    • Push to main/master: Builds and pushes images with latest and SHA tags.
    • Release: Tags the image with the release version and prd.
    • Manual (workflow_dispatch): Allows manual execution with an optional skip-validation toggle.

    GitLab CI (.gitlab-ci.yml)

    Triggers:

    • Pushing a Git tag.
    • Manual starts via Web UI, API, or upstream trigger.

    Note: There is no default rule to run on every push to main. You must modify the workflow: rules section in .gitlab-ci.yml to enable branch pipelines.

  10. Initialize an Ansible playbook project

    main

    Use the init playbook command to scaffold an Ansible playbook project. This command requires an adjacent collection name in the <namespace>.<name> format and a destination path.

    Command Template:

    ansible-creator init playbook <collection-name> <path>

    Example:

    ansible-creator init playbook myorg.myproject $HOME/ansible-projects/playbook-project

    The generated project includes an inventory directory, ansible.cfg, and GitHub Action workflows configured to use ansible-content-actions for testing and publishing.

    ansible-creator init playbook myorg.myproject $HOME/ansible-projects/playbook-project

  11. Scaffold an Execution Environment (EE) project

    main

    Use the ansible-creator init execution_env command to scaffold a complete Execution Environment project. This includes an EE definition file (execution-environment.yml), a CI/CD workflow, and optional configuration for Ansible Galaxy servers. By default, it scaffolds a project for GitHub Actions.

    ansible-creator init execution_env my-ee-project

  12. Configure command line completion for ansible-creator

    main

    To enable experimental command line completion for common shells, you must have the argcomplete package installed and configured. Run the following commands:

    1. Install argcomplete for your user.
    2. Activate global Python argcomplete.
    pip install argcomplete --user
activate-global-python-argcomplete --user