cloud-run-explore

Cloud Run Explore

Introduction

This blueprint contains all the necessary Terraform modules to build and publicly expose Cloud Run services in a variety of use cases.

The content of this blueprint corresponds to the chapter 'Exploring Cloud Run - My serverless "Hello, World!"' of the Serverless Networking Guide. This guide is an easy to follow introduction to Cloud Run, where a couple of friendly characters will guide you from the basics to more advanced topics with a very practical approach and in record time! The code here complements this learning and allows you to test the scenarios presented and your knowledge.

If you are interested in following this guide, take a look to the chapters' blueprints:

• Exploring Cloud Run - My serverless "Hello, World!"
• The corporate environment - Developing an enterprise application
• Microservices architectures - Developing Microservices applications

Architecture

The following diagram depicts the main components that this blueprint will set up:

The following products or features are used to fulfill the different use cases covered in this blueprint (to learn more about them click on the hyperlinks):

• Cloud Run - Cloud Run is a managed compute platform that lets you run containers directly on top of Google's scalable infrastructure.
• Cloud Run Ingress Settings - feature that restricts network access to your Cloud Run service. At a network level, by default, any resource on the Internet can reach your Cloud Run service on its run.app URL or at a custom domain set up in Cloud Run. You can change this default by specifying a different setting for its ingress. All ingress paths, including the default run.app URL, are subject to your ingress setting. Ingress is set at the service level. The following settings are available:
  • Internal: Allows requests from VPC networks that are in the same project or VPC Service Controls perimeter as your Cloud Run service.
  • Internal and Cloud Load Balancing: Allows requests from resources allowed by the more restrictive Internal setting and an External HTTP(S) load balancer.
  • All (default): Allows all requests, including requests directly from the Internet to the default run.app URL.
• Google Cloud Load Balancer - When an HTTP(S) load balancer is enabled for Cloud Run, you can reach your serverless app through a custom domain mapped to a single dedicated global Anycast IP address that is not shared with other services.
• Cloud Armor - Google Cloud Armor is the web-application firewall (WAF) and DDoS mitigation service that helps users defend their web apps and services at Google scale at the edge of Google’s network.
• Identity Aware Proxy - IAP lets you establish a central authorization layer for applications accessed by HTTPS, so you can use an application-level access control model instead of relying on network-level firewalls. External Load Balancing with IAP is supported for Cloud Run with Serverless NEGs.
• Cloud CDN - Configure fast, reliable web and video content delivery with global scale and reach. Note: Cloud CDN is not part of this blueprint yet.

Prerequisites

You will need an existing project with billing enabled and a user with the “Project owner” IAM role on that project. Note: to grant a user a role, take a look at the Granting and Revoking Access documentation.

Spinning up the architecture

General steps

1. Clone the repo to your local machine or Cloud Shell:

git clone https://github.com/GoogleCloudPlatform/cloud-foundation-fabric

2. Change to the directory of the blueprint:

cd cloud-foundation-fabric/blueprints/serverless/cloud-run-explore

You should see this README and some terraform files.

3. To deploy a specific use case, you will need to create a file in this directory called terraform.tfvars and follow the corresponding instructions to set variables. Values that are meant to be substituted will be shown inside brackets but you need to omit these brackets. E.g.:

project_id = "[your-project_id]"

may become

project_id = "spiritual-hour-331417"

Although each use case is somehow built around the previous one they are self-contained so you can deploy any of them at will.

4. The usual terraform commands will do the work:

terraform init
terraform plan
terraform apply

It will take a few minutes. When complete, you should see an output stating the command completed successfully, a list of the created resources, and some output variables with information to access your services.

Congratulations! You have successfully deployed the use case you chose based on the variables configuration.

Use case 1: Cloud Run service with default URL

This is the simplest case, the "Hello World" for Cloud Run. A Cloud Run service is deployed with a default URL based in your project, service name and cloud region where it is deployed:

In this case the only variable that you need to set in terraform.tfvars is the project ID:

project_id = "[your-project-id]"

Alternatively you can pass this value on the command line:

terraform apply -var project_id="[your-project-id]"

The default URL is automatically created and shown as a terraform output variable. It will be similar to the one shown in the picture above. Now use your browser to visit it, you should see the following:

