2024-05-12 03:00:39 -07:00
# Cloud SQL instance module
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.
2024-05-12 03:00:39 -07:00
<!-- BEGIN TOC -->
- [Examples ](#examples )
- [Simple example ](#simple-example )
- [Cross-regional read replica ](#cross-regional-read-replica )
- [Custom flags, databases and users ](#custom-flags-databases-and-users )
- [CMEK encryption ](#cmek-encryption )
- [Instance with PSC enabled ](#instance-with-psc-enabled )
- [Enable public IP ](#enable-public-ip )
- [Query Insights ](#query-insights )
- [Maintenance Config ](#maintenance-config )
- [SSL Config ](#ssl-config )
- [Variables ](#variables )
- [Outputs ](#outputs )
- [Fixtures ](#fixtures )
<!-- END TOC -->
## Examples
### Simple example
2021-10-07 09:20:07 -07:00
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
2024-05-12 03:00:39 -07:00
parent = var.folder_id
name = "db-prj"
prefix = var.prefix
2021-10-07 09:20:07 -07:00
services = [
2024-05-12 03:00:39 -07:00
"servicenetworking.googleapis.com",
"sqladmin.googleapis.com",
2021-10-07 09:20:07 -07:00
]
}
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"
2024-05-12 03:00:39 -07:00
# need only one - psa_config or subnets_psc
2024-04-16 08:02:36 -07:00
psa_configs = [{
2024-05-12 03:00:39 -07:00
ranges = { cloud-sql = "10.60.0.0/16" }
deletion_policy = "ABANDON"
2024-04-16 08:02:36 -07:00
}]
2024-05-12 03:00:39 -07:00
subnets_psc = [
{
ip_cidr_range = "10.0.3.0/24"
name = "psc"
region = var.region
}
]
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
}
2024-05-12 03:00:39 -07:00
# psc_allowed_consumer_projects = [var.project_id]
2023-11-24 06:47:45 -08:00
}
}
2024-05-12 03:00:39 -07:00
name = "db"
region = var.region
database_version = "POSTGRES_13"
tier = "db-g1-small"
gcp_deletion_protection = false
terraform_deletion_protection = false
2021-10-07 09:20:07 -07:00
}
2024-05-12 03:00:39 -07:00
# tftest modules=3 resources=14 inventory=simple.yaml e2e
2021-10-07 09:20:07 -07:00
```
2024-05-12 03:00:39 -07:00
### Cross-regional read replica
2021-10-07 09:20:07 -07:00
```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"
2024-05-12 03:00:39 -07:00
prefix = "myprefix"
region = var.region
2021-10-07 09:20:07 -07:00
database_version = "POSTGRES_13"
tier = "db-g1-small"
replicas = {
2024-05-12 03:00:39 -07:00
replica1 = { region = "europe-west3" }
replica2 = { region = "us-central1" }
2021-10-07 09:20:07 -07:00
}
2024-05-12 03:00:39 -07:00
gcp_deletion_protection = false
terraform_deletion_protection = false
2021-10-07 09:20:07 -07:00
}
2024-05-12 03:00:39 -07:00
# tftest modules=1 resources=3 inventory=replicas.yaml e2e
2021-10-07 09:20:07 -07:00
```
2024-05-12 03:00:39 -07:00
### Custom flags, databases and users
2021-10-07 09:20:07 -07:00
```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"
2024-05-12 03:00:39 -07:00
region = var.region
2021-10-07 09:20:07 -07:00
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
}
2024-05-12 03:00:39 -07:00
gcp_deletion_protection = false
terraform_deletion_protection = false
2021-10-07 09:20:07 -07:00
}
2024-05-12 03:00:39 -07:00
# tftest modules=1 resources=6 inventory=custom.yaml e2e
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
2024-04-16 08:02:36 -07:00
2022-04-12 10:01:34 -07:00
```hcl
module "db" {
2022-09-06 08:46:09 -07:00
source = "./fabric/modules/cloudsql-instance"
2024-05-12 03:00:39 -07:00
project_id = var.project_id
encryption_key_name = var.kms_key.id
2023-11-24 06:47:45 -08:00
network_config = {
connectivity = {
psa_config = {
private_network = var.vpc.self_link
}
}
}
2024-05-12 03:00:39 -07:00
name = "db"
region = var.region
database_version = "POSTGRES_13"
tier = "db-g1-small"
gcp_deletion_protection = false
terraform_deletion_protection = false
2022-04-12 10:01:34 -07:00
}
2024-05-12 03:00:39 -07:00
# tftest modules=1 resources=2 fixtures=fixtures/cloudsql-kms-iam-grant.tf e2e
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 = {
2024-05-12 03:00:39 -07:00
psc_allowed_consumer_projects = [var.project_id]
2023-11-24 06:47:45 -08:00
}
}
prefix = "myprefix"
name = "db"
2024-05-12 03:00:39 -07:00
region = var.region
2023-11-24 06:47:45 -08:00
availability_type = "REGIONAL"
database_version = "POSTGRES_13"
tier = "db-g1-small"
2024-05-12 03:00:39 -07:00
gcp_deletion_protection = false
terraform_deletion_protection = false
2023-11-24 06:47:45 -08:00
}
2024-05-12 03:00:39 -07:00
# tftest modules=1 resources=1 inventory=psc.yaml e2e
2023-11-24 06:47:45 -08:00
```
2023-04-14 09:02:36 -07:00
### Enable public IP
2024-05-12 03:00:39 -07:00
Use `public_ipv4` to create instances with a public IP.
2023-04-14 09:02:36 -07:00
```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
}
}
}
2024-05-12 03:00:39 -07:00
name = "db"
region = var.region
tier = "db-g1-small"
database_version = "MYSQL_8_0"
gcp_deletion_protection = false
terraform_deletion_protection = false
2023-04-14 09:02:36 -07:00
}
2024-05-12 03:00:39 -07:00
# tftest modules=1 resources=1 inventory=public-ip.yaml e2e
2023-04-14 09:02:36 -07:00
```
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"
2024-05-12 03:00:39 -07:00
region = var.region
2023-07-21 11:14:34 -07:00
database_version = "POSTGRES_13"
tier = "db-g1-small"
insights_config = {
query_string_length = 2048
}
2024-05-12 03:00:39 -07:00
gcp_deletion_protection = false
terraform_deletion_protection = false
2023-07-21 11:14:34 -07:00
}
2024-05-12 03:00:39 -07:00
# tftest modules=1 resources=1 inventory=insights.yaml e2e
2023-07-21 11:14:34 -07:00
```
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"
2024-05-12 03:00:39 -07:00
region = var.region
2024-01-25 07:29:07 -08:00
database_version = "POSTGRES_13"
tier = "db-g1-small"
2024-05-12 03:00:39 -07:00
maintenance_config = {}
gcp_deletion_protection = false
terraform_deletion_protection = false
2024-01-25 07:29:07 -08:00
}
2024-05-12 03:00:39 -07:00
# tftest modules=1 resources=1 e2e
2024-01-25 07:29:07 -08:00
```
### 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"
2024-05-12 03:00:39 -07:00
region = var.region
2024-01-25 07:29:07 -08:00
database_version = "POSTGRES_13"
tier = "db-g1-small"
2024-05-12 03:00:39 -07:00
ssl = {}
gcp_deletion_protection = false
terraform_deletion_protection = false
2024-01-25 07:29:07 -08:00
}
2024-05-12 03:00:39 -07:00
# tftest modules=1 resources=1 e2e
2024-01-25 07:29:07 -08:00
```
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 > |
2024-05-12 03:00:39 -07:00
| [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 = optional(string) }))" > map( object({…})) </ code > | | < code > {} </ code > |
2024-04-09 23:24:00 -07:00
| [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. | ✓ |
2024-05-12 03:00:39 -07:00
## Fixtures
- [cloudsql-kms-iam-grant.tf ](../../tests/fixtures/cloudsql-kms-iam-grant.tf )
2021-10-07 09:20:07 -07:00
<!-- END TFDOC -->