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:
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.
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.
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:
Make sure that the specified resource is present.
Make sure that the named resource is not present.
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.