consul
: Installs, configures and manages consul
consul::config
: This class is called from consul::init to install the config file.consul::install
: Installs consul based on the parameters from initconsul::params
: == Class consul::params This class is meant to be called from consul It sets variables according to platformconsul::reload_service
: This class is meant to be called from certain configuration changes that support reload.consul::run_service
: This class is meant to be called from consul. It ensures the service is runningconsul::windows_service
: Installs consul windows server
consul::check
: Sets up a Consul healthcheckconsul::service
: Sets up a Consul service definitionconsul::watch
: Sets up Consul watch, to span commands when data changes.
consul_acl
: Manage a consul token and its ACLs.consul_key_value
: Manage a consul key value object.consul_policy
: Manages a Consul ACL policyconsul_prepared_query
: Manage a consul prepared query.consul_token
: Manages a v2 Consul token
Installs, configures and manages consul
class { 'consul':
config_hash => {
'datacenter' => 'east-aws',
'node_name' => $facts['fqdn'],
'pretty_config => true,
'retry-join' => ['172.16.0.1'],
},
}
The following parameters are available in the consul
class:
acls
tokens
policies
acl_api_hostname
acl_api_protocol
acl_api_port
acl_api_tries
acl_api_token
arch
archive_path
bin_dir
binary_group
binary_mode
binary_name
binary_owner
checks
config_defaults
config_dir
config_name
config_hash
config_mode
config_owner
data_dir_mode
docker_image
download_extension
download_url
download_url_base
extra_groups
extra_options
group
init_style
install_method
join_wan
manage_group
manage_repo
manage_service
manage_user
manage_user_home_location
manage_data_dir
os
package_ensure
package_name
pretty_config
pretty_config_indent
proxy_server
purge_config_dir
restart_on_change
service_enable
service_ensure
services
user
version
watches
shell
enable_beta_ui
allow_binding_to_root_ports
log_file
comment
uid
gid
Data type: Hash
Hash of consul_acl resources to create.
Default value: {}
Data type: Hash[String[1], Consul::TokenStruct]
Hash of consul_token resources to create.
Default value: {}
Data type: Hash[String[1], Consul::PolicyStruct]
Hash of consul_policy resources to create.
Default value: {}
Data type: String[1]
Global hostname of ACL API, will be merged with consul_token resources
Default value: 'localhost'
Data type: String[1]
Global protocl of ACL API, will be merged with consul_token resources
Default value: 'http'
Data type: Integer[1, 65535]
Global port of ACL API, will be merged with consul_token resources
Default value: 8500
Data type: Integer[1]
Global max. tries of ACL API, will be merged with consul_token resources
Default value: 3
Data type: String[0]
Global token of ACL API, will be merged with consul_token resources
Default value: ''
Data type: String[1]
Architecture of consul binary to download
Default value: $consul::params::arch
Data type: Optional[Stdlib::Absolutepath]
Path used when installing consul via the url
Default value: undef
Data type: Stdlib::Absolutepath
Directory to create the symlink to the consul binary in.
Default value: $consul::params::bin_dir
Data type: Optional[String[1]]
The group that the file belongs to.
Default value: $consul::params::binary_group
Data type: String[1]
Permissions mode for the file.
Default value: $consul::params::binary_mode
Data type: String[1]
The binary name file.
Default value: $consul::params::binary_name
Data type: String[1]
The user that owns the file.
Default value: $consul::params::binary_owner
Data type: Hash
Hash of consul::check resources to create.
Default value: {}
Data type: Hash
Configuration defaults hash. Gets merged with config_hash.
Default value: $consul::params::config_defaults
Data type: Stdlib::Absolutepath
Directory to place consul configuration files in.
Default value: $consul::params::config_dir
Data type: String[1]
Name of the consul configuration file.
Default value: 'config.json'
Data type: Variant[Hash,Sensitive[Hash]]
Use this to populate the JSON config file for consul.
Default value: {}
Data type: String[1]
Use this to set the JSON config file mode for consul.
Default value: '0664'
Data type: Optional[String[1]]
The user that owns the config_dir directory and its files.
Default value: undef
Data type: String[1]
Use this to set the data_dir directory mode for consul.
Default value: $consul::params::data_dir_mode
Data type: String[1]
Only valid when the install_method == docker. Defaults to consul
.
Default value: 'consul'
Data type: String[1]
The extension of the archive file containing the consul binary to download.
Default value: 'zip'
Data type: Optional[Stdlib::Filesource]
Fully qualified url, puppet uri or absolute path to the location of the archive file containing the consul binary.
Default value: undef
Data type: String[1]
Base url to the location of the archive file containing the consul binary.
Default value: 'https://releases.hashicorp.com/consul/'
Data type: Array
Extra groups to add the consul system user to.
Default value: []
Data type: Optional[String[1]]
Extra arguments to be passed to the consul agent
Default value: undef
Data type: String[1]
Name of the group that should own the consul configuration files.
Default value: $consul::params::group
Data type: String[1]
What style of init system your system uses. Set to 'unmanaged' to disable managing init system files for the consul service entirely. This is ignored when install_method == 'docker'
Default value: $consul::params::init_style
Data type: String[1]
Valid strings: docker
- install via docker container
package
- install via system package
url
- download and extract from a url. Defaults to url
.
none
- disable install.
Default value: 'url'
Data type: Optional[String[1]]
The wan to join on service start (e.g. 'wan.foo.com'). Defaults to undef (i.e. won't join a wan).
Default value: undef
Data type: Boolean
Whether to create/manage the group that should own the consul configuration files.
Default value: $consul::params::manage_group
Data type: Boolean
Configure the upstream HashiCorp repository. Only relevant when $consul::install_method = 'package'.
Default value: false
Data type: Boolean
Whether to manage the consul service.
Default value: true
Data type: Boolean
Whether to create/manage the user that should own consul's configuration files.
Default value: $consul::params::manage_user
Data type: Boolean
Whether to explicitly set the location of the consul user's home directory when this modules
manages the creation of the user (aka manage_user = true
). If the consul user already exists
and this is enabled, puppet tries to change the consul user's home to the new location. This
will cause the puppet run to fail if the consul service is currently running.
Default value: false
Data type: Boolean
Whether to manage the consul storage data directory.
Default value: true
Data type: String[1]
OS component in the name of the archive file containing the consul binary.
Default value: $facts['kernel'].downcase
Data type: String[1]
Only valid when the install_method == package. Defaults to latest
.
Default value: 'latest'
Data type: String[1]
Only valid when the install_method == package. Defaults to consul
.
Default value: 'consul'
Data type: Boolean
Generates a human readable JSON config file. Defaults to false
.
Default value: false
Data type: Integer
Toggle indentation for human readable JSON file. Defaults to 4
.
Default value: 4
Data type: Optional[Stdlib::HTTPUrl]
Specify a proxy server, with port number if needed. ie: https://example.com:8080.
Default value: undef
Data type: Boolean
Purge config files no longer generated by Puppet
Default value: true
Data type: Boolean
Determines whether to restart consul agent on $config_hash changes. This will not affect reloads when service, check or watch configs change.
Default value: true
Data type: Boolean
Whether to enable the consul service to start at boot.
Default value: true
Data type: Enum['stopped', 'running']
Whether the consul service should be running or not.
Default value: 'running'
Data type: Hash
Hash of consul::service resources to create.
Default value: {}
Data type: String[1]
Name of the user that should own the consul configuration files.
Default value: $consul::params::user
Data type: String[1]
Specify version of consul binary to download.
Default value: '1.20.0'
Data type: Hash
Hash of consul::watch resources to create.
Default value: {}
Data type: Optional[String[1]]
The shell for the consul user. Defaults to something that prohibits login, like /usr/sbin/nologin
Default value: $consul::params::shell
Data type: Boolean
consul 1.1.0 introduced a new UI, which is currently (2018-05-12) in beta status. You can enable it by setting this variable to true. Defaults to false
Default value: false
Data type: Boolean
enables CAP_NET_BIND_SERVICE if true. This is currently only implemented on systemd nodes
Default value: false
Data type: Stdlib::Absolutepath
where should the log file be located
Default value: '/var/log/consul'
Data type: Optional[String[1]]
the comment for the consul user, will be added to /etc/passwd
Default value: undef
Data type: Optional[Integer[1]]
the ID for the consul user
Default value: undef
Data type: Optional[Integer[1]]
the ID for the consul group
Default value: undef
Sets up a Consul healthcheck
The following parameters are available in the consul::check
defined type:
ensure
http
id
interval
notes
script
args
service_id
status
tcp
grpc
timeout
token
ttl
success_before_passing
failures_before_critical
Data type: Enum['absent', 'present']
Define availability of check. Use 'absent' to remove existing checks
Default value: present
Data type: Optional
HTTP endpoint for the service healthcheck
Default value: undef
Data type: String[1]
The id for the check (defaults to $title)
Default value: $title
Data type: Optional
Value in seconds for the interval between runs of the check
Default value: undef
Data type: Optional
Human readable description of the check
Default value: undef
Data type: Optional
Full path to the location of the healthcheck script. Must be nagios compliant with regards to the return codes. This parameter is deprecated in Consul 1.0.0, see hashicorp/consul#3509.
Default value: undef
Data type: Optional
Arguments to be exec
ed for the healthcheck script.
Default value: undef
Data type: Optional
An optional service_id to match this check against
Default value: undef
Data type: Optional
The default state of the check when it is registered against a consul agent. Should be either "critical" or "passing"
Default value: undef
Data type: Optional
The IP/hostname and port for the service healthcheck. Should be in 'hostname:port' format.
Default value: undef
Data type: Optional
GRPC endpoint for the service healthcheck
Default value: undef
Data type: Optional
A timeout value for HTTP request only
Default value: undef
Data type: Optional
ACL token for interacting with the catalog (must be 'management' type)
Default value: undef
Data type: Optional
Value in seconds before the http endpoint considers a failing healthcheck to be "HARD" down.
Default value: undef
Data type: Optional
Value may be set to become check passing only after a specified number of consecutive checks return passing
Default value: undef
Data type: Optional
Value may be set to become check critical only after a specified number of consecutive checks return critical
Default value: undef
Sets up a Consul service definition
consul::service { 'my_db':
port => 3306,
tags => ['db','mysql'],
address => '1.2.3.4',
token => 'xxxxxxxxxx',
service_config_hash => {
'connect' => {
'sidecar_service' => {},
},
},
checks => [
{
name => 'MySQL Port',
tcp => 'localhost:3306',
interval => '10s',
},
],
}
consul::service { 'my_https_app':
port => 443,
tags => ['web','rails'],
address => '1.2.3.5',
token => 'xxxxxxxxxx',
service_config_hash => {
'connect' => {
'sidecar_service' => {},
},
},
checks => [
{
name => 'HTTPS Request',
http => 'https://localhost:443',
tls_skip_verify => true,
method => "GET",
headers => { "Host" => ["test.example.com"] },
},
],
}
The following parameters are available in the consul::service
defined type:
Data type: Optional[String[1]]
IP address the service is running at.
Default value: undef
Data type: Array[Hash]
If provided an array of checks that will be added to this service
Default value: []
Data type: Boolean
enable_tag_override support for service. Defaults to False.
Default value: false
Data type: String[1]
Define availability of service. Use 'absent' to remove existing services. Defaults to 'present'
Default value: 'present'
Data type: String[1]
The unique ID of the service on the node. Defaults to title.
Default value: $title
Data type: Optional[Integer[0, 65535]]
TCP port the service runs on.
Default value: undef
Data type: String[1]
Name of the service. Defaults to title.
Default value: $title
Data type: Hash
Use this to populate the basic service params for each of the services
Default value: {}
Data type: Array[String[1]]
Array of strings.
Default value: []
Data type: Optional[String[1]]
ACL token for interacting with the catalog (must be 'management' type)
Default value: undef
Data type:
Optional[Hash[
String[1],
Variant[
String[1],
Numeric,
Boolean,
]]]
Service meta key/value pairs as hash.
Default value: undef
Sets up Consul watch, to span commands when data changes.
The following parameters are available in the consul::watch
defined type:
datacenter
ensure
event_name
handler
args
key
keyprefix
passingonly
service
service_tag
state
token
type
Data type: Optional
String overriding consul's default datacenter.
Default value: undef
Data type: Enum['present', 'absent']
Define availability of watch. Use 'absent' to remove existing watches.
Default value: present
Data type: Optional
Name of an event to watch for.
Default value: undef
Data type: Optional
Full path to the script that will be excuted. This parameter is deprecated in Consul 1.0.0
Default value: undef
Data type: Optional
Arguments to be exec
ed for the watch.
Default value: undef
Data type: Optional
Watch a specific key.
Default value: undef
Data type: Optional
Watch a whole keyprefix
Default value: undef
Data type: Optional[Boolean]
Watch only those services that are passing healthchecks.
Default value: undef
Data type: Optional
Watch a particular service
Default value: undef
Data type: Optional
This actually maps to the "tag" param for service watches. (tag
is a puppet builtin metaparameter)
Default value: undef
Data type: Optional
Watch a state change on a service healthcheck.
Default value: undef
Data type: Optional
String to override the default token.
Default value: undef
Data type: Optional
Type of data to watch. (Like key, service, services, nodes)
Default value: undef
Manage a consul token and its ACLs.
The following properties are available in the consul_acl
type.
Valid values: present
, absent
The basic property that the resource should be in.
Default value: present
ID of token
Valid values: http
, https
consul protocol
Default value: http
hash of ACL rules for this token
Valid values: client
, management
Type of token
Default value: client
The following parameters are available in the consul_acl
type.
Token for accessing the ACL API
Default value: anonymous
number of tries when contacting the Consul REST API
Default value: 3
consul hostname
Default value: localhost
namevar
Name of the token
consul port
Default value: 8500
The specific backend to use for this consul_acl
resource. You will seldom need to specify this --- Puppet will usually
discover the appropriate provider for your platform.
Manage a consul key value object.
The following properties are available in the consul_key_value
type.
Valid values: present
, absent
The basic property that the resource should be in.
Default value: present
The key value string
The following parameters are available in the consul_key_value
type.
Token for accessing the ACL API
Default value: anonymous
number of tries when contacting the Consul REST API
Default value: 3
Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.
Default value: ''
Flags integer
Default value: 0
consul hostname
Default value: localhost
namevar
Name of the key/value object
consul port
Default value: 8500
Valid values: http
, https
consul protocol
Default value: http
The specific backend to use for this consul_key_value
resource. You will seldom need to specify this --- Puppet will
usually discover the appropriate provider for your platform.
Manages a Consul ACL policy
The following properties are available in the consul_policy
type.
List of datacenter names assigned to the policy
Default value: []
Description of the policy
Valid values: present
, absent
The basic property that the resource should be in.
Default value: present
ID of already existing policy
Default value: ''
List of ACL rules for this policy
Default value: []
The following parameters are available in the consul_policy
type.
Token for accessing the ACL API
Default value: ''
number of tries when contacting the Consul REST API
Default value: 3
consul hostname
Default value: localhost
namevar
Name of the policy
consul port
Default value: 8500
Valid values: http
, https
consul protocol
Default value: http
The specific backend to use for this consul_policy
resource. You will seldom need to specify this --- Puppet will
usually discover the appropriate provider for your platform.
Manage a consul prepared query.
The following properties are available in the consul_prepared_query
type.
Valid values: present
, absent
The basic property that the resource should be in.
Default value: present
ID of prepared query
The following parameters are available in the consul_prepared_query
type.
acl_api_token
api_tries
hostname
name
node_meta
port
protocol
provider
service_failover_dcs
service_failover_n
service_meta
service_name
service_near
service_only_passing
service_tags
template
template_regexp
template_type
token
ttl
Token for accessing the ACL API
Default value: anonymous
number of tries when contacting the Consul REST API
Default value: 3
consul hostname
Default value: localhost
namevar
Name of the prepared query
List of user-defined key/value pairs to filter on NodeMeta
consul port
Default value: 8500
Valid values: http
, https
consul protocol
Default value: http
The specific backend to use for this consul_prepared_query
resource. You will seldom need to specify this --- Puppet
will usually discover the appropriate provider for your platform.
List of datacenters to forward queries to if no health services found locally
Default value: []
Failover to the nearest datacenters
Default value: 0
List of user-defined key/value pairs to filter on ServiceMeta
Service name for the prepared query
Resurn results in ascending order of estimated RTT from given node name, or _agent special value
Default value: ''
Only return services in the passing state
Default value: false
List of tags to filter the query with
Default value: []
Valid values: true
, false
, yes
, no
is template?
Default value: false
regexp for template
Default value: ''
type for template
Default value: name_prefix_match
The prepared query token
Default value: ''
TTL for the DNS lookup
Default value: 0
Manages a v2 Consul token
The following properties are available in the consul_token
type.
Accessor ID of the token
Description of the token
Valid values: present
, absent
The basic property that the resource should be in.
Default value: present
List of policy IDs assigned to the token
Default value: []
List of policy names assigned to the token
Default value: []
Secret ID of the token
Default value: ''
The following parameters are available in the consul_token
type.
Token for accessing the ACL API
Default value: ''
number of tries when contacting the Consul REST API
Default value: 3
consul hostname
Default value: localhost
namevar
Name of the token
consul port
Default value: 8500
Valid values: http
, https
consul protocol
Default value: http
The specific backend to use for this consul_token
resource. You will seldom need to specify this --- Puppet will
usually discover the appropriate provider for your platform.
Type: Ruby 4.x API
The consul::sorted_json function.
consul::sorted_json(Optional[Any] $unsorted_hash = {}, Optional[Any] $pretty = false, Optional[Any] $indent_len = 4)
The consul::sorted_json function.
Returns: Any
Data type: Optional[Any]
Data type: Optional[Any]
Data type: Optional[Any]
Type: Ruby 4.x API
The consul::validate_checks function.
The consul::validate_checks function.
Returns: Any
Data type: HashOrArray
The Consul::PolicyStruct data type.
Alias of
Struct[{
id => Optional[String[1]],
ensure => Optional[Enum['present', 'absent']],
description => Optional[String[0]],
datacenters => Optional[Array[String[1]]],
rules => Optional[Array[Struct[{
resource => String[1],
segment => Optional[String[0]],
disposition => String[1],
}]]],
acl_api_token => Optional[String[1]],
protocol => Optional[String[1]],
port => Optional[Integer[1, 65535]],
hostname => Optional[String[1]],
api_tries => Optional[Integer[1]],
}]
The Consul::TokenStruct data type.
Alias of
Struct[{
description => Optional[String[0]],
accessor_id => String[1],
ensure => Optional[Enum['present', 'absent']],
secret_id => Optional[String[1]],
policies_by_name => Optional[Array[String]],
policies_by_id => Optional[Array[String]],
acl_api_token => Optional[String[1]],
protocol => Optional[String[1]],
port => Optional[Integer[1, 65535]],
hostname => Optional[String[1]],
api_tries => Optional[Integer[1]],
}]