community.general.supervisorctl module – Manage the state of a program or group of programs managed by supervisord

Note

This module is part of the community.general collection (version 14.0.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.supervisorctl.

Synopsis

  • Manage the state of a program or group of programs managed by supervisord.

Requirements

The below requirements are needed on the host that executes this module.

  • supervisorctl

Parameters

Parameter

Comments

config

path

The supervisor configuration file path.

name

string / required

The name of the supervisord program or group to manage.

The name is taken as group name when it ends with a colon :.

If name=all, all programs and program groups are managed.

password

string

Password to use for authentication.

server_url

string

URL on which supervisord server is listening.

signal

string

The signal to send to the program/group, when combined with the signalled state. Required when l(state=signalled).

state

string / required

The desired state of program/group.

Choices:

  • "present"

  • "started"

  • "stopped"

  • "restarted"

  • "absent"

  • "signalled"

stop_before_removing

boolean

added in community.general 7.5.0

Use stop_before_removing=true to stop the program/group before removing it.

Choices:

  • false ← (default)

  • true

supervisorctl_path

path

Path to supervisorctl executable.

username

string

Username to use for authentication.

wait

boolean

added in community.general 14.0.0

When state=started or state=restarted, wait while the programs are in the STARTING or BACKOFF states, and fail if any of them does not reach the RUNNING state.

This includes programs that were already in the STARTING or BACKOFF states, for example after being added with state=present and autostart=true.

When a program fails to start but supervisord is still retrying it (see startretries in the supervisord configuration), the module keeps waiting instead of failing.

Depending on the startsecs and startretries settings of the programs, the wait may take a long time.

This option is ignored in check mode.

Choices:

  • false ← (default)

  • true

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • When state=present, the module calls supervisorctl reread then supervisorctl add if the program/group does not exist.

  • When state=restarted, the module calls supervisorctl update then calls supervisorctl restart.

  • When state=absent, the module calls supervisorctl reread then supervisorctl remove to remove the target program/group. If the program/group is still running, the action fails. If you want to stop the program/group before removing, use stop_before_removing=true.

Examples

- name: Manage the state of program to be in started state
  community.general.supervisorctl:
    name: my_app
    state: started

- name: Manage the state of program group to be in started state
  community.general.supervisorctl:
    name: 'my_apps:'
    state: started

- name: Restart my_app, reading supervisorctl configuration from a specified file
  community.general.supervisorctl:
    name: my_app
    state: restarted
    config: /var/opt/my_project/supervisord.conf

- name: Restart my_app, connecting to supervisord with credentials and server URL
  community.general.supervisorctl:
    name: my_app
    state: restarted
    username: test
    password: testpass
    server_url: http://localhost:9001

- name: Send a signal to my_app via supervisorctl
  community.general.supervisorctl:
    name: my_app
    state: signalled
    signal: USR1

- name: Restart all programs and program groups
  community.general.supervisorctl:
    name: all
    state: restarted

- name: Start my_app and fail unless it reaches the RUNNING state
  community.general.supervisorctl:
    name: my_app
    state: started
    wait: true

Authors

  • Matt Wright (@mattupstate)

  • Aaron Wang (@inetfuture)