Deploy an App Engine app in the standard environment to Cloud Run

Region ID

The REGION_ID is an abbreviated code that Google assigns based on the region you select when you create your app. The code does not correspond to a country or province, even though some region IDs may appear similar to commonly used country and province codes. For apps created after February 2020, REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

Learn more about region IDs.

This guide describes how to deploy your apps in the standard environment to Cloud Run using the Google Cloud CLI. The instructions are applicable for second-generation runtimes that don't use the App Engine legacy bundled services.

The steps described in this guide don't affect your existing App Engine app's functionality or traffic flow. The newly created Cloud Run service is a replica of the App Engine service that you can test independently.

Cloud Run uses much of the same infrastructure as the App Engine standard environment, resulting in many similarities between the platforms. To learn more about the similarities and differences between App Engine and Cloud Run, including the benefits of migrating to Cloud Run, see the comparison summary.

To deploy to Cloud Run, choose one of the following strategies:

Before you begin

  1. Make sure that you have access to the App Engine source code, and your App Engine application runs without errors.

  2. Enable the Cloud Run Admin API and the Artifact Registry API:

    Enable APIs

  3. Configure your project and region using the following command:

    gcloud auth login
gcloud config set project PROJECT_ID
gcloud config set run/region REGION
gcloud components update

    Replace the following:

    • PROJECT_ID with your Google Cloud project ID.
    • REGION with your region.

  4. Review the incompatible features in your application, and remove them before migrating to Cloud Run. If there are incompatible features in your existing application, the migration process stops and lists the incompatibilities.

  5. Review the following Cloud Run differences:

    • Cloud Run uses the term Revision, instead of Version, to represent each time that you deploy changes to a specific service. Deploying your app to a service in Cloud Run for the first time creates its first revision. Each subsequent deployment of a service creates another revision. Learn more about deploying to Cloud Run.

    • You can deploy your source code to Cloud Run using the gcloud CLI or Google Cloud console to configure and manage your app settings. Cloud Run doesn't require file-based configuration; however, YAML configuration is supported.

    • Every service that you deploy to Cloud Run uses the run.app domain in the URL to access the service publicly.

    • Unlike App Engine services that are public by default, Cloud Run services are private by default and require you to configure them for public (unauthenticated) access.

Required roles

You can choose to either create a new service account or use the same user-managed service account in Cloud Run that you are using for App Engine. You or your administrator must grant the deployer account and the Cloud Build service account the following IAM roles.

Click to view required roles for the deployer account

To get the permissions that you need to build and deploy from source, ask your administrator to grant you the following IAM roles:

Click to view required roles for the Cloud Build service account

Cloud Build automatically uses the Compute Engine default service account as the default Cloud Build service account to build your source code and Cloud Run resource, unless you override this behavior. For Cloud Build to build your sources, ask your administrator to grant Cloud Run Builder (roles/run.builder) to the Compute Engine default service account on your project:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --role=roles/run.builder

Replace PROJECT_NUMBER with your Google Cloud project number, and PROJECT_ID with your Google Cloud project ID. For detailed instructions on how to find your project ID, and project number, see Creating and managing projects.

Granting the Cloud Run builder role to the Compute Engine default service account takes a couple of minutes to propagate.

For a list of IAM roles and permissions that are associated with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run service interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Deploy an existing App Engine application

Deploy an existing App Engine app directly to Cloud Run using the Google Cloud console or the gcloud CLI.

Console

  1. In the Google Cloud console, go to the App Engine page.

    Go to App Engine

  2. In the navigation menu, click Migration hub to deploy your App Engine app to Cloud Run. The Migration hub also lets you check your estimated savings on Cloud Run for cost estimation and recommendations.

  3. Select the service you want to migrate, and click Check compatibility.

  4. Select your Service and Version to see the compatibility results. The migration hub runs a compatibility checker to identify incompatible features.

  5. Review the results to verify that your app is fully compatible with Cloud Run, and click Continue to proceed to the Review & Deploy section.

  6. Copy the command in the Deploy through gcloud section, and run it within your project directory.

  7. Click View deployed versions to see your App Engine services deployed in Cloud Run.

gcloud

Use the Google Cloud CLI to migrate your application using your local app.yaml file or an existing App Engine deployment configuration.

  1. In your terminal, change to your project source directory where the app.yaml file exists.

  2. Run the following command:

    gcloud beta app migrate-to-run

    If your app.yaml file is in a different directory, include the --appyaml flag:

    gcloud beta app migrate-to-run --appyaml=PATH

    Replace PATH with the path to your app.yaml file.

For more information, see gcloud beta app migrate-to-run.

Use the app.yaml file

Translate your local App Engine app.yaml file to a Cloud Run service by running the following command:

  1. In your terminal, change to your project source directory where the app.yaml file exists.

  2. Run the following command:

    gcloud beta app migrate-to-run

    If your app.yaml file is in a different directory, include the --appyaml flag:

    gcloud beta app migrate-to-run --appyaml=PATH

    Replace PATH with the path to your app.yaml file.

For more information, see gcloud beta app migrate-to-run.

Use the configuration of an existing deployment

To use the configuration of a deployed App Engine service instead of a local app.yaml file, run the following command.

gcloud beta app migrate-to-run --service=SERVICE --version=VERSION

This command uses the app.yaml file configuration from an existing deployment, which might be outdated if you have made recent changes to your local app.yaml file:

Replace the following:

  • SERVICE with the name of your App Engine service. App Engine uses the configuration of the existing service, and ignores the app.yaml file configuration in your local directory.
  • VERSION with the version ID of your service. App Engine uses the configuration of the existing version, and ignores the app.yaml file configuration in your local directory.

For more information, see gcloud beta app migrate-to-run.

Incompatible features

The migration command fails if your app.yaml file contains any of the following unsupported configurations:

  • Inbound services:

    inbound_services:
- warmup

  • Custom error pages:

    error_handlers:
- file: default_error.html
- error_code: over_quota
  file: over_quota.html

  • Bundled services for second-generation runtimes:

    app_engine_apis: true

  • Build environment variables:

    build_env_variables:
  Foo: Bar

  • First-generation runtimes:

    runtime: python27

What's next