Modules

While different modules perform different tasks, their interfaces all follow the same pattern as much as possible. For example, all Sensu Go modules support check mode, most of them can have their state set to either present or absent, and they identify the resource to operate on using the name and namespace parameters.

The API of each module is composed of two parts. The auth parameter contains the pieces of information that are related to the Sensu Go backend that the module is connecting to. All other parameters hold the information related to the resource that we are operating on.

Authentication parameters

Each module has an auth parameter that holds the following information about the Sensu Go backend:

  1. The url key holds the address of the Sensu Go backend. If this key is not present in the task’s definition, Ansible will consult the SENSU_URL environment variable and, if the variable is not set, use the default value of http://localhost:8080.

  2. The user and password keys contain the credentials that the module will use when connecting to the backend. It not present, Ansible will try to look up the SENSU_USER and SENSU_PASSWORD environment variables, falling back to the default values of admin and P@ssw0rd!.

  3. The api_key field should contain an API key that module will use to authenticate with the backend. If not present, Ansible will try to use the value stored in the SENSU_API_KEY.

Note

The API key authentication is only available in Sensu Go 5.15 or newer.

When Ansible tries to connect to the Sensu Go backend, it will try to authenticate using the API key. If the api_key is not set, Ansible will fallback to using the user and password values for authentication. What this basically means is that there are two valid sets of auth parameters:

- name: Use API key authentication
  asset:
    auth:
      url: http://my.sensu.host:8765
      api_key: 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2
    # Other asset parameters here

- name: Use user and password authentication
  asset:
    auth:
      url: http://my.sensu.host:8765
      user: my-user
      password: my-password
    # Other asset parameters here

It is not an error to specify all four parameters when writing an Ansible task, but the user and password fields are ignored in this case:

- name: Use API key authentication and ignore user and password values
  asset:
    auth:
      url: http://my.sensu.host:8765
      user: my-user          # IGNORED
      password: my-password  # IGNORED
      api_key: 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2
    # Other asset parameters here

Note

If the api_key parameter is set to an invalid value, Ansible will NOT fallback to the second method of authentication. Instead, it will report an error and abort the run.

Managing Sensu Go resources

There are three things we can do using the Sensu Go Ansible modules:

  1. Make sure that the specified resource is present on the backend.

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

  3. List all currently available resources on the backend.

Note

We left out the auth parameter from the following examples in order to keep them short and readable.

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

- name: Make sure asset is present
  asset:
    namespace: my-namespace
    name: my-asset-name
    # Other asset parameters go here

We need to specify the resource’s name and decide into what namespace to place it if the resource is not a cluster-wide resource. There are a few exceptions to this rule, but not many.

If we would like to remove a certain resource from the Sensu backend (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 asset is absent
  asset:
    namespace: my-namespace
    name: my-asset-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 asset and asset_info modules.

- name: Fetch a list of all assets
  asset_info:
    namespace: my-namespace
  register: result

Note the usage of the asset_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 asset
  asset_info:
    namespace: my-namespace
    name: my-asset-name
  register: result

Info modules always return a list of objects that Sensu API returned. 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 asset
  asset_info:
    namespace: my-namespace
    name: my-asset-name
  register: result

- name: Do something if asset 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 assets
  asset_info:
    namespace: my-namespace
  register: result

- name: Display number of builds in an asset
  debug:
    msg: "{{ item.metadata.name }}: {{ item.builds | 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.

Module reference