Modules

While different modules perform different tasks, their interfaces all follow the same pattern as much as possible.

The API of each module is composed of two parts. Information iside the provider parameter influences how moddules connect to the Unit service. All other parameters hold the information related to the resource that we are operating on.

Provider parameters

Each module has a provider parameter that holds the following information about the Unit process we would like to manage:

  1. The endpoint key holds the address of the Unit’s control socket. If this key is not present in the task’s definition, modules will consult the UNIT_ENDPOINT environment variable and, if the variable is not set, try to use the common unix socket paths. We can leave this variable unset in most cases.

  2. username and password keys contain the credentials that modules will use when connecting to the Unit via the IP-based socket. It not present, modules will try to look up the UNIT_USERNAME and UNIT_PASSWORD environment variables. Again, we can leave these two variable unset in vast majority of use cases.

  3. verify and ca_path keys control how IP-based socket is verified. By default, modules perform strict verification using system certificates. By providing the ca_path parameter, we can instruct modules to verify socket agains a custom CA bundle. We can also turn off the verification entirely by setting the verify parameter to false. If parameters are not set, modules will try to load valus from UNIT_VERIFY and UNIT_CA_PATH environment variables.

In most common scenario where we want to interact with the Unit process via the UNIX socket, we can leave out the provider parameter completely and modules will do the right thing.

Managing Unit resources

There are three things we can do using modules from the Unit Ansible Collection:

  1. Make sure that the specified resource is present.

  2. Make sure that the named resource is not present.

  3. List all currently available resources.

A typical task for creating (and by creating we mean making sure it exists) a resource would look like this:

- name: Make sure application is present
  steampunk.unit.python_app:
    name: app-name
    # Other application parameters go here

There are a few exceptions to this rule (for example, listeners are not named because they are uniquely identified by their pattern), but not many.

If we would like to remove a certain resource (and by remove we mean make sure it is not present), we can write a task and set its state parameter to absent:

- name: Make sure application is absent
  steampunk.unit.python_app:
    name: app-name
    state: absent

Almost every module for manipulating resources has its counterpart module that can be used to retrieve information about the corresponding resources, for instance steampunk.unit.route and steampunk.unit.route_info module pair.

- name: Fetch a list of all routes
  steampunk.unit.route_info:
  register: result

Note the usage of the steampunk.unit.route_info module in the example above. We can also retrieve information about a single asset by adding a name parameter to the previous task:

- name: Fetch a specific route
  steampunk.unit.route_info:
    name: my-route
  register: result

Info modules always return a list of objects. And if we try to fetch a non-existing resource, the result will hold an empty list. This makes it easy to write conditional tasks using next pattern:

- name: Fetch a specific route
  steampunk.unit.route_info:
    name: my-route
  register: result

- name: Do something if route is there
  debug:
    msg: We are doing something
  when: result.objects | length == 1

Of course, you can also loop over the result using a loop construct:

- name: Fetch a list of all routes
  steampunk.unit.route_info:
  register: result

- name: Count the steps in each route
  debug:
    msg: "{{ item.name }}: {{ item.steps | length }}"
  loop: result.objects

Reference material for each module contains documentation on what parameters certain modules accept and what values they expect those parameters to be.