Skip to content

Latest commit

 

History

History
1711 lines (983 loc) · 39.1 KB

REFERENCE.md

File metadata and controls

1711 lines (983 loc) · 39.1 KB

Reference

Table of Contents

Classes

Public Classes

  • consul: Installs, configures and manages consul

Private Classes

  • consul::config: This class is called from consul::init to install the config file.
  • consul::install: Installs consul based on the parameters from init
  • consul::params: == Class consul::params This class is meant to be called from consul It sets variables according to platform
  • consul::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 running
  • consul::windows_service: Installs consul windows server

Defined types

Resource types

Functions

Data types

Classes

consul

Installs, configures and manages consul

Examples

simple consul setup
class { 'consul':
  config_hash => {
    'datacenter'   => 'east-aws',
    'node_name'    => $facts['fqdn'],
    'pretty_config => true,
    'retry-join'   => ['172.16.0.1'],
  },
}

Parameters

The following parameters are available in the consul class:

acls

Data type: Hash

Hash of consul_acl resources to create.

Default value: {}

tokens

Data type: Hash[String[1], Consul::TokenStruct]

Hash of consul_token resources to create.

Default value: {}

policies

Data type: Hash[String[1], Consul::PolicyStruct]

Hash of consul_policy resources to create.

Default value: {}

acl_api_hostname

Data type: String[1]

Global hostname of ACL API, will be merged with consul_token resources

Default value: 'localhost'

acl_api_protocol

Data type: String[1]

Global protocl of ACL API, will be merged with consul_token resources

Default value: 'http'

acl_api_port

Data type: Integer[1, 65535]

Global port of ACL API, will be merged with consul_token resources

Default value: 8500

acl_api_tries

Data type: Integer[1]

Global max. tries of ACL API, will be merged with consul_token resources

Default value: 3

acl_api_token

Data type: String[0]

Global token of ACL API, will be merged with consul_token resources

Default value: ''

arch

Data type: String[1]

Architecture of consul binary to download

Default value: $consul::params::arch

archive_path

Data type: Optional[Stdlib::Absolutepath]

Path used when installing consul via the url

Default value: undef

bin_dir

Data type: Stdlib::Absolutepath

Directory to create the symlink to the consul binary in.

Default value: $consul::params::bin_dir

binary_group

Data type: Optional[String[1]]

The group that the file belongs to.

Default value: $consul::params::binary_group

binary_mode

Data type: String[1]

Permissions mode for the file.

Default value: $consul::params::binary_mode

binary_name

Data type: String[1]

The binary name file.

Default value: $consul::params::binary_name

binary_owner

Data type: String[1]

The user that owns the file.

Default value: $consul::params::binary_owner

checks

Data type: Hash

Hash of consul::check resources to create.

Default value: {}

config_defaults

Data type: Hash

Configuration defaults hash. Gets merged with config_hash.

Default value: $consul::params::config_defaults

config_dir

Data type: Stdlib::Absolutepath

Directory to place consul configuration files in.

Default value: $consul::params::config_dir

config_name

Data type: String[1]

Name of the consul configuration file.

Default value: 'config.json'

config_hash

Data type: Variant[Hash,Sensitive[Hash]]

Use this to populate the JSON config file for consul.

Default value: {}

config_mode

Data type: String[1]

Use this to set the JSON config file mode for consul.

Default value: '0664'

config_owner

Data type: Optional[String[1]]

The user that owns the config_dir directory and its files.

Default value: undef

data_dir_mode

Data type: String[1]

Use this to set the data_dir directory mode for consul.

Default value: $consul::params::data_dir_mode

docker_image

Data type: String[1]

Only valid when the install_method == docker. Defaults to consul.

Default value: 'consul'

download_extension

Data type: String[1]

The extension of the archive file containing the consul binary to download.

Default value: 'zip'

download_url

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

download_url_base

Data type: String[1]

Base url to the location of the archive file containing the consul binary.

