This page shows how to use NGINX as a frontend proxy for your application container. This is useful if you want to process requests or responses. You can add gzip compression, or translate HTTP/2 to HTTP/1 if your application containers supports only HTTP/1 and you need to use HTTP/2 end-to-end for performance reasons.
In the example provided in this page, an Nginx container runs on every Cloud Run instance as the main serving container, and it is configured to forward requests to the application container, which runs as a sidecar container, as shown in this diagram:
The most effective way to do frontend proxying in Cloud Run is to deploy the Nginx server proxy server container and the web app container as a single Cloud Run service:
This single Cloud Run service accepts requests and delivers them to the ingress (serving) container, which
in this case is the proxy server. The proxy server then sends requests to the web app over the localhost
network
interface, which avoids any external network.
Deploying as a single Cloud Run service reduces latencies, service management overhead, and eliminates exposure to external networks. Cloud Run does not directly interact with the sidecar containers, other than to start or stop them whenever the service is started or stopped.
The web app container and any sidecar containers can be written in different programming languages. For a sample written in PHP, see the PHP nginx sample in GitHub.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Run and Secret Manager APIs.
- Install and initialize the gcloud CLI.
- Update Google Cloud CLI:
gcloud components update
- Configure Google Cloud CLI:
gcloud init
- Authenticate with Google Cloud CLI:
gcloud auth login
Permissions required to deploy
You must have ONE of the following:
- Both the Cloud Run Admin and Service Account User roles
- Any custom role that includes this specific list of permissions
Configuration overview
These instructions use prebuilt container images, so the only thing required for frontend proxying is to configure the containers and the service itself.
Configure the Nginx ingress container
The container image is nginx
available at Docker Hub.
It is mostly ready to use as is, except it needs to be configured to run as a
proxy service, delivering the proxied requests to the port where the sidecar container is
listening on localhost
. The example on this page also enables gzip compression for
requests and responses.
Configuration is provided using a text file mounted
at /etc/nginx/conf.d/nginx.conf
. Because you can't directly edit files in the
container, you must mount a volume at /etc/nginx/conf.d/
that contains
the configuration file. One way to mount a file at a specific location in a
container running on Cloud Run is to store the file content in a
Secret Manager secret, and mount that secret at the selected location.
Copy the following in a file named nginx.conf
on the current directory of your local machine.
In the configuration, do the following:
- Assign
nginx
to listen at the same Cloud Run default port8080
, located onlocalhost
. - Apply gzip compression for performance enhancement.
- Instruct
proxy_pass
to deliver any requests to this ingress container to the web app sidecar container at localhost port8888
.
Create a secret with the content of the nginx.conf
file.
Console
Go to the Secret Manager page of the Google Cloud console:
Click Create secret.
In the
name
form field, enter nginx_config.Upload the
nginx.conf
file located atmulti-container/hello-nginx-sample/nginx.conf
as the secret value.Keep the defaults (
Google-managed encryption key, etc
).Click Create secret.
Grant the project compute service account access to this new secret. To do this, go to the IAM page in the Google Cloud console:
Locate the principal service account with name:
Compute Engine default service account
and click Edit principal.Click Add another role and select Secret Manager Secret Accessor.
Click Save.
gcloud
In a terminal, use the following command to create a new
nginx_config
secret in Secret Manager:gcloud secrets create nginx_config --replication-policy='automatic' --data-file='./nginx.conf'
Grant the project compute service account access to this new secret using the command
export PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)') gcloud secrets add-iam-policy-binding nginx_config --member=serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com --role='roles/secretmanager.secretAccessor'
Verify that your secret was created by running
gcloud secrets list
.
About the web app sidecar sample image
These instructions use the sample container image at
us-docker.pkg.dev/cloudrun/container/hello
. You need to
specify the port number the container will listen on and localhost
as the host, as described under Specify sidecar container configuration, as described in the following sections.
Configure the multicontainer service
You can use the Google Cloud console or the Cloud Run YAML file to configure a Cloud Run service with more than one container.
In the service configuration, specify the Nginx proxy server as ingress (serving) container, the port it will listen on, whether it accepts HTTP 1 or HTTP 2 requests, and the container start order. The ingress container (proxy server) depends on the web app sidecar, so the web app sidecar must be started first.
These configurations are shown in the next few sections.
Add YAML metadata
Console
Navigate to Deploy the service for the full console instructions.
YAML
If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:
gcloud run services describe SERVICE --format export > service.yaml
In
service.yaml
, add the following:
The section describes the revision of the service, which includes properties that could vary from revision to revision.
Specify container start-up order
Console
Navigate to Deploy the service for the full console instructions.
YAML
In service.yaml
, append the following:
Note the container-dependencies
annotation that tells Cloud Run to wait for the hello container to start up
before starting the nginx container. Otherwise, if the nginx container starts first, it could try to proxy a web request to the web app container that isn't ready, which would generate web error responses.
Each container can optionally have a name property defined for it, that can be used to refer to it in other directives.
The serving container runs the proxy server, named nginx
. This is the container that Cloud Run delivers incoming requests to
so you must specify the version of HTTP
and container port to deliver them to.
Specify serving container configuration
Console
Navigate to Deploy the service for the full console instructions.
YAML
In service.yaml
file, append the following:
The nginx
server requires a configuration file in the /etc/nginx/conf.d/
directory. To do this, mount a volume containing the file at that location. The volumeMount
section specifies a volume called configuration
to be placed there. The volume itself is defined in its own section later in the file.
Specify sidecar container configuration
Console
Navigate to Deploy the service for the full console instructions.
YAML
In service.yaml
, append the following:
The hello
application also needs configuration information. It listens for incoming requests at the port specified in the PORT
environment variable. That name and value are specified in the env
section.
Specify the secret volume
Console
Navigate to Deploy the service for the full console instructions.
YAML
In service.yaml
file, append the following:
Specify the configuration volume
mounted in the volumeMount
section. It contains a single file called nginx.conf
whose contents are defined
as the value of the secret named nginx-conf-secret
.
Deploy the service
Console
Go to the Cloud Run page in the Google Cloud console:
Click Deploy container and select Service to display the Create service form.
- Select Deploy one revision from an existing container image and enter
nginx
as Container image URL. - In the Service name field, supply a name for your service, for example,
hello-mc
. - From the Region list, select a location to deploy to, for example,
us-west1
. - Under Authentication, select
Allow unauthenticated invocations
. If you don't have permissions (Cloud Run Admin role) to select this, the service will deploy and require authentication.
- Select Deploy one revision from an existing container image and enter
Click Container(s), volumes, networking, security to expand the configuration form.
- Click the Volumes tab.
- Click Add volume.
- From the Volume type list, select Secret.
- In the Volume name field, enter
nginx-conf-secret
. - In the Secret field, enter nginx_config.
- Under Specified paths for secret versions, specify default.conf as the path and latest as the version.
- Click Create to create the secret volume.
Click the Containers tab to display the Edit container form.
- Click Settings, then under Resources, change memory to 256MiB and CPU to 1 CPU.
- Click Volume mounts.
- Click Mount volume.
- Select nginx-conf-secret from the name list.
- For Mount path, enter etc/nginx/conf.d.
- Click Done to complete configuration for the first container.
Click Add container to add the sidecar container and display the New container form.
- Select the default container image URL us-docker.pkg.dev/cloudrun/container/hello
- Click the Settings tab, then under Resources, change memory to 256MiB and CPU to 1 CPU.
- Click Variables & Secrets.
- Click Add variable.
- Enter PORT as the new environment variable name and 8888 as the value.
- Click Done.
Navigate to the Edit container form for the first container (
nginx
).- Click the Settings tab.
- Under Container start up order, select
nginx
from the Depends on list. This means thenginx
container starts up only after thehello
container starts up successfully. - Click Create and wait for your service to deploy.
gcloud
To deploy the proxy server container and web app container as a single service:
gcloud run services replace service.yaml
Verify the deployed service
gcloud
To verify successful deployment, copy the generated Cloud Run URL and open it in a browser, or use this command to send an authenticated request:
curl --header "Authorization: Bearer $(gcloud auth print-identity-token)"
You should be greeted with a nginx proxy that
has successfully ported to the hello sidecar container with
response status 200
.
Try this yourself
To follow along with this tutorial:
gcloud
In a terminal, clone the sample app repository to your local machine:
git clone https://github.com/GoogleCloudPlatform/cloud-run-samples
Change to the directory that contains the Cloud Run sample code:
cd cloud-run-samples/multi-container/hello-nginx-sample/
What's next
To explore more about using sidecars in a Cloud Run service: