Deploying container images

This page describes how to deploy new services and new revisions to Cloud Run for Anthos on Google Cloud.

Permissions required to deploy

You need permissions to create, update, and delete on the apiGroup serving.knative.dev and kind Service, and in addition you must have ONE of the following roles:

• Owner
• Editor
• GKE Admin
• GKE Developer

Images you can deploy

There is no size limit that applies to the container image you can deploy.

You can use containers from any container registry, such as Docker Hub. For information on deploying private images from registries different from Container Registry or Artifact Registry, see Deploying private container images from other container registries.

Note: As of November 1, 2020, Docker Hub rate limits apply to unauthenticated or authenticated pull requests on the Docker Free plan. To avoid disruptions and have greater control over your software supply chain, you can migrate your dependencies to Container Registry or Artifact Registry.

Deploying a new service

You can specify a container image with a tag (for example, gcr.io/my-project/my-image:latest) or with an exact digest (for example, gcr.io/my-project/my-image@sha256:41f34ab970ee...).

Deploying to a service for the first time creates its first revision. Note that revisions are immutable. If you deploy from a container image tag, it will be resolved to a digest and the revision will always serve this particular digest.

You can deploy a container using the Cloud Console, the gcloud command line or from a YAML configuration file.

Click the tab for instructions using the tool of your choice.

Console

To deploy a container image:

1. Go to Cloud Run

2. Click Create service to display the Create service page.

   In the form,

   1. Select the Cloud Run platform you are deploying to:

      • Cloud Run for Anthos to deploy to a GKE or GKE on-prem cluster with Cloud Run for Anthos enabled.

   2. From the dropdown menu, select one of the available GKE clusters for your service.

   3. Enter the desired service name. Service names must be unique per region and project or per cluster. A service name cannot be changed later.

   4. Under Connectivity:

      • Select Internal if you want to restrict access only to other Cloud Run for Anthos services or services in your cluster that use Istio.
      • Select External to allow external access to your service

      Note that you can change the connectivity option at any time, as described in Changing service connectivity settings.

   5. Click Next to continue to the second page of the service creation form:

      

      In the form,

      1. In the Container image URL textbox, supply the URL of an image from a supported registry, for example: gcr.io/cloudrun/hello

         To use Artifact Registry with your private container images, you must use the image digest. If you want use the image tag of your private container images, you must create and use an imagePullSecret until the known issue is resolved.

      2. Optionally, click Show Advanced Settings and the subsequent tabs to set:

         • Container configuration
         • Concurrency
         • Request timeout
         • CPU allocation
         • Memory limits
         • Maximum instances
         • Environment variables

      3. Click Create to deploy the image to Cloud Run for Anthos and wait for the deployment to finish.

   You have just deployed a service to a Cloud Run for Anthos enabled cluster.

Command line

To deploy a container image:

1. Run the command:

   gcloud run deploy SERVICE --image IMAGE_URL

   • Replace SERVICE with the name of the service you want to deploy to. If the service does not exist yet, this command creates the service during the deployment. You can omit this parameter entirely, but you will be prompted for the service name if you omit it.

   • Replace IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest.

     If you are using a namespace other than the default, you must also specify that namespace using the --namespace parameter.

     To use Artifact Registry with your private container images, you must use the image digest. If you want use the image tag of your private container images, you must create and use an imagePullSecret until the known issue is resolved.

     You can set connectivity options with the --connectivity flag as described in Changing service connectivity settings to specify internal or external access.

2. Wait for the deployment to finish. Upon successful completion, a success message is displayed along with the URL of the deployed service.

To deploy to a different location from the one you set via the run/region or run/cluster and run/cluster_location gcloud properties, use:

• For Cloud Run for Anthos:

  gcloud run deploy SERVICE --platform gke --cluster CLUSTER-NAME --cluster-location CLUSTER-LOCATION

• For Cloud Run for Anthos on-prem:

  gcloud run deploy SERVICE --platform kubernetes --kubeconfig KUBECONFIG-FILE

YAML

You can store your service specification in a YAML file and then deploy it using the gcloud command line.

1. Create a new service.yaml file with this content:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
   spec:
     template:
       spec:
         containers:
         - image: IMAGE

   Replace

   • SERVICE with the name of your Cloud Run for Anthos service
   • IMAGE with the URL of your container image. To use Artifact Registry with your private container images, you must use the image digest. If you want use the image tag of your private container images, you must create and use an imagePullSecret until the known issue is resolved.

   You can also specify more configuration such as environment variables or memory limits.

2. Deploy the new service using the following command:

   gcloud beta run services replace service.yaml

Cloud Code

To deploy with Cloud Code, read the IntelliJ and Visual Studio Code guides.

Deploying a new revision of an existing service

You can deploy a new revision using the Cloud Console, the gcloud command line, or a YAML configuration file.

Note that changing any configuration settings results in the creation of a new revision, even if there is no change to the container image. Each revision created is immutable.

Click the tab for instructions using the tool of your choice.

Console

To deploy a new revision of an existing service:

1. Go to Cloud Run for Anthos

2. Locate the service you want to update in the services list, and click on it to open the details of that service.

3. Click EDIT & DEPLOY NEW REVISION. This displays the revision deployment form:

   

4. If needed, supply the URL to the new container image you want to deploy.

