pcg.alpaca_operator.alpaca_command_set module – Manage all ALPACA Operator commands of a specific system 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_command_set.

New in pcg.alpaca_operator 1.0.0

Synopsis
Requirements
Parameters
Attributes
Examples
Return Values

Synopsis

This Ansible module manages an entire set of ALPACA Operator commands associated with a system using a REST API. It is designed to apply bulk changes, for example, deploying multiple commands at once or cleaning up an existing command set. Use this module when you need to apply or remove multiple commands at once on a given ALPACA system. It simplifies large-scale system updates and is optimal for automation scenarios. Important: This module takes full control of the command set on the target system. Any commands not defined via Ansible will be removed from the system!

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.
commands list / elements=dictionary added in pcg.alpaca_operator 1.0.0	List of desired commands to manage. Each command can include fields such as `commands.name`, `commands.agent_id` or `commands.agent_name`, `commands.process_id`, `commands.parameters`, `commands.schedule`, `commands.history`, `commands.escalation`, etc. Default: `[]`
agent_id integer added in pcg.alpaca_operator 2.0.0	Numeric ID of the agent. Optional if `commands.agent_name` is provided. Note: This agent must also be assigned to the corresponding system if the system is managed via Ansible.
agent_name string added in pcg.alpaca_operator 2.0.0	Name of the agent. Optional if `commands.agent_id` is provided. Note: This agent must also be assigned to the corresponding system if the system is managed via Ansible.
auto_deploy boolean added in pcg.alpaca_operator 2.0.0	Whether to automatically deploy the command. Choices: `false` `true`
critical boolean added in pcg.alpaca_operator 1.0.0	Whether the command is marked as critical. Choices: `false` `true`
disabled boolean added in pcg.alpaca_operator 1.0.0	Whether the command is currently disabled. Choices: `false` `true`
escalation dictionary added in pcg.alpaca_operator 1.0.0	Escalation configuration.
mail_address string added in pcg.alpaca_operator 2.0.0	Email address for alerts.
mail_enabled boolean added in pcg.alpaca_operator 2.0.0	Whether email alerts are enabled. Choices: `false` `true`
min_failure_count integer added in pcg.alpaca_operator 2.0.0	Minimum number of failures before escalation.
sms_address string added in pcg.alpaca_operator 2.0.0	SMS number for alerts.
sms_enabled boolean added in pcg.alpaca_operator 2.0.0	Whether SMS alerts are enabled. Choices: `false` `true`
triggers dictionary added in pcg.alpaca_operator 1.0.0	Trigger types for escalation.
every_change boolean added in pcg.alpaca_operator 2.0.0	Currently no description available Choices: `false` `true`
to_green boolean added in pcg.alpaca_operator 2.0.0	Currently no description available Choices: `false` `true`
to_red boolean added in pcg.alpaca_operator 2.0.0	Currently no description available Choices: `false` `true`
to_yellow boolean added in pcg.alpaca_operator 2.0.0	Currently no description available Choices: `false` `true`
history dictionary added in pcg.alpaca_operator 1.0.0	Command history retention settings.
document_all_runs boolean added in pcg.alpaca_operator 2.0.0	Whether to document all executions. Choices: `false` `true`
retention integer added in pcg.alpaca_operator 1.0.0	Retention time in seconds.
name string added in pcg.alpaca_operator 1.0.0	Name or description of the command.
parameters string added in pcg.alpaca_operator 1.0.0	Parameters for the process.
parameters_needed boolean added in pcg.alpaca_operator 2.0.0	Whether the execution of the command requires additional parameters. Choices: `false` `true`
process_central_id integer added in pcg.alpaca_operator 2.0.0	Central ID / Global ID of the process to be executed. Optional if `commands.process_id` is provided.
process_id integer added in pcg.alpaca_operator 2.0.0	ID of the process to be executed. Optional if `commands.process_central_id` is provided.
schedule dictionary added in pcg.alpaca_operator 1.0.0	Scheduling configuration.
cron_expression string added in pcg.alpaca_operator 2.0.0	Quartz-compatible cron expression. Required when `commands.schedule.period` is `cron_expression`.
days_of_week list / elements=string added in pcg.alpaca_operator 2.0.0	List of weekdays for execution. Choices: `"monday"` `"tuesday"` `"wednesday"` `"thursday"` `"friday"` `"saturday"` `"sunday"`
period string added in pcg.alpaca_operator 1.0.0	Scheduling period. Choices: `"every_5min"` `"one_per_day"` `"hourly"` `"manually"` `"fixed_time"` `"hourly_with_mn"` `"every_minute"` `"even_hours_with_mn"` `"odd_hours_with_mn"` `"even_hours"` `"odd_hours"` `"fixed_time_once"` `"fixed_time_immediate"` `"cron_expression"` `"disabled"` `"start_fixed_time_and_hourly_mn"`
time string added in pcg.alpaca_operator 1.0.0	Execution time in HH:mm:ss. Required when `commands.schedule.period` is `fixed_time`, `fixed_time_once`, or `start_fixed_time_and_hourly_mn`.
state string added in pcg.alpaca_operator 1.0.0	Desired state of the command. Choices: `"present"` ← (default) `"absent"`
timeout dictionary added in pcg.alpaca_operator 1.0.0	Timeout configuration for command execution.
type string added in pcg.alpaca_operator 1.0.0	Type of timeout. Can be `none`, `default`, or `custom`. Choices: `"none"` `"default"` `"custom"`
value integer added in pcg.alpaca_operator 1.0.0	Timeout value in seconds (for `custom` type).
system dictionary / required added in pcg.alpaca_operator 1.0.0	Dictionary containing system identification. Either `system.system_id` or `system.system_name` must be provided.
system_id integer added in pcg.alpaca_operator 2.0.0	Numeric ID of the target system. Optional if `system.system_name` is provided.
system_name string added in pcg.alpaca_operator 2.0.0	Name of the target system. Optional if `system.system_id` is provided.

