Ansible Quickstart

Windmill Scripts

In this quickstart guide, we will write our first script/playbook with ansible.

This tutorial covers how to create a simple ansible script through Windmill web IDE. See the dedicated page to Develop Scripts Locally.

Local Development

Develop from various environments such as your terminal, VS Code, and JetBrains IDEs.

Scripts are the basic building blocks in Windmill. They can be run and scheduled as standalone, chained together to create Flows or displayed with a personalized User Interface as Apps.

Script Editor

All the details on scripts.

Triggering Scripts

Trigger flows on-demand, by schedule or on external events.

Scripts consist of 2 parts:

• Code: For ansible this is a playbook file written in yaml.
• Settings: settings & metadata about the Script such as its path, summary, description, jsonschema of its inputs (inferred from its signature).

When stored in a code repository, these 2 parts are stored separately at <path>.playbook.yml and <path>.script.yaml

Create an Ansible playbook script

Code (Playbook)

In order to make Ansible playbooks compatible with the windmill environment and script model, there is some extra information preceding the start of the playbook that can be entered. Because of this, an Ansible playbook in Windmill will typically look like this:

---
inventory:
  - resource_type: ansible_inventory
    # You can pin an inventory to this script:
    # resource: u/user/your_resource

# File resources will be written in the relative \`target\` location before
# running the playbook
file_resources:
  - resource: u/user/fabulous_jinja_template
    target:  ./config_template.j2

# Define the arguments of the windmill script
extra_vars:
  world_qualifier:
    type: string

dependencies:
  galaxy:
    collections:
      - name: community.general
      - name: community.vmware
  python:
    - jmespath
---
- name: Echo
  hosts: 127.0.0.1
  connection: local
  vars:
    my_result:
      a: 2
      b: true
      c: "Hello"

  tasks:
  - name: Print debug message
    debug:
      msg: "Hello, {{world_qualifier}} world!"
  - name: Write variable my_result to result.json
    delegate_to: localhost
    copy:
      content: "{{ my_result | to_json }}"
      dest: result.json

There are two YAML documents in series, the second being the Ansible Playbook. The first one is only used by windmill, and will not be visible to Ansible when executing the playbook. It contains different sections that declare some metadata about the script.

We will now go thorugh each of these sections.

Arguments (extra-args)

Windmill scripts can take arguments, and in order to define the names and types of the arguments you can use this section. These definitions will be parsed allowing the frontend to interactively display dynamic inputs for the script.

extra_vars:
  world_qualifier:
    type: string
  nested_object:
    type: object
    properties:
      a:
        type: string
      b:
        type: number
  some_arr:
    type: array
    objects:
      type: string

The type definition is inspired and tries to follow the OpenAPI Data Types standard. Note that not all features / types are supported, the best way to know what is supported is to test it out in the Web IDE.

To use windmill resources as types you can use the following type definition:

extra_vars:
  my_resource:
    type: windmill_resource
    resource_type: postgresql

Under the hood, Windmill will pass these variables using the --extra-args flag to Ansible, so you can expect the according behavior.

Return Values

In windmill scripts usually have a return value, which allows scripts to be chained in flows and run conditionally on the result of a previous operation. For Ansible playbooks you can achieve the same result by having one of the tasks (preferably the last one for coherence of results/errors) write a file named result.json with the JSON object you want to return:

---
tasks:

  [...]

  - name: Write variable my_result to result.json
    delegate_to: localhost
    copy:
      content: "{{ my_result | to_json }}"
      dest: result.json

Note that valid json must be written to the file or else the job will fail. Also, this should be done by the control node i.e. your worker, so it's important to use the delegate_to: localhost directive.

Inventories

When using ansbile playbooks, you would usually run a command such as ansible-playbook playbook.yml -i inventory.ini. The ways to pass inventories to Ansible in Windmill is by filling the following section:

inventory:
  - resource_type: ansible_inventory

After adding this in the Web IDE, you will see a new inventory.ini argument pop up. You can then select or create a new ansible_inventory resource.

If you don't want one of the inputs of the script be the inventory, you can pin a specific resource to the script by specifying its path. In this case you don't need to specify the resource_type anymore:

inventory:
  - resource: u/user/my_ansible_inventory

Then the UI will not prompt you for the inventory but will use this resource at every run of the script. If otherwise you wish to not specify any inventory, you can remove the section altogether

Other non-inventory file resources

It sometimes happens that your Ansible playbook depends on some text file existing at a relative path to the playbook. This can be a configuration file, a template, some other file that you can't inline or otherwise is simpler to keep as a separate file. In this case, Windmill offers a feature to create these files at the specified path before running the playbook. The syntax will be the following:

file_resources:
  - resource: u/user/fabulous_jinja_template
    target:  ./config_template.j2

In the example above, the resource u/user/faboulous_jinja_template is a special plain text file resource. The target ./config_template.j2 is the path relative to the playbook where the file will be created and where the playbook can access it.

Now you can write your notebook assuming that this file will exist at the time of execution.

Dependencies

Ansible playbooks often depend on python packages or Ansible Galaxy Collections. In windmill you can specify these dependencies in the dependencies section and Windmill will take care of satisfying them before running the playbook.

dependencies:
  galaxy:
    collections:
      - name: community.general
      - name: community.vmware
  python:
    - jmespath

The syntax is similar to ansible-builder and Execution Environments, however all is installed locally using the same technology as for managing Python Dependencies in python scripts, meaning no extra container is created.

Ansible vs Ansible-core

Currently the Windmill image supporting ansible runs the full ansible and not ansible-core. You can expect the respective collections to be preinstalled.