Configure automatic base image updates

Configuring automatic base image updates for Cloud Run enables Google to make security patches to the operating system and runtime components of the application image automatically. You don't have to rebuild or redeploy your service.

To configure automatic base image updates, do the following:

  • Select a compatible Cloud Run base image.
  • Build and deploy your application image in a way that preserves the ability to safely rebase your running service.

Select a Base Image

A base image is the starting point for most container-based development workflows. Developers start with a base image and layer on top of it the necessary libraries, binaries, and configuration files used to run their application.

Google Cloud's buildpacks publishes and maintains base images for building Serverless applications. These base images are built on top of the Ubuntu Linux distribution.

Cloud Run only supports automatic base images that use Google Cloud's buildpacks base images.

You must consider the following when choosing a Google Cloud's buildpacks:

  • Stack: A stack is made up of a Linux distribution version and system packages, such as OpenSSL and curl
  • Language: The specific version of the programming language used by your application

Review runtime base images to learn more about base image variations.

Building the application image

Services with automatic updates enabled will need to provide an application image that omits the base operating system layers. There are two ways to do this:

Deploy from source

You can use the Cloud Run deploy from source feature to build your application so that is compatible with automatic updates. To do this, you must supply the --base-image flag when creating your application.

For example, to deploy a Python service or function with automatic base image updates enabled, you would use the following command:

gcloud beta run deploy python-application \
  --source . \
  --base-image=python312

Build on scratch

You can also use your build toolchain to create an application image that is compatible with automatic base image updates. To do this you will:

  1. Create a multi-stage Dockerfile.
    1. Build the application using an appropriate base image with required dependencies.
    2. Copy the built components on to of a scratch image.
  2. Build the application image(s) and publish to Artifact Registry.
  3. Deploy the application with Cloud Run.

Create a multi-stage Dockerfile

We will use a Node.js application for this guide. This guide is not language specific, and can be customized for your application and language.

  • Create a Dockerfile in the root directory of our project with the following:

    FROM node:18-slim as builder

# Create and change to the app directory.
WORKDIR /usr/src/app

# Copy application dependency manifests to the container image and install
# production dependencies.
COPY package*.json ./
RUN npm install --only=production

# Copy local code to the container image.
COPY . ./

# Copy the application source code and depenencies onto a scratch image.
FROM scratch
COPY --from=builder --chown=33:33 /usr/src/app/ ./

# Run the web service on container startup.
CMD [ "node", "index.js" ]

This Dockerfile uses a multi-stage build to copy the application source code and dependencies onto a scratch image that omits the operating system, packages, and runtime components that will be supplied at runtime by the Cloud Run managed base image.

Building your application image

Build your application image and upload it into Artifact Registry. Refer to building containers for details on how to build a Dockerfile with Cloud Build and uploading it to Artifact Registry.

Deploy the application image

You are now ready to deploy your application image with automatic updates enabled using the most compatible base image for your application. We will use the Node.js 18 runtime from us-central1 for this example. Review runtime base images to learn more about base image variations.

Refer to deploying container images to Cloud Run for additional details on required roles and permissions.

gcloud beta run deploy SERVICE \
  --image=IMAGE \
  --base-image=us-central1-docker.pkg.dev/serverless-runtimes/google-22/runtimes/nodejs18

Replace:

  • SERVICE with the name of the service you want to deploy to. Service names must be 49 characters or less and must be unique per region and project. If the service does not exist yet, this command creates the service during the deployment. You can omit this parameter entirely, but you will be prompted for the service name if you omit it.
  • IMAGE with the URL of your container image.

Service fields and annotations

By enabling Automatic security updates your service configuration will be enriched with the following data.

YAML

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
name: SERVICE
annotations:
    ...
    run.googleapis.com/build-base-image: BASE_IMAGE_URL
    run.googleapis.com/launch-stage: BETA
    ...
spec:
...
runtimeClassName: run.googleapis.com/linux-base-image-update

Replace:

  • SERVICE the name of the service you want to deploy to. Service names must be 49 characters or less and must be unique per region and project. If the service does not exist yet, this command creates the service during the deployment. You can omit this parameter entirely, but you will be prompted for the service name if you omit it.
  • BASE_IMAGE_URL, the base image that will be used on next deployment. BASE_IMAGE_URL will be used on the next source or function deployment. Review Runtime base images to learn more about base image variations.

Disable automatic updates

Automatic security updates can be disabled by updating your service definition.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. To disable automatic updates for the Node.js 18 runtime, run the following command:

gcloud beta run deploy SERVICE \
    --image=IMAGE \
    --base-image=nodejs18 \
    --no-automatic-updates

Replace:

  • SERVICE with the name of the service you want to deploy to. Service names must be 49 characters or less and must be unique per region and project. If the service does not exist yet, this command creates the service during the deployment. You can omit this parameter entirely, but you will be prompted for the service name if you omit it.
  • IMAGE with the URL of your container image

YAML

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

  2. Delete the run.googleapis.com/build-base-image: BASE_IMAGE_URL line. It is optional remove the runtimeClassName line.

  3. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml

Known limitations

  • Cloud Run only supports Google Cloud's buildpacks base images.

  • Applications using compiled languages won't be recompiled as a result of a automatic base image update.

  • Security scans on your application image might be incomplete. Because your application image is now built on scratch, security scanners will only scan the application portion of your image. To get a more complete image of your container security, you must run scans on the corresponding Google-provided base image as well. You can download the base image and use open source tools to run a scan.