Deploy an App Engine app in the flexible 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 flexible environment to Cloud Run.

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.

App Engine flexible environment and Cloud Run are both fully managed, container-native application platforms, however, they differ structurally. 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

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.
Enable the Cloud Run Admin API and the Artifact Registry API:

Enable APIs
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.
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.
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 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 flexible 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:

Cloud Run Source Developer (roles/run.sourceDeveloper) on your project
Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) on your project
Service Account User (roles/iam.serviceAccountUser) on the Cloud Run service identity

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.

Note:

The iam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint prevents the Editor role from being automatically granted to default service accounts. If you created your organization after May 3, 2024, this constraint is enforced by default.

We strongly recommend that you enforce this constraint to disable the automatic role grant. If you disable the automatic role grant, you must decide which roles to grant to the default service accounts, and then grant these roles yourself.

If the default service account already has the Editor role, we recommend that you replace the Editor role with less permissive roles.To safely modify the service account's roles, use Policy Simulator to see the impact of the change, and then grant and revoke the appropriate roles.

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

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

In your terminal, change to your source directory where the app.yaml file exists.
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.
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, run the following command:
```
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.

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.
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 the following unsupported configuration:

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.

What's next

Understand how to manage your Cloud Run services.
See the Cloud Run container runtime contract to understand the requirements and behaviors of containers in Cloud Run.
Learn how to store dependencies for your service requiring API keys, passwords, or other sensitive information using a Secret Manager.