consul integration pack v0.6.7

consul jfryman [email protected]

HashiCorp Consul

Quick Start

Install the pack

st2 pack install consul

Configuration

The configuration for this pack is used to specify connection information for all Consul servers you'll be communicating with. The location for the config file is /opt/stackstorm/configs/consul.yaml. An example configuration located in the repo named consul.yaml.example can be copied to /opt/stackstorm/configs/consul.yaml and edited as required.

It should contain:

• default_profile - URL for the Vault server
• consul_profiles - Mapping of name to an object containing Consul profile settings
  • name - Name of the consul profile
  • host - Consul server IP/name. Default 127.0.0.1
  • port - Consul server port. Default 8500
  • token - Consul API token
  • scheme - Consul scheme to use. Default http
  • verify - Verify the SSL certificate for HTTPS requests. Default false (this option is ignored if ca_cert_path is supplied)
  • ca_cert_path - CA Certificate path. Defaults to empty string. When path is provided, SSL certificates are verified
  • client_cert_path - Client side certificates for HTTPS request
  • client_key_path - Client private key for HTTPS request
  • preserve_varenv - Enable preservation of environment variables. If disable, all CONSUL_* environment variables are deleted from the action execution
  • consistency - The consistency mode to use by default for all reads that support the consistency option

Note : When modifying the configuration in /opt/stackstorm/configs/ please remember to tell StackStorm to load these new values by running st2ctl reload --register-configs

Schema Examples

---
consul_profiles:
  -
    name: production
    ca_cert_path: /etc/ssl/certs/ca.pem
    client_cert_path: /etc/ssl/certs/client-cert.pem
    client_key_path: /etc/ssl/private/client-key.pem
    consistency: default
    host: 127.0.0.1
    port: 8500
    scheme: https
    token: 11111111-bbbb-aaaa-cccc-222222222222
    verify: true
    preserve_varenv: false
  -
    name: dev
    ca_cert_path: /etc/ssl/certs/dev-ca.pem
    client_cert_path: /etc/ssl/certs/dev-client-cert.pem
    client_key_path: /etc/ssl/private/dev-client-key.pem
    consistency: default
    host: 10.11.12.13
    port: 8500
    scheme: https
    token: 22222222-bbbb-aaaa-cccc-444444444444
    verify: false
    preserve_varenv: false
default_profile: production

Configuration

The following options are required to be configured for the pack to work correctly.

Option	Type	Required	Secret	Description
default_profile	string	True		The default consul profile to use in actions when none is given.
consul_profiles	array	True		Consul cluster profiles

Actions

The pack provides the following actions:

acl_clone

Clones the ACL token 'acl_id'.

Parameter	Type	Required	Secret	Description
acl_id	string	True	default	'acl_id' to clone.
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.

catalog_node

Returns all services provided by node.

Parameter	Type	Required	Secret	Description
node	string	True	default	Node to query in Consul
index	string	False	default	The current Consul index, suitable for making subsequent calls to wait for changes since this query was last run.
wait	string	False	default	The maximum duration to wait (e.g. '10s') to retrieve a given index.
consistency	string	False	default	Can be either 'default', 'consistent' or 'stale'.
dc	string	False	default	The datacenter to query for nodes.
token	string	False	True	An optional ACL token to apply to this request.
consul_profile	string	False	default	Consul profile to use to run the action.

acl_info

Returns the token information for 'acl_id'.

Parameter	Type	Required	Secret	Description
acl_id	string	True	default	Fetch information for 'acl_id'.
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.

catalog_service

Returns the nodes providing service in the dc datacenter.

Parameter	Type	Required	Secret	Description
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.
service	string	True	default	The service to query for nodes.
index	string	False	default	The current Consul index, suitable for making subsequent calls to wait for changes since this query was last run.
wait	string	False	default	The maximum duration to wait (e.g. '10s') to retrieve a given index.
tag	string	False	default	The list of nodes returned will be filtered by that tag
consistency	string	False	default	Can be either 'default', 'consistent' or 'stale'.
dc	string	False	default	The datacenter to query for nodes.
near	string	False	default	A node name to sort the resulting list in ascending order based on the estimated round trip time from that node.

