From ee9fafb9427eed2045d86a87ffccd7a1746f44ab Mon Sep 17 00:00:00 2001 From: Petri Autero Date: Thu, 14 Feb 2019 23:58:35 +0200 Subject: [PATCH] Improved module documentation --- modules/cloud-sql/README.md | 59 ++++++++++++++++++++++++++++--------- 1 file changed, 45 insertions(+), 14 deletions(-) diff --git a/modules/cloud-sql/README.md b/modules/cloud-sql/README.md index 72c92a7..3520331 100644 --- a/modules/cloud-sql/README.md +++ b/modules/cloud-sql/README.md @@ -1,9 +1,9 @@ -# MySQL Module +# Cloud SQL Module -This module creates a [Google Cloud SQL](https://cloud.google.com/sql/) [MySQL](https://cloud.google.com/sql/docs/mysql/) cluster. +This module creates a [Google Cloud SQL](https://cloud.google.com/sql/) cluster. The cluster is managed by Google, automating backups, replication, patches, and updates. -This module helps you run [MySQL](https://cloud.google.com/sql/docs/mysql/), see [postgres](../postgresql) for running [PostgreSQL](https://cloud.google.com/sql/docs/postgres/). +This module helps you run [MySQL](https://cloud.google.com/sql/docs/mysql/) and [PostgreSQL](https://cloud.google.com/sql/docs/postgres/) databases in [Google Cloud](https://cloud.google.com/). ## How do you use this module? @@ -11,40 +11,71 @@ See the [examples](/examples) folder for an example. ## How do you configure this module? -This module allows you to configure a number of parameters, such as backup windows, maintenance window, replicas -and encryption. For a list of all available variables and their descriptions, see [variables.tf](./variables.tf). +This module allows you to configure a number of parameters, such as high availability, backup windows, maintenance window and replicas. +For a list of all available variables and their descriptions, see [variables.tf](./variables.tf). ## How do you connect to the database? **Cloud SQL instances are created in a producer network (a VPC network internal to Google). They are not created in your VPC network. See https://cloud.google.com/sql/docs/mysql/private-ip** -You can use both [public IP](https://cloud.google.com/sql/docs/mysql/connect-admin-ip) and [private IP](https://cloud.google.com/sql/docs/mysql/private-ip) to connect to a Cloud SQL instance. +You can use both public IP and private IP to connect to a Cloud SQL instance. Neither connection method affects the other; you must protect the public IP connection whether the instance is configured to use private IP or not. -You can also use the [Cloud SQL Proxy](https://cloud.google.com/sql/docs/mysql/connect-admin-proxy) to connect to an instance that is also configured to use private IP. The proxy can connect using either the private IP address or a public IP address. +You can also use the [Cloud SQL Proxy for MySQL](https://cloud.google.com/sql/docs/mysql/sql-proxy) and [Cloud SQL Proxy for PostgreSQL](https://cloud.google.com/sql/docs/postgres/sql-proxy) +to connect to an instance that is also configured to use private IP. The proxy can connect using either the private IP address or a public IP address. This module provides the connection details as [Terraform output variables](https://www.terraform.io/intro/getting-started/outputs.html): -1. **First IP Address** `first_ip_address`: The first IPv4 address of the addresses assigned to the instance. If the instance has only public IP, it is the [public IP address](https://cloud.google.com/sql/docs/mysql/connect-admin-ip). If it has only private IP, it the [private IP address](https://cloud.google.com/sql/docs/mysql/private-ip). If it has both, it is the first item in the list and full IP address details are in `instance_ip_addresses`. -1. **Proxy connection** `proxy_connection`: Instance path for connecting with Cloud SQL Proxy; see [Connecting mysql Client Using the Cloud SQL Proxy](https://cloud.google.com/sql/docs/mysql/connect-admin-proxy). -1. TODO: **Replica endpoints** `replica_endpoints`: A comma-separated list of all DB instance URLs in the cluster, including the primary and all - read replicas. Use these URLs for reads (see "How do you scale this DB?" below). +1. **Master First IP Address** `master_first_ip_address`: The first IPv4 address of the addresses assigned to the instance. If the instance has only public IP, it is the [public IP address](https://cloud.google.com/sql/docs/mysql/connect-admin-ip). If it has only private IP, it the [private IP address](https://cloud.google.com/sql/docs/mysql/private-ip). If it has both, it is the first item in the list and full IP address details are in `instance_ip_addresses`. +1. **Master Proxy connection** `master_proxy_connection`: Instance path for connecting with Cloud SQL Proxy; see [Connecting mysql Client Using the Cloud SQL Proxy](https://cloud.google.com/sql/docs/mysql/connect-admin-proxy). +1. **Read Replica First IP Addresses** `read_replica_first_ip_addresses`: A list of all read replica IP addresses in the cluster. Use these addresses for reads (see "How do you scale this database?" below). +1. **Read Replica Proxy Connections** `read_replica_proxy_connections`: A list of instance paths for connecting with Cloud SQL Proxy; see [Connecting Using the Cloud SQL Proxy](https://cloud.google.com/sql/docs/mysql/connect-admin-proxy). You can programmatically extract these variables in your Terraform templates and pass them to other resources. You'll also see the variables at the end of each `terraform apply` call or if you run `terraform output`. -For full connectivity options and detailed documentation, see [Connecting to Cloud SQL from External Applications](https://cloud.google.com/sql/docs/mysql/connect-external-app). +For full connectivity options and detailed documentation, see [Connecting to Cloud SQL MySQL from External Applications](https://cloud.google.com/sql/docs/mysql/connect-external-app) and [Connecting to Cloud SQL PostgreSQL from External Applications](https://cloud.google.com/sql/docs/postgres/external-connection-methods). + +## How do you configure High Availability? + +You can enable High Availability using the `enable_failover_replica` input variable. + +### High Availability for MySQL + +The configuration is made up of a primary instance (master) in the primary zone (`master_zone` input variable) and a failover replica in the secondary zone (`failover_replica_zone` input variable). +The failover replica is configured with the same database flags, users and passwords, authorized applications and networks, and databases as the primary instance. + +For full details about MySQL High Availability, see https://cloud.google.com/sql/docs/mysql/high-availability + +### High Availability for PostgreSQL + +A Cloud SQL PostgreSQL instance configured for HA is also called a _regional instance_ and is located in a primary and secondary zone within the configured region. Within a regional instance, +the configuration is made up of a primary instance (master) and a standby instance. You control the primary zone for the master instance +with input variable `master_zone` and Google will automatically place the standby instance in another zone. + +For full details about PostgreSQL High Availability, see https://cloud.google.com/sql/docs/postgres/high-availability + + +## How do you secure this database? + +Cloud SQL customer data is encrypted when stored in database tables, temporary files, and backups. +External connections can be encrypted by using SSL, or by using the Cloud SQL Proxy, which automatically encrypts traffic to and from the database. +If you do not use the proxy, you can enforce SSL for external connections using the `require_ssl` input variable. + +For further information, see https://cloud.google.com/blog/products/gcp/best-practices-for-securing-your-google-cloud-databases and +https://cloud.google.com/sql/faq#encryption ## How do you scale this database? -* **Storage**: Cloud SQL manages storage for you, automatically growing cluster volume up to 10TB. +* **Storage**: Cloud SQL manages storage for you, automatically growing cluster volume up to 10TB You can set the +initial disk size using the `disk_size` input variable. * **Vertical scaling**: To scale vertically (i.e. bigger DB instances with more CPU and RAM), use the `machine_type` input variable. For a list of Cloud SQL Machine Types, see [Cloud SQL Pricing](https://cloud.google.com/sql/pricing#2nd-gen-pricing). -* **Horizontal scaling**: To scale horizontally, you can add more replicas using the `instance_count` input variable, +* **Horizontal scaling**: To scale horizontally, you can add more replicas using the `num_read_replicas` and `read_replica_zones` input variables, and the module will automatically deploy the new instances, sync them to the master, and make them available as read replicas.