pcg.alpaca_operator.alpaca_command module – Manage a single ALPACA Operator command 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.

New in pcg.alpaca_operator 1.0.0

Synopsis
Requirements
Parameters
Attributes
Examples
Return Values

Synopsis

This Ansible module manages a single ALPACA Operator command. It provides fine-grained control over individual command properties. Use this module when you need to configure or modify one specific command, such as changing its timeout, toggling disabled, or setting a new schedule. Each command is uniquely identified by the combination of its name (description) and the assigned agentHostname. Note: Renaming a command or reassigning it to a different agent is not supported by this module, as these properties are used for identification. Update behavior: If the desired command already exists, only the fields required for unique identification need to be provided (i.e., either system.system_id or system.system_name, and either command.agent_id or command.agent_name. Any options not explicitly set in the module call or the playbook will retain their existing values from the current configuration.

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.
command dictionary / required added in pcg.alpaca_operator 1.0.0	Definition of the desired command. The definition can include fields such as `command.name`, `command.agent_id` or `command.agent_name`, `command.process_id`, `command.parameters`, `command.schedule`, `command.history`, `command.escalation`, etc.
agent_id integer added in pcg.alpaca_operator 2.0.0	Numeric ID of the agent. Optional if `command.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 `command.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 `command.process_id` is provided.
process_id integer added in pcg.alpaca_operator 2.0.0	ID of the process to be executed. Optional if `command.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 `command.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 `command.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 a specific system command exist
  pcg.alpaca_operator.alpaca_command:
    system:
      system_name: system01
    command:
      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
    api_connection:
      host: "{{ ALPACA_Operator_API_Host }}"
      protocol: "{{ ALPACA_Operator_API_Protocol }}"
      port: "{{ ALPACA_Operator_API_Port }}"
      username: "{{ ALPACA_Operator_API_Username }}"
      password: "{{ ALPACA_Operator_API_Password }}"
      tls_verify: "{{ ALPACA_Operator_API_Validate_Certs }}"

- name: Delete a specific command
  pcg.alpaca_operator.alpaca_command:
  system:
      system_name: system01
  command:
      name: "BKP: DB log sync"
      agent_name: agent01
      state: absent
  api_connection:
      host: "{{ ALPACA_Operator_API_Host }}"
      protocol: "{{ ALPACA_Operator_API_Protocol }}"
      port: "{{ ALPACA_Operator_API_Port }}"
      username: "{{ ALPACA_Operator_API_Username }}"
      password: "{{ ALPACA_Operator_API_Password }}"
      tls_verify: "{{ ALPACA_Operator_API_Validate_Certs }}"

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 changes were made Returned: always
changes dictionary added in pcg.alpaca_operator 1.0.0	Dictionary containing the differences between the current and desired command configuration. Only returned when a change is detected or would occur in check mode. Returned: when changes are detected (or would be applied in check_mode)
escalation dictionary added in pcg.alpaca_operator 1.0.0	Changed escalation section (if any) Returned: success Sample: `{"min_failure_count": {"current": 0, "desired": 1}}`
parameters dictionary added in pcg.alpaca_operator 1.0.0	Changed parameters of the command (if any) Returned: success Sample: `{"current": "-p foo -s A -d B", "desired": "-p foo -s A -d B -t X"}`
schedule dictionary added in pcg.alpaca_operator 1.0.0	Changed schedule section (if any) Returned: success Sample: `{"period": {"current": "manually", "desired": "every_minute"}}`
command dictionary added in pcg.alpaca_operator 1.0.0	Information about the deleted command Returned: when state=absent and command was deleted Sample: `{"agentHostname": "agent-01", "id": 123, "name": "Backup Job"}`
msg string added in pcg.alpaca_operator 1.0.0	Status message describing what the module did Returned: always Sample: `"Command updated in system 42."`
payload dictionary added in pcg.alpaca_operator 1.0.0	Full payload that would be sent to the API (in check_mode) or that was sent (when changed) Returned: when state is present and change occurred or would occur

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