acl_list

Lists all the active ACL tokens.

Parameter	Type	Required	Secret	Description
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.

agent_checks

Returns all the checks that are registered with the local agent.

Parameter	Type	Required	Secret	Description
consul_profile	string	False	default	Consul profile to use to run the action.

session_list

Returns a tuple of (index, sessions) of all active sessions in the datacenter.

Parameter	Type	Required	Secret	Description
index	array	False	default	The current Consul index.
wait	string	False	default	The maximum duration to wait (e.g. '10s') to retrieve a given index.
consistency	string	False	default	The consistency mode to use reads.
dc	string	False	default	The datacenter that this agent will communicate with.
consul_profile	string	False	default	Consul profile to use to run the action.

agent_services

Returns all the services that are registered with the local agent.

Parameter	Type	Required	Secret	Description
consul_profile	string	False	default	Consul profile to use to run the action.

agent_join

Instructs the agent to attempt to connect to a given address.

Parameter	Type	Required	Secret	Description
address	string	True	default	The ip to connect to.
wan	boolean	False	default	True: causes the agent to attempt to join using the WAN pool.
consul_profile	string	False	default	Consul profile to use to run the action.

service_deregister

Remove a service from the local agent.

Parameter	Type	Required	Secret	Description
service_id	string	False	default	The id of the service to be removed.
consul_profile	string	False	default	Consul profile to use to run the action.

session_renew

Extend the expiration by the TTL for sessions that have a TTL.

Parameter	Type	Required	Secret	Description
session_id	string	True	default	The session to renew.
dc	string	False	default	The datacenter that this agent will communicate with.
consul_profile	string	False	default	Consul profile to use to run the action.

event_fire

Send an event to Consul's gossip protocol.

Parameter	Type	Required	Secret	Description
name	string	True	default	Key to write in Consul
body	string	True	default	A Consul-opaque body to be delivered with the event. Small than 100 bytes!
node	string	False	default	A Regex which remote agents will filter against to determine if they should store the event.
service	string	False	default	A Regex which remote agents will filter against to determine if they should store the event.
tag	string	False	default	A Regex which remote agents will filter against to determine if they should store the event.
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.

health_checks

Returns the checks of a service

Parameter	Type	Required	Secret	Description
service	string	True	default	Name of the service to query in Consul.
index	integer	False	default	The current Consul index. Useful to check for changes since last query was run.
wait	string	False	default	Maximum duration to wait (e.g. '10s') to retrieve a given index.
dc	string	False	default	The datacenter of the node and defaults to this agents datacenter.
near	string	False	default	A node name to sort the resulting list in ascending order based on the estimated round trip time from that node.
token	string	False	True	An optional ACL token to apply to this request.
node_meta	object	False	default	An optional meta data used for filtering.
consul_profile	string	False	default	Consul profile to use to run the action.

acl_create

Creates a new ACL token.

Parameter	Type	Required	Secret	Description
name	string	True	default	Name of token
acl_type	string	True	default	Type of token
rules	string	False	default	HCL rules
consul_profile	string	False	default	Consul profile to use to run the action.
token	string	False	True	An ACL token to use instead of the agent token.
acl_id	string	False	default	Consul Policy ID to apply to the token

kv_put

Set value in Consul key/value store.

Parameter	Type	Required	Secret	Description
key	string	True	default	Key to write in Consul
value	string	True	default	Value of Key to write in Consul
cas	integer	False	default	An optional flag is used to turn the PUT into a Check-And-Set operation.
flags	integer	False	default	Optional unsigned value between 0 and 2^64-1.
acquire	string	False	default	An optional session_id to attempt the acquisition of a lock.
release	string	False	default	An optional session_id to attempt to release a lock.
token	string	False	True	An ACL token to use instead of the agent token.
dc	string	False	default	Optional datacenter that you wish to communicate with.
to_json	boolean	False	default	Serialise value to JSON before storing in consul k/v
consul_profile	string	False	default	Consul profile to use to run the action.

acl_destroy

Destroys the ACL token 'acl_id'

Parameter	Type	Required	Secret	Description
acl_id	string	True	default	Token to destroy
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.

acl_update

Updates the ACL token 'acl_id'.

Parameter	Type	Required	Secret	Description
name	string	True	default	Name of token
acl_type	string	True	default	Type of token
rules	string	False	default	HCL rules
consul_profile	string	False	default	Consul profile to use to run the action.
token	string	False	True	An ACL token to use instead of the agent token.
acl_id	string	True	default	Consul Policy ID to update.

agent_maintenance

Place the agent into 'maintenance mode'.

Parameter	Type	Required	Secret	Description
enable	boolean	False	default	True: enables maintenance mode. False: disables maintenance mode.
reason	string	False	default	An optional string to aid human operators.
consul_profile	string	False	default	Consul profile to use to run the action.

session_node

Returns a tuple of (index, session) but filters the sessions returned to only those active for a node.

Parameter	Type	Required	Secret	Description
node	string	True	default	The node to use in the filter when listing active sessions.
index	array	False	default	The current Consul index.
wait	string	False	default	The maximum duration to wait (e.g. '10s') to retrieve a given index.
consistency	string	False	default	The consistency mode to use reads.
dc	string	False	default	The datacenter that this agent will communicate with.
consul_profile	string	False	default	Consul profile to use to run the action.

service_maintenance

Put a given service into maintenance mode.

Parameter	Type	Required	Secret	Description
service_id	string	True	default	The id of the service to be removed.
enable	boolean	True	default	True: enable maintenance mode. False; disable maintenance mode.
reason	string	False	default	An optional string to aid human operators.
consul_profile	string	False	default	Consul profile to use to run the action.

kv_list

List values from Consul server

Parameter	Type	Required	Secret	Description
key	string	True	default	Root Key for listing from Consul
recurse	boolean	False	default	Do a recursive retrieval?
keys	boolean	False	default	Return a list of keys only
consul_profile	string	False	default	Consul profile to use to run the action.

catalog_datacenters

Real-time query of all known datacenters in Consul

Parameter	Type	Required	Secret	Description
consul_profile	string	False	default	Consul profile to use to run the action.

catalog_deregister

Deregister an external service in Consul

Parameter	Type	Required	Secret	Description
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.
node	string	True	default	Node Name/ID
service	string	False	default	Service Name/ID
check_id	string	False	default	Check Name/ID
dc	string	default	default	Optional Data Center ID

agent_members

Returns all the members that this agent currently sees.

Parameter	Type	Required	Secret	Description
wan	boolean	False	default	Returns the list of WAN members instead of the LAN members.
consul_profile	string	False	default	Consul profile to use to run the action.

service_register

Add a new service to the local agent.

Parameter	Type	Required	Secret	Description
name	string	True	default	The name of the service.
service_id	string	False	default	The id of the service
address	string	False	default	IP address. Defaults to the address of the agent.
port	string	False	default	Port.
tags	array	False	default	Tags.
check	object	False	default	An optional health check can be created for this service.
token	string	False	True	An optional ACL token to apply to this request.
enable_tag_override	boolean	False	default	An optional bool that enable you to modify a service tags from servers(consul agent role server)
consul_profile	string	False	default	Consul profile to use to run the action.

session_destroy

Destroy an existing session.

Parameter	Type	Required	Secret	Description
session_id	string	True	default	The session id to be destoryed.
dc	integer	False	default	dc is the datacenter that this agent will communicate with.
consul_profile	string	False	default	Consul profile to use to run the action.

test_pack_actions

