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 existing apps in the standard environment to Cloud Run. 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 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:

  • Use the local configuration of an app.yaml file (recommended): Choose this option to build a container image directly from your local source code and deploy it to Cloud Run. This ensures that any recent local modifications to your code or configuration are included in the new deployment.

  • Use a previously built image: This option is useful if you don't have access to the source code. Choose this option to deploy an exact copy of a version that is already running onvApp Engine, without rebuilding the container image. This is useful if you want to verify the behavior of the active deployment without code changes.

Before you begin

  1. Make sure that your App Engine application runs without errors. You need access to your App Engine source code if you choose to deploy using your local configuration.

  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: your Google Cloud project ID.
    • REGION: the region where you want to deploy your Cloud Run service.

  4. Check for incompatible features in your application, and remove them before migrating to Cloud Run. To check your application for incompatibility without performing a migration or deployment, run the following command:

    gcloud beta app migrate-to-run --dry-run

    Review the compatibility check results and make the recommended changes if required.

  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 the standard environment. 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.

Use the local configuration of an app.yaml file

Deploy your local App Engine configuration 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

To deploy your Cloud Run service using the local app.yaml file of an existing App Engine configuration, follow these steps:

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

  2. Run the following command to deploy your service to Cloud Run:

    gcloud beta app migrate-to-run

    This command generates the service.yaml file configuration for Cloud Run and saves it locally to the same directory as your app.yaml file. For more information, see gcloud beta app migrate-to-run.

    • When prompted Proceed with the deployment?, enter Y to build a container image from your source code, and deploy the service to Cloud Run.

  3. Visit your deployed Cloud Run service by opening the service URL in a web browser.

    Optional:

    • If your app.yaml file is in a different directory, specify its path using the --appyaml flag:

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

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

    • To generate and export the Cloud Run service.yaml configuration without deploying the service, use the --export-only flag:

      gcloud beta app migrate-to-run --export-only=EXPORT_PATH

      Replace EXPORT_PATH with the directory or path where you want to save the service.yaml file.

Use a previously built image

To deploy using a previously built container image from a deployed App Engine version instead of rebuilding the container image from a local app.yaml file, follow these steps:

You don't need your application's source code for this deployment.

  1. Run the following command to deploy your service to Cloud Run. This command uses the container image of an active App Engine deployment and doesn't capture recent changes from your local app.yaml file, which might result in an outdated deployment:

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

    Replace the following:

    • SERVICE: the name of your App Engine service.
    • VERSION: the version ID of your service.

    This command fetches the configuration of the specified service and version to generate the service.yaml file for Cloud Run. For more information, see gcloud beta app migrate-to-run.

    • When prompted with Proceed with the deployment?, enter Y to export your existing App Engine container image and deploy the service to Cloud Run.

  2. Visit your deployed Cloud Run service by opening the service URL in a web browser.

    Optional:

    • To generate the Cloud Run service.yaml configuration without deploying the service, run the following command:

      gcloud beta app migrate-to-run --service=SERVICE \
    --version=VERSION \
    --from-image \
    --export-only=EXPORT_PATH

      Replace EXPORT_PATH with the directory or path where you want to save the service.yaml file.

Incompatible features

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

  • Inbound services:

    inbound_services:
- warmup

    Solution: Delete the inbound_services section from your app.yaml file. Cloud Run warms up instances using the container entrypoint, so you don't need to configure warmup requests. If you need to run initialization code before serving traffic, configure your service to run it at startup, before listening for requests or use startup probes. You can also configure minimum instances to keep instances warm.

  • Custom error pages:

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

    Solution: Delete the error_handlers section from your app.yaml file, and follow either or both of these strategies:

    • Implement error handling directly within your application code. Catch standard HTTP error codes, such as 404 or 500, and serve your custom HTML error pages from within your application logic.
    • If you are using Cloud Load Balancing with Cloud Run, configure custom error responses at the load balancer level. This lets you serve custom error pages from Cloud Storage based on the response code from your Cloud Run service.

  • Bundled services for second-generation runtimes:

    app_engine_apis: true

    Solution: Delete the app_engine_apis setting from your app.yaml file, and migrate to Google Cloud APIs or third-party alternatives instead. For more information, see Migrating from bundled services.

  • First-generation runtimes:

    runtime: python27

    Solution: Upgrade your application to a supported second-generation runtime. For more information, see the Migrating to second-generation runtimes overview.

What's next