master interface — VMware Salt API

master interface — VMware Salt API

master interface

The LoadedMod class allows for the module loaded onto the sub to return custom sequencing, for instance it can be iterated over to return all functions

authenticate_master(master_id: <class 'str'>, pubkey: <class 'str'>, nonce: <class 'dict'>)
Returns: <class 'dict'>

Authenticate a salt-master. If the master's key is not yet in the database, save it in pending state (a pending key remains in that state until it is accepted, rejected, or deleted, or until another new key is submitted for the same salt-master). If the key is accepted, return a new jwt.

Parameters

master_id:Salt master ID
pubkey:Salt master public key in PEM format
nonce:Encrypted and signed payloads

The nonce dict contains two base64-encoded strings: "enc", a random string which has been encrypted with the salt-master's private auth key, and "sig", a signature on the "enc" value created with the raas public auth key. The encryption and the signature serve as a way for the salt-master and raas to authenticate themselves to each other, proving that they each have their private key. If either one doesn't check out, raas will report an error. If both look good, raas will re-encrypt the decrypted "enc" string with the salt-master's public key and add it to the return payload.

Return payload:

{
"key_state": "...", # accepted, pending, or rejected "enc": "...", # nonce, decrypted and re-encrypted "jwt": "..." # if the key is accepted

}

If the "enc" string in the return payload doesn't match what the salt-master sent, it should ignore the response.

delete_master(master_id: str | None, master_uuid: uuid.UUID | None)

Delete master and its grains from RaaS.

Parameters

master_id:ID (not UUID) of the master to delete.
master_uuid:UUID of the master to delete.

Note

use master_id or master_uuid, but not both.

deploy_master(host_name_ip: <class 'str'>, username: <class 'str'>, master_id: str | None, minion_id: str | None, password: str | None, private_key: str | None, req_salt_version: str | None)
Returns: <class 'uuid.UUID'>

Deploy a Salt master on a target host

Parameters

host_name_ip:Host name or IP address of the target system on which master is to be deployed
username:User name to connect to the target system through SSH. Required during master deployment.
master_id:Salt master ID to be assigned to the deployed master. Optional.
minion_id:Optional. Minion ID to be assigned to the deployed master. If not provided, the master will use its host name as the minion ID.
password:Password to connect to the target system through SSH. One of password / private_key / private_key_path is required during master deployment.
private_key:Private key to connect to the target system through SSH. One of password / private_key / private_key_path is required during master deployment.
req_salt_version:Optional. The required salt version to be installed on the master.
get_master_deployments(deploy_uuid: uuid.UUID | None, master_id: str | None, page: int | None, limit: int | None = 50)
Returns: <class 'dict'>

Get master deployments done using VMware Salt.

Parameters

deploy_uuid:Filter by deployment uuid. Optional.
master_id:Filter by Salt master id. Optional.
page:Return data from this page number.
limit:Set page size (maximum number of master deployment records to return).
get_master_details(master_id: str | None, cluster_id: str | None, state: str | None, status: str | None, plugin_status: list[str] | None, plugin_version: str | None, salt_version: str | None, sort_by: str | None, reverse: bool | None, page: int | None, limit: int | None = 100)
Returns: <class 'dict'>

Get details for a master.

Parameters

master_id:(Optional) ID (not UUID) of the master.
cluster_id:(Optional) Cluster with which the master is associated with.
state:Filter by key state: accepted, pending, or rejected.
status:(Optional) Presence status of the master.
plugin_status:(Optional) List of plugin_statuses to filter on.
plugin_version:(Optional) Plugin version to filter on.
salt_version:(Optional) Salt version to filter on.
sort_by:(Optional) Sort by one of master_id, cluster_id, status or last_seen.
reverse:(Optional) Sort by in ascending order of the sort_by column when reverse is False, and vice-versa.
page:(Optional) Return data from this page number.
limit:(Optional) Set page size (maximum number of records to return).

Example:

client.api.master.get_master_details()

RPCResponse(riq=9, ret={
      'results': [
              {'master_id': 'master_id', 'state': 'accepted', 'cluster_id': 'cluster_id', 'salt_version': '3001.1', 'plugin_version': 'v8.16.0.24', 'plugin_status': 'cannot_update_salt_old', 'last_update_jid': None, 'presence_status': 'lost'},
          ],
      'count': 1
    },
    error=None, warnings=[])
get_master_grains(master_id: str | None, master_uuid: uuid.UUID | None, split_cluster: <class 'bool'>)
Returns: <class 'dict'>

Get grains for a master.

Parameters

master_id:ID (not UUID) of the master.
master_uuid:UUID for the master.
split_cluster:If True return the grains for the individual master. If False return the grains for the cluster in which the master resides.

Example:

client.api.master.get_master_grains('saltmaster1_master')

