cockroachdb

contributions requested

pdk

tasks

Puppet module for CockroachDB. Created as part of a project in the subject Infrastructure as Code (IMT3005) at NTNU Gjøvik.

Project URL RSS Feed Report issues

Module Stats

7,638 downloads

1,946 latest version

5.0 quality score

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

Version information

released Oct 31st 2019

This version is compatible with:

Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
Puppet >= 4.10.0 < 7.0.0
Debian
,
Ubuntu

Tasks:

cockroachdb

node_decommission

node_ls

node_status

quit

restart_service

sql

Start using this module

Installation method

Add this module to your Puppetfile:

mod 'neckbeards-cockroachdb', '1.1.0'

Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add neckbeards-cockroachdb

Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install neckbeards-cockroachdb --version 1.1.0

Documentation

neckbeards/cockroachdb — version 1.1.0 Oct 31st 2019

cockroachdb

Description
Setup - Getting started with cockroachdb
Example Usage
Limitations and Known Issues
Development - Guide for contributing to the module

Description

This is a CockroachDB module for Puppet. It will help you set up a database cluster quickly and provides basic functionality for managing it using Bolt tasks. The module is created using PDK for Open Source Puppet and using the Open Source version of CockroachDB.

The module was initially created as part of a project in the subject Infrastructure as Code (IMT3005) at NTNU Gjøvik.

Setup

What cockroachdb affects

Dependencies installed by cockroachdb by default:

tar
wget
puppet-archive v4.2.0
puppetlabs-stdlib >= 4.13.1 < 7.0.0

Setup Requirements

At the moment the module requires that database nodes are identified by FQDNs, so DNS should be configured prior to use.

To use secure mode, you need to handle the certificates either manually, or using other modules/programs.

Beginning with cockroachdb

First add the module to your Puppetfile, see the Forge instructions. Then all you need in your manifest to get started is:

Insecure mode

class { 'cockroachdb':
  node1ip     => 'db0',
  node2ip     => 'db1',
  node3ip     => 'db2',
  secure_mode => false,
}

Secure mode

class { 'cockroachdb':
  node1ip     => 'db0',
  node2ip     => 'db1',
  node3ip     => 'db2',
  secure_mode => true,
  certs_dir   => '/root/certs',
}

Client To just install the cockroach client and not run it as a server, just add include cockroachdb::client to your Puppet manifest.

Usage

Specifying different cockroachdb version:

class { 'cockroachdb':
  node1ip        => 'db0',
  node2ip        => 'db1',
  node3ip        => 'db2',
  package_ensure => 'v19.1.0.linux-amd64',
  secure_mode    => false,
}

Adding additional parameters to cockroachdb that are not directly supported in the module:

class { 'cockroachdb':
  node1ip           => 'db0',
  node2ip           => 'db1',
  node3ip           => 'db2',
  secure_mode       => false,
  additional_params => '--store=/mnt/ssd01',
}

Initializing a cluster using bolt tasks:

To then initialize the database cluster, use:

bolt task run cockroachdb -n db0 insecure=true

Verify that the cluster is online:

bolt task run cockroachdb::node_ls -n db0 insecure=true

Limitations

Limitations:

Only a three node initial cluster is supported. But still works with more nodes joining later
Can not switch from secure to insecure mode

Known Issues:

Warnings:

Development

Contribution guidelines for this project

Changelog

Reference

Classes

cockroachdb: Recives parameters from the user and initializes the cockroach::install and cockroach::config classes.
cockroachdb::client: Install the cockroachdb client
cockroachdb::config: This class is called from the cockroachdb class to configure the program.
cockroachdb::install: This class is called from the the cockroachdb class for installation.
cockroachdb::params: Default values for cockroachdb module.
cockroachdb::service: This class is called from the cockroachdb class to configure the service.

Tasks

init: Initialize a database cluster
node_decommission: Decommission a node from the cluster
node_ls: List nodes in a cluster.
node_status: Check status of a node in the cluster.
quit: Stop a node in a cluster.
restart_service: Restart cockroachdb service
sql: Run a sql command on a cluster

Classes

