This document explains how to create and utilize a public or private Google Container Registry (GCR) docker image from inside FireCloud. This guide is useful for migrating or mirroring existing images from other repositories such as DockerHub. For a primer on what Docker containers are for and related terminology, see this Dictionary entry.
Some of these instructions were adapted from Google GCR Documentation.
To create a new image, follow the first section of this tutorial to create a docker image and tag an image.
If you already have an image you want to use and you have a local copy, simply continue to the next step (2. Tag image). If your image is stored in DockerHub and you want to migrate it to GCR, first you need to pull it locally with this command:
docker pull <REPOSITORY-NAME>/<IMAGE>:<TAG>
<REPOSITORY-NAME> is the name of the repository where the docker is stored,
<IMAGE> is the name of the image you are pulling, and
<TAG> is a keyword or version number that you want to attach to identify a specific image.
Note that the default tag is
latest. While this can be convenient for some purposes, we don't recommend using the "latest" tag when pipelining commands in real work, unless you're sure that you're willing to take the chance that the version of what you're running might change without warning. It's better practice to use explicit tags. both for pulling and pushing images.
Before you push your Docker image to GCR, you need to tag it with its registry name. Tagging your Docker image with a registry name configures the docker push command to push the image to a specific location. The registry name format is:
[PROJECT-ID] is your Google Cloud Platform Console project ID and
[IMAGE] is your image's name.
To tag your Docker image for Container Registry, run this command:
docker tag [IMAGE] gcr.io/[PROJECT-ID]/[IMAGE]
docker tag quickstart-image gcr.io/my-project/quickstart-image
You are now ready to push your image to GCR!
To push your Docker image to Container Registry, run this command:
docker push gcr.io/[PROJECT-ID]/[IMAGE]
docker push gcr.io/my-project/quickstart-image
You can view your freshly-pushed image in GCR by visiting the image’s registry at
http://gcr.io/<PROJECT-ID>/<IMAGE>. You can also view your image where it is stored in the Google Bucket. The directory will be named
artifacts.<PROJECT-ID>.appspot.com for images pushed to
By default, Google stores your images privately so only authorized users have permission to use them. You have the option of sharing your images publicly as well; see the next step, which is optional.
You can also make your images public, which has the benefit of allowing you to use them in FireCloud or directly through Cromwell without following any more steps in this tutorial.
To do this through the Google Console, go to the Google Bucket that you want to make public.
allUsersin the “Add members” field.
This will give pull (read-only) permissions to all users. You can also change the Bucket permissions with the Google Cloud SDK. Note that each Google Bucket is either entirely public or not; it is not possible to publicly serve only specific images. If you have specific images you want to make public while keeping the rest private, create a separate Bucket and GCR to make it public.
If in the future you change an image from public to private, be aware that any pipelines that use this formerly-public image will break for anyone who does not have access to the private image.
You can share your images with a new group or an existing group within FireCloud. We strongly recommend that you share with a group (as opposed to an individual) if you ever plan on sharing your images in the future, as you can easily add new people to the FireCloud group. As an added benefit, they will have access to all of the images that you have ever shared with that group.
To do this, go to FireCloud and view your groups. To create a new group, click “Create New Group…” and follow the instructions to create and save a group.
Then you can simply give that group access to your GCR bucket as follows:
This will give pull (read-only) permissions to FireCloud users who are in the FireCloud group.
The path to your image in GCR is
gcr.io/<PROJECT-ID>/<IMAGE>, for example,
gcr.io/my-project/quickstart-image; use this image path in your WDL workflow.