pcg.alpaca_operator.alpaca_agent module – Manage ALPACA Operator agents via REST API

Note

This module is part of the pcg.alpaca_operator collection (version 2.2.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 pcg.alpaca_operator. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: pcg.alpaca_operator.alpaca_agent.

New in pcg.alpaca_operator 1.0.0

Synopsis
Requirements
Parameters
Attributes
Examples
Return Values

Synopsis

This module allows you to create, update or delete ALPACA Operator agents using the REST API.

Requirements

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

ALPACA Operator >= 5.6.0

Parameters

Parameter	Comments
api_connection dictionary / required added in pcg.alpaca_operator 2.0.0	Connection details for accessing the ALPACA Operator API.
host string added in pcg.alpaca_operator 1.0.0	Hostname of the ALPACA Operator server. Default: `"localhost"`
password string / required added in pcg.alpaca_operator 1.0.0	Password for authentication against the ALPACA Operator API.
port integer added in pcg.alpaca_operator 1.0.0	Port of the ALPACA Operator API. Default: `8443`
protocol string added in pcg.alpaca_operator 1.0.0	Protocol to use. Can be `http` or `https`. Choices: `"http"` `"https"` ← (default)
tls_verify boolean added in pcg.alpaca_operator 1.0.0	Validate SSL certificates. Choices: `false` `true` ← (default)
username string / required added in pcg.alpaca_operator 1.0.0	Username for authentication against the ALPACA Operator API.
description string added in pcg.alpaca_operator 1.0.0	Unique description of the agent.
escalation dictionary added in pcg.alpaca_operator 1.0.0	Escalation configuration.
failures_before_report integer added in pcg.alpaca_operator 2.0.0	Number of failures before reporting. Default: `0`
mail_address string added in pcg.alpaca_operator 2.0.0	Mail address for notifications. Default: `""`
mail_enabled boolean added in pcg.alpaca_operator 2.0.0	Whether mail notification is enabled. Choices: `false` ← (default) `true`
sms_address string added in pcg.alpaca_operator 2.0.0	SMS address for notifications. Default: `""`
sms_enabled boolean added in pcg.alpaca_operator 2.0.0	Whether SMS notification is enabled. Choices: `false` ← (default) `true`
ip_address string added in pcg.alpaca_operator 2.0.0	IP address of the agent.
location string added in pcg.alpaca_operator 1.0.0	Location of the agent. Can be `virtual`, `local1`, `local2`, or `remote`. Choices: `"virtual"` ← (default) `"local1"` `"local2"` `"remote"`
name string / required added in pcg.alpaca_operator 1.0.0	Unique name (hostname) of the agent.
new_name string added in pcg.alpaca_operator 1.0.0	Optional new name for the agent. If the agent specified in `name` exists, it will be renamed to this value. If the agent does not exist, a new agent will be created using this value.
script_group_id integer added in pcg.alpaca_operator 2.0.0	Script Group ID. Default: `-1`
state string added in pcg.alpaca_operator 1.0.0	Desired state of the agent. Choices: `"present"` ← (default) `"absent"`

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.

Examples

- name: Ensure agent exists
  pcg.alpaca_operator.alpaca_agent:
    name: agent01
    ip_address: 192.168.1.100
    location: virtual
    description: Test agent
    escalation:
      failures_before_report: 3
      mail_enabled: true
      mail_address: my.mail@pcg.io
      sms_enabled: true
      sms_address: 0123456789
    script_group_id: 0
    state: present
    api_connection:
      host: localhost
      port: 8443
      protocol: https
      username: secret
      password: secret
      tls_verify: False

- name: Ensure agent is absent
  pcg.alpaca_operator.alpaca_agent:
    name: agent01
    state: absent
    api_connection:
      host: localhost
      port: 8443
      protocol: https
      username: secret
      password: secret
      tls_verify: False

- name: Rename an existing agent
  pcg.alpaca_operator.alpaca_agent:
    name: agent01
    new_name: agent_renamed
    state: present
    api_connection:
      host: localhost
      port: 8443
      protocol: https
      username: secret
      password: secret
      tls_verify: False

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
agent_config dictionary added in pcg.alpaca_operator 1.0.0	Details of the created, updated, or deleted agent configuration Returned: when state is present or absent Sample: `{"description": "Test agent", "escalation": {"failures_before_report": 3, "mail_address": "monitoring@pcg.io", "mail_enabled": true, "sms_address": "", "sms_enabled": false}, "hostname": "testagent", "id": 7, "ip_address": "10.1.1.1", "location": "virtual", "script_group_id": 2}`
changed boolean added in pcg.alpaca_operator 1.0.0	Indicates whether any change was made Returned: always Sample: `true`
changes dictionary added in pcg.alpaca_operator 1.0.0	Dictionary showing differences between the current and desired configuration Returned: when state is present and a change occurred Sample: `{"escalation": {"mail_enabled": {"current": false, "desired": true}}, "ip_address": {"current": "10.1.1.1", "desired": "10.1.1.2"}}`
msg string added in pcg.alpaca_operator 1.0.0	Status message indicating the result of the operation Returned: always Sample: `"Agent created"`

Authors

Jan-Karsten Hansmeyer (@pcg)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/pcg/alpaca_operator/alpaca_agent_module.html