Cloud Run and Kubernetes both use standard container images asdeployment artifacts, they both use a declarative API model with resources thatcan be represented in YAML files with the same standard structure.

Introduction

TheCloud Run Admin API v1is designed to maximize portability with Kubernetes,for example, the Cloud Run Admin API resources share the same structureconventions and attribute names as Kubernetes resources. See theCloud Run service YAML reference.

The Cloud Run Admin API v1 implements theKnative Serving API specification,but you donot need to be using Knative in your existing Kubernetescluster in order to migrate some of your Kubernetes workloads toCloud Run.

The primary resource of Cloud Run is theservice.You can think of a Cloud Run service as a high levelabstraction that looks like a Kubernetesdeployment with a built-in pod autoscaler and unique endpoint. A "Pod" in Kubernetescorresponds to an "instance" in Cloud Run.We recommend transforming your Kubernetes deployments into Cloud Runservices, one service at a time.You will also be able to merge some configuration of your KubernetesHorizontal Pod Autoscaler and Kubernetesservices into the Cloud Run service.

Cloud Run does not have the concept of namespace, instead theGoogle Cloud project is used as an isolation boundary between resources.When migrating to Cloud Run from Kubernetes, we recommend creating oneGoogle Cloud project for each namespace. In theYAML of a Cloud Runservice, the namespace value is the Google Cloud project number.

Cloud Run has abuilt-in zonal redundancy,this means that you do not need to provision replica to ensure your service isresilient to a zonal outage in the selected Google Cloud region.

Quickstart

This quickstart is an example of a simple migration example.

Simple resource comparison

Compare the following simple Kubernetesdeployment namedmy-app with the equivalent Cloud Run service.Note how the YAML files are almost identical.

The parts inblue are different andneed to be changed.The parts inred should be deletedbecause Cloud Run has a built-in autoscaler.

apiVersion:apps/v1kind:Deploymentmetadata:  name: my-app  namespace: default  labels:    app: my-appspec:  template:    metadata:      labels:        app: my-app    spec:      containers:      - image: gcr.io/cloudrun/hello        env:        - name: HELLO          value: worldreplicas: 3selector:matchLabels:app: my-app

apiVersion:serving.knative.dev/v1kind:Servicemetadata:  name: my-app  namespace: 'PROJECT_NUMBER'  labels:    app: my-appspec:  template:    metadata:      labels:        app: my-app    spec:      containers:      - image: gcr.io/cloudrun/hello        env:        - name: HELLO          value: world

Migrate a simple Kubernetes deployment to Cloud Run

1. Download the YAML file of your deployment in the current directory with:

   kubectlgetdeploymentmy-app-oyaml>my-app.yaml

2. Modify the YAML to match a Cloud Run service.Update themy-app.yaml file:

   • For the "kind" attribute: replace the value "Deployment" with "Service"
   • For the "apiVersion" attribute: replace the value "apps/v1" with"serving.knative.dev/v1"
   • Delete themetadata.namespace attribute or change its value to matchyour Google Cloud project number.
   • Deletespec.replicas andspec.selector

3. Deploy themy-app.yaml file to Cloud Run using the followingcommand, replacingREGION with the desired Google Cloud region,for exampleeurope-west1:

   gcloudrunservicesreplacemy-app.yaml--regionREGION

Invoking a Cloud Run service is protected by an IAM permission.If you want to expose the new Cloud Run service publicly tothe internet and allow public access, run the following command:

gcloudrunservicesadd-iam-policy-bindingmy-app--member="allUsers"--role="roles/run.invoker"--regionREGION

Features not supported by Cloud Run

Only workloads that are afit for Cloud Runcan be migrated.

Notably, the following Kubernetes features are not supported byCloud Run:

