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.

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 using the gcloud beta app migrate command, choose one of the following strategies:

Use the app.yaml file to deploy a service to Cloud Run using your existing App Engine configuration.
Deploy an existing App Engine application directly to Cloud Run.

Before you begin

Make sure that you have access to the App Engine source code, and your App Engine application runs without errors.
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 with your Google Cloud project ID.
- REGION with your region.
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.
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:

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[email protected] \
      --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 `app.yaml` file

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

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

Replace the following:

PATH with the path to your app.yaml file.
ENTRYPOINT with the entrypoint command for your application.

If you are in the project directory, both PATH and ENTRYPOINT arguments are optional.

For more information on the arguments you can use with the gcloud beta app migrate-to-run command, see gcloud beta app migrate-to-run.

Deploy an existing App Engine application

Deploy an existing App Engine app directly to Cloud Run by running the following command:

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

This command prompts you to specify the relative path to your source code directory.

Replace the following:

SERVICE with the name of your App Engine service.
VERSION with the version ID of your service.
ENTRYPOINT with the entrypoint command for your application. If you are in the project directory, this argument is optional.

For more information on the arguments you can use with the gcloud beta app migrate command, 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

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.