Test all actions in the consul pack.

Parameter	Type	Required	Secret	Description
consul_profile	string	False	default	Consul profile to use to run the action.

session_info

Returns a tuple of (index, session) for the session in the dc datacenter.

Parameter	Type	Required	Secret	Description
session_id	string	True	default	Search for the session which has the id in the datacenter.
index	array	False	default	The current Consul index.
wait	string	False	default	The maximum duration to wait (e.g. '10s') to retrieve a given index.
consistency	string	False	default	The consistency mode to use reads.
dc	string	False	default	The datacenter that this agent will communicate with.
consul_profile	string	False	default	Consul profile to use to run the action.

agent_force_leave

Instructs the agent to force a node into the left state.

Parameter	Type	Required	Secret	Description
node	string	True	default	The node to change state for.
consul_profile	string	False	default	Consul profile to use to run the action.

event_list

Fetch events from Consul agent's buffer.

Parameter	Type	Required	Secret	Description
name	string	True	default	The type of events to list. An empty string, lists all available.
index	integer	False	default	The current event Consul index
wait	string	False	default	The maximum duration to wait (e.g. '10s') to retrieve a given index.
consul_profile	string	False	default	Consul profile to use to run the action.

session_create

Create a new session.

Parameter	Type	Required	Secret	Description
name	string	False	default	An optional human readable name for the session.
node	string	False	default	The node to create the session on
checks	array	False	default	A list of checks to associate with the session.
lock_delay	integer	False	default	An integer of seconds.
behavior	string	False	default	This controls the behavior when a session is invalidated.
ttl	integer	False	default	Invalidate the session if it is not renewed before the TTL expires.
dc	string	False	default	The datacenter that this agent will communicate with.
consul_profile	string	False	default	Consul profile to use to run the action.

kv_delete

Deletes a single key or if recurse is True, all keys sharing a prefix.

Parameter	Type	Required	Secret	Description
key	string	True	default	Key to Delete from Consul
recurse	boolean	False	default	Recursively delete keys?
cas	integer	False	default	An optional flag is used to turn the DELETE into a Check-And-Set operation.
dc	string	False	default	Optional datacenter that you wish to communicate with.
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.

health_state

Returns the checks in a given state

Parameter	Type	Required	Secret	Description
name	string	True	default	Name of the supported state (any, unknown, passing, warning, critical).
index	integer	False	default	The current Consul index. Useful to check for changes since last query was run.
wait	string	False	default	Maximum duration to wait (e.g. '10s') to retrieve a given index.
dc	string	False	default	The datacenter of the node and defaults to this agents datacenter.
near	string	False	default	A node name to sort the resulting list in ascending order based on the estimated round trip time from that node.
token	string	False	True	An optional ACL token to apply to this request.
node_meta	object	False	default	An optional meta data used for filtering.
consul_profile	string	False	default	Consul profile to use to run the action.

catalog_services

Returns all services known about in the dc datacenter.

Parameter	Type	Required	Secret	Description
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.
index	integer	False	default	The current Consul index. Used to check for changes since last query was run.
wait	string	False	default	Maximum duration to wait (e.g. '10s') to retrieve a given index.
consistency	string	False	default	Consul supports 3 different consistency modes for reads. Read Consul's documentation for details.
dc	string	False	default	The datacenter that this agent will communicate with.
node_meta	object	False	default	An optional meta data used for filtering.

custom_lock

Create a lock or semaphore. Used for synchronising discret workflows.

Parameter	Type	Required	Secret	Description
key_prefix	string	True	default	KV path to prefix to lock name.
max_locks	integer	False	default	Maximum number of concurrent holders for the lock.
acquire_timeout	integer	False	default	Number of seconds to wait for the lock to be acquired.
name	string	False	default	The name of the lock.
node	string	False	default	The node that will establish and maintain the lock.
checks	array	False	default	A list of the health checks used to determine if the lock should be invalidated.
behavior	string	False	default	The behavior to use when the lock expires (release or delete).
ttl	integer	False	default	Time to Live before the lock expires (between 10 and 86400 seconds).
token	string	False	True	An optional ACL token to apply to this request.
dc	string	False	default	Optional datacenter that you wish to communicate with.
consul_profile	string	False	default	Consul profile to use to run the action.

custom_unlock

Release a lock or semaphore. Used for synchronising discret workflows.

Parameter	Type	Required	Secret	Description
session_id	string	True	default	The session id that currently holds the lock on the key.
key_prefix	string	True	default	KV path to prefix to lock name.
name	string	True	default	The name of the lock.
node	string	False	default	The node that will establish and maintain the lock.
token	string	False	default	An optional ACL token to apply to this request.
dc	string	False	default	Optional datacenter that you wish to communicate with.
consul_profile	string	False	default	Consul profile to use to run the action.

kv_get

Get value from Consul key/value store

Parameter	Type	Required	Secret	Description
key	string	True	default	Key to retrieve from Consul
index	integer	False	default	The current Consul index, suitable to wait for changes since this query was last run.
recurse	boolean	False	default	Do a recursive retrieval?
wait	string	False	default	The maximum duration to wait (e.g. '10s') to retrieve a given index.
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.
consistency	string	False	default	Can be either default, consistent or stale
keys	boolean	False	default	Return a list of keys only
separator	string	False	default	Can be used with keys to list keys only up to a given separator character.
dc	string	False	default	Optionally the datacenter to communicate with.
from_json	boolean	False	default	Deserialise retrieved keys as JSON.

health_service

Returns the nodes and health info of a service

Parameter	Type	Required	Secret	Description
service	string	True	default	Name of the service to query in Consul.
index	integer	False	default	The current Consul index. Useful to check for changes since last query was run.
wait	string	False	default	Maximum duration to wait (e.g. '10s') to retrieve a given index.
passing	string	False	default	Set to True will filter results to only those nodes whose checks are currently passing.
tag	string	False	default	Filter the results by tag.
dc	string	False	default	The datacenter of the node and defaults to this agents datacenter.
near	string	False	default	A node name to sort the resulting list in ascending order based on the estimated round trip time from that node.
token	string	False	True	An ACL token to use instead of the agent token.
node_meta	object	False	default	An optional meta data used for filtering.
consul_profile	string	False	default	Consul profile to use to run the action.

health_node

Returns the health info of a node

Parameter	Type	Required	Secret	Description
node	string	True	default	The node providing the given service.
index	integer	False	default	The current Consul index. Useful to check for changes since last query was run.
wait	string	False	default	Maximum duration to wait (e.g. '10s') to retrieve a given index.
dc	string	False	default	The datacenter of the node and defaults to this agents datacenter.
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.

catalog_register

Register an external service in Consul

Parameter	Type	Required	Secret	Description
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.
node	string	True	default	Node Name/ID
address	string	True	default	IP Address of the service
service	object	False	default	An option service Service Name/ID
check	object	False	default	An optional check to register.
dc	string	False	default	Optional Data Center ID

catalog_nodes

Return all nodes known about in the dc datacenter.

Parameter	Type	Required	Secret	Description
token	string	False	True	An ACL token to use instead of the agent token.
consul_profile	string	False	default	Consul profile to use to run the action.
index	string	False	default	The current Consul index, suitable for making subsequent calls to wait for changes since this query was last run.
wait	string	False	default	The maximum duration to wait (e.g. '10s') to retrieve a given index.
consistency	string	False	default	Can be either 'default', 'consistent' or 'stale'.
dc	string	False	default	The datacenter to query for nodes.
near	string	False	default	A node name to sort the resulting list in ascending order based on the estimated round trip time from that node.
node_meta	object	False	default	An optional meta data used for filtering.

Sensors

There are no sensors available for this pack.

_{Documentation generated using pack2md}