cockroachdb

Recives parameters from the user and initializes the cockroach::install and cockroach::config classes.

Parameters

The following parameters are available in the cockroachdb class.

`servicepath`

Data type: Optional[Stdlib::Absolutepath]

Location of where the ".service" file is to be saved. If the parameter is not defined it will be saved in "/etc/systemd/system".

Default value: $cockroachdb::params::servicepath

`workingdirectory`

Data type: Optional[Stdlib::Absolutepath]

Location of where the working directory will be created. If the parameter is not defined it will be created in "/var/lib/cockroach".

Default value: $cockroachdb::params::workingdirectory

`dependencies`

Data type: Optional[Tuple]

Consists of dependencies 'tar' and 'wget' by default. Failing to include these dependencies while defining this parameter yourself may result in dependency issues.

Default value: $cockroachdb::params::dependencies

`description`

Data type: Optional[String]

Cockroachdb node description.

Default value: $cockroachdb::params::description

`cache`

Data type: Optional[String]

The total size for caches, shared if there are multiple storage devices, noted with a decimal or '%'.

Default value: $cockroachdb::params::cache

`maxsqlmemory`

Data type: Optional[String]

The maximum in-memory storage capaciy available to store temprary data for SQL queries. Noted with a decimal point or '%'.

Default value: $cockroachdb::params::maxsqlmemory

`timeoutstopsec`

Data type: Optional[String]

Configures the time to wait for each ExecStop command for systemd.

Default value: $cockroachdb::params::timeoutstopsec

`restart`

Data type: Optional[String]

Defines when the service is to be restarted. Configured with always by default and will restart on every restart setting and exit cause.

Default value: $cockroachdb::params::restart

`restartsec`

Data type: Optional[String]

Defines the time to sleep before restarting the service.

Default value: $cockroachdb::params::restartsec

`standardoutput`

Data type: Optional[String]

Controls where the file descriptor 1 (STDOUT) of the executed processes is connected to.

Default value: $cockroachdb::params::standardoutput

`standarderror`

Data type: Optional[String]

Controls where the file descriptor 2 (STDERR) of the executed process is connected to.

Default value: $cockroachdb::params::standarderror

`syslogidentifier`

Data type: Optional[String]

Sets the process name ("syslog tag") to prefix log lines sent to the logging system or the kernel log buffer.

Default value: $cockroachdb::params::syslogidentifier

`user`

Data type: Optional[String]

Sets the user/group that the processes are executed as.

Default value: $cockroachdb::params::user

`node1ip`

Data type: String

Sets the ip-address for node one. Set to localhost when in single node mode.

Default value: $cockroachdb::params::node1ip

`node2ip`

Data type: Optional[String]

Sets the ip-address for node two. Skip for single node mode.

Default value: $cockroachdb::params::node2ip

`node3ip`

Data type: Optional[String]

Sets the ip-address for node three. Skip for single node mode.

Default value: $cockroachdb::params::node3ip

`install_path`

Data type: Optional[Stdlib::Absolutepath]

Location where the program binary file is to be located.

Default value: $cockroachdb::params::install_path

`package_name`

Data type: Optional[String]

Name of the package to install.

Default value: $cockroachdb::params::package_name

`package_ensure`

Data type: String

Version number and linux distribution name.

Default value: $cockroachdb::params::package_ensure

`repository_url`

Data type: Optional[String]

Base repository URL.

Default value: $cockroachdb::params::repository_url

`archive_name`

Data type: Optional[String]

Archive path of the binary file in the base repository.

Default value: $cockroachdb::params::archive_name

`cockroachdb_package_source`

Data type: Optional[String]

Full binary package source.

Default value: $cockroachdb::params::cockroachdb_package_source

`additional_params`

Data type: Optional[String]

Additional params and flags to pass to cockroachdb on startup. Must be provided as fully valid cockroachdb flags.

Default value: $cockroachdb::params::additional_params

`secure_mode`

Data type: Boolean

If cockroachdb secure mode is enabled or not. Currently only supports insecure mode.

Default value: $cockroachdb::params::secure_mode

`locality`

