consul

Interact with Consul

https://www.consul.io

saltext.consul.modules.consul.list_(consul_url=None, token=None, key=None, **kwargs)[source]

List keys in Consul

Parameters:

  • consul_url – The Consul server URL.

  • key – The key to use as the starting point for the list.

Returns:

The list of keys.

CLI Example:

salt '*' consul.list
salt '*' consul.list key='web'
saltext.consul.modules.consul.get(consul_url=None, key=None, token=None, recurse=False, decode=False, raw=False)[source]

Get key from Consul

Parameters:

  • consul_url – The Consul server URL.

  • key – The key to use as the starting point for the list.

  • recurse – Return values recursively beginning at the value of key.

  • decode – By default values are stored as Base64 encoded values, decode will return the whole key with the value decoded.

  • raw – Simply return the decoded value of the key.

Returns:

The keys in Consul.

CLI Example:

salt '*' consul.get key='web/key1'
salt '*' consul.get key='web' recurse=True
salt '*' consul.get key='web' recurse=True decode=True

By default values stored in Consul are base64 encoded, passing the decode option will show them as the decoded values.

salt '*' consul.get key='web' recurse=True decode=True raw=True

By default Consult will return other information about the key, the raw option will return only the raw value.

saltext.consul.modules.consul.put(consul_url=None, token=None, key=None, value=None, **kwargs)[source]

Put values into Consul

Parameters:

  • consul_url – The Consul server URL.

  • key – The key to use as the starting point for the list.

  • value – The value to set the key to.

  • flags – This can be used to specify an unsigned value between 0 and 2^64-1. Clients can choose to use this however makes sense for their application.

  • cas – This flag is used to turn the PUT into a Check-And-Set operation.

  • acquire – This flag is used to turn the PUT into a lock acquisition operation.

  • release – This flag is used to turn the PUT into a lock release operation.

Returns:

Boolean & message of success or failure.

CLI Example:

salt '*' consul.put key='web/key1' value="Hello there"

salt '*' consul.put key='web/key1' value="Hello there" acquire='d5d371f4-c380-5280-12fd-8810be175592'

salt '*' consul.put key='web/key1' value="Hello there" release='d5d371f4-c380-5280-12fd-8810be175592'
saltext.consul.modules.consul.delete(consul_url=None, token=None, key=None, **kwargs)[source]

Delete values from Consul

Parameters:

  • consul_url – The Consul server URL.

  • key – The key to use as the starting point for the list.

  • recurse – Delete values recursively beginning at the value of key.

  • cas – This flag is used to turn the DELETE into a Check-And-Set operation.

Returns:

Boolean & message of success or failure.

CLI Example:

salt '*' consul.delete key='web'
salt '*' consul.delete key='web' recurse='True'
saltext.consul.modules.consul.agent_checks(consul_url=None, token=None)[source]

Returns the checks the local agent is managing

Parameters:

consul_url – The Consul server URL.

Returns:

Returns the checks the local agent is managing

CLI Example:

salt '*' consul.agent_checks
saltext.consul.modules.consul.agent_services(consul_url=None, token=None)[source]

Returns the services the local agent is managing

Parameters:

consul_url – The Consul server URL.

Returns:

Returns the services the local agent is managing

CLI Example:

salt '*' consul.agent_services
saltext.consul.modules.consul.agent_members(consul_url=None, token=None, **kwargs)[source]

Returns the members as seen by the local serf agent

Parameters:

consul_url – The Consul server URL.

Returns:

Returns the members as seen by the local serf agent

CLI Example:

salt '*' consul.agent_members
saltext.consul.modules.consul.agent_self(consul_url=None, token=None)[source]

Returns the local node configuration

Parameters:

consul_url – The Consul server URL.

Returns:

Returns the local node configuration

CLI Example:

salt '*' consul.agent_self
saltext.consul.modules.consul.agent_maintenance(consul_url=None, token=None, **kwargs)[source]

Manages node maintenance mode

Parameters:

  • consul_url – The Consul server URL.

  • enable – The enable flag is required. Acceptable values are either true (to enter maintenance mode) or false (to resume normal operation).

  • reason – If provided, its value should be a text string explaining the reason for placing the node into maintenance mode.

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_maintenance enable='False' reason='Upgrade in progress'
saltext.consul.modules.consul.agent_join(consul_url=None, token=None, address=None, **kwargs)[source]

Triggers the local agent to join a node

Parameters:

  • consul_url – The Consul server URL.

  • address – The address for the agent to connect to.

  • wan – Causes the agent to attempt to join using the WAN pool.

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_join address='192.168.1.1'
saltext.consul.modules.consul.agent_leave(consul_url=None, token=None, node=None)[source]

Used to instruct the agent to force a node into the left state.

Parameters:

  • consul_url – The Consul server URL.

  • node – The node the agent will force into left state

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_leave node='web1.example.com'
saltext.consul.modules.consul.agent_check_register(consul_url=None, token=None, **kwargs)[source]

The register endpoint is used to add a new check to the local agent.

Parameters:

  • consul_url – The Consul server URL.

  • name – The description of what the check is for.

  • id – The unique name to use for the check, if not provided ‘name’ is used.

  • notes – Human readable description of the check.

  • script – If script is provided, the check type is a script, and Consul will evaluate that script based on the interval parameter.

  • http – Check will perform an HTTP GET request against the value of HTTP (expected to be a URL) based on the interval parameter.

  • ttl – If a TTL type is used, then the TTL update endpoint must be used periodically to update the state of the check.

  • interval – Interval at which the check should run.

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_check_register name='Memory Utilization' script='/usr/local/bin/check_mem.py' interval='15s'
saltext.consul.modules.consul.agent_check_deregister(consul_url=None, token=None, checkid=None)[source]

The agent will take care of deregistering the check from the Catalog.

Parameters:

  • consul_url – The Consul server URL.

  • checkid – The ID of the check to deregister from Consul.

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_check_deregister checkid='Memory Utilization'
saltext.consul.modules.consul.agent_check_pass(consul_url=None, token=None, checkid=None, **kwargs)[source]

This endpoint is used with a check that is of the TTL type. When this is called, the status of the check is set to passing and the TTL clock is reset.

Parameters:

  • consul_url – The Consul server URL.

  • checkid – The ID of the check to mark as passing.

  • note – A human-readable message with the status of the check.

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_check_pass checkid='redis_check1' note='Forcing check into passing state.'
saltext.consul.modules.consul.agent_check_warn(consul_url=None, token=None, checkid=None, **kwargs)[source]

This endpoint is used with a check that is of the TTL type. When this is called, the status of the check is set to warning and the TTL clock is reset.

Parameters:

  • consul_url – The Consul server URL.

  • checkid – The ID of the check to deregister from Consul.

  • note – A human-readable message with the status of the check.

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_check_warn checkid='redis_check1' note='Forcing check into warning state.'
saltext.consul.modules.consul.agent_check_fail(consul_url=None, token=None, checkid=None, **kwargs)[source]

This endpoint is used with a check that is of the TTL type. When this is called, the status of the check is set to critical and the TTL clock is reset.

Parameters:

  • consul_url – The Consul server URL.

  • checkid – The ID of the check to deregister from Consul.

  • note – A human-readable message with the status of the check.

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_check_fail checkid='redis_check1' note='Forcing check into critical state.'
saltext.consul.modules.consul.agent_service_register(consul_url=None, token=None, decode=False, text=True, **kwargs)[source]

The used to add a new service, with an optional health check, to the local agent.