Default value: 'https://releases.hashicorp.com/consul/'

extra_groups

Data type: Array

Extra groups to add the consul system user to.

Default value: []

extra_options

Data type: Optional[String[1]]

Extra arguments to be passed to the consul agent

Default value: undef

group

Data type: String[1]

Name of the group that should own the consul configuration files.

Default value: $consul::params::group

init_style

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

install_method

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'

join_wan

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

manage_group

Data type: Boolean

Whether to create/manage the group that should own the consul configuration files.

Default value: $consul::params::manage_group

manage_repo

Data type: Boolean

Configure the upstream HashiCorp repository. Only relevant when $consul::install_method = 'package'.

Default value: false

manage_service

Data type: Boolean

Whether to manage the consul service.

Default value: true

manage_user

Data type: Boolean

Whether to create/manage the user that should own consul's configuration files.

Default value: $consul::params::manage_user

manage_user_home_location

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

manage_data_dir

Data type: Boolean

Whether to manage the consul storage data directory.

Default value: true

os

Data type: String[1]

OS component in the name of the archive file containing the consul binary.

Default value: $facts['kernel'].downcase

package_ensure

Data type: String[1]

Only valid when the install_method == package. Defaults to latest.

Default value: 'latest'

package_name

Data type: String[1]

Only valid when the install_method == package. Defaults to consul.

Default value: 'consul'

pretty_config

Data type: Boolean

Generates a human readable JSON config file. Defaults to false.

Default value: false

pretty_config_indent

Data type: Integer

Toggle indentation for human readable JSON file. Defaults to 4.

Default value: 4

proxy_server

Data type: Optional[Stdlib::HTTPUrl]

Specify a proxy server, with port number if needed. ie: https://example.com:8080.

Default value: undef

purge_config_dir

Data type: Boolean

Purge config files no longer generated by Puppet

Default value: true

restart_on_change

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

service_enable

Data type: Boolean

Whether to enable the consul service to start at boot.

Default value: true

service_ensure

Data type: Enum['stopped', 'running']

Whether the consul service should be running or not.

Default value: 'running'

services

Data type: Hash

Hash of consul::service resources to create.

Default value: {}

user

Data type: String[1]

Name of the user that should own the consul configuration files.

Default value: $consul::params::user

version

Data type: String[1]

Specify version of consul binary to download.

Default value: '1.20.0'

watches

Data type: Hash

Hash of consul::watch resources to create.

Default value: {}

shell

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

enable_beta_ui

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

allow_binding_to_root_ports

Data type: Boolean

enables CAP_NET_BIND_SERVICE if true. This is currently only implemented on systemd nodes

Default value: false

log_file

Data type: Stdlib::Absolutepath

where should the log file be located

Default value: '/var/log/consul'

comment

Data type: Optional[String[1]]

the comment for the consul user, will be added to /etc/passwd

Default value: undef

uid

Data type: Optional[Integer[1]]

the ID for the consul user

Default value: undef

gid

Data type: Optional[Integer[1]]

the ID for the consul group

Default value: undef

Defined types

consul::check

Sets up a Consul healthcheck

Parameters

The following parameters are available in the consul::check defined type:

ensure

Data type: Enum['absent', 'present']

Define availability of check. Use 'absent' to remove existing checks

Default value: present

http

Data type: Optional

HTTP endpoint for the service healthcheck

Default value: undef

id

Data type: String[1]

The id for the check (defaults to $title)

Default value: $title

interval

Data type: Optional

Value in seconds for the interval between runs of the check

Default value: undef

notes

Data type: Optional

Human readable description of the check

Default value: undef

script

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

args

Data type: Optional

Arguments to be execed for the healthcheck script.

Default value: undef

service_id

Data type: Optional

An optional service_id to match this check against

Default value: undef

status

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

tcp

Data type: Optional

The IP/hostname and port for the service healthcheck. Should be in 'hostname:port' format.