Data type: Optional[Array[String, 1]]

Array of Hashes containing locality information for nodes.

Default value: $cockroachdb::params::locality

`certs_dir`

Data type: Optional[Stdlib::Absolutepath]

The directory where CockroachDB can find certificates.

Default value: $cockroachdb::params::certs_dir

`dns_mode`

Data type: Optional[Enum['hostname', 'fqdn', 'ipaddress', 'custom']]

Use FQDN, hostnames, IPs or custom facts to identify nodes.

Default value: $cockroachdb::params::dns_mode

`dns_mode_custom`

Data type: Optional[String]

Custom fact used to identify nodes. Can be any valid facter fact, like custom facts.

Default value: $cockroachdb::params::dns_mode_custom

cockroachdb::client

Install the cockroachdb client

Examples

include cockroachdb::client

Parameters

The following parameters are available in the cockroachdb::client class.

`workingdirectory`

Data type: Optional[Stdlib::Absolutepath]

Location of where the working directory will be created. If the parameter is not defined it will be created in "/var/lib/cockroach".

Default value: $cockroachdb::params::workingdirectory

`dependencies`

Data type: Optional[Tuple]

Consists of dependencies 'tar' and 'wget' by default. Failing to include these dependencies while defining this parameter yourself may result in dependency issues.

Default value: $cockroachdb::params::dependencies

`install_path`

Data type: Optional[Stdlib::Absolutepath]

Location where the program binary file is to be located.

Default value: $cockroachdb::params::install_path

`package_name`

Data type: Optional[String]

Name of the package to install.

Default value: $cockroachdb::params::package_name

`package_ensure`

Data type: String

Version number and linux distribution name.

Default value: $cockroachdb::params::package_ensure

`repository_url`

Data type: Optional[String]

Base repository URL.

Default value: $cockroachdb::params::repository_url

`archive_name`

Data type: Optional[String]

Archive path of the binary file in the base repository.

Default value: $cockroachdb::params::archive_name

`cockroachdb_package_source`

Data type: Optional[String]

Full binary package source.

Default value: $cockroachdb::params::cockroachdb_package_source

cockroachdb::config

This class is called from the cockroachdb class to configure the program.

cockroachdb::install

This class is called from the the cockroachdb class for installation.

cockroachdb::params

Default values for cockroachdb module.

cockroachdb::service

This class is called from the cockroachdb class to configure the service.

Tasks

init

Initialize a database cluster

Supports noop? false

Parameters

`host`

Data type: Optional[String[1]]

The server host and port number to connect to. This can be the address of any node in the cluster.

`port`

Data type: Optional[Integer[1]]

The server port to connect to. Note: The port number can also be specified via --host.

`user`

Data type: Optional[String[1]]

The SQL user that will own the client session.

`insecure`

Data type: Optional[Boolean]

Use an insecure connection.

`certs_dir`

Data type: Optional[String[1]]

The path to the certificate directory containing the CA and client certificates and client key.

`url`

Data type: Optional[String[1]]

A connection URL to use instead of the other arguments.

node_decommission

Decommission a node from the cluster

Supports noop? false

Parameters

`host`

Data type: Optional[String[1]]

The server host and port number to connect to. This can be the address of any node in the cluster.

`port`

Data type: Optional[Integer[1]]

The server port to connect to. Note: The port number can also be specified via --host.

`user`

Data type: Optional[String[1]]

The SQL user that will own the client session.

`insecure`

Data type: Optional[Boolean]

Use an insecure connection.

`certs_dir`

Data type: Optional[String[1]]

The path to the certificate directory containing the CA and client certificates and client key.

`url`

Data type: Optional[String[1]]

A connection URL to use instead of the other arguments.

`wait`

Data type: Optional[Enum[all,none]]

When to return to the client. Possible values: all, none.

node_ls

List nodes in a cluster.

Supports noop? false

Parameters

`host`

Data type: Optional[String[1]]

The server host and port number to connect to. This can be the address of any node in the cluster.

`port`

Data type: Optional[Integer[1]]

The server port to connect to. Note: The port number can also be specified via --host.

`user`