Parameters:

  • consul_url – The Consul server URL.

  • name – A name describing the service.

  • address – The address used by the service, defaults to the address of the agent.

  • port – The port used by the service.

  • id – Unique ID to identify the service, if not provided the value of the name parameter is used.

  • tags – Identifying tags for service, string or list.

  • script – If script is provided, the check type is a script, and Consul will evaluate that script based on the interval parameter.

  • http – Check will perform an HTTP GET request against the value of HTTP (expected to be a URL) based on the interval parameter.

  • check_ttl – If a TTL type is used, then the TTL update endpoint must be used periodically to update the state of the check.

  • check_interval – Interval at which the check should run.

  • decode – Passed to salt.utils.http.query to decode the output into a data structure.

  • text – Passed to salt.utils.http.query to return the raw response body in the “text” key.

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_service_register name='redis' tags='["master", "v1"]' address="127.0.0.1" port="8080" check_script="/usr/local/bin/check_redis.py" interval="10s"
saltext.consul.modules.consul.agent_service_deregister(consul_url=None, token=None, serviceid=None, decode=True, text=False)[source]

Used to remove a service.

Parameters:

  • consul_url – The Consul server URL.

  • serviceid – A serviceid describing the service.

  • decode – Passed to salt.utils.http.query to decode the output into a data structure.

  • text – Passed to salt.utils.http.query to return the raw response body in the “text” key.

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_service_deregister serviceid='redis'
saltext.consul.modules.consul.agent_service_maintenance(consul_url=None, token=None, serviceid=None, **kwargs)[source]

Used to place a service into maintenance mode.

Parameters:

  • consul_url – The Consul server URL.

  • serviceid – A name of the service.

  • enable – Whether the service should be enabled or disabled.

  • reason – A human readable message of why the service was enabled or disabled.

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.agent_service_deregister serviceid='redis' enable='True' reason='Down for upgrade'
saltext.consul.modules.consul.session_create(consul_url=None, token=None, **kwargs)[source]

Used to create a session.

Parameters:

  • consul_url – The Consul server URL.

  • lockdelay – Duration string using a “s” suffix for seconds. The default is 15s.

  • node – Must refer to a node that is already registered, if specified. By default, the agent’s own node name is used.

  • name – A human-readable name for the session

  • checks – A list of associated health checks. It is highly recommended that, if you override this list, you include the default “serfHealth”.

  • behavior – Can be set to either release or delete. This controls the behavior when a session is invalidated. By default, this is release, causing any locks that are held to be released. Changing this to delete causes any locks that are held to be deleted. delete is useful for creating ephemeral key/value entries.

  • ttl – Session is invalidated if it is not renewed before the TTL expires

Returns:

Boolean and message indicating success or failure.

CLI Example:

salt '*' consul.session_create node='node1' name='my-session' behavior='delete' ttl='3600s'
saltext.consul.modules.consul.session_list(consul_url=None, token=None, return_list=False, **kwargs)[source]

Used to list sessions.

Parameters:

  • consul_url – The Consul server URL.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

  • return_list – By default, all information about the sessions is returned, using the return_list parameter will return a list of session IDs.

Returns:

A list of all available sessions.

CLI Example:

salt '*' consul.session_list
saltext.consul.modules.consul.session_destroy(consul_url=None, token=None, session=None, **kwargs)[source]

Destroy session

Parameters:

  • consul_url – The Consul server URL.

  • session – The ID of the session to destroy.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

Returns:

Boolean & message of success or failure.

CLI Example:

salt '*' consul.session_destroy session='c1c4d223-91cb-3d1f-1ee8-f2af9e7b6716'
saltext.consul.modules.consul.session_info(consul_url=None, token=None, session=None, **kwargs)[source]

Information about a session

Parameters:

  • consul_url – The Consul server URL.

  • session – The ID of the session to return information about.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

Returns:

Boolean & message of success or failure.

CLI Example:

salt '*' consul.session_info session='c1c4d223-91cb-3d1f-1ee8-f2af9e7b6716'
saltext.consul.modules.consul.catalog_register(consul_url=None, token=None, **kwargs)[source]

Registers a new node, service, or check

Parameters:

  • consul_url – The Consul server URL.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

  • node – The node to register.

  • address – The address of the node.

  • service – The service that will be registered.

  • service_address – The address that the service listens on.

  • service_port – The port for the service.

  • service_id – A unique identifier for the service, if this is not provided “name” will be used.

  • service_tags – Any tags associated with the service.

  • check – The name of the health check to register

  • check_status – The initial status of the check, must be one of unknown, passing, warning, or critical.

  • check_service – The service that the check is performed against.

  • check_id – Unique identifier for the service.

  • check_notes – An opaque field that is meant to hold human-readable text.