RPCResponse(riq=26, ret=
    {u'saltmaster1_master': {u'grains': {u'biosversion': u'4.2.amazon',
                                         u'kernel': u'Linux',
                                         u'domain': u'localdomain',
                                         u'uid': 0,
                                         u'zmqversion': u'4.1.4',
                                         u'kernelrelease': u'3.10.0-693.5.2.el7.x86_64',
                                         ...... }}
    error=None, warnings=[])
get_master_keys(state: str | None, master_id: str | None, sort_by: str | None, reverse: bool | None)
Returns: <class 'list'>

Query salt-master authentication keys

Parameters

state:Filter by key state: accepted, pending, or rejected
master_id:Filter by master id (substring match)
sort_by:Sort results: master_id, state, created (default master_id)
reverse:Reverse sort order
get_master_presence(master_id: str | None, cluster_id: str | None, status: str | None, sort_by: str | None, reverse: bool | None, page: int | None, limit: int | None = 100)
Returns: <class 'dict'>

Retrieve presence status for all salt masters in the infrastructure.

Parameters

master_id:(Optional) ID (not UUID) of the master.
cluster_id:(Optional) Cluster with which the master is associated with.
status:(Optional) Presence status of the master.
sort_by:(Optional) Sort by one of master_id, cluster_id, status or last_seen.
reverse:(Optional) Sort by in ascending order of the sort_by column when reverse is False, and vice-versa.
page:(Optional) Return data from this page number.
limit:(Optional) Set page size (maximum number of records to return).

Example:

client.api.master.get_master_presence()

RPCResponse(riq=6543, ret={
      'results': [
              {'uuid': 'aa3616d5-bf1e-40ad-a207-45c2a06bb47f', 'master_id': 'master1', 'cluster_id': 'salt',
               'last_seen': '2020-11-14T19:15:24.200667', 'status': 'lost'},
              {'uuid': 'd1a884c6-16bd-4095-b226-568d0e578a00', 'master_id': 'master2', 'cluster_id': 'salt',
               'last_seen': '2020-11-14T19:15:24.200667', 'status': 'present'},
          ],
      'count': 2
    },
    error=None, warnings=[])
get_plugin_status(master_id: str | None, cluster_id: str | None, plugin_status: list[str] | None, sort_by: str | None, reverse: bool | None, page: int | None, limit: int | None = 100)
Returns: <class 'dict'>

Retrieve the status of the plugin on all connected masters. Depends on get_master_presence.

Parameters

master_id:(Optional) ID (not UUID) of the master.
cluster_id:(Optional) Cluster with which the master is associated with.
plugin_status:(Optional) List of plugin_statuses to filter on
sort_by:(Optional) Sort by one of master_id, cluster_id, status or last_seen.
reverse:(Optional) Sort by in ascending order of the sort_by column when reverse is False, and vice-versa.
page:(Optional) Return data from this page number.
limit:(Optional) Set page size (maximum number of records to return).
get_plugin_versions()
Returns: <class 'dict'>

Retrieve available master plugin versions from RaaS.

Example:

client.api.master.get_plugin_versions()

RPCResponse(
    riq=3,
    ret={
    "current": {
        "build_date": "2022-10-04T17:28:57",
        "git_describe": "v8.10.1.0",
        "name": "/app/raas/raas/static/master_plugins/SSEAPE-8.10.1.0-py3-none-any.whl",
        "message": "success",
        "sha256": "9b7279f1bc927e20c6965f194f93880c5b262777daddf1052cc1b08047bcceea",
        "filename": "SSEAPE-8.10.1.0-py3-none-any.whl"
    },
    "rollback": {
        "name": "SSEAPE-8.10.0.0-py3-none-any.whl",
        "message": "Unpacking of whl /app/raas/raas/static/master_plugins/SSEAPE-8.10.0.0-py3-none-any.whl failed with return code 1: Missing SSEAPE-8.10.0.0.dist-info/RECORD file
",
"filename": "SSEAPE-8.10.0.0-py3-none-any.whl"

}, error=None, warnings=[]

)

save_master(master_id: str | None, cluster_id: str | None, master_uuid: uuid.UUID | None, grains: dict | None)
Returns: <class 'str'>

Update or add a salt-master to the database.

Returns the UUID of the master in the database.

Parameters

master_id:ID (not UUID) of new/updated master
cluster_id:ID of cluster to which this master belongs or None if no cluster is in place.
master_uuid:UUID of master. If blank and no master with master_id exists a new one will be assigned.
grains:Master-level grains for this new master.
save_master_key(title: <class 'str'>, public_key: <class 'str'>, state: <class 'str'>)
Returns: <class 'bool'>

Pre-seed a salt master's public key for auto-acceptance.

Parameters

title:Title for the trusted salt master's public key.
public_key:Base64 encoded public key for the salt master.
state:Status for the salt master's public key. One of 'accept', 'reject'.

Returns True when the salt master key is successfully saved.

set_master_key_state(masters: list[str], action: <class 'str'>)
Returns: <class 'list'>

Set RSA key state of masters. Parameters

masters:(Required) Master IDs
action:(Required) accept, reject, delete.
set_plugin_status(master_id: <class 'str'>, status: <class 'str'>, last_update_jid: str | None, log_messages: str | None)

Set status of the VMware Salt plugin on a salt-master

Parameters

param master_id:ID (not UUID) of the salt-master to update.
param status:Plugin update status
param last_update_jid:(Optional) last known jid used to upgrade/update the plugin
param log_messages:log messages that the runner wants to report in the UI
return:
update_plugin(master_id: <class 'str'>)
Returns: <class 'str'>

Triggers update of the VMware Salt plugin on a salt-master to the latest available version. This call routes a salt-run command to the master to do the upgrade and returns the jid associated with that command.

Parameters

master_id:ID (not UUID) of the salt-master to update.

Returns the jid of the command routed to the master to do the upgrade.

update_target_group_from_master(master_id: <class 'str'>, tgt_uuid: <class 'str'>, minions_added: list[str], minions_deleted: list[str], canonical_list: <class 'bool'>, cluster_id: str | None)

Allows a master to tell RaaS that it has an updated list of minions for a given target group.

Parameters

master_id:ID (not UUID) of the master to which these minions belong
tgt_uuid:UUID of the target group to be changed
minions_added:List of minions ids added to the target group
minions_deleted:List of minions ids deleted from the target group
canonical_list:Request that RaaS remove all minions for this master and tg and replace them with the minions_added list.