Overview

This Ansible module helps you show simple messages to users running a Playbook. It offers a better way to display messages compared to the default debug task. You can also use it to prompt for user feedback, which can be saved as Ansible variables.

Installation

You can find this plugin on Ansible Galaxy. After installing Ansible Galaxy, use this command to install the plugin:

ansible-galaxy install andrewvaughan.prompt

To use the plugin, add the following line to your playbook:

roles:
- andrewvaughan.prompt

For detailed steps, refer to the Usage Guidelines.

Manual Installation

To manually add the plugin, copy the file /action_plugins/prompt.py to a folder called action_plugins at the root of your playbook. Ansible will find and enable the commands from this plugin automatically.

Dependencies

This module works with Ansible v2.0 and above. It may also work with earlier versions, but those are not officially supported. After installing Ansible and its dependencies, you should be able to use this plugin.

Usage

Currently, the Ansible Prompt module has limited functionality, mainly allowing you to send messages to users.

The plugin accepts a single parameter, msg, which can hold one or more messages for the user. Examples are:

- name: Simple Message
  prompt:
    msg: Hello World

- name: Multiple Messages
  prompt:
    msg:
      - Hello World
      - Hello Universe

Alignment

Note: The align option doesn’t work with the ask option.

You can align messages to be shown on the left (default), center, or right:

- name: Alignment Messages
  prompt:
    msg:
      - say: Left Alignment
        align: left
      - say: Center Alignment
        align: center
      - say: Right Alignment
        align: right

Preventing Newlines

Note: The newline option doesn’t work with the ask option.

To stop the module from adding an automatic newline after a message, set newline to false:

- name: No Newline Message
  prompt:
    msg:
      - say: "Start of line..."
        newline: false
      - say: "middle of line"
        newline: false
      - say: "...end of line"

Asking Questions

The prompt plugin excels at gathering user input. To turn your prompt into a question, include both say and ask variables for each question.

For example:

- name: Simple Question
  prompt:
    msg:
      say: "What is your first name?"
      ask: first_name

- debug:
    var: first_name

You can also ask multiple questions in one prompt:

- name: Address Information
  prompt:
    msg:
      - say: "Street Address:"
        ask: address
      - say: "City:"
        ask: city
      - say: "State:"
        ask: state
      - say: "Zip Code:"
        ask: zipcode

Please note, variables are created only after the task is done. So this example won't work:

- name: Address Information
  prompt:
    msg:
      - say: "First Name:"
        ask: first_name
      - say: "Hello {{ first_name }}! What's your favorite color?"
        ask: color

You need to separate these into two different prompt tasks.

Frequently Asked Questions

Why not use Ansible's debug or prompt_vars?

While Ansible has basic messaging options, using debug and prompt_vars has drawbacks:

• debug is mainly for debugging and doesn't format output well.
• prompt_vars can only be used at the start of a script, limiting its effectiveness for gathering input during task execution.
• prompt_vars has limited support for using conditions.

Contributing

You can contribute in various ways! If you see a bug or have an idea, please open an issue.

If you wish to help with development or design, please check our Contribution Guidelines.

Testing

A Makefile is included to help with code checks, testing, and generating reports. Dependencies will be managed automatically while testing:

make test      # Runs checks and tests
make coverage  # Runs checks, tests, and creates a coverage report

Make sure to include complete tests when contributing!

Release Policy

We follow Semantic Versioning standards:

• MAJOR changes for incompatible updates,
• MINOR changes for new features that are compatible,
• PATCH changes for minor fixes and documentation updates.

License

This project is under the MIT License.

Copyright 2017 Andrew Vaughan

You can use, copy, modify, and share this software as long as you include the copyright notice.
The software is provided "as is" without any warranty.