Returns:

Boolean & message of success or failure.

CLI Example:

salt '*' consul.catalog_register node='node1' address='192.168.1.1' service='redis' service_address='127.0.0.1' service_port='8080' service_id='redis_server1'
saltext.consul.modules.consul.catalog_deregister(consul_url=None, token=None, **kwargs)[source]

Deregisters a node, service, or check

Parameters:

  • consul_url – The Consul server URL.

  • node – The node to deregister.

  • datacenter – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

  • checkid – The ID of the health check to deregister.

  • serviceid – The ID of the service to deregister.

Returns:

Boolean & message of success or failure.

CLI Example:

salt '*' consul.catalog_register node='node1' serviceid='redis_server1' checkid='redis_check1'
saltext.consul.modules.consul.catalog_datacenters(consul_url=None, token=None)[source]

Return list of available datacenters from catalog.

Parameters:

consul_url – The Consul server URL.

Returns:

The list of available datacenters.

CLI Example:

salt '*' consul.catalog_datacenters
saltext.consul.modules.consul.catalog_nodes(consul_url=None, token=None, **kwargs)[source]

Return list of available nodes from catalog.

Parameters:

  • consul_url – The Consul server URL.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

Returns:

The list of available nodes.

CLI Example:

salt '*' consul.catalog_nodes
saltext.consul.modules.consul.catalog_services(consul_url=None, token=None, **kwargs)[source]

Return list of available services rom catalog.

Parameters:

  • consul_url – The Consul server URL.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

Returns:

The list of available services.

CLI Example:

salt '*' consul.catalog_services
saltext.consul.modules.consul.catalog_service(consul_url=None, token=None, service=None, **kwargs)[source]

Information about the registered service.

Parameters:

  • consul_url – The Consul server URL.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

  • tag – Filter returned services with tag parameter.

Returns:

Information about the requested service.

CLI Example:

salt '*' consul.catalog_service service='redis'
saltext.consul.modules.consul.catalog_node(consul_url=None, token=None, node=None, **kwargs)[source]

Information about the registered node.

Parameters:

  • consul_url – The Consul server URL.

  • node – The node to request information about.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

Returns:

Information about the requested node.

CLI Example:

salt '*' consul.catalog_service service='redis'
saltext.consul.modules.consul.health_node(consul_url=None, token=None, node=None, **kwargs)[source]

Health information about the registered node.

Parameters:

  • consul_url – The Consul server URL.

  • node – The node to request health information about.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

Returns:

Health information about the requested node.

CLI Example:

salt '*' consul.health_node node='node1'
saltext.consul.modules.consul.health_checks(consul_url=None, token=None, service=None, **kwargs)[source]

Health information about the registered service.

Parameters:

  • consul_url – The Consul server URL.

  • service – The service to request health information about.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

Returns:

Health information about the requested node.

CLI Example:

salt '*' consul.health_checks service='redis1'
saltext.consul.modules.consul.health_service(consul_url=None, token=None, service=None, **kwargs)[source]

Health information about the registered service.

Parameters:

  • consul_url – The Consul server URL.

  • service – The service to request health information about.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

  • tag – Filter returned services with tag parameter.

  • passing – Filter results to only nodes with all checks in the passing state.

Returns:

Health information about the requested node.

CLI Example:

salt '*' consul.health_service service='redis1'

salt '*' consul.health_service service='redis1' passing='True'
saltext.consul.modules.consul.health_state(consul_url=None, token=None, state=None, **kwargs)[source]

Returns the checks in the state provided on the path.

Parameters:

  • consul_url – The Consul server URL.

  • state – The state to show checks for. The supported states are any, unknown, passing, warning, or critical. The any state is a wildcard that can be used to return all checks.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

Returns:

The checks in the provided state.

CLI Example:

salt '*' consul.health_state state='redis1'

salt '*' consul.health_state service='redis1' passing='True'
saltext.consul.modules.consul.status_leader(consul_url=None, token=None)[source]

Returns the current Raft leader

Parameters:

consul_url – The Consul server URL.

Returns:

The address of the Raft leader.

CLI Example:

salt '*' consul.status_leader
saltext.consul.modules.consul.status_peers(consul_url, token=None)[source]

Returns the current Raft peer set

Parameters:

consul_url – The Consul server URL.

Returns:

Retrieves the Raft peers for the datacenter in which the agent is running.

CLI Example:

salt '*' consul.status_peers
saltext.consul.modules.consul.acl_create(consul_url=None, token=None, **kwargs)[source]

Create a new ACL token.

Parameters:

  • consul_url – The Consul server URL.

  • name – Meaningful indicator of the ACL’s purpose.

  • type – Type is either client or management. A management token is comparable to a root user and has the ability to perform any action including creating, modifying, and deleting ACLs.

  • rules – The Consul server URL.

Returns:

Boolean & message of success or failure.

CLI Example:

salt '*' consul.acl_create
saltext.consul.modules.consul.acl_update(consul_url=None, token=None, **kwargs)[source]

Update an ACL token.

Parameters:

  • consul_url – The Consul server URL.

  • name – Meaningful indicator of the ACL’s purpose.

  • id – Unique identifier for the ACL to update.

  • type – Type is either client or management. A management token is comparable to a root user and has the ability to perform any action including creating, modifying, and deleting ACLs.

  • rules – The Consul server URL.

Returns:

Boolean & message of success or failure.

CLI Example:

salt '*' consul.acl_update
saltext.consul.modules.consul.acl_delete(consul_url=None, token=None, **kwargs)[source]

Delete an ACL token.

Parameters:

  • consul_url – The Consul server URL.

  • id – Unique identifier for the ACL to update.

Returns:

Boolean & message of success or failure.

CLI Example:

salt '*' consul.acl_delete id='c1c4d223-91cb-3d1f-1ee8-f2af9e7b6716'
saltext.consul.modules.consul.acl_info(consul_url=None, **kwargs)[source]

Information about an ACL token.

Parameters:

  • consul_url – The Consul server URL.

  • id – Unique identifier for the ACL to update.

Returns:

Information about the ACL requested.

CLI Example:

salt '*' consul.acl_info id='c1c4d223-91cb-3d1f-1ee8-f2af9e7b6716'
saltext.consul.modules.consul.acl_clone(consul_url=None, token=None, **kwargs)[source]

Information about an ACL token.

Parameters:

  • consul_url – The Consul server URL.

  • id – Unique identifier for the ACL to update.

Returns:

Boolean, message of success or failure, and new ID of cloned ACL.

CLI Example:

salt '*' consul.acl_info id='c1c4d223-91cb-3d1f-1ee8-f2af9e7b6716'
saltext.consul.modules.consul.acl_list(consul_url=None, token=None, **kwargs)[source]

List the ACL tokens.

Parameters:

consul_url – The Consul server URL.

Returns:

List of ACLs

CLI Example:

salt '*' consul.acl_list
saltext.consul.modules.consul.event_fire(consul_url=None, token=None, name=None, **kwargs)[source]

List the ACL tokens.

Parameters:

  • consul_url – The Consul server URL.

  • name – The name of the event to fire.

  • dc – By default, the datacenter of the agent is queried; however, the dc can be provided using the “dc” parameter.

  • node – Filter by node name.

  • service – Filter by service name.

  • tag – Filter by tag name.

Returns:

List of ACLs

CLI Example:

salt '*' consul.event_fire name='deploy'
saltext.consul.modules.consul.event_list(consul_url=None, token=None, **kwargs)[source]

List the recent events.

Parameters:

  • consul_url – The Consul server URL.

  • name – The name of the event to fire.

Returns:

List of ACLs

CLI Example:

salt '*' consul.event_list