2021-10-07 09:22:43 -07:00
# Cloud SQL instance with read replicas
2021-10-07 09:20:07 -07:00
2021-10-07 10:41:12 -07:00
This module manages the creation of Cloud SQL instances with potential read replicas in other regions. It can also create an initial set of users and databases via the `users` and `databases` parameters.
2021-10-07 09:20:07 -07:00
Note that this module assumes that some options are the same for both the primary instance and all the replicas (e.g. tier, disks, labels, flags, etc).
2021-10-07 12:50:16 -07:00
*Warning:* if you use the `users` field, you terraform state will contain each user's password in plain text.
2021-10-07 09:20:07 -07:00
## Simple example
This example shows how to setup a project, VPC and a standalone Cloud SQL instance.
```hcl
module "project" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/project"
2021-10-07 09:20:07 -07:00
billing_account = var.billing_account_id
parent = var.organization_id
name = "my-db-project"
services = [
"servicenetworking.googleapis.com"
]
}
module "vpc" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/net-vpc"
2021-10-07 09:20:07 -07:00
project_id = module.project.project_id
name = "my-network"
2022-03-17 06:29:28 -07:00
psa_config = {
ranges = { cloud-sql = "10.60.0.0/16" }
}
2021-10-07 09:20:07 -07:00
}
module "db" {
2023-11-24 06:47:45 -08:00
source = "./fabric/modules/cloudsql-instance"
project_id = module.project.project_id
network_config = {
connectivity = {
psa_config = {
private_network = module.vpc.self_link
}
}
}
2021-10-07 09:20:07 -07:00
name = "db"
region = "europe-west1"
database_version = "POSTGRES_13"
tier = "db-g1-small"
}
2023-05-26 04:12:19 -07:00
# tftest modules=3 resources=11 inventory=simple.yaml
2021-10-07 09:20:07 -07:00
```
## Cross-regional read replica
```hcl
module "db" {
2023-11-24 06:47:45 -08:00
source = "./fabric/modules/cloudsql-instance"
project_id = var.project_id
network_config = {
connectivity = {
psa_config = {
private_network = var.vpc.self_link
}
}
}
2023-04-14 09:02:36 -07:00
prefix = "myprefix"
2021-10-07 09:20:07 -07:00
name = "db"
region = "europe-west1"
database_version = "POSTGRES_13"
tier = "db-g1-small"
replicas = {
2022-04-12 15:22:54 -07:00
replica1 = { region = "europe-west3", encryption_key_name = null }
replica2 = { region = "us-central1", encryption_key_name = null }
2021-10-07 09:20:07 -07:00
}
}
2023-04-14 09:02:36 -07:00
# tftest modules=1 resources=3 inventory=replicas.yaml
2021-10-07 09:20:07 -07:00
```
## Custom flags, databases and users
```hcl
module "db" {
2023-11-24 06:47:45 -08:00
source = "./fabric/modules/cloudsql-instance"
project_id = var.project_id
network_config = {
connectivity = {
psa_config = {
private_network = var.vpc.self_link
}
}
}
2021-10-07 09:20:07 -07:00
name = "db"
region = "europe-west1"
database_version = "MYSQL_8_0"
tier = "db-g1-small"
flags = {
disconnect_on_expired_password = "on"
}
databases = [
"people",
"departments"
]
users = {
# generatea password for user1
2023-11-13 01:27:14 -08:00
user1 = {
password = null
}
2021-10-07 09:20:07 -07:00
# assign a password to user2
2023-11-13 01:27:14 -08:00
user2 = {
password = "mypassword"
}
2021-10-07 09:20:07 -07:00
}
}
2023-04-14 09:02:36 -07:00
# tftest modules=1 resources=6 inventory=custom.yaml
2021-10-07 09:20:07 -07:00
```
2022-04-12 10:01:34 -07:00
2022-04-12 23:59:14 -07:00
### CMEK encryption
2022-04-12 10:01:34 -07:00
```hcl
module "project" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/project"
2022-04-12 10:01:34 -07:00
billing_account = var.billing_account_id
parent = var.organization_id
name = "my-db-project"
services = [
2022-04-12 15:22:54 -07:00
"servicenetworking.googleapis.com",
"sqladmin.googleapis.com",
2022-04-12 10:01:34 -07:00
]
}
module "kms" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/kms"
2022-04-12 10:01:34 -07:00
project_id = module.project.project_id
keyring = {
name = "keyring"
location = var.region
}
keys = {
key-sql = {
2023-09-16 09:58:07 -07:00
iam = {
"roles/cloudkms.cryptoKeyEncrypterDecrypter" = [
"serviceAccount:${module.project.service_accounts.robots.sqladmin}"
]
}
2022-04-12 10:01:34 -07:00
}
}
}
module "db" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/cloudsql-instance"
2022-04-12 10:01:34 -07:00
project_id = module.project.project_id
encryption_key_name = module.kms.keys["key-sql"].id
2023-11-24 06:47:45 -08:00
network_config = {
connectivity = {
psa_config = {
private_network = var.vpc.self_link
}
}
}
name = "db"
region = var.region
database_version = "POSTGRES_13"
tier = "db-g1-small"
2022-04-12 10:01:34 -07:00
}
2022-04-12 15:22:54 -07:00
# tftest modules=3 resources=10
2022-04-12 10:01:34 -07:00
```
2023-04-14 09:02:36 -07:00
2023-11-24 06:47:45 -08:00
### Instance with PSC enabled
```hcl
module "db" {
source = "./fabric/modules/cloudsql-instance"
project_id = var.project_id
network_config = {
connectivity = {
psc_allowed_consumer_projects = ["my-project-id"]
}
}
prefix = "myprefix"
name = "db"
region = "europe-west1"
availability_type = "REGIONAL"
database_version = "POSTGRES_13"
tier = "db-g1-small"
}
# tftest modules=1 resources=1
```
2023-04-14 09:02:36 -07:00
### Enable public IP
Use `ipv_enabled` to create instances with a public IP.
```hcl
module "db" {
2023-11-24 06:47:45 -08:00
source = "./fabric/modules/cloudsql-instance"
project_id = var.project_id
network_config = {
connectivity = {
public_ipv4 = true
psa_config = {
private_network = var.vpc.self_link
}
}
}
2023-04-14 09:02:36 -07:00
name = "db"
region = "europe-west1"
tier = "db-g1-small"
database_version = "MYSQL_8_0"
replicas = {
replica1 = { region = "europe-west3", encryption_key_name = null }
}
}
# tftest modules=1 resources=2 inventory=public-ip.yaml
```
2023-07-21 11:14:34 -07:00
### Query Insights
Provide `insights_config` (can be just empty `{}` ) to enable [Query Insights ](https://cloud.google.com/sql/docs/postgres/using-query-insights )
```hcl
module "db" {
2023-11-24 06:47:45 -08:00
source = "./fabric/modules/cloudsql-instance"
project_id = var.project_id
network_config = {
connectivity = {
psa_config = {
private_network = var.vpc.self_link
}
}
}
2023-07-21 11:14:34 -07:00
name = "db"
region = "europe-west1"
database_version = "POSTGRES_13"
tier = "db-g1-small"
insights_config = {
query_string_length = 2048
}
}
# tftest modules=1 resources=1 inventory=insights.yaml
```
2024-01-25 07:29:07 -08:00
### Maintenance Config
Provide `maintenance_config` (can be just empty `{}` ) to enable [Maintenance ](https://cloud.google.com/sql/docs/postgres/maintenance )
```hcl
module "db" {
source = "./fabric/modules/cloudsql-instance"
project_id = var.project_id
network_config = {
connectivity = {
psa_config = {
private_network = var.vpc.self_link
}
}
}
name = "db"
region = "europe-west1"
database_version = "POSTGRES_13"
tier = "db-g1-small"
maintenance_config = {}
}
# tftest modules=1 resources=1
```
### SSL Config
Provide `ssl` (can be just empty `{}` ) to enable [SSL ](https://cloud.google.com/sql/docs/postgres/configure-ssl-instance )
```hcl
module "db" {
source = "./fabric/modules/cloudsql-instance"
project_id = var.project_id
network_config = {
connectivity = {
psa_config = {
private_network = var.vpc.self_link
}
}
}
name = "db"
region = "europe-west1"
database_version = "POSTGRES_13"
tier = "db-g1-small"
ssl = {}
}
# tftest modules=1 resources=1
```
2021-10-07 09:20:07 -07:00
<!-- BEGIN TFDOC -->
## Variables
| name | description | type | required | default |
2021-12-20 23:51:51 -08:00
|---|---|:---:|:---:|:---:|
2024-04-09 23:24:00 -07:00
| [database_version ](variables.tf#L75 ) | Database type and version to create. | < code > string</ code > | ✓ | |
| [name ](variables.tf#L179 ) | Name of primary instance. | < code > string</ code > | ✓ | |
| [network_config ](variables.tf#L184 ) | Network configuration for the instance. Only one between private_network and psc_config can be used. | < code title = "object({ authorized_networks = optional(map(string)) connectivity = object({ public_ipv4 = optional(bool, false) psa_config = optional(object({ private_network = string allocated_ip_ranges = optional(object({ primary = optional(string) replica = optional(string) })) })) psc_allowed_consumer_projects = optional(list(string)) }) })" > object({…}) </ code > | ✓ | |
| [project_id ](variables.tf#L217 ) | The ID of the project where this instances will be created. | < code > string</ code > | ✓ | |
| [region ](variables.tf#L222 ) | Region of the primary instance. | < code > string</ code > | ✓ | |
| [tier ](variables.tf#L265 ) | The machine type to use for the instances. | < code > string</ code > | ✓ | |
2023-08-25 03:12:08 -07:00
| [activation_policy ](variables.tf#L16 ) | This variable specifies when the instance should be active. Can be either ALWAYS, NEVER or ON_DEMAND. Default is ALWAYS. | < code > string</ code > | | < code > " ALWAYS" </ code > |
2023-11-24 06:47:45 -08:00
| [availability_type ](variables.tf#L27 ) | Availability type for the primary replica. Either `ZONAL` or `REGIONAL` . | < code > string</ code > | | < code > " ZONAL" </ code > |
| [backup_configuration ](variables.tf#L33 ) | Backup settings for primary instance. Will be automatically enabled if using MySQL with one or more replicas. | < code title = "object({ enabled = optional(bool, false) binary_log_enabled = optional(bool, false) start_time = optional(string, "23:00") location = optional(string) log_retention_days = optional(number, 7) point_in_time_recovery_enabled = optional(bool) retention_count = optional(number, 7) })" > object({…}) </ code > | | < code title = "{ enabled = false binary_log_enabled = false start_time = "23:00" location = null log_retention_days = 7 point_in_time_recovery_enabled = null retention_count = 7 }" > {…} </ code > |
| [collation ](variables.tf#L56 ) | The name of server instance collation. | < code > string</ code > | | < code > null</ code > |
| [connector_enforcement ](variables.tf#L62 ) | Specifies if connections must use Cloud SQL connectors. | < code > string</ code > | | < code > null</ code > |
2024-04-09 23:24:00 -07:00
| [data_cache ](variables.tf#L68 ) | Enable data cache. Only used for Enterprise MYSQL and PostgreSQL. | < code > bool</ code > | | < code > false</ code > |
| [databases ](variables.tf#L80 ) | Databases to create once the primary instance is created. | < code > list( string) </ code > | | < code > null</ code > |
| [disk_autoresize_limit ](variables.tf#L86 ) | The maximum size to which storage capacity can be automatically increased. The default value is 0, which specifies that there is no limit. | < code > number</ code > | | < code > 0</ code > |
| [disk_size ](variables.tf#L92 ) | Disk size in GB. Set to null to enable autoresize. | < code > number</ code > | | < code > null</ code > |
| [disk_type ](variables.tf#L98 ) | The type of data disk: `PD_SSD` or `PD_HDD` . | < code > string</ code > | | < code > " PD_SSD" </ code > |
| [edition ](variables.tf#L104 ) | The edition of the instance, can be ENTERPRISE or ENTERPRISE_PLUS. | < code > string</ code > | | < code > " ENTERPRISE" </ code > |
| [encryption_key_name ](variables.tf#L110 ) | The full path to the encryption key used for the CMEK disk encryption of the primary instance. | < code > string</ code > | | < code > null</ code > |
| [flags ](variables.tf#L116 ) | Map FLAG_NAME=>VALUE for database-specific tuning. | < code > map( string) </ code > | | < code > null</ code > |
| [gcp_deletion_protection ](variables.tf#L122 ) | Set Google's deletion protection attribute which applies across all surfaces (UI, API, & Terraform). | < code > bool</ code > | | < code > true</ code > |
| [insights_config ](variables.tf#L129 ) | Query Insights configuration. Defaults to null which disables Query Insights. | < code title = "object({ query_string_length = optional(number, 1024) record_application_tags = optional(bool, false) record_client_address = optional(bool, false) query_plans_per_minute = optional(number, 5) })" > object({…}) </ code > | | < code > null</ code > |
| [labels ](variables.tf#L140 ) | Labels to be attached to all instances. | < code > map( string) </ code > | | < code > null</ code > |
| [maintenance_config ](variables.tf#L146 ) | Set maintenance window configuration and maintenance deny period (up to 90 days). Date format: 'yyyy-mm-dd'. | < code title = "object({ maintenance_window = optional(object({ day = number hour = number update_track = optional(string, null) }), null) deny_maintenance_period = optional(object({ start_date = string end_date = string start_time = optional(string, "00:00:00") }), null) })" > object({…}) </ code > | | < code > {} </ code > |
| [prefix ](variables.tf#L207 ) | Optional prefix used to generate instance names. | < code > string</ code > | | < code > null</ code > |
| [replicas ](variables.tf#L227 ) | Map of NAME=> {REGION, KMS_KEY} for additional read replicas. Set to null to disable replica creation. | < code title = "map(object({ region = string encryption_key_name = string }))" > map( object({…})) </ code > | | < code > {} </ code > |
| [root_password ](variables.tf#L236 ) | Root password of the Cloud SQL instance. Required for MS SQL Server. | < code > string</ code > | | < code > null</ code > |
| [ssl ](variables.tf#L242 ) | Setting to enable SSL, set config and certificates. | < code title = "object({ client_certificates = optional(list(string)) require_ssl = optional(bool) ssl_mode = optional(string) })" > object({…}) </ code > | | < code > {} </ code > |
| [terraform_deletion_protection ](variables.tf#L258 ) | Prevent terraform from deleting instances. | < code > bool</ code > | | < code > true</ code > |
| [time_zone ](variables.tf#L270 ) | The time_zone to be used by the database engine (supported only for SQL Server), in SQL Server timezone format. | < code > string</ code > | | < code > null</ code > |
| [users ](variables.tf#L276 ) | Map of users to create in the primary instance (and replicated to other replicas). For MySQL, anything after the first `@` (if present) will be used as the user's host. Set PASSWORD to null if you want to get an autogenerated password. The user types available are: 'BUILT_IN', 'CLOUD_IAM_USER' or 'CLOUD_IAM_SERVICE_ACCOUNT'. | < code title = "map(object({ password = optional(string) type = optional(string) }))" > map( object({…})) </ code > | | < code > null</ code > |
2021-10-07 09:20:07 -07:00
## Outputs
| name | description | sensitive |
|---|---|:---:|
2024-01-25 07:29:07 -08:00
| [client_certificates ](outputs.tf#L24 ) | The CA Certificate used to connect to the SQL Instance via SSL. | ✓ |
| [connection_name ](outputs.tf#L30 ) | Connection name of the primary instance. | |
| [connection_names ](outputs.tf#L35 ) | Connection names of all instances. | |
| [dns_name ](outputs.tf#L43 ) | The dns name of the instance. | |
| [dns_names ](outputs.tf#L48 ) | Dns names of all instances. | |
| [id ](outputs.tf#L56 ) | Fully qualified primary instance id. | |
| [ids ](outputs.tf#L61 ) | Fully qualified ids of all instances. | |
| [instances ](outputs.tf#L69 ) | Cloud SQL instance resources. | ✓ |
| [ip ](outputs.tf#L75 ) | IP address of the primary instance. | |
| [ips ](outputs.tf#L80 ) | IP addresses of all instances. | |
| [name ](outputs.tf#L88 ) | Name of the primary instance. | |
| [names ](outputs.tf#L93 ) | Names of all instances. | |
2023-11-24 06:47:45 -08:00
| [psc_service_attachment_link ](outputs.tf#L101 ) | The link to service attachment of PSC instance. | |
| [psc_service_attachment_links ](outputs.tf#L106 ) | Links to service attachment of PSC instances. | |
| [self_link ](outputs.tf#L114 ) | Self link of the primary instance. | |
| [self_links ](outputs.tf#L119 ) | Self links of all instances. | |
| [user_passwords ](outputs.tf#L127 ) | Map of containing the password of all users created through terraform. | ✓ |
2021-10-07 09:20:07 -07:00
<!-- END TFDOC -->