Attributes

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

Examples

- name: Ensure that multiple commands are configured correctly on system01
  pcg.alpaca_operator.alpaca_command_set:
    system:
      system_name: system01
    commands:
      - name: "BKP: DB log sync"
        state: present
        agent_name: agent01
        parameters: "-p GLTarch -s <BKP_LOG_SRC> -l 4 -d <BKP_LOG_DEST1> -r <BKP_LOG_DEST2> -b <BKP_LOG_CLEANUP_INT> -t <BKP_LOG_CLEANUP_INT2> -h DB_HOST"
        process_id: 801
        schedule:
          period: manually
          time: "01:00:00"
          days_of_week:
            - monday
            - sunday
        parameters_needed: false
        disabled: false
        critical: true
        history:
          document_all_runs: true
          retention: 900
        auto_deploy: false
        timeout:
          type: default
          value: 30
        escalation:
          mail_enabled: true
          sms_enabled: true
          mail_address: "monitoring@pcg.io"
          sms_address: "0123456789"
          min_failure_count: 1
          triggers:
            every_change: true
            to_red: false
            to_yellow: false
            to_green: true
      - name: "BKP: DB log sync 2"
        state: present
        agent_name: agent02
        parameters: "-p GLTarch -s <BKP_LOG_SRC> -l 4 -d <BKP_LOG_DEST1> -r <BKP_LOG_DEST2> -b <BKP_LOG_CLEANUP_INT> -t <BKP_LOG_CLEANUP_INT2> -h DB_HOST"
        process_id: 801
        schedule:
          period: cron_expression
          cron_expression: '0 */5 * * * ?'
        parameters_needed: false
        disabled: false
        critical: true
        history:
          document_all_runs: true
          retention: 900
        auto_deploy: false
        timeout:
          type: default
          value: 30
        escalation:
          mail_enabled: true
          sms_enabled: true
          mail_address: "monitoring@pcg.io"
          sms_address: "0123456789"
          min_failure_count: 1
          triggers:
            every_change: true
            to_red: false
            to_yellow: false
            to_green: true
    api_connection:
      host: localhost
      port: 8443
      protocol: https
      username: secret
      password: secret
      tls_verify: false

- name: Remove all commands from system system01
  pcg.alpaca_operator.alpaca_command_set:
    system:
      system_name: system01
    commands: []
    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
changed boolean added in pcg.alpaca_operator 1.0.0	Whether any change was made Returned: always
changes dictionary added in pcg.alpaca_operator 1.0.0	A dictionary describing all changes that were or would be applied. Keys typically follow the format `commandIndex_XXX`, representing the index in the `commands` list. Each entry includes diffs between the current and desired state. Also includes `removed_commands` if commands were deleted. Returned: when changes are detected (or would be applied in check_mode)
command_index_000 dictionary	Diff of the command at index 0. Contains changed fields with current and desired values. Returned: success Sample: `{"parameters": {"current": "-p foo -s A -d B", "desired": "-p foo -s A -d B -t X"}, "schedule": {"period": {"current": "manually", "desired": "every_minute"}}}`
removed_commands list / elements=dictionary	List of commands that were removed because they were not included in the desired state. Contains the complete configuration of each command before deletion. Returned: success Sample: [{"agentHostname": "my-agent-01", "agentId": 789, "autoDeploy": false, "critical": true, "disabled": false, "escalation": {"mailAddress": null, "mailEnabled": false, "minFailureCount": 0, "smsAddress": null, "smsEnabled": false, "triggers": {"everyChange": true, "toGreen": true, "toRed": true, "toYellow": true}}, "history": {"documentAllRuns": true, "retention": 900}, "id": 123, "name": "Old Command", "parameters": "-p foo -s A -d B", "parametersNeeded": false, "processId": 456, "schedule": {"daysOfWeek": [], "period": "manually", "time": "01:00:00"}, "timeout": {"type": "DEFAULT", "value": null}}]
msg string added in pcg.alpaca_operator 1.0.0	Status message Returned: always Sample: `"One or multiple commands have been created, updated or deleted in system 42"`

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_command_set_module.html