Data type: Optional[String[1]]

The SQL user that will own the client session.

`insecure`

Data type: Optional[Boolean]

Use an insecure connection.

`certs_dir`

Data type: Optional[String[1]]

The path to the certificate directory containing the CA and client certificates and client key.

`url`

Data type: Optional[String[1]]

A connection URL to use instead of the other arguments.

`format`

Data type: Optional[Enum[tsv,csv,table,records,sql,html]]

How to display table rows printed to the standard output. Possible values: tsv, csv, table, records, sql, html.

`timeout`

Data type: Optional[Pattern[/^[0-9]{1,}(s|m|h)$/]]

Set the duration of time that the subcommand is allowed to run before it returns an error and prints partial information. The timeout is specified with a suffix of s for seconds, m for minutes, and h for hours. If this flag is not set, the subcommand may hang.

node_status

Check status of a node in the cluster.

Supports noop? false

Parameters

`host`

Data type: Optional[String[1]]

The server host and port number to connect to. This can be the address of any node in the cluster.

`port`

Data type: Optional[Integer[1]]

The server port to connect to. Note: The port number can also be specified via --host.

`user`

Data type: Optional[String[1]]

The SQL user that will own the client session.

`insecure`

Data type: Optional[Boolean]

Use an insecure connection.

`certs_dir`

Data type: Optional[String[1]]

The path to the certificate directory containing the CA and client certificates and client key.

`url`

Data type: Optional[String[1]]

A connection URL to use instead of the other arguments.

`format`

Data type: Optional[Enum[tsv,csv,table,records,sql,html]]

How to display table rows printed to the standard output. Possible values: tsv, csv, table, records, sql, html.

`timeout`

Data type: Optional[Pattern[/^[0-9]{1,}(s|m|h)$/]]

`all`

Data type: Optional[Boolean]

Show all node details.

`decommission`

Data type: Optional[Boolean]

Show node decommissioning details.

`ranges`

Data type: Optional[Boolean]

Show node details for ranges and replicas.

`stats`

Data type: Optional[Boolean]

Show node disk usage details.

quit

Stop a node in a cluster.

Supports noop? false

Parameters

`host`

Data type: Optional[String[1]]

The server host and port number to connect to. This can be the address of any node in the cluster.

`port`

Data type: Optional[Integer[1]]

The server port to connect to. Note: The port number can also be specified via --host.

`user`

Data type: Optional[String[1]]

The SQL user that will own the client session.

`insecure`

Data type: Optional[Boolean]

Use an insecure connection.

`certs_dir`

Data type: Optional[String[1]]

The path to the certificate directory containing the CA and client certificates and client key.

`url`

Data type: Optional[String[1]]

A connection URL to use instead of the other arguments.

`decommission`

Data type: Optional[Boolean]

If specified, the node will be permanently removed instead of temporarily stopped.

restart_service

Restart cockroachdb service

Supports noop? false

sql

Run a sql command on a cluster

Supports noop? false

Parameters

`host`

Data type: Optional[String[1]]

The server host and port number to connect to. This can be the address of any node in the cluster.

`port`

Data type: Optional[Integer[1]]

The server port to connect to. Note: The port number can also be specified via --host.

`user`

Data type: Optional[String[1]]

The SQL user that will own the client session.

`insecure`

Data type: Optional[Boolean]

Use an insecure connection.

`certs_dir`

Data type: Optional[String[1]]

The path to the certificate directory containing the CA and client certificates and client key.

`url`

Data type: Optional[String[1]]

A connection URL to use instead of the other arguments.

`database`

Data type: Optional[String[1]]

A database name to use as current database in the newly created session.

`echo_sql`

Data type: Optional[String[1]]

Reveal the SQL statements sent implicitly by the command-line utility.

`execute`

Data type: String[1]

Execute SQL statements directly from the command line, without opening a shell. Non-optional, to prevent shell from opening

`format`

Data type: Optional[Enum[tsv,csv,table,raw,records,sql,html]]

How to display table rows printed to the standard output. Possible values: tsv, csv, table, raw, records, sql, html.

`safe_updates`

