<br />

<br />

<br />

<br />

<br />

<br />

<br />

### Region ID

<br />


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.

<br />

<br />

Learn more
[about region IDs](https://docs.cloud.google.com/appengine/docs/standard/python/how-requests-are-routed#region-id).
<button class="devsite-dialog-close">OK</button>

> [!WARNING]
>
> **Preview
> --- Deploy an existing App Engine app in the standard environment to Cloud Run**
>
>
> This feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the
> [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

This guide describes how to deploy your existing apps in the
standard environment to
[Cloud Run](https://docs.cloud.google.com/run/docs/overview/what-is-cloud-run.md.txt).
The instructions are applicable for [second-generation
runtimes](https://docs.cloud.google.com/appengine/docs/standard/lifecycle/support-schedule) 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](https://docs.cloud.google.com/appengine/migration-center/run/compare-gae-with-run).

<br />

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

<br />

- **[Use the local configuration of an `app.yaml` file](https://docs.cloud.google.com/appengine/migration-center/run/migrate-app-engine-standard-to-run.md.txt#appyaml-config) (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](https://docs.cloud.google.com/appengine/migration-center/run/migrate-app-engine-standard-to-run.md.txt#existing-app-deploys)**:
  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 on
  App Engine, without rebuilding the container image, or 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](https://docs.cloud.google.com/appengine/migration-center/run/migrate-app-engine-standard-to-run#appyaml-config).

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

   [Enable APIs](https://console.cloud.google.com/apis/enableflow?apiid=run.googleapis.com,artifactregistry.googleapis.com)
3. Configure your project and region using the following command:

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

   Replace the following:
   - <var translate="no">PROJECT_ID</var>: your Google Cloud project ID.
   - <var translate="no">REGION</var>: the region where you want to deploy your Cloud Run service.
4. Check for [incompatible features](https://docs.cloud.google.com/appengine/migration-center/run/migrate-app-engine-standard-to-run.md.txt#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 from the directory where your
   `app.yaml` file is located:

   ```bash
   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](https://docs.cloud.google.com/run/docs/deploying#service).

   - You can deploy your source code to Cloud Run using the
     Google Cloud console or the Google Cloud CLI to configure and manage
     your app settings. Cloud Run doesn't require file-based
     configuration; however,
     [YAML configuration](https://docs.cloud.google.com/run/docs/deploying.md.txt?tab=yaml#revision) is
     supported.

   - Every service that you deploy to Cloud Run uses the
     [`run.app`](https://docs.cloud.google.com/run/docs/triggering/https-request.md.txt#url)
     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](https://docs.cloud.google.com/run/docs/authenticating/overview.md.txt)
     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:

- [Cloud Run Source Developer](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.sourceDeveloper) (`roles/run.sourceDeveloper`) on your project
- [Service Usage Consumer](https://docs.cloud.google.com/iam/docs/roles-permissions/serviceusage.md.txt#serviceusage.serviceUsageConsumer) (`roles/serviceusage.serviceUsageConsumer`) on your project
- [Service Account User](https://docs.cloud.google.com/iam/docs/roles-permissions/iam.md.txt#iam.serviceAccountUser) (`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](https://docs.cloud.google.com/build/docs/cloud-build-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](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.builder)
(`roles/run.builder`) to the Compute Engine default
service account on your project:

```bash
  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](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects).

Granting the Cloud Run builder role to the Compute Engine default service account
takes a couple of minutes to [propagate](https://docs.cloud.google.com/iam/docs/access-change-propagation.md.txt).

> [!NOTE]
> **Note:**
>
>
> The [`iam.automaticIamGrantsForDefaultServiceAccounts` organization policy constraint](https://docs.cloud.google.com/resource-manager/docs/organization-policy/restricting-service-accounts#disable_service_account_default_grants)
> 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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt)
> 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](https://docs.cloud.google.com/policy-intelligence/docs/simulate-iam-policies.md.txt) to see the impact of
> the change, and then [grant and revoke the
> appropriate roles](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).

<br />

To [deploy a previously built image](https://docs.cloud.google.com/appengine/migration-center/run/migrate-app-engine-standard-to-run.md.txt#existing-app-deploys), ask your administrator to grant you the following IAM roles:

<br />

- [App Engine Deployer](https://docs.cloud.google.com/iam/docs/roles-permissions/appengine.md.txt#appengine.deployer) (`roles/appengine.deployer`) on your project. This role contains the `appengine.versions.exportAppImage` permission, which you need to export the container image of your App Engine version.
- [Cloud Run Developer](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.developer) (`roles/run.developer`) on your project.
- [Artifact Registry Reader](https://docs.cloud.google.com/iam/docs/roles-permissions/artifactregistry.md.txt#artifactregistry.reader) (`roles/artifactregistry.reader`) on your project.
- [Service Account User](https://docs.cloud.google.com/iam/docs/roles-permissions/iam.md.txt#iam.serviceAccountUser) (`roles/iam.serviceAccountUser`) on the Cloud Run service identity.

Optional: To view estimated cost savings in the **Migration hub** , you need
the `recommender.appengineVersionCostRecommendations.list` permission. The
App Engine Deployer role and the
[App Engine Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/appengine.md.txt#appengine.appViewer)
(`roles/appengine.appViewer`) role contain this permission.


For a list of IAM roles and permissions that are associated with
Cloud Run, see
[Cloud Run IAM roles](https://docs.cloud.google.com/run/docs/reference/iam/roles.md.txt)
and [Cloud Run IAM permissions](https://docs.cloud.google.com/run/docs/reference/iam/permissions.md.txt).
If your Cloud Run service interfaces with
Google Cloud APIs, such as Cloud Client Libraries, see the
[service identity configuration guide](https://docs.cloud.google.com/run/docs/configuring/services/service-identity.md.txt).
For more information about granting roles, see
[deployment permissions](https://docs.cloud.google.com/run/docs/reference/iam/roles.md.txt#additional-configuration)
and [manage access](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

## 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 Google Cloud CLI.

### Console

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

   [Go to App Engine](https://console.cloud.google.com/appengine)
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 recommendations.

3. In the **Standard to Cloud Run
   migration**
   card, select the **Service** that you want to migrate, and then click
   **Check compatibility**.

4. In the **Check compatibility** section,
   confirm or select your **Version**
   to view the compatibility results. The migration hub runs a
   compatibility checker to identify
   [incompatible features](https://docs.cloud.google.com/appengine/migration-center/run/migrate-app-engine-standard-to-run.md.txt#incompatible-features).

5. Review the results to verify that your app has no blocking
   incompatibilities, and then click **Continue** to proceed to the
   **Review \& Deploy** section.

6. On the **Source based deployment**
   tab, copy the command in the **Deploy through
   Gcloud** section, replace the <var translate="no">PATH_TO_APP_YAML</var> placeholder
   with the path to your `app.yaml` file, and run the command from your
   application source 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:

   ```bash
   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`](https://docs.cloud.google.com/sdk/gcloud/reference/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. Test your deployed Cloud Run service. Because your
   Cloud Run service is private by default, opening the service
   URL directly in a web browser returns a `403 Forbidden` error. To view
   your service, do one of the following:

   - To test the service privately (recommended), run the [`gcloud run services proxy`](https://docs.cloud.google.com/run/docs/authenticating/developers.md.txt#proxy) command, and then open the local proxy URL in a web browser.
   - If you want your service to be publicly available, [enable public access](https://docs.cloud.google.com/run/docs/authenticating/public.md.txt), and then open 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:

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

     Replace <var translate="no">PATH</var> 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:

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

     Replace <var translate="no">EXPORT_PATH</var> with the directory or path where you want
     to save the `service.yaml` file.

## Use a previously built image

Deploy a previously built container image from a deployed App Engine
version to Cloud Run using the Google Cloud console or the
Google Cloud CLI. This doesn't rebuild the container image from a local
`app.yaml` file, and you don't need your application's source code.

### Console

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

   [Go to App Engine](https://console.cloud.google.com/appengine)
2. In the navigation menu, click **Migration hub**.

3. In the **Standard to Cloud Run migration** card, select the
   **Service** that you want to migrate, and then click
   **Check compatibility**.

4. In the **Check compatibility** section, confirm or select the
   **Version** that you want to deploy. The migration hub runs a
   compatibility checker to identify
   [incompatible features](https://docs.cloud.google.com/appengine/migration-center/run/migrate-app-engine-standard-to-run.md.txt#incompatible-features).

5. Review the results to verify that your app has no blocking
   incompatibilities, and then click **Continue** to proceed to the
   **Review \& Deploy** section.

6. Click the **Image based deployment** tab.

7. Review the Cloud Run settings that the migration hub derives
   from your App Engine version, such as CPU, memory, scaling,
   concurrency, service account, and environment variables. You can
   change these settings after deployment. To deploy a different
   version, click **Change version**.

8. If you haven't enabled the required APIs, click
   **Enable Cloud Run APIs** , and then click **Enable all** to enable
   the Cloud Run Admin API and the Cloud Build API.

9. Click **Match permissions** , and then click **Grant all** to grant
   the following IAM roles to your user account:

   - Cloud Run Developer (`roles/run.developer`)
   - Service Account User (`roles/iam.serviceAccountUser`)
   - Artifact Registry Reader (`roles/artifactregistry.reader`)

   If you don't have permission to enable APIs or grant roles, ask your
   administrator to enable the APIs and grant the roles.
10. Click **Deploy**. The migration hub exports the container image of
    your App Engine version and deploys it to a Cloud Run
    service that has the same name as your App Engine service. The
    service is created in the Cloud Run region that corresponds
    to the region of your App Engine app.

    If a Cloud Run service with the same name already exists in
    that region, click **Overwrite and deploy** in the confirmation
    dialog. The deployment creates a new revision that serves 100% of
    traffic and keeps the existing authentication and ingress settings
    of the service.

    After the deployment completes, the Cloud Run **Services**
    page opens, filtered to show the services migrated from
    App Engine.
11. Test your deployed Cloud Run service. Because your
    Cloud Run service is private by default, opening the service
    URL directly in a web browser returns a `403 Forbidden` error. To view
    your service, do one of the following:

    - To test the service privately (recommended), run the [`gcloud run services proxy`](https://docs.cloud.google.com/run/docs/authenticating/developers.md.txt#proxy) command, and then open the local proxy URL in a web browser.
    - If you want your service to be publicly available, [enable public access](https://docs.cloud.google.com/run/docs/authenticating/public.md.txt), and then open the service URL in a web browser.

### gcloud

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:

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

   Replace the following:
   - <var translate="no">SERVICE</var>: the name of your App Engine service.
   - <var translate="no">VERSION</var>: 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`](https://docs.cloud.google.com/sdk/gcloud/reference/beta/app/migrate-to-run.md.txt).
   - 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. Test your deployed Cloud Run service. Because your
   Cloud Run service is private by default, opening the service URL
   directly in a web browser returns a `403 Forbidden` error. To view your
   service, do one of the following:

   - To test the service privately (recommended), run the [`gcloud run services proxy`](https://docs.cloud.google.com/run/docs/authenticating/developers.md.txt#proxy) command, and then open the local proxy URL in a web browser.
   - If you want your service to be publicly available, [enable public access](https://docs.cloud.google.com/run/docs/authenticating/public.md.txt), and then open the service URL in a web browser.

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

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

     Replace <var translate="no">EXPORT_PATH</var> with the directory or path where you
     want to save the `service.yaml` file.

## Incompatible features

The migration command fails or displays a warning if your `app.yaml` file
contains any of the following unsupported configurations:

- **Inbound services**:

  ```yaml
  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](https://docs.cloud.google.com/run/docs/configuring/healthchecks#configure-probes). You can also
  configure [minimum instances](https://docs.cloud.google.com/run/docs/configuring/min-instances.md.txt) to keep
  instances warm.
- **Custom error pages**:

  ```yaml
  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.
- **URL and static file handlers**:

  ```yaml
  handlers:
  - url: /stylesheets
    static_dir: stylesheets
  ```

  **Solution** : Delete the `handlers` section from your `app.yaml`
  file, or keep only a catch-all
  handler that routes all traffic to your application (`url: /.*` or
  `url: .*` with `script: auto`). Cloud Run doesn't
  support `app.yaml` request routing or static file handlers. Instead, serve
  static files directly from your Cloud Run service or from
  [Cloud Storage](https://docs.cloud.google.com/storage/docs/hosting-static-website.md.txt), and handle URL
  routing within your application code or by using
  [Cloud Load Balancing](https://docs.cloud.google.com/load-balancing/docs/https/url-map-concepts).
- **Build environment variables**:

  ```yaml
  build_env_variables:
    BUILD_MODE: "production"
  ```

  The compatibility check in the migration hub reports this
  configuration as a blocking incompatibility. The
  `gcloud beta app migrate-to-run` command doesn't report it, and applies
  the variables to the build when you deploy from source.

  **Solution** : Delete the `build_env_variables` section from your
  `app.yaml` file. If your build still requires these values, [set build environment
  variables](https://docs.cloud.google.com/run/docs/configuring/services/build-environment-variables)
  when you deploy your Cloud Run service from source. If your app
  needs these values at runtime, set them as [environment
  variables](https://docs.cloud.google.com/run/docs/configuring/services/environment-variables) on the
  service.
- **Basic scaling**:

  ```yaml
  basic_scaling:
    max_instances: 10
    idle_timeout: 10m
  ```

  Cloud Run doesn't have a
  basic scaling setting. The migration command displays a warning and uses
  the `max_instances` value as the maximum number of instances for your
  Cloud Run service.

  **Solution** : Verify that
  [Cloud Run autoscaling](https://docs.cloud.google.com/run/docs/about-instance-autoscaling.md.txt)
  meets your needs.
- **Resource and scaling values outside Cloud Run limits**:

  ```yaml
  manual_scaling:
    instances: 1500
  ```

  The migration displays a warning if your configuration is outside any of
  the following Cloud Run limits:
  - CPU: 8 vCPUs
  - Memory: 512 MiB to 32 GiB
  - Minimum, maximum, or manual scaling instances: 1,000
  - Concurrent requests per instance: 1,000

  **Solution** : Update your `app.yaml` file to use values within these
  limits. For more information, see
  [CPU limits](https://docs.cloud.google.com/run/docs/configuring/services/cpu.md.txt),
  [memory limits](https://docs.cloud.google.com/run/docs/configuring/services/memory-limits.md.txt), and
  [concurrency](https://docs.cloud.google.com/run/docs/configuring/concurrency.md.txt). If you need more than
  1,000 instances, [request a quota increase](https://docs.cloud.google.com/run/quotas.md.txt).

<!-- -->

- **Bundled services for second-generation runtimes**:

  ```yaml
  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](https://docs.cloud.google.com/appengine/migration-center/standard/services/migrating-services).
- **First-generation runtimes**:

  ```yaml
  runtime: python27
  ```

  **Solution** : Upgrade your application to a [supported second-generation
  runtime](https://docs.cloud.google.com/appengine/docs/standard/lifecycle/support-schedule). For more
  information, see the [Migrating to second-generation runtimes
  overview](https://docs.cloud.google.com/appengine/migration-center/standard/migrate-to-second-gen/overview).

## What's next

- Understand how to [manage your Cloud Run services](https://docs.cloud.google.com/run/docs/managing/services.md.txt).
- See the Cloud Run [container runtime contract](https://docs.cloud.google.com/run/docs/container-contract.md.txt) 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](https://docs.cloud.google.com/run/docs/configuring/services/secrets.md.txt).