Use case 2: Cloud Run service with custom domain

If you want to use your own custom domain you need a GCLB in front of your Cloud Run app:

The following values will need to be set in terraform.tfvars, replacing the custom_domain value with your own domain:

project_id    = "[your-project-id]"
custom_domain = "cloud-run-explore.example.org"

Since it is an HTTPS connection a Google managed certificate is created, but for it to be provisioned correctly you will need to point to the load balancer IP address with an A DNS record at your registrar: Use Google-managed SSL certificates | Load Balancing. The LB IP is shown as a terraform output.

Be aware that in this case the Cloud Run service can also be reached through the default URL. To limit access only through the custom domain see the next use case.

Use case 3: Cloud Run service exposed only via custom domain

To block access to the default URL, you can configure Ingress Settings so that Internet requests will be accepted only if they come through the Load Balancer:

You only need to set one more value in the previous terraform.tfvars file:

project_id       = "[your-project-id]"
custom_domain    = "cloud-run-explore.example.org"
ingress_settings = "internal-and-cloud-load-balancing"

The default URL is still created but if you try to visit it, you should see a forbidden error:

Use case 4: Cloud Run service protected by Cloud Armor

To use Cloud Armor to protect the Cloud Run service, you need to create a security policy to enforce in the load balancer:

The code allows to block a list of IPs and a specific URL path. For example, you may want to block access to a login page to external users. To test its behavior, by default all IPs and the path "/login.html" are blocked, but you can override any of these settings with your own values:

project_id       = "[your-project-id]"
custom_domain    = "cloud-run-explore.example.org"
ingress_settings = "internal-and-cloud-load-balancing"
security_policy = {
  enabled      = true
  ip_blacklist = ["79.149.0.0/16"]
  path_blocked = "/admin.html"
}

Note that to avoid users to bypass the Cloud Armor policy you need to block access through the default URL. Ingress settings is configured to do that.

Use case 5: Cloud Run service protected by Cloud Armor and Identity-Aware Proxy

You can enable IAP at the load balancer to control access using identity and context:

Use your own email as identity to access the Cloud Run service:

project_id       = "[your-project-id]"
custom_domain    = "cloud-run-explore.example.org"
ingress_settings = "internal-and-cloud-load-balancing"
security_policy = {
  enabled      = true
  ip_blacklist = ["79.149.0.0/16"]
}
iap = {
  enabled = true
  email   = "[email protected]"
}

When visiting it you may be redirected to login with Google. You can use an incognito window to test this behavior.

Cleaning up your environment

The easiest way to remove all the deployed resources is to run the following command:

terraform destroy

The above command will delete the associated resources so there will be no billable charges afterwards. IAP Brands, though, can only be created once per project and not deleted. Destroying a Terraform-managed IAP Brand will remove it from state but will not delete it from Google Cloud.

Variables

name	description	type	required	default
project_id	Project ID.	string	✓
custom_domain	Custom domain for the Load Balancer.	string		null
iap	Identity-Aware Proxy for Cloud Run in the LB.	object({…})		{}
image	Container image to deploy.	string		"us-docker.pkg.dev/cloudrun/container/hello"
ingress_settings	Ingress traffic sources allowed to call the service.	string		"all"
project_create	Parameters for the creation of a new project.	object({…})		null
region	Cloud region where resource will be deployed.	string		"europe-west1"
run_svc_name	Cloud Run service name.	string		"hello"
security_policy	Security policy (Cloud Armor) to enforce in the LB.	object({…})		{}

Outputs

name	description	sensitive
custom_domain	Custom domain for the Load Balancer.
default_URL	Cloud Run service default URL.
load_balancer_ip	LB IP that forwards to Cloud Run service.

Tests

module "test" {
  source = "./fabric/blueprints/serverless/cloud-run-explore"
  project_create = {
    billing_account_id = "ABCDE-12345-ABCDE"
    parent             = "organizations/0123456789"
  }
  project_id       = "myproject"
  custom_domain    = "cloud-run-explore.example.org"
  ingress_settings = "internal-and-cloud-load-balancing"
  security_policy = {
    enabled      = true
    ip_blacklist = ["79.149.0.0/16"]
  }
  iap = {
    enabled = true
    email   = "[email protected]"
  }
}

# tftest modules=4 resources=22