Improve README

examples/data-solutions/cloudsql-multiregion/README.md

@@ -1,18 +1,62 @@
 # Cloud SQL instance with multi-region read replicas
 
-TBD
+This example creates the [Cloud SQL instance](https://cloud.google.com/sql) with multi-reagion read replica solution described in the [`Cloud SQL for PostgreSQL disaster recovery`](https://cloud.google.com/architecture/cloud-sql-postgres-disaster-recovery-complete-failover-fallback) article. 
+
+The solution is resiliant to a regional outage. To get familiar with the procedure needed in the unfortunate case of a disaster recovery, we suggest to follow steps described in the [`Simulating a disaster (region outage)`](https://cloud.google.com/architecture/cloud-sql-postgres-disaster-recovery-complete-failover-fallback#phase-2) article.
+
+The solution will use:
+- Postgre SQL instance with Private IP
+
+This is the high level diagram:
+
+![Cloud SQL multi-region.](diagram.png "Cloud SQL multi-region")
+
+## Move to real use case consideration
+In the example we implemented some compromise to keep the example minimal and easy to read. On a real word use case, you may evaluate the option to:
+ - Configure a Shared-VPC
+ - Use VPC-SC to mitigate data exfiltration
+
+## Deploy your enviroment
+
+We assume the identiy running the following steps has the following role:
+ - `resourcemanager.projectCreator` in case a new project will be created.
+ - `owner` on the project in case you use an existing project. 
+
+Run Terraform init:
+
+```
+$ terraform init
+```
+
+Configure the Terraform variable in your `terraform.tfvars` file. You need to spefify at least the following variables:
+
+```
+data_eng_principals = ["user:data-eng@domain.com"]
+project_id      = "datalake-001"
+prefix          = "prefix"
+```
+
+You can run now:
+
+```
+$ terraform apply
+```
+
+You should see the output of the Terraform script with resources created and some command pre-created for you to run the example following steps below.
+TBC
 <!-- BEGIN TFDOC -->
 
 ## Variables
 
 | name | description | type | required | default |
 |---|---|:---:|:---:|:---:|
-| [prefix](variables.tf#L23) | Unique prefix used for resource names. Not used for project if 'project_create' is null. | <code>string</code> | ✓ |  |
-| [project_id](variables.tf#L37) | Project id, references existing project if `project_create` is null. | <code>string</code> | ✓ |  |
-| [regions](variables.tf#L42) | Map of instance_name => location where instances will be deployed. | <code>map&#40;string&#41;</code> | ✓ |  |
+| [prefix](variables.tf#L29) | Unique prefix used for resource names. Not used for project if 'project_create' is null. | <code>string</code> | ✓ |  |
+| [project_id](variables.tf#L43) | Project id, references existing project if `project_create` is null. | <code>string</code> | ✓ |  |
+| [regions](variables.tf#L48) | Map of instance_name => location where instances will be deployed. | <code>map&#40;string&#41;</code> | ✓ |  |
 | [cloudsql_psa_range](variables.tf#L17) | Range used for the Private Service Access. | <code>string</code> |  | <code>&#34;10.60.0.0&#47;16&#34;</code> |
-| [project_create](variables.tf#L28) | Provide values if project creation is needed, uses existing project if null. Parent is in 'folders/nnn' or 'organizations/nnn' format. | <code title="object&#40;&#123;&#10;  billing_account_id &#61; string&#10;  parent             &#61; string&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> |  | <code>null</code> |
-| [tier](variables.tf#L51) | The machine type to use for the instances. See See https://cloud.google.com/sql/docs/postgres/create-instance#machine-types. | <code>string</code> |  | <code>&#34;db-g1-small&#34;</code> |
+| [database_version](variables.tf#L23) | Database type and version to create. | <code>string</code> |  | <code>&#34;POSTGRES_13&#34;</code> |
+| [project_create](variables.tf#L34) | Provide values if project creation is needed, uses existing project if null. Parent is in 'folders/nnn' or 'organizations/nnn' format. | <code title="object&#40;&#123;&#10;  billing_account_id &#61; string&#10;  parent             &#61; string&#10;&#125;&#41;">object&#40;&#123;&#8230;&#125;&#41;</code> |  | <code>null</code> |
+| [tier](variables.tf#L57) | The machine type to use for the instances. See See https://cloud.google.com/sql/docs/postgres/create-instance#machine-types. | <code>string</code> |  | <code>&#34;db-g1-small&#34;</code> |
 
 ## Outputs
 

examples/data-solutions/cloudsql-multiregion/backend.tf.sample

@@ -0,0 +1,30 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# The `impersonate_service_account` option require the identity launching terraform
+# role `roles/iam.serviceAccountTokenCreator` on the Service Account specified.
+
+terraform {
+  backend "gcs" {
+    bucket                      = "BUCKET_NAME"
+    prefix                      = "PREFIX"
+    impersonate_service_account = "SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"
+  }
+}
+provider "google" {
+  impersonate_service_account = "SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"
+}
+provider "google-beta" {
+  impersonate_service_account = "SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"
+}

examples/data-solutions/cloudsql-multiregion/main.tf

@@ -40,9 +40,9 @@ module "db" {
   source           = "../../../modules/cloudsql-instance"
   project_id       = module.project.project_id
   network          = module.vpc.self_link
-  name             = "db"
+  name             = "${var.prefix}-db"
   region           = var.regions.primary
-  database_version = "POSTGRES_13"
+  database_version = var.database_version
   tier             = var.tier
 
   replicas = {

examples/data-solutions/cloudsql-multiregion/terraform.tfvars.sample

@@ -0,0 +1,2 @@
+project_id          = "datalake-001"
+prefix              = "prefix"

examples/data-solutions/cloudsql-multiregion/variables.tf

@@ -20,6 +20,12 @@ variable "cloudsql_psa_range" {
   default     = "10.60.0.0/16"
 }
 
+variable "database_version" {
+  description = "Database type and version to create."
+  type        = string
+  default     = "POSTGRES_13"
+}
+
 variable "prefix" {
   description = "Unique prefix used for resource names. Not used for project if 'project_create' is null."
   type        = string
@@ -46,6 +52,10 @@ variable "regions" {
     condition     = contains(keys(var.regions), "primary")
     error_message = "Regions map must contain `primary` as a key."
   }
+  default = {
+    primary = "europe-west1"
+    replica = "europe-west3"
+  }
 }
 
 variable "tier" {