Deploy a Cloud Run service or job

This document describes how to deploy your applications, including Cloud Run services and Cloud Run jobs.

Cloud Deploy allows you to deploy your container-based workloads to any Cloud Run service or job. All Cloud Deploy features are supported when you deploy to Cloud Run targets for Cloud Run services, but canary deployments aren't supported for Cloud Run jobs.

This document describes the three main configurations you need to complete in order to deploy to Cloud Run:

Limitations

  • You can only deploy one Cloud Run service or job per target.

  • You can't run a canary deployment against a Cloud Run job.

    Cloud Run services, however, can use a canary deployment.

Before you begin

Create your target configuration

The target can be configured in your delivery pipeline YAML, or can be in a separate file. Also, you can configure more than one target in the same file.

Targets must be defined in the same project and region as the delivery pipeline. But the services or jobs the targets deploy to can be in different projects and regions, as long as the service account has access to those projects.

In the target definition, create a run stanza to identify the location where the Cloud Run service will be created.

The syntax for specifying the Cloud Run service or job in your target definition is as follows:

run:
 location: projects/[project_name]/locations/[region_name]

This resource identifier uses the following elements:

  • [project_name] is the name of the Google Cloud project in which your Cloud Run service or job will be created.

    You'll do this for each target. We recommend a different project for each Cloud Run service or job. If you want more than one service or job in the same project, you need to use Skaffold profiles in your skaffold.yaml configuration file.

  • [region_name] is the region in which the service or job will be created. Your service or job can be in any region that Cloud Run supports.

The following is an example target configuration, defining the Cloud Run service or job to create:

      apiVersion: deploy.cloud.google.com/v1
      kind: Target
      metadata:
       name: dev
      description: development service
      run:
       location: projects/my-app/locations/us-central1

You can define this target inside a Cloud Deploy delivery pipeline definition, or separately. Either way, you must register the target before you create the release to deploy your Cloud Run service or job.

Create your Skaffold configuration

The following is an example skaffold.yaml file for a Cloud Run deployment:

apiVersion: skaffold/v4beta7
kind: Config
metadata: 
  name: cloud-run-application
manifests:
  rawYaml:
  - service.yaml
deploy:
  cloudrun: {}

In this skaffold.yaml file...

  • manifests.rawYaml provides the names of the Cloud Run service definitions.

    In this example, service.yaml is the file that defines a Cloud Run service that Skaffold will deploy. This filename can be anything, but by convention it's service.yaml for a service, and job.yaml for a job.

  • The deploy stanza specifies how you want the manifest to be deployed, specifically, the project and location. deploy is required.

    We recommend you leave the empty {}. Cloud Deploy populates this during rendering, based on the project and location from the target definition.

    For local development, however, you can provide values here. However, Cloud Deploy always use the project and location from the target definition, regardless of whether values are provided here.

Create your Cloud Run service definitions

To create a Cloud Run service definition, you can either create one manually, or copy one from an existing service. Both are described in this section.

Option 1: create a new Cloud Run service.yaml

The service.yaml defines your Cloud Run service. When you create a release, Skaffold uses this definition to deploy your service.

Here's a simplified example:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
 name: [SERVICE_NAME]
spec:
 template:
  spec:
   containers:
   - image: [IMAGE_PATH]

Where:

  • [SERVICE_NAME] is a name for this Cloud Run service.

  • [IMAGE_PATH] points to the container image or images you're deploying with this service.

Option 2: copy a service.yaml from an existing service using Google Cloud console

You can create a service using Google Cloud console or use an existing one, and copy your service.yaml from there.

To get the service.yaml using Google Cloud CLI:

gcloud run services describe [service_name] --format=export

To get the service.yaml from Google Cloud console:

  1. In Google Cloud console, go to the Cloud Run Services page.

  2. Select the existing service whose definition you want to use.

Or you can create a new one, then select it. When you select the service, the Service Details page is shown:

service details page Google Cloud console, showing the YAML tab

  1. Select the YAML tab.

  2. Click Edit, then copy the contents of the YAML into a new file called service.yaml, in your file system, such that Skaffold can use it when you create a release.

Create your Cloud Run job definitions

To deploy a Cloud Run job definition, you can either create one manually, or copy one from an existing job. Both are described in this section.

Note that jobs aren't necessarily run upon being deployed by Cloud Deploy. This is different from services, which are running applications after they're deployed. How a job is invoked depends on the job itself.

Option 1: create a new Cloud Run job.yaml

The job.yaml defines your Cloud Run job. When you create a release, Skaffold uses this definition to deploy the job.

Here's a simplified example:

apiVersion: run.googleapis.com/v1
kind: Job
metadata:
 name: [JOB_NAME]
spec:
  template:
  spec:
   containers:
   - image: [IMAGE_PATH]

Where:

  • [JOB_NAME] is a name for this Cloud Run job.

  • [IMAGE_PATH] points to the container image you're deploying for this job.

Option 2: copy a job.yaml from an existing job using Google Cloud console

You can create a job using Google Cloud console or use an existing one, and copy your job.yaml from there.

To get the job.yaml using Google Cloud CLI:

gcloud run jobs describe [job_name] --format=export

To get the job.yaml from Google Cloud console:

  1. In Google Cloud console, go to the Cloud Run Jobs page.

  2. Select the existing job whose definition you want to use.

Or you can create a new one, then select it. When you select the job, the Job Details page is shown:

job details page Google Cloud console, showing the YAML tab

  1. Select the YAML tab.

  2. Click Edit, then copy the contents of the YAML into a new file called job.yaml, in your file system, such that Skaffold can use it when you create a release.

Putting it all together

Now that you have your Cloud Run service or job definition, your skaffold.yaml configuration, and your Cloud Deploy target definition, and you've registered your target as a Cloud Deploy resource, you can now invoke your delivery pipeline to create a release and progress it through the progression of targets defined in the pipeline.

The quickstart Deploy an app to Cloud Run using Cloud Deploy shows all of this in action.

Behavior of services across revisions

When you re-deploy a service, the new revision is based on the newly deployed service.yaml. Nothing about the previous revision is maintained, unless it's the same in the newly deployed YAML. For example, if there are configuration settings or labels in the previous revision that are not in the new YAML, those settings or labels are absent from the new revision.

Triggering Cloud Run jobs

After you deploy a job, you can trigger it as described in the Cloud Run documentation.

Deploying Cloud Run services and jobs in multiple projects

If you need to deploy services or jobs that are in different projects, your execution service account needs permission to access the projects in which those services or jobs are defined.

See Cloud Deploy execution service account and Identity and Access Management roles and permissions for more information.

What's next