Secure-cloud-run readme update

examples/secure_cloud_run/README.md

@@ -1,17 +1,57 @@
-# Simple Cloud Run Example
+# Secure Cloud Run Example
 
-This example showcases the basic deployment of containerized applications on Cloud Run, along with domain mapping and IAM policy for the service.
+This example showcases the deployment of Secure Cloud Run, along with domain mapping and IAM policy for the service.
 
 The resources/services/activations/deletions that this example will create/trigger are:
 
-* Creates a Cloud Run service with provided name and container
-* Creates a Service Account to be used by Cloud Run Service.
+* Creates Firewall rules on your **VPC Project**.
+  * Serverless to VPC Connector
+  * VPC Connector to Serverless
+  * VPC Connector to LB
+  * VPC Connector Health Checks
+* Creates a sub network to VPC Connector usage purpose.
+* Creates Serverless Connector on your **VPC Project** or **Serverless Project**. Refer the comparison below:
+  * Advantages of creating connectors in the [VPC Project](https://cloud.google.com/run/docs/configuring/connecting-shared-vpc#host-project)
+  * Advantages of creating connectors in the [Serverless Project](https://cloud.google.com/run/docs/configuring/connecting-shared-vpc#service-projects)
+* Grant the necessary roles for Cloud Run are able to use VPC Connector on your Shared VPC when creating VPC Connector in host project.
+  * Grant Network User role to Cloud Services service account.
+  * Grant VPC Access User to Cloud Run Service Identity when deploying VPC Access.
+  * Creates KMS Keyring and Key for [customer managed encryption keys](https://cloud.google.com/run/docs/securing/using-cmek) in the **KMS Project** to be used by Cloud Run.
+  * Enables Organization Policies related to Cloud Run in the **Serverless Project**.
+  * Allow Ingress only from internal and Cloud Load Balancing.
+  * Allow VPC Egress to Private Ranges Only.
+  * Creates a Cloud Run Service.
+  * Creates a Load Balancer Service using Google-managed SSL certificates.
+  * Creates Cloud Armor Service only including the preconfigured rules for SQLi, XSS, LFI, RCE, RFI, Scannerdetection, Protocolattack and Sessionfixation.
+
+## Organization Policies
+
+By default, this example will apply 2 organization policies at the project level for the **Serverless Project**.
+  * Allow Ingress only from internal and Cloud Load Balancing.
+  * Allow VPC Egress to Private Ranges Only.
+
+To the organization policies to be applied at folder or organization level, the `policy_for` variable needs to be changed. Possible values: [\"project\", \"folder\", \"organization\"] and the variables `folder_id` or `organization_id` need to be be filled up, respectively.
+
+## Usage
+
+To provision this example, run the following from within this directory:
+
+- Rename `terraform.example.tfvars` to `terraform.tfvars` by running `mv terraform.example.tfvars terraform.tfvars` and update the file with values from your environment.
+- `terraform init` to get the plugins
+- `terraform plan` to see the infrastructure plan
+- `terraform apply` to apply the infrastructure build
+
+### Clean up
+
+- Run `terraform destroy` to clean up your environment.
 
 ## Assumptions and Prerequisites
 
-This example assumes that below mentioned prerequisites are in place before consuming the example.
+This example assumes that below mentioned pre-requisites are in place before consuming the example.
 
-* All required APIs are enabled in the GCP Project
+* All required APIs are enabled in the GCP Project.
+* An Organization.
+* A Billing Account.
 
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Inputs
@@ -21,7 +61,7 @@ This example assumes that below mentioned prerequisites are in place before cons
 | cloud\_run\_sa | Service account to be used on Cloud Run. | `string` | n/a | yes |
 | domain | Domain name to run the load balancer on. Used if `ssl` is `true`. | `string` | n/a | yes |
 | folder\_id | The folder ID to apply the policy to. | `string` | `""` | no |
-| ip\_cidr\_range | The range of internal addresses that are owned by this subnetwork. Provide this property when you create the subnetwork. For example, 10.0.0.0/28 or 192.168.0.0/28. Ranges must be unique and non-overlapping within a network. Only IPv4 is supported | `string` | n/a | yes |
+| ip\_cidr\_range | The range of internal addresses that are owned by the subnetwork and which is going to be used by VPC Connector. For example, 10.0.0.0/28 or 192.168.0.0/28. Ranges must be unique and non-overlapping within a network. Only IPv4 is supported. | `string` | n/a | yes |
 | kms\_project\_id | The project where KMS will be created. | `string` | n/a | yes |
 | organization\_id | The organization ID to apply the policy to. | `string` | `""` | no |
 | policy\_for | Policy Root: set one of the following values to determine where the policy is applied. Possible values: ["project", "folder", "organization"]. | `string` | `"project"` | no |
@@ -66,23 +106,20 @@ These sections describe requirements for using this example.
 ### Software
 
 * [Terraform](https://www.terraform.io/downloads.html) ~> v0.13+
-* [Terraform Provider for GCP](/~https://github.com/terraform-providers/terraform-provider-google) ~> v3.53+
-* [Terraform Provider for GCP Beta](/~https://github.com/terraform-providers/terraform-provider-google-beta) ~>
-  v3.53+
+* [Terraform Provider for GCP](/~https://github.com/terraform-providers/terraform-provider-google) >= 3.53, < 5.0
+* [Terraform Provider for GCP Beta](/~https://github.com/terraform-providers/terraform-provider-google-beta) >= 3.53, < 5.0
 
 ### Service Account
 
 A service account can be used with required roles to execute this example:
 
-* Cloud Run Admin: `roles/run.admin`
-
-Know more about [Cloud Run Deployment Permissions](https://cloud.google.com/run/docs/reference/iam/roles#additional-configuration).
-
-The [Project Factory module](https://registry.terraform.io/modules/terraform-google-modules/project-factory/google/latest) and the
-[IAM module](https://registry.terraform.io/modules/terraform-google-modules/iam/google/latest) may be used in combination to provision a service account with the necessary roles applied.
-
-### APIs
-
-A project with the following APIs enabled must be used to host the main resource of this example:
-
-* Google Cloud Run: `run.googleapis.com`
+* Compute Shared VPC Admin: `roles/compute.xpnAdmin`
+* Network Admin: `roles/compute.networkAdmin`
+* Security Admin: `roles/compute.securityAdmin`
+* Serverless VPC Access Admin: `roles/vpcaccess.admin`
+* Cloud KMS Admin: `roles/cloudkms.admin`
+* Security Admin: `roles/compute.securityAdmin`
+* Serverless VPC Access Admin: `roles/vpcaccess.admin`
+* Cloud Run Developer: `roles/run.developer`
+* Compute Network User: `roles/compute.networkUser`
+* Artifact Registry Reader: `roles/artifactregistry.reader`

examples/secure_cloud_run/terraform.example.tfvars

@@ -0,0 +1,23 @@
+/**
+ * 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
+ *
+ *      http://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.
+ */
+
+cloud_run_sa          = "YOUR-CLOUDRUN-SERVICE-ACCOUNT-EMAIL"
+domain                = "YOUR-DOMAIN-NAME"
+ip_cidr_range         = "0.0.0.0/28"
+kms_project_id        = "YOUR-KMS-PROJECT-ID"
+vpc_project_id        = "YOUR-VPC-PROJECT-ID"
+serverless_project_id = "YOUR-SERVERLESS-PROJECT-ID"
+shared_vpc_name       = "YOUR-SHARED-VPC-NAME"

examples/secure_cloud_run/variables.tf

@@ -75,6 +75,6 @@ variable "resource_names_suffix" {
 }
 
 variable "ip_cidr_range" {
-  description = "The range of internal addresses that are owned by this subnetwork. Provide this property when you create the subnetwork. For example, 10.0.0.0/28 or 192.168.0.0/28. Ranges must be unique and non-overlapping within a network. Only IPv4 is supported"
+  description = "The range of internal addresses that are owned by the subnetwork and which is going to be used by VPC Connector. For example, 10.0.0.0/28 or 192.168.0.0/28. Ranges must be unique and non-overlapping within a network. Only IPv4 is supported."
   type        = string
 }

modules/secure-cloud-run/README.md

@@ -1,5 +1,62 @@
 # Secure Cloud Run
 
+This module handles the deployment required for Cloud Run usage. Secure-cloud-run module will call the secure-cloud-run-core, secure-cloud-run-net and secure-cloud-run-net modules.
+
+When using a Shared VPC, you can chose where to create the VPC Connector.
+
+_Note:_ When using a single VPC you should provides VPC and Serverless project id with the same value and the value for `connector_on_host_project` variable must be `false`.
+
+The resources/services/activations/deletions that this module will create/trigger are:
+
+* Creates Firewall rules on your **VPC Project**.
+  * Serverless to VPC Connector
+  * VPC Connector to Serverless
+  * VPC Connector to LB
+  * VPC Connector Health Checks
+* Creates a sub network to VPC Connector usage purpose.
+* Creates Serverless Connector on your **VPC Project** or **Serverless Project**. Refer the comparison below:
+  * Advantages of creating connectors in the [VPC Project](https://cloud.google.com/run/docs/configuring/connecting-shared-vpc#host-project)
+  * Advantages of creating connectors in the [Serverless Project](https://cloud.google.com/run/docs/configuring/connecting-shared-vpc#service-projects)
+* Grant the necessary roles for Cloud Run are able to use VPC Connector on your Shared VPC when creating VPC Connector in host project.
+  * Grant Network User role to Cloud Services service account.
+  * Grant VPC Access User to Cloud Run Service Identity when deploying VPC Access.
+
+* Secure-cloud-run-security module will apply:
+  * Creates KMS Keyring and Key for [customer managed encryption keys](https://cloud.google.com/run/docs/securing/using-cmek) in the **KMS Project** to be used by Cloud Run.
+  * Enables Organization Policies related to Cloud Run in the **Serverless Project**.
+  * Allow Ingress only from internal and Cloud Load Balancing.
+  * Allow VPC Egress to Private Ranges Only.
+
+* Secure-cloud-run-core module will apply:
+  * Creates a Cloud Run Service.
+  * Creates a Load Balancer Service using Google-managed SSL certificates.
+  * Creates Cloud Armor Service only including the preconfigured rules for SQLi, XSS, LFI, RCE, RFI, Scannerdetection, Protocolattack and Sessionfixation.
+
+## Usage
+
+Basic usage of this module is as follows:
+
+```hcl
+module "secure_cloud_run" {
+  source = "../modules/secure-cloud-run"
+
+  vpc_project_id                          = <VPC Project ID>
+  kms_project_id                          = <KMS Project ID>
+  serverless_project_id                   = <Serverless Project ID>
+  domain                                  = <Domain>
+  shared_vpc_name                         = <Shared VPC Name
+  ip_cidr_range                           = <IP CIDR Range>
+  service_name                            = <Service Name>
+  location                                = <Location>
+  region                                  = <Region>
+  image                                   = <Image>
+  cloud_run_sa                            = <Cloud Run Service Account>
+  artifact_registry_repository_location   = <Artifact Registry Repository Location>
+  artifact_registry_repository_name       = <Artifact Registry Repository Name>
+  artifact_registry_repository_project_id = <Artifact Registry Repository Project ID>
+}
+```
+
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Inputs
 
@@ -16,7 +73,7 @@
 | folder\_id | The folder ID to apply the policy to. | `string` | `""` | no |
 | grant\_artifact\_register\_reader | When true it will grant permission to read an image from your artifact registry. When true, you must provide `artifact_registry_repository_project_id`, `artifact_registry_repository_location` and `artifact_registry_repository_name`. | `bool` | `false` | no |
 | image | Image url to be deployed on Cloud Run. | `string` | n/a | yes |
-| ip\_cidr\_range | The range of internal addresses that are owned by this subnetwork. Provide this property when you create the subnetwork. For example, 10.0.0.0/8 or 192.168.0.0/16. Ranges must be unique and non-overlapping within a network. Only IPv4 is supported | `string` | n/a | yes |
+| ip\_cidr\_range | The range of internal addresses that are owned by the subnetwork and which is going to be used by VPC Connector. For example, 10.0.0.0/28 or 192.168.0.0/28. Ranges must be unique and non-overlapping within a network. Only IPv4 is supported. | `string` | n/a | yes |
 | key\_name | The name of KMS Key to be created and used in Cloud Run. | `string` | `"cloud-run-kms-key"` | no |
 | key\_protection\_level | The protection level to use when creating a version based on this template. Possible values: ["SOFTWARE", "HSM"] | `string` | `"HSM"` | no |
 | key\_rotation\_period | Period of key rotation in seconds. | `string` | `"2592000s"` | no |
@@ -54,3 +111,48 @@
 | service\_url | Url of the created service. |
 
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+
+## Requirements
+
+### Software
+
+The following dependencies must be available:
+
+* [Terraform](https://www.terraform.io/downloads.html) >= 0.13.0
+* [Terraform Provider for GCP](/~https://github.com/terraform-providers/terraform-provider-google) < 5.0
+
+### APIs
+
+The Secure-cloud-run project will enable the following APIs to the Serverlesss Project:
+
+* Google VPC Access API: `vpcaccess.googleapis.com`
+* Compute API: `compute.googleapis.com`
+* Container Registry API: `container.googleapis.com`
+* Cloud Run API: `run.googleapis.com`
+* Cloud KMS API: `cloudkms.googleapis.com`
+
+The Secure-cloud-run project will enable the following APIs to the VPC Project:
+
+* Google VPC Access API: `vpcaccess.googleapis.com`
+* Compute API: `compute.googleapis.com`
+
+### Service Account
+
+A service account with the following roles must be used to provision
+the resources of this module:
+
+* VPC Project
+  * Compute Shared VPC Admin: `roles/compute.xpnAdmin`
+  * Network Admin: `roles/compute.networkAdmin`
+  * Security Admin: `roles/compute.securityAdmin`
+  * Serverless VPC Access Admin: `roles/vpcaccess.admin`
+* KMS Project
+  * Cloud KMS Admin: `roles/cloudkms.admin`
+* Serverless Project
+  * Security Admin: `roles/compute.securityAdmin`
+  * Serverless VPC Access Admin: `roles/vpcaccess.admin`
+  * Cloud Run Developer: `roles/run.developer`
+  * Compute Network User: `roles/compute.networkUser`
+  * Artifact Registry Reader: `roles/artifactregistry.reader`
+
+**Note:** [Secret Manager Secret Accessor](https://cloud.google.com/run/docs/configuring/secrets#access-secret) role must be granted to the Cloud Run service account to allow read access on the secret.

modules/secure-cloud-run/variables.tf

@@ -117,7 +117,7 @@ variable "key_protection_level" {
 }
 
 variable "ip_cidr_range" {
-  description = "The range of internal addresses that are owned by this subnetwork. Provide this property when you create the subnetwork. For example, 10.0.0.0/8 or 192.168.0.0/16. Ranges must be unique and non-overlapping within a network. Only IPv4 is supported"
+  description = "The range of internal addresses that are owned by the subnetwork and which is going to be used by VPC Connector. For example, 10.0.0.0/28 or 192.168.0.0/28. Ranges must be unique and non-overlapping within a network. Only IPv4 is supported."
   type        = string
 }