Default value: undef

grpc

Data type: Optional

GRPC endpoint for the service healthcheck

Default value: undef

timeout

Data type: Optional

A timeout value for HTTP request only

Default value: undef

token

Data type: Optional

ACL token for interacting with the catalog (must be 'management' type)

Default value: undef

ttl

Data type: Optional

Value in seconds before the http endpoint considers a failing healthcheck to be "HARD" down.

Default value: undef

success_before_passing

Data type: Optional

Value may be set to become check passing only after a specified number of consecutive checks return passing

Default value: undef

failures_before_critical

Data type: Optional

Value may be set to become check critical only after a specified number of consecutive checks return critical

Default value: undef

consul::service

Sets up a Consul service definition

Examples

simple MySQL service
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',
    },
  ],
}
simple HTTPS service
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"] },
    },
  ],
}

Parameters

The following parameters are available in the consul::service defined type:

address

Data type: Optional[String[1]]

IP address the service is running at.

Default value: undef

checks

Data type: Array[Hash]

If provided an array of checks that will be added to this service

Default value: []

enable_tag_override

Data type: Boolean

enable_tag_override support for service. Defaults to False.

Default value: false

ensure

Data type: String[1]

Define availability of service. Use 'absent' to remove existing services. Defaults to 'present'

Default value: 'present'

id

Data type: String[1]

The unique ID of the service on the node. Defaults to title.

Default value: $title

port

Data type: Optional[Integer[0, 65535]]

TCP port the service runs on.

Default value: undef

service_name

Data type: String[1]

Name of the service. Defaults to title.

Default value: $title

service_config_hash

Data type: Hash

Use this to populate the basic service params for each of the services

Default value: {}

tags

Data type: Array[String[1]]

Array of strings.

Default value: []

token

Data type: Optional[String[1]]

ACL token for interacting with the catalog (must be 'management' type)

Default value: undef

meta

Data type:

Optional[Hash[
      String[1],
      Variant[
        String[1],
        Numeric,
        Boolean,
  ]]]

Service meta key/value pairs as hash.

Default value: undef

consul::watch

Sets up Consul watch, to span commands when data changes.

Parameters

The following parameters are available in the consul::watch defined type:

datacenter

Data type: Optional

String overriding consul's default datacenter.

Default value: undef

ensure

Data type: Enum['present', 'absent']

Define availability of watch. Use 'absent' to remove existing watches.

Default value: present

event_name

Data type: Optional

Name of an event to watch for.

Default value: undef

handler

Data type: Optional

Full path to the script that will be excuted. This parameter is deprecated in Consul 1.0.0

Default value: undef

args

Data type: Optional

Arguments to be execed for the watch.

Default value: undef

key

Data type: Optional

Watch a specific key.

Default value: undef

keyprefix

Data type: Optional

Watch a whole keyprefix

Default value: undef

passingonly

Data type: Optional[Boolean]

Watch only those services that are passing healthchecks.

Default value: undef

service

Data type: Optional

Watch a particular service

Default value: undef

service_tag

Data type: Optional

This actually maps to the "tag" param for service watches. (tag is a puppet builtin metaparameter)

Default value: undef

state

Data type: Optional

Watch a state change on a service healthcheck.

Default value: undef

token

Data type: Optional

String to override the default token.

Default value: undef

type

Data type: Optional

Type of data to watch. (Like key, service, services, nodes)

Default value: undef

Resource types

consul_acl

Manage a consul token and its ACLs.

Properties

The following properties are available in the consul_acl type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

id

ID of token

protocol

Valid values: http, https

consul protocol

Default value: http

rules

hash of ACL rules for this token

type

Valid values: client, management

Type of token

Default value: client

Parameters

The following parameters are available in the consul_acl type.

acl_api_token

Token for accessing the ACL API

Default value: anonymous

api_tries

number of tries when contacting the Consul REST API

Default value: 3

hostname

