<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 flexible 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

flexible environment to
[Cloud Run](https://docs.cloud.google.com/run/docs/overview/what-is-cloud-run.md.txt).

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](https://docs.cloud.google.com/appengine/migration-center/run/compare-gae-with-run).

<br />

To deploy to Cloud Run, [use the local configuration of your `app.yaml`
file](https://docs.cloud.google.com/appengine/migration-center/run/migrate-app-engine-flexible-to-run#appyaml-config). This builds a container image from your local source code, so any recent changes to your code or configuration are included in the new deployment.

## Before you begin

1. Make sure that your App Engine application runs without errors. You need
   access to your App Engine source code.

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-flexible-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 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](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 />

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.

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

4. In the **Check compatibility** section,
   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-flexible-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. 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.

## 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. 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
  ```

  <br />

  **Solution** : Replace the `basic_scaling` section in your
  `app.yaml` file with `automatic_scaling` or `manual_scaling`. The
  compatibility check in the **Migration hub** blocks versions that use
  basic scaling.
- **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).

<!-- -->

- **Forwarded ports with host port mappings, protocols, or multiple ports**:

  ```yaml
  network:
    forwarded_ports:
    - 8080:8000
    - 2222/udp
  ```

  **Solution** : Update `network.forwarded_ports` in your `app.yaml` file to
  specify only a single numeric container port, such as `8080`, or
  delete `forwarded_ports` and [configure the container
  port](https://docs.cloud.google.com/run/docs/configuring/services/containers#configure-port) in
  Cloud Run. Cloud Run accepts only inbound TCP traffic on a
  single container port and doesn't support host-to-container port mappings or
  UDP traffic. The migration tool accepts only bare port numbers, so host port
  mappings and `/tcp` or `/udp` protocol suffixes, such as `8080/tcp`, cause
  the migration to fail. If you specify multiple numeric ports, the migration tool logs a warning and
  configures only the first port.
- **Disk size**:

  ```yaml
  resources:
    disk_size_gb: 20
  ```

  **Solution** : Delete `disk_size_gb` from the `resources` section of your
  `app.yaml` file. The migration tool displays a warning and ignores this
  setting because Cloud Run defaults to an in-memory file system,
  where writing files consumes instance memory. If your application needs to write
  files without consuming memory, configure an [ephemeral disk volume
  mount](https://docs.cloud.google.com/run/docs/configuring/services/ephemeral-disk) or a [Cloud Storage
  volume mount](https://docs.cloud.google.com/run/docs/configuring/services/cloud-storage-volume-mounts) in
  Cloud Run to avoid out-of-memory (OOM) errors.

## 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).