How to Use the Command 'salt-call' (with Examples)

‘salt-call’ is an essential command in the SaltStack ecosystem, designed to invoke salt functions directly on a Salt minion. This local execution bypasses the need for a Salt master, making it useful for troubleshooting, testing, or running Salt functions independently. By using ‘salt-call’, system administrators can quickly execute Salt states or modules, gather system information, and debug configurations directly from the minion.

Use Case 1: Perform a Highstate on This Minion

Code:

salt-call state.highstate

Motivation: Running a highstate applies the desired configuration state to a Salt minion as defined in the state’s top file and related state files. This is essential for ensuring that systems are in compliance with their specified configurations, which is critical in maintaining consistency and order across a fleet of machines. For system administrators, executing a highstate can help to automate the setup and provisioning of new systems or ensure that existing systems remain within the intended configuration.

Explanation:

• salt-call: This command tells the Salt minion to execute a function directly without needing a Salt master.
• state.highstate: This argument triggers the execution of the highstate, which is a complete application of all states relevant to that minion according to the top file configuration.

Example Output:

local:
----------
          ID: /etc/ntp.conf
    Function: file.managed
      Result: True
     Comment: File /etc/ntp.conf is in the correct state
     Changes:   
----------
          ID: ntp
    Function: service.running
      Result: True
     Comment: Service ntp is running
     Changes:   

Use Case 2: Perform a Highstate Dry-Run, Compute All Changes but Don’t Actually Perform Them

Code:

salt-call state.highstate test=true

Motivation: A dry-run is invaluable when one wants to understand the impact of a highstate without making actual changes on the system. It allows administrators to preview the potential changes a highstate would implement, thus providing a safety net to prevent unexpected modifications. This becomes particularly useful when testing new configurations or state files, allowing a safe trial before full deployment.

Explanation:

• salt-call: Invokes the command locally on the minion.
• state.highstate: Invokes the execution of the highstate.
• test=true: A special argument that tells Salt to execute in a test mode, performing a dry-run. It calculates and shows the changes that would be made without actually applying them.

Example Output:

local:
----------
          ID: /etc/ntp.conf
    Function: file.managed
      Result: None
     Comment: The file /etc/ntp.conf would be updated
     Changes:   
----------
          ID: ntp
    Function: service.running
      Result: None
     Comment: Service ntp would be started
     Changes:   

Use Case 3: Perform a Highstate with Verbose Debugging Output

Code:

salt-call -l debug state.highstate

Motivation: When troubleshooting complex configurations or unexpected behavior during the application of a highstate, detailed logs are necessary. Running the highstate with verbose debugging output provides comprehensive details about each step of the process, allowing administrators to pinpoint any issues or understand how changes are being applied. This is particularly beneficial in a debugging context to ensure that each step of the state execution is visible and transparent.

Explanation:

• salt-call: Executes the command on the local minion.
• -l debug: Sets the log level to debug, which provides very detailed output beneficial for troubleshooting.
• state.highstate: Executes the highstate on the minion to apply all relevant states.

Example Output:

[DEBUG   ] Reading configuration from /etc/salt/minion
[DEBUG   ] Defaulting class _specifiers_extension to None
[INFO    ] Running state [/etc/ntp.conf] at time 10:15:20.12345
[DEBUG   ] Template found: /path/to/template.jinja
...
[INFO    ] Completed state [ntp] at time 10:15:25.67890

Use Case 4: List This Minion’s Grains

Code:

salt-call grains.items

Motivation: Grains are pieces of static information Salt collects about the minion, such as its operating system, network interfaces, or hardware details. Listing grains is crucial for understanding the system characteristics, which can inform decision-making for system roles and configurations. Additionally, grains can be used to target specific minions for state application or command execution based on their system attributes.

Explanation:

• salt-call: Triggers the command locally on the minion.
• grains.items: A salt function that retrieves all the grains data for the minion, effectively listing all the static information Salt knows about the system.

Example Output:

local:
    biosreleasedate: '04/01/2014'
    biosversion: '1.7.0'
    cpuarch: x86_64
    domain: example.com
    fqdn: hostname.example.com
    ip4_interfaces:
      eth0:
        - 192.168.0.10
    os: Ubuntu
    os_family: Debian
    os_kernel: Linux
    osrelease: '20.04'

Conclusion:

‘salt-call’ provides a versatile toolkit for system administrators to run highstates, test configurations, troubleshoot with verbose logging, and gather system information via grains. By understanding and effectively using this command, administrators can ensure system consistency, safely test deployments, and gather critical data about their minion systems, all without needing direct intervention from a Salt master.