Data type: Optional[Boolean]

Disallow potentially unsafe SQL statements.

`set`

Data type: Optional[String[1]]

Set a client-side option before executing SQL statements from the command line via --execute.

What are tasks?

Modules can contain tasks that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.

Tasks in this module release

cockroachdb

Initialize a database cluster

Parameters
certs_dir	The path to the certificate directory containing the CA and client certificates and client key. `Optional[String[1]]`
host	The server host and port number to connect to. This can be the address of any node in the cluster. `Optional[String[1]]`
insecure	Use an insecure connection. `Optional[Boolean]`
port	The server port to connect to. Note: The port number can also be specified via --host. `Optional[Integer[1]]`
url	A connection URL to use instead of the other arguments. `Optional[String[1]]`
user	The SQL user that will own the client session. `Optional[String[1]]`

Input method

stdin

node_decommission

Decommission a node from the cluster

Parameters
certs_dir	The path to the certificate directory containing the CA and client certificates and client key. `Optional[String[1]]`
host	The server host and port number to connect to. This can be the address of any node in the cluster. `Optional[String[1]]`
insecure	Use an insecure connection. `Optional[Boolean]`
port	The server port to connect to. Note: The port number can also be specified via --host. `Optional[Integer[1]]`
url	A connection URL to use instead of the other arguments. `Optional[String[1]]`
user	The SQL user that will own the client session. `Optional[String[1]]`
wait	When to return to the client. Possible values: all, none. `Optional[Enum[all,none]]`

Input method

stdin

node_ls

List nodes in a cluster.

Parameters
certs_dir	The path to the certificate directory containing the CA and client certificates and client key. `Optional[String[1]]`
format	How to display table rows printed to the standard output. Possible values: tsv, csv, table, records, sql, html. `Optional[Enum[tsv,csv,table,records,sql,html]]`
host	The server host and port number to connect to. This can be the address of any node in the cluster. `Optional[String[1]]`
insecure	Use an insecure connection. `Optional[Boolean]`
port	The server port to connect to. Note: The port number can also be specified via --host. `Optional[Integer[1]]`
timeout	Set the duration of time that the subcommand is allowed to run before it returns an error and prints partial information. The timeout is specified with a suffix of s for seconds, m for minutes, and h for hours. If this flag is not set, the subcommand may hang. `Optional[Pattern[/^[0-9]{1,}(s\|m\|h)$/]]`
url	A connection URL to use instead of the other arguments. `Optional[String[1]]`
user	The SQL user that will own the client session. `Optional[String[1]]`

Input method

stdin

node_status

Check status of a node in the cluster.

Parameters
all	Show all node details. `Optional[Boolean]`
certs_dir	The path to the certificate directory containing the CA and client certificates and client key. `Optional[String[1]]`
decommission	Show node decommissioning details. `Optional[Boolean]`
format	How to display table rows printed to the standard output. Possible values: tsv, csv, table, records, sql, html. `Optional[Enum[tsv,csv,table,records,sql,html]]`
host	The server host and port number to connect to. This can be the address of any node in the cluster. `Optional[String[1]]`
insecure	Use an insecure connection. `Optional[Boolean]`
port	The server port to connect to. Note: The port number can also be specified via --host. `Optional[Integer[1]]`
ranges	Show node details for ranges and replicas. `Optional[Boolean]`
stats	Show node disk usage details. `Optional[Boolean]`
timeout	Set the duration of time that the subcommand is allowed to run before it returns an error and prints partial information. The timeout is specified with a suffix of s for seconds, m for minutes, and h for hours. If this flag is not set, the subcommand may hang. `Optional[Pattern[/^[0-9]{1,}(s\|m\|h)$/]]`
url	A connection URL to use instead of the other arguments. `Optional[String[1]]`
user	The SQL user that will own the client session. `Optional[String[1]]`

Input method

stdin

quit

Stop a node in a cluster.