5. Optionally, set:

   • Container configuration
   • Concurrency
   • Request timeout
   • CPU allocation
   • Memory limits
   • Maximum instances
   • Environment variables

6. To send all traffic to the new revision, check the checkbox labelled Serve this revision immediately. To gradually roll out a new revision, uncheck that checkbox: this will result in a deployment where no traffic is sent to the new revision--follow the instructions for gradual rollouts after you deploy.

7. Click DEPLOY and wait for the deployment to finish.

Command line

To use the command line, you need to have already set up the gcloud command line.

To deploy a container image:

1. Run the command:

   gcloud run deploy SERVICE --image IMAGE_URL

   • Replace SERVICE with the name of the service you are deploying to. You can omit this parameter entirely, but you will be prompted for the service name if you omit it.

   • Replace IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest.

     If you are using a namespace other than the default, you must also specify that namespace using the --namespace parameter.

     The revision suffix is assigned automatically for new revisions. If you want to supply your own revision suffix, use the gcloud command line parameter --revision-suffix.

2. Wait for the deployment to finish. Upon successful completion, a success message is displayed along with the URL of the deployed service.

YAML

Caution: The following instructions replaces your existing service configuration with the one specified in the YAML file. So if you use YAML to make revision changes, you should avoid also using the Cloud Console or gcloud command line to make configuration changes because those can be overwritten when you use YAML.

If you need to download or view the configuration of an existing service, use the following command to save results to a YAML file:

gcloud run services describe SERVICE --format export > service.yaml

From a service configuration YAML file, modify any spec.template child attributes as desired to update revision settings, then deploy the new revision:

gcloud beta run services replace service.yaml

Cloud Code

To deploy a new revision of an existing service with Cloud Code, read the IntelliJ and Visual Studio Code guides.

Deploying images from other Google Cloud projects

You can deploy container images from other Google Cloud projects if you set the correct IAM permissions:

1. In the Cloud Console console, open the project for your Cloud Run for Anthos service.

2. Go to the IAM page

3. If you deploy to:

   • Cloud Run for Anthos, copy the email of the Compute Engine default service account. It has the suffix @developer.gserviceaccount.com

   • Cloud Run for Anthos on-prem, create a Google Cloud service account and download the credentials. Add these credentials as the default imagePullSecrets of the Kubernetes Service Account.

4. Open the project that owns the container registry you want to use.

5. Go to the IAM page

6. Click Add to add a new member.

7. In the New members text box, paste in the email of the service account that you copied earlier.

8. In the Select a role dropdown list, select the role Storage -> Storage Object Viewer.

9. Deploy the container image to the project that contains your Cloud Run for Anthos service.

   Note: For stronger security, you can limit grant access to only the Cloud Storage bucket that contains your container images.

Deploying private container images from other container registries

This section describes setting up correct permissions to deploy container images from an arbitrary private registry to Cloud Run for Anthos. A private container registry requires credentials to access the container image. Note that you do not need to follow these steps to deploy private container images from Container Registry or Artifact Registry in the same project as your cluster.

To be able to deploy a private container image, you must create an imagePullSecret type Kubernetes secret and associate it with a service account:

1. Create an imagePullSecret secret called container-registry:

   kubectl create secret container-registry \
   --docker-server=DOCKER_REGISTRY_SERVER \
   --docker-email=REGISTRY_EMAIL \
   --docker-username=REGISTRY_USER \
   --docker-password=REGISTRY_PASSWORD

   • Replace DOCKER_REGISTRY_SERVER with your private registry FQDN (ex: https://gcr.io/ for Container Registry or https://hub.docker.com for DockerHub).
   • Replace REGISTRY_EMAIL with your email.

   • Replace REGISTRY_USER with your container registry username.

     If you're using Container Registry or Artifact Registry and would like to store and pull long-lived credentials instead of passing short-lived access tokens, see Authentication methods: JSON key file.

   • Replace REGISTRY_PASSWORD with your container registry password.

2. Open your default service account:

   kubectl edit serviceaccount default --namespace default

   Every namespace in your Kubernetes cluster has a default service account called default. This default service account is used to pull your container image unless otherwise specified when you deploy your Cloud Run for Anthos service.

3. Add the newly created imagePullSecret secret to your default service account:

   imagePullSecrets:
   - name: container-registry
   

   Your service account should now look like this:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: default
     namespace: default
     ...
   secrets:
   - name: default-token-zd84v
   # The secret we just created:
   imagePullSecrets:
   - name: container-registry
   

Now, any new pods created in the current default namespace will have the imagePullSecret secret defined.

Deploying with automatic Istio sidecar injection enabled

To deploy your service on the namespace with automatic Istio sidecar injection enabled, you must use a separate Istio installation.

Deploying services on an internal network

Deploying services on an internal network is useful for enterprises that provide internal apps to their staff, and for services that are used by clients that run outside the Cloud Run for Anthos cluster.

To deploy services on an internal network, see Setting up a private, internal network.

What's next

After you deploy a new service, you can do the following:

• Gradual rollouts, rollback revisions, traffic migration
• View service logs
• Monitor service performances
• Set memory limits
• Set environment variables
• Change service concurrency
• Manage the service
• Manage service revisions

You can automate the builds and deployments of your Cloud Run for Anthos services using Cloud Build Triggers:

• Set up Continuous Deployment