consul hostname

Default value: localhost

name

namevar

Name of the token

port

consul port

Default value: 8500

provider

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.

consul_key_value

Manage a consul key value object.

Properties

The following properties are available in the consul_key_value type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

value

The key value string

Parameters

The following parameters are available in the consul_key_value type.

acl_api_token

Token for accessing the ACL API

Default value: anonymous

api_tries

number of tries when contacting the Consul REST API

Default value: 3

datacenter

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

Flags integer

Default value: 0

hostname

consul hostname

Default value: localhost

name

namevar

Name of the key/value object

port

consul port

Default value: 8500

protocol

Valid values: http, https

consul protocol

Default value: http

provider

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.

consul_policy

Manages a Consul ACL policy

Properties

The following properties are available in the consul_policy type.

datacenters

List of datacenter names assigned to the policy

Default value: []

description

Description of the policy

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

id

ID of already existing policy

Default value: ''

rules

List of ACL rules for this policy

Default value: []

Parameters

The following parameters are available in the consul_policy type.

acl_api_token

Token for accessing the ACL API

Default value: ''

api_tries

number of tries when contacting the Consul REST API

Default value: 3

hostname

consul hostname

Default value: localhost

name

namevar

Name of the policy

port

consul port

Default value: 8500

protocol

Valid values: http, https

consul protocol

Default value: http

provider

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.

consul_prepared_query

Manage a consul prepared query.

Properties

The following properties are available in the consul_prepared_query type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

id

ID of prepared query

Parameters

The following parameters are available in the consul_prepared_query type.

acl_api_token

Token for accessing the ACL API

Default value: anonymous

api_tries

number of tries when contacting the Consul REST API

Default value: 3

hostname

consul hostname

Default value: localhost

name

namevar

Name of the prepared query

node_meta

List of user-defined key/value pairs to filter on NodeMeta

port

consul port

Default value: 8500

protocol

Valid values: http, https

consul protocol

Default value: http

provider

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.

service_failover_dcs

List of datacenters to forward queries to if no health services found locally

Default value: []

service_failover_n

Failover to the nearest datacenters

Default value: 0

service_meta

List of user-defined key/value pairs to filter on ServiceMeta

service_name

Service name for the prepared query

service_near

Resurn results in ascending order of estimated RTT from given node name, or _agent special value

Default value: ''

service_only_passing

Only return services in the passing state

Default value: false

service_tags

List of tags to filter the query with

Default value: []

template

Valid values: true, false, yes, no

is template?

Default value: false

template_regexp

regexp for template

Default value: ''

template_type

type for template

Default value: name_prefix_match

token

The prepared query token

Default value: ''

ttl

TTL for the DNS lookup

Default value: 0

consul_token

Manages a v2 Consul token

Properties

The following properties are available in the consul_token type.

accessor_id

Accessor ID of the token

description

Description of the token

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

policies_by_id

List of policy IDs assigned to the token

Default value: []

policies_by_name

List of policy names assigned to the token

Default value: []

secret_id

Secret ID of the token

Default value: ''

Parameters

The following parameters are available in the consul_token type.

acl_api_token

Token for accessing the ACL API

Default value: ''

api_tries

number of tries when contacting the Consul REST API

Default value: 3

hostname

consul hostname

Default value: localhost

name

namevar

Name of the token

port

consul port

Default value: 8500

protocol

Valid values: http, https

consul protocol

Default value: http

provider

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.

Functions

consul::sorted_json

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

unsorted_hash

Data type: Optional[Any]

pretty

Data type: Optional[Any]

indent_len

Data type: Optional[Any]

consul::validate_checks

Type: Ruby 4.x API

The consul::validate_checks function.

consul::validate_checks(HashOrArray $obj)

The consul::validate_checks function.

Returns: Any

obj

Data type: HashOrArray

Data types

Consul::PolicyStruct

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]],
  }]

Consul::TokenStruct

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]],
  }]