Parameters
certs_dir	The path to the certificate directory containing the CA and client certificates and client key. `Optional[String[1]]`
decommission	If specified, the node will be permanently removed instead of temporarily stopped. `Optional[Boolean]`
host	The server host and port number to connect to. This can be the address of any node in the cluster. `Optional[String[1]]`
insecure	Use an insecure connection. `Optional[Boolean]`
port	The server port to connect to. Note: The port number can also be specified via --host. `Optional[Integer[1]]`
url	A connection URL to use instead of the other arguments. `Optional[String[1]]`
user	The SQL user that will own the client session. `Optional[String[1]]`

Input method

stdin

restart_service

Restart cockroachdb service

sql

Run a sql command on a cluster

Parameters
certs_dir	The path to the certificate directory containing the CA and client certificates and client key. `Optional[String[1]]`
database	A database name to use as current database in the newly created session. `Optional[String[1]]`
echo_sql	Reveal the SQL statements sent implicitly by the command-line utility. `Optional[String[1]]`
execute	Execute SQL statements directly from the command line, without opening a shell. Non-optional, to prevent shell from opening `String[1]`
format	How to display table rows printed to the standard output. Possible values: tsv, csv, table, raw, records, sql, html. `Optional[Enum[tsv,csv,table,raw,records,sql,html]]`
host	The server host and port number to connect to. This can be the address of any node in the cluster. `Optional[String[1]]`
insecure	Use an insecure connection. `Optional[Boolean]`
port	The server port to connect to. Note: The port number can also be specified via --host. `Optional[Integer[1]]`
safe_updates	Disallow potentially unsafe SQL statements. `Optional[Boolean]`
set	Set a client-side option before executing SQL statements from the command line via --execute. `Optional[String[1]]`
url	A connection URL to use instead of the other arguments. `Optional[String[1]]`
user	The SQL user that will own the client session. `Optional[String[1]]`

Input method

stdin

cockroachdb

Support the Puppet Community by contributing to this module

Version information

This version is compatible with:

Tasks:

Start using this module

Documentation

cockroachdb

Table of Contents

Description

Setup

What cockroachdb affects

Setup Requirements

Beginning with cockroachdb

Usage

Limitations

Development

Changelog

Reference

Table of Contents

Classes

cockroachdb

Parameters

servicepath

workingdirectory

dependencies

description

cache

maxsqlmemory

timeoutstopsec

restart

restartsec

standardoutput

standarderror

syslogidentifier

user

node1ip

node2ip

node3ip

install_path

package_name

package_ensure

repository_url

archive_name

cockroachdb_package_source

additional_params

secure_mode

locality

certs_dir

dns_mode

dns_mode_custom

cockroachdb::client

Examples

Parameters

workingdirectory

dependencies

install_path

package_name

package_ensure

repository_url

archive_name

cockroachdb_package_source

cockroachdb::config

cockroachdb::install

cockroachdb::params

cockroachdb::service

Tasks

init

Parameters

host

port

user

insecure

certs_dir

url

node_decommission

Parameters

host

port

user

`servicepath`

`workingdirectory`

`dependencies`

`description`

`cache`

`maxsqlmemory`

`timeoutstopsec`

`restart`

`restartsec`

`standardoutput`

`standarderror`

`syslogidentifier`

`user`

`node1ip`

`node2ip`

`node3ip`

`install_path`

`package_name`

`package_ensure`

`repository_url`

`archive_name`

`cockroachdb_package_source`

`additional_params`

`secure_mode`

`locality`

`certs_dir`

`dns_mode`

`dns_mode_custom`

`workingdirectory`

`dependencies`

`install_path`

`package_name`

`package_ensure`

`repository_url`

`archive_name`

`cockroachdb_package_source`

`host`

`port`

`user`

`insecure`

`certs_dir`

`url`

`host`

`port`

`user`

`insecure`

`certs_dir`

`url`

`wait`

`host`

`port`

`user`

`insecure`

`certs_dir`

`url`

`format`

`timeout`

`host`

`port`

`user`

`insecure`

`certs_dir`

`url`

`format`

`timeout`

`all`

`decommission`

`ranges`

`stats`

`host`

`port`

`user`

`insecure`

`certs_dir`

`url`

`decommission`

`host`

`port`

`user`

`insecure`