Migrating a Knative serving service to Cloud Run

Use this guide to migrate your workloads to Cloud Run. In general, migrating your workloads requires you to port over any of the Kubernetes-based features and then redeploy each of your existing services to Cloud Run.

Key benefits of migrating to Cloud Run:

  • Fully managed serverless product that implements the Knative Serving API specification and adheres to the container contract.

  • The v1 Admin API of Cloud Run is designed to maximize portability with Knative serving.

  • The user experience is similar across Cloud Run and Knative serving:

    • The gcloud run command group is used across both products.
    • Similar user interface layout and behavior in Google Cloud console.

Before you begin

The following Google Kubernetes Engine features are not supported in Cloud Run, including:

Migration considerations

You must review and understand the following differences across the products to ensure that you can port over all your dependencies and requirements.


In Cloud Run, you can choose to mount secrets as environment variables or volumes, but secrets with sensitive information should be stored in Secret Manager.

Important differences between secrets in Secret Manager and Kubernetes secrets:

Feature Secret Manager secrets Kubernetes secrets
Allowed characters in names [a-zA-Z0-9_-]{1,255} [a-z0-9-.]{1,253}
Versioning Secrets are versioned No support
Secret Payload Single []byte Map: <string, string>

Learn how to use Secret Manager to create versioned secrets for the secret keys of your Knative serving services.


Use the following information to help you port over your existing network configuration to Cloud Run.

Service Endpoints
The Kubernetes Endpoints of your Knative serving services are not supported in Cloud Run. Learn more about the unique endpoints in Cloud Run.
Domains Mappings
The Cloud Run DomainMapping API is compatible with Knative serving. However, Cloud Run offers domain mapping in a subset of the available Cloud Run locations. A recommended alternative is to leverage Global HTTP(S) Load Balancer for your custom domains.
VPC connectivity
Cloud Run services reside outside your VPC. To communicate with resources within a VPC, you must use the Serverless VPC Access Connector.
Ingress controls
If your Knative serving service is configured for a private internal network and uses an internal load balancer (ILB), you can configure your Cloud Run service to Ingress = Internal. Configuring your services to internal restricts access to within your VPC or other Cloud Run services. Learn more about service to service communication.

Migrating a service

To migrate a service, you must export your Knative serving service, edit the exported YAML file, and then deploy your reconfigured service to Cloud Run.

  1. Export your Knative serving service to a local YAML file by running the following command:

    gcloud run services describe SERVICE --format export --namespace NAMESPACE --cluster CLUSTER --platform gke > FILENAME.yaml


    • SERVICE with the name of your Knative serving service.
    • NAMESPACE with the namespace where your service is running.
    • CLUSTER with the name of the cluster where your service is running.
    • FILENAME with a unique filename of your choice.
  2. Modify the exported FILENAME.yaml file for Cloud Run:

    • You must search and replace the Kubernetes namespace with the ID of your Google Cloud project. For example, you must replace namespace:default with namespace:my-unique-id.
    • You must update all configurations for any of the unsupported features.
    • You must delete any of the following attributes and their values:

      • metadata.annotations.kubectl.kubernetes.io/last-applied-configuration
      • metadata.managedFields
      • spec.template.spec.containers.readinessProbes
      • spec.template.spec.enableServiceLinks

      For example, you might need to remove the following configuration from under the spec: > template: > spec: > containers: attributes:

         successThreshold: 1
         tcpSocket: {}
  3. Deploy the modified .yaml file to Cloud Run using the --platform managed flag. Learn more about deploying.

    Note that you can use the same Google Cloud project for Cloud Run.

    gcloud run services replace FILENAME.yaml --platform managed --region REGION


    • FILENAME with the name of the exported configuration file that you created.
    • REGION with a supported Cloud Run location. For example: us-central1
  4. Configure access to your Cloud Run service:

  5. In the Google Cloud console, within your services page, you can click the displayed URL link to open the unique and stable endpoint of your deployed service.

    Go to Cloud Run

Migrating traffic to your service

After you have tested your newly deployed services and are ready to migrate all of your production traffic, you can configure your custom domain and update your DNS records with your registrar. Follow the instructions at Mapping custom domains.