Nov 18, 20267 min read

How to Migrate from App Engine to Cloud Run

A step-by-step migration from App Engine standard to Cloud Run: checking compatibility with gcloud app migrate-to-run, mapping app.yaml, replacing bundled services, cron.yaml and task queues, and cutting traffic over without downtime.

Illustration for How to Migrate from App Engine to Cloud Run

App Engine standard was Google Cloud's original way to run a web app without servers: write app.yaml, run gcloud app deploy, and Google handles instances, scaling, cron and task queues. Google now points new work at Cloud Run, and the reasons to move are concrete: Cloud Run runs any container and any language version, instances serve many requests at once instead of a handful, and the second-generation runtimes App Engine still offers already behave like containers anyway.

The migration is mostly mechanical for a second-generation app without legacy bundled services, and a larger project for an older app that leans on Memcache, Task Queues or the Users API. This guide walks through both, from the compatibility check to the traffic cutover, and shows how to land the app on Cloud Run with its database, queues and cron declared in code.

Before You Start: What Moves and What Does Not

App Engine standardCloud Run equivalent
app.yamlService settings, or a service.yaml
Versions and traffic splittingRevisions and traffic splitting
instance_classCPU and memory per instance
automatic_scalingMin and max instances, concurrency
MemcacheMemorystore for Redis or Valkey
Task Queues (push)Cloud Tasks
cron.yamlCloud Scheduler jobs
DatastoreFirestore in Datastore mode, unchanged, through client libraries
Public by defaultPrivate by default, public access must be allowed
appspot.com URLrun.app URL, or your domain through a load balancer

Step 1: Check Compatibility

Google ships a migration command that reads app.yaml, reports incompatible features and generates a Cloud Run service. From the directory with app.yaml:

~/my-app
$ gcloud beta app migrate-to-run --dry-run$ gcloud beta app migrate-to-run --export-only=./run

The dry run validates without deploying, and --export-only writes the generated service.yaml so you can review it. The Google migration guide applies to second-generation runtimes that do not use the legacy bundled services, and the App Engine migration hub in the console runs the same check and estimates savings.

Step 2: Replace Bundled Services

First-generation apps, and second-generation apps that enabled bundled services, need code changes before they run on Cloud Run:

  • Memcache becomes Memorystore reached over Direct VPC egress, with cache code moved to a Redis client.
  • Push task queues become Cloud Tasks queues that call an HTTP endpoint on the service, authenticated with an OIDC token.
  • Users API becomes Identity Platform or another identity provider.
  • Mail API becomes an email provider's API.
  • Datastore needs no data move: the Datastore client library works from Cloud Run with the service's identity.

Step 3: Map Scaling, Instance Class and Identity

An App Engine F2 instance class maps to CPU and memory settings on the Cloud Run service. max_instances and min_instances carry over, and Cloud Run's concurrency setting, 80 requests per instance by default, replaces App Engine's lower per-instance limits, so many apps need fewer instances after the move.

App Engine services ran as the App Engine default service account. Give the Cloud Run service its own service account with only the roles it needs, such as Datastore User, instead of carrying over the broad default.

Step 4: Move Cron and Task Queues

Each cron.yaml entry becomes a Cloud Scheduler job that calls the service URL with an OIDC token for a service account holding the Cloud Run Invoker role. Task queues become Cloud Tasks queues with the same rate and retry settings, targeting the service with an OIDC token as well. Cloud Run services are private unless you allow unauthenticated access. If user traffic must be public, keep the cron and task handlers on a separate private service, or verify the OIDC token in those handlers. Do not make a service that also serves those internal paths unauthenticated.

Step 5: Cut Traffic Over

Deploy the Cloud Run service next to the App Engine app, which keeps serving. Test the run.app URL, then put both behind an external Application Load Balancer with serverless network endpoint groups and shift traffic, or move your custom domain's DNS once you are confident. Keep the App Engine version running until the new service has handled a full day of traffic and every cron job has fired at least once.

How Does Encore Fit an App Engine Migration?

Encore

Encore brings infrastructure from code to Go and TypeScript, and it is a good landing spot for an App Engine app being rewritten during the move, which first-generation Go and Python 2 apps often are. The database, the queue that replaces push task queues and the cron jobs that replace cron.yaml are declared in code, and Encore deploys the services to Cloud Run in your own GCP project with Cloud SQL and Pub/Sub, as described in the GCP infrastructure docs.

Set up the app

Install the Encore CLI with the command for your system, then create the app:

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create guestbook --example=hello-world$ cd guestbook && mkdir -p entries/migrations

The migration creates an entries table with id BIGSERIAL, author, body, created_at and a nullable moderated_at. The handler stores an entry and enqueues moderation, the job a push task queue did, and a cron job replaces the cron.yaml digest:

// entries/entries.go package entries import ( "context" "encore.dev/beta/errs" "encore.dev/cron" "encore.dev/pubsub" "encore.dev/rlog" "encore.dev/storage/sqldb" ) // Cloud SQL for PostgreSQL in your GCP project. var db = sqldb.NewDatabase("entries", sqldb.DatabaseConfig{Migrations: "./migrations"}) type Posted struct{ EntryID int64 } // Replaces the push task queue: a Pub/Sub topic and subscription. var Moderation = pubsub.NewTopic[*Posted]("moderation", pubsub.TopicConfig{ DeliveryGuarantee: pubsub.AtLeastOnce, }) type PostParams struct { Author string `json:"author"` Body string `json:"body"` } //encore:api public method=POST path=/entries func Post(ctx context.Context, p *PostParams) error { if p.Author == "" || p.Body == "" { return &errs.Error{Code: errs.InvalidArgument, Message: "author and body are required"} } var id int64 if err := db.QueryRow(ctx, ` INSERT INTO entries (author, body) VALUES ($1, $2) RETURNING id`, p.Author, p.Body).Scan(&id); err != nil { return err } _, err := Moderation.Publish(ctx, &Posted{EntryID: id}) return err } var _ = pubsub.NewSubscription(Moderation, "moderate-entry", pubsub.SubscriptionConfig[*Posted]{ Handler: func(ctx context.Context, m *Posted) error { // Only the first delivery marks the entry; later ones change nothing. _, err := db.Exec(ctx, ` UPDATE entries SET moderated_at = now() WHERE id = $1 AND moderated_at IS NULL`, m.EntryID) return err }, }) // Replaces the cron.yaml entry "every 24 hours". var _ = cron.NewJob("daily-digest", cron.JobConfig{ Title: "Log a daily count of new entries", Schedule: "0 6 * * *", Endpoint: DailyDigest, }) //encore:api private func DailyDigest(ctx context.Context) error { var n int if err := db.QueryRow(ctx, ` SELECT count(*) FROM entries WHERE created_at > now() - interval '1 day'`).Scan(&n); err != nil { return err } rlog.Info("daily digest", "new_entries", n) return nil }
~/guestbook
$ encore run$ curl -X POST localhost:4000/entries -d '{"author":"ada","body":"hello"}'

encore run starts Postgres and Pub/Sub locally, which App Engine's dev_appserver never fully matched. Cron jobs are managed by the Encore platform and do not run locally or in preview environments, so DailyDigest is called from the local development dashboard while testing. On deploy to a GCP environment, Encore provisions the services on Cloud Run, the Cloud SQL database, the Pub/Sub topic and subscription with a dead-letter topic, and Encore provisions an IAM role for the service, or a service account on GCP, so there is no default service account to narrow down. A coding agent porting the next app.yaml handler adds it to this service and runs it locally in the same change.

Data in Datastore stays in Datastore unless you choose to move it, and a Go service can keep using the Datastore client library alongside the declared Postgres database.

The database, Pub/Sub and cron job docs cover each declaration used here in more detail.

Best fit: teams rewriting an App Engine app during the move who want Cloud Run in their own GCP project, with the database, queues and cron declared in the code.

Common Problems After the Move

  • 403 on every request: the service is private by default. If user traffic must be public, allow unauthenticated invocations only on the service that serves that traffic, keep cron and task handlers on a private service or verify the OIDC token in those handlers, or put user traffic behind a load balancer with IAP.
  • Cron jobs not firing: the Cloud Scheduler job's service account lacks the Cloud Run Invoker role on the service.
  • Memcache calls failing: bundled services do not exist on Cloud Run, so replace them before cutover.
  • Higher latency on the first request: set a minimum number of instances, as App Engine's min_idle_instances did.

Frequently asked questions

How do I migrate an App Engine app to Cloud Run?

For second-generation runtimes without legacy bundled services, run gcloud beta app migrate-to-run --dry-run in the directory with app.yaml to check compatibility, then run it without the flag to build and deploy a Cloud Run service from the same source. Then move cron.yaml and task queues to their replacements, allow public access for user traffic if needed without exposing those internal paths, and shift traffic through a load balancer or DNS.

Can I use App Engine bundled services on Cloud Run?

No. Legacy bundled services such as Memcache, Task Queues, Users and the Mail API are App Engine features. Before moving, replace them with Memorystore, Cloud Tasks or Pub/Sub, Identity Platform and an email provider. Datastore data stays where it is and is reached through the Firestore in Datastore mode client libraries.

Is Cloud Run cheaper than App Engine?

Yes. It is often cheaper, because Cloud Run instances handle many requests at once, 80 by default, while App Engine standard instances typically handle fewer, and Cloud Run can scale to zero for every service. The App Engine migration hub in the console shows estimated savings for your services.

What replaces cron.yaml on Cloud Run?

Cloud Scheduler jobs that call the Cloud Run service's URL with an OIDC token for a service account that has the Cloud Run Invoker role. With Encore, cron jobs are declared in code next to the endpoint they call and are managed by the Encore platform.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders