Terraform Provider for ClusterControl

The GitHub repository contains examples of deploying database clusters of various types (MySQL/MariaDB replication or galera with ProxySQL, PostgreSQL replication, MongoDB replica set and/or sharded, Redis sentinel, Microsoft SQL server, and Elasticsearch)

Navigate to the repository docs folder for generated documentation on the terraform provider plugin for ClusterControl.

The sub-folders contain examples of the following:

Database type	Description
MySQL/MariaDB	MySQL and/or MariaDB database (both Master/Slave and Galera multi-master)
ProxySQL	ProxySQL load balancer with MySQL/MariaDB database clusters
PostgreSQL	Postgres (Primary with Hot-Standby clusters)
MongoDB	Both sharded clusters and single Replicaset clusters
Redis	Redis sentinel clusters
Microsoft SQL Server	Both standalone and hot-standby cluster with one hot-standby (async)
Elasticsearch	Elasticsearch clusters

Provider Configuration

Use the following to configure the Terraform provider for ClusterControl:

terraform {
  required_providers {
    clustercontrol = {
      source = "severalnines/clustercontrol"
      version = "0.2.15"
    }
  }
}

provider "clustercontrol" {
  # Configuration options:
  # cc_api_url = ""
  # cc_api_user = "" 
  # cc_api_user_password = ""
}

Resources

Name
clustercontrol_db_cluster
clustercontrol_db_cluster_backup
clustercontrol_db_cluster_backup_schedule
clustercontrol_db_cluster_maintenance

clustercontrol_db_cluster

Required

• db_admin_user_password (String, Sensitive) Password for the admin/root user for the database. Note that this may show up in logs, and it will be stored in the state file
• db_cluster_name (String) The name of the database cluster.
• db_cluster_type (String) Type of cluster – replication, galera, postgresql_single (single is a misnomer), etc
• db_vendor (String) Database vendor – oracle, percona, mariadb, 10gen, microsoft, redis, elasticsearch, for postgresql it is defaultetc
• db_version (String) The database version
• ssh_key_file (String) SSH Key file. The path to the private key file for the Sudo user on the ClusterControl host
• ssh_user (String) The SSH user ClusterControl will use to SSH to the DB host from the ClusterControl host

Optional

• db_admin_username (String) Name for the admin/root user for the database
• db_auto_recovery (Boolean) Have cluster auto-recovery on (or off)
• db_cluster_create (Boolean) Whether to create this resource or not?
• db_cluster_import (Boolean) Whether to import this resource or not?
• db_config_server (Block List) Specification for the MongoDB Configuration Server. (see below for nested schema)
• db_data_directory (String) The data directory for the database data files. If not set explicily, the default for the respective DB vendor will be chosen
• db_deploy_agents (Boolean) Automatically deploy prometheus and other relevant agents after setting up the intial DB cluster.
• db_elasticsearch_http_port (String) The port on which Elasticsearch will accept client http connections
• db_elasticsearch_transfer_port (String) The port on which Elasticsearch will accept client connections for data transfer(?)
• db_enable_pbm_agent (Boolean) Enable percona backup for mongodb.
• db_enable_pgbackrest_agent (Boolean) Enable PgBackRest for Postgres.
• db_enable_ssl (Boolean) Enable SSL based comms between the cluster nodes and client access to node.
• db_enable_timescale (Boolean) Whether to setup TimescaleDB extension or not
• db_enable_uninstall (Boolean) When removing DB cluster from ClusterControl, enable uinstalling DB packages.
• db_host (Block List) The list of nodes/hosts that make up the cluster (see below for nested schema)
• db_install_software (Boolean) Install DB packages from respective repos
• db_load_balancer (Block List) The list of nodes/hosts that make up the cluster (see below for nested schema)
• db_mongo_auth_db (String) The mongodb database to use for authentication purposes
• db_mongo_config_server_port (String) The port on which MongoDB config server will accept client connections. MongoS server will use same port number as db_mongo_port
• db_mongo_port (String) The port on which MongoDB will accept client connections
• db_mongos_server (Block List) Specification for the MongoDB mongos Server. (see below for nested schema)
• db_mssqlserver_port (String) The port on which MSSQL will accept client connections
• db_mysql_port (String) The port on which MySQL will accept client connections
• db_pbm_backup_dir (String) Backup dir, nfs mounted directory/path for PBM backup.
• db_postgres_port (String) The port on which PostgreSql will accept client connections
• db_redis_port (String) The port on which Redis will accept client connections
• db_replica_set (Block List) The hosts that make up the cluster. (see below for nested schema)
• db_semi_sync_replication (Boolean) Semi-synchronous replication for MySQL and MariaDB non-galera clusters
• db_sentinel_port (String) The port Redis Sentinel uses to communicate
• db_snapshot_host (String) Elasticsearch snapshot host
• db_snapshot_location (String) Elasticsearch snapshot location
• db_snapshot_repository (String) Elasticsearch snapshot repository
• db_tags (Set of String) Tags to associate with a DB cluster. The tags are only relevant in the ClusterControl domain.
• db_topology (Block List) Only applicable to MySQL/MariaDB non-galera clusters. A way to specify Master and Slave(s). (see below for nested schema)
• disable_firewall (Boolean) Disable firewall on the host OS when installing DB packages.
• disable_selinux (Boolean) Disable SELinux on the host OS when installing DB packages.
• ssh_port (String) The ssh port.
• ssh_user_password (String, Sensitive) Sudo user’s password. If sudo user doesn’t have a password, leave this field blank

Read-Only

• db_cluster_id (String) TODO
• id (String) The ID of this resource.
• last_updated (String) TODO

Nested Schema for db_config_server

Required:

• member (Block List, Min: 1) The host that make up the replicaset member. (see below for nested schema)
• rs (String) The replicaset’s name.

Nested Schema for db_config_server.member

Required:

• hostname (String) Hostname of the DB host. Can be IP address as well.

Optional:

• hostname_data (String) Hostname/IP used for data comms (may be legacy ClusterControl).
• hostname_internal (String) If there’s a private net that all DB hosts can communicate, use it here.

Nested Schema for db_host

Required:

• hostname (String) Hostname of the DB host. Can be IP address as well

Optional:

• datadir (String) The data directory for the database data files. If not set explicily, default for the DB type will be used, or inherited from earlier/top-level specification.
• hostname_data (String) Hostname/IP used for data comms (may be legacy ClusterControl).
• hostname_internal (String) If there’s a private net that all DB hosts can communicate, use it here.
• protocol (String) TODO.
• roles (String) Applicable to Elasticsearch – the role of this host (master-data: host will be designated as the master node and a data node, etc)
• sync_replication (Boolean) Applicable to PostgreSQL hot-standby nodes only. Use synchronous replication (or not)

Nested Schema for db_load_balancer

Required:

• db_lb_admin_user_password (String, Sensitive) The load balancer admin user’s password
• db_lb_monitor_user_password (String, Sensitive) The load balancer monitor user’s password
• db_lb_type (String) The load balancer type (e.g., proxysql, haproxy, etc)
• db_lb_version (String) Software version
• ssh_user (String) The SSH user ClusterControl will use to SSH to the DB host from the ClusterControl host

Optional:

• db_lb_admin_port (String) The load balancer admin port that will be used to administer it.
• db_lb_admin_username (String) The load balancer admin user
• db_lb_enable_uninstall (Boolean) When removing DB cluster from ClusterControl, enable uinstalling DB packages.
• db_lb_install_software (Boolean) Install DB packages from respective repos
• db_lb_monitor_username (String) The load balancer monitor user (only applicable to proxysql)
• db_lb_port (String) The load balancer port that it will accept connections on behalf of the database it is front-ending.
• db_lb_use_clustering (Boolean) Whether to use ProxySQL clustering or not. Only applicable to ProxySQL at this time
• db_lb_use_rw_splitting (Boolean) Whether to Read/Write splitting for queries or not?
• db_my_host (Block List) The load balancer host in question (i.e, self) (see below for nested schema)
• disable_firewall (Boolean) Disable firewall on the host OS when installing DB packages.
• disable_selinux (Boolean) Disable SELinux on the host OS when installing DB packages.
• ssh_key_file (String) SSH Key file. The path to the private key file for the Sudo user on the ClusterControl host.
• ssh_port (String) The ssh port.
• ssh_user_password (String, Sensitive) Sudo user’s password. If sudo user doesn’t have a password, leave this field blank

Nested Schema for db_load_balancer.db_my_host

Required:

• hostname (String) Hostname/IP of this load balancer. Can be IP address as well.

Nested Schema for db_mongos_server

Required:

• hostname (String) Hostname of the DB host. Can be IP address as well.

Optional:

• hostname_data (String) Hostname/IP used for data comms (may be legacy ClusterControl).
• hostname_internal (String) If there’s a private net that all DB hosts can communicate, use it here.

Nested Schema for db_replica_set

Required:

• member (Block List, Min: 1) The hosts that make up the replicaset HA nodes. (see below for nested schema)
• rs (String) The replicaset’s name.

Nested Schema for db_replica_set.member

Required:

• hostname (String) Hostname of the DB host. Can be IP address as well

Optional:

• arbiter_only (Boolean) The host is acting as an arbiter only.
• hidden (Boolean) TODO.
• hostname_data (String) Hostname/IP used for data comms (may be legacy ClusterControl).
• hostname_internal (String) If there’s a private net that all DB hosts can communicate, use it here.
• priority (Number) Priority of the host in the mongo replication setup.
• slave_delay (String) Used in non-galera MySQL/MariaDB standby setup. Specifies the lag for the slave.

Nested Schema for db_topology

Optional:

• primary (String) The Master host
• replica (String) The Slave host.

clustercontrol_db_cluster_backup

Required

• db_backup_method (String) mariabackup, xtrabackup, …
• db_cluster_id (String) The database cluster ID for which this LB is being deployed to.

Optional

• db_backup_compression (Boolean) Whether to compress backups or not
• db_backup_compression_level (Number) Compression level
• db_backup_dir (String) Base direcory where backups is to be stored
• db_backup_encrypt (Boolean) Whether to encrypt or not
• db_backup_failover_host (String) If backup failover is enabled, which host to use as backup host in the event of failure of first choice host.
• db_backup_host (String) Where there are multiple hosts, which host to choose to create backup from.
• db_backup_retention (Number) Backup retention period in days
• db_backup_storage_controller (Boolean) Whether to store the backup on CMON controller host or not
• db_backup_storage_host (String) Which host to store the backup on. Typically, used with mongodump backup method.
• db_backup_subdir (String) Sub-dir for backups – default: “BACKUP-%I”
• db_backup_system_db (Boolean) Whether to enable backup failover to another host in case the host crashes
• db_enable_backup_failover (Boolean) Whether to enable backup failover to another host in case the host crashes

Read-Only

• db_resource_id (String) TODO
• id (String) The ID of this resource.
• last_updated (String) TODO

clustercontrol_db_cluster_backup_schedule

Required

• db_backup_method (String) mariabackup, xtrabackup, …
• db_backup_sched_time (String) The time to kick off a backup (e.g. ‘TZ=UTC 0 0 * * *’)
• db_cluster_id (String) The database cluster ID for which this LB is being deployed to.

Optional

• db_backup_compression (Boolean) Whether to compress backups or not
• db_backup_compression_level (Number) Compression level
• db_backup_dir (String) Base direcory where backups is to be stored
• db_backup_encrypt (Boolean) Whether to encrypt or not
• db_backup_failover_host (String) If backup failover is enabled, which host to use as backup host in the event of failure of first choice host.
• db_backup_host (String) Where there are multiple hosts, which host to choose to create backup from.
• db_backup_retention (Number) Backup retention period in days
• db_backup_sched_title (String) A title for the backup schedule (e.g., Daily full, Hourly incremental, etc)
• db_backup_storage_controller (Boolean) Whether to store the backup on CMON controller host or not
• db_backup_storage_host (String) Which host to store the backup on. Typically, used with mongodump backup method.
• db_backup_subdir (String) Sub-dir for backups – default: “BACKUP-%I”
• db_backup_system_db (Boolean) Whether to enable backup failover to another host in case the host crashes
• db_enable_backup_failover (Boolean) Whether to enable backup failover to another host in case the host crashes

Read-Only

• db_resource_id (String) TODO
• id (String) The ID of this resource.
• last_updated (String) TODO

clustercontrol_db_cluster_maintenance

Required

• db_cluster_id (String) The database cluster ID for which this LB is being deployed to.
• db_maint_start_time (String) Format: Jan-02-2006T15:04
• db_maint_stop_time (String) Format: Jan-02-2006T15:04

Optional

• db_maint_reason (String) TODO

Read-Only

• db_resource_id (String) TODO
• id (String) The ID of this resource.
• last_updated (String) TODO

Common fields in the resource definition

Resource – clustercontrol_db_cluster

db_host

The db_host block inside the clsutercontrol_db_cluster resource specifies the hosts that make up the cluster. Each host that makes up the DB cluster should have one of these blocks. The mandatory attribute for each db_host block is the hostname.

Example:

resource "clustercontrol_db_cluster" "this" {
    ...
    db_host {
        hostname = "host-1"
    }
    db_host {
        hostname = "host-2"
    }
    ...

}

Scheduling Backups using the clustercontrol_db_cluster_backup_scheduler resource

The backup schedule resource allows you to create a backup schedule for a cluster in ClusterControl through the terraform provider. Here’s an example of a daily full backup schedule using xtrabackup. As can be seen the clustercontrol_db_cluster_backup_scheduleresource depends on the clustercontrol_db_cluster resource.

 resource "clustercontrol_db_cluster_backup_schedule" "full-1" {
   depends_on                   = [clustercontrol_db_cluster.this]
   db_backup_sched_title        = "Daily full"
   db_backup_sched_time         = "TZ=UTC 0 0 * * *"
   db_cluster_id                = clustercontrol_db_cluster.this.id
   db_backup_method             = "xtrabackupfull"
   db_backup_dir                = var.db_backup_dir
   db_backup_subdir             = var.db_backup_subdir
   db_backup_encrypt            = var.db_backup_encrypt
   db_backup_host               = var.db_backup_host
   db_backup_storage_controller = var.db_backup_storage_controller
   db_backup_compression        = var.db_backup_compression
   db_backup_compression_level  = var.db_backup_compression_level
   db_backup_retention          = var.db_backup_retention
 }

Taking adhoc backups using the clustercontrol_db_cluster_backup resource

You can a maintenance window for a cluster using the clustercontrol_db_cluster_backup resource. Here’s an example of a full backup using xtrabackup.

 resource "clustercontrol_db_cluster_backup" "full-1" {
   depends_on                   = [clustercontrol_db_cluster.this]
   db_cluster_id                = clustercontrol_db_cluster.this.id
   db_backup_method             = "xtrabackupfull"
   db_backup_dir                = var.db_backup_dir
   db_backup_subdir             = var.db_backup_subdir
   db_backup_encrypt            = var.db_backup_encrypt
   db_backup_host               = var.db_backup_host
   db_backup_storage_controller = var.db_backup_storage_controller
   db_backup_compression        = var.db_backup_compression
   db_backup_compression_level  = var.db_backup_compression_level
   db_backup_retention          = var.db_backup_retention
 }

Setting a maintenance window using the clustercontrol_db_cluster_maintenance resource

You can take adhoc backups (full or incremental) of a cluster using the clustercontrol_db_cluster_backup resource. Here’s an example of a full backup using xtrabackup.

 resource "clustercontrol_db_cluster_maintenance" "server-upgrade-03312024" {
   depends_on = [clustercontrol_db_cluster.this]
   db_cluster_id       = clustercontrol_db_cluster.this.id
   db_maint_start_time = "Mar-31-2024T00:00"
   db_maint_stop_time  = "Mar-31-2024T23:30"
   db_maint_reason     = "Hardware refresh March 31, 2024"
 }

Note

The db_maint_start_time and db_maint_stop_time should be specified in local time (without the timezone).

Supported backup methods for the respective database types (and vendors)

The following types are supported:

Database type	Vendor	Backup method
MySQL	Oracle, Percona	xtrabackupfull, xtrabackupincr, mysqldump
MariaDB	MariaDB	mariabackupfull, mariabackupincr, mysqldump
PostgreSQL	Community	pg_basebackup, pgdumpall, pgbackrest(full,incr,diff)
MongoDB	MongoDB	mongodump, percona-backup-mongodb
Redis	Redis	Use the value "" to indicate (aof – default redis)
SQL Server	Microsoft	mssql_full
Elasticsearch	Elastic	TBD – default snapshot

Toggling cluster auto-recovery option

You can toggle the cluster-auto-recovery feature in ClusterControl using the db_auto_recovery field of the clustercontrol_db_clusterresource.

resource "clustercontrol_db_cluster" "this" {
...
  db_auto_recovery         = true
...
}