• Fixed numbers ofreplicas (a workaround is to use the same number ofminimum andmaximum instances
• Config Maps (workaround available)
• Custom horizontal Pod autoscaler strategies
• Service Discovery
• Local Disk (Ephemeral and Persistent)

When migrating a YAML file from a Kubernetes deployment to a Cloud Runservice, thegcloud run services replace command will return a clear errormessage for any attribute that is not supported by Cloud Run.Delete or update these attributes, then repeat the command until it succeeds.

You can refer to theYAML Reference for anexhaustive list of attributes support by Cloud Run.

Migrate Kubernetes resources

Migrate Kubernetes secrets

Like Kubernetes, Cloud Run supports mounting secrets as environmentvariables or volumes, but secrets should be stored inSecret Manager.

There are several important differences between Secret Managersecrets and Kubernetes secrets:

• Allowed characters in names:
  • Kubernetes secrets:[a-z0-9-.]{1,253}
  • Secret Manager secrets:[a-zA-Z0-9_-]{1,255}
• Versioning: Secrets from Secret Manager are versioned, whileKubernetes secrets aren't.
• Payload: Secrets from Secret Manager contain a single[]byte, while Kubernetes secrets contain amap<string, string>.

Follow the Secret Manager documentation tocreate a secretandadd a new secret versionfor every secret key your Kubernetes app depends on.

Migrate Kubernetes ConfigMaps

Cloud Run does not have an equivalent of KubernetesConfigMaps,but because ConfigMaps can be seen as unencrypted Secrets, you can transformyour ConfigMaps into secrets in Secret Manager instead.See instructions underMigrate Kubernetes secrets.

Migrate a Kubernetes deployment

The Kubernetes deployment exposed by a service is the resource that maps theclosest to a Cloud Run service.We recommend starting from the YAML of your Kubernetes deploymentand editing it to transform it into a Cloud Run service.

The main required changes are:

• Thenamespace must be replaced with the Google Cloud project number.
• Labels (metadata.labels andspec.template.metadata.labels) must bevalid Google Cloud labels.
• Containers must be stored in asupported container registry.
• CPU andmemorylimits might need to be adjusted.
• When referencing a secret, the "key" attribute is used to capture theversion in Secret Manager, with "latest" referencing the latestversion of the secret.
• serviceAccountName should reference a Service Account inthe current Google Cloud project
• References to ConfigMaps (configMapKeyRef) should be replaced withreferences to secrets (secretKeyRef)

If your Kubernetes deployment is accessing other resources in your Kubernetescluster or resources on a VPC, you mustconnect the Cloud Runservice to the appropriate VPC

Migrate a Kubernetes service

Cloud Run services automatically expose a unique endpoint that routestraffic to the container with acontainerPort.After you have migrated your Kubernetes deployment to a Cloud Runservice, you don't need to migrate theKubernetes services that was routing traffic to this deployment.

Migrate a Kubernetes HorizontalPodAutoscaler

Cloud Run services have a built-in horizontal autoscaler:Cloud Run automatically scales pods (called "instances") usinga combination of factors within theboundaries of its defined minimum and maximum number of instances.

Migrate theminReplicas andmaxReplicas attributes of theHorizontalPodAutoscaler to theautoscaling.knative.dev/minScale andautoscaling.knative.dev/maxScaleannotations of the Cloud Run service.Refer to the documentation on configuringminimum instances andmaximum instances.

Migrate a Kubernetes deployment without a service

If your Kubernetes deployment performs background or scheduled tasks, and isn'texposed by a service, you can migrate to aCloud Run worker pool.

The following samples show the structural difference between aKubernetes deployment and a Cloud Run worker pool:

apiVersion:apps/v1kind:Deploymentmetadata:  name: my-app  namespace: default  labels:    app: my-appspec:  template:    metadata:      labels:        app: my-app    spec:      containers:      - image: gcr.io/cloudrun/hello        env:        - name: HELLO          value: worldreplicas: 3selector:matchLabels:

apiVersion:run.googleapis.com/v1kind:WorkerPoolmetadata:  name: my-app  annotations:    run.googleapis.com/manualInstanceCount:'1'spec:template:    metadata:      labels:      app: my-app    spec:      containers:      - image: gcr.io/cloudrun/hello        env:        - name: HELLO          value: world

Migrate a Kubernetes job

Because aKubernetes job is similar to aCloud Run job execution.You can migrate to aCloud Run jobandexecute the job.

The following samples show the structural difference between aKubernetes job and a Cloud Run job:

apiVersion:batch/v1kind: Jobmetadata:  name: my-jobspec:  template:    spec:      containers:      - image: us-docker.pkg.dev/cloudrun/container/job

apiVersion:run.googleapis.com/v1kind: Jobmetadata:  name: my-jobspec:template:    spec:      template:        spec:          containers:          - image: us-docker.pkg.dev/cloudrun/container/job

Migration strategy

After youcreate the equivalent resources, exposing external endpoints behind a global external Application Load Balancerenables you to gradually migrate traffic between Cloud Run andGoogle Kubernetes Engine (GKE).