jprdonnelly/terraform-google-sql
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Improved module documentation

Browse Source
This commit is contained in:
Petri Autero
2019-02-14 23:58:35 +02:00
parent 58f9e9e2db
commit ee9fafb942
1 changed files with 45 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
modules/cloud-sql/README.md
View File

@@ -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.