Container concepts

This document introduces key concepts related to containers including registries, repositories, and artifacts. Some basic information on how these concepts apply to Artifact Registry and Container Registry is also included.

Registries

A registry stores and distributes container images and artifacts organized by name within repositories. A registry may contain either a single repository or multiple repositories and can be public or private.

Registry services such as Docker Hub and Artifact Registry provide options to create public or private repositories. When pulling public images it is important to understand the possible security concerns. Read about dependency management for more information on vulnerability monitoring and reducing your dependency footprint.

Registries are organized into repositories which store individual container images. Artifact Registry lets you to create multiple repositories in a single project and associate a specific region or multi-region with each repository. Related repositories may be grouped by labels.

Repositories

Images and artifacts with the same name, but different tags are organized into repositories. If no tag is specified when an image is pushed to a repository, the image is tagged with the latest tag. If another image is pushed without specifying a tag, the latest tag is moved from the original image to the newer image, leaving the first image without a tag. We recommend giving releases a tag other than latest.

The term repository is not always used consistently; within Artifact Registry it is more useful to use parts of the path to the image to identify the project, region or multi-region and name of the image along with the tag or manifest digest to identify the correct version.

For example:

docker push us-west1-docker.pkg.dev/PROJECT/quickstart-docker-repo/quickstart-image:tag1

  • us-west1 is the location of the repository
  • docker.pkg.dev is the hostname for Docker repositories.
  • PROJECT is the namespace created by your Google Cloud project ID.
  • quickstart-docker-repo is the namespace under your project where you store images. In Artifact Registry, this part of the path is called the repository.
  • quickstart-image is the repository for all versions of quickstart-image and is often referred to as the image.
  • tag1 is the tag specifying the version of the image.

Images

Both artifacts and images can be stored within Artifact Registry. An artifact can be anything: a text file, a docker image, or a Helm chart, while an image typically refers to a container image. Container images are packages of software that contain all the necessary elements to run in any environment. Read What are containers for more information.

Images are pushed or uploaded to repositories and pulled or downloaded from repositories. In order to specify the correct image and version the unique registry and artifact must be specified.

For example:

docker pull us-west1-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0

  • us-west1-docker.pkg.dev is the registry
  • /google-samples/containers/gke/ are the namespace and sub-namespaces. In Artifact Registry google-samples is the Google Cloud project and containers is referred to as the Artifact Registry repository
  • hello-app is the artifact name
  • :1.0 is the tag specifying the version of artifact to be pulled

Layers

Container images stored in repositories are constructed incrementally using layers. Different images can use some of the same layers. Layers are defined in different ways depending on the type of image, for instance, each instruction in a Dockerfile corresponds to a layer in the Docker image. Within a registry, images with common layers share those layers, increasing storage efficiency. For security, layers are not shared across different registries.

When you delete a container image, the layers aren't deleted immediately. Layers that aren't referenced by any images in the registry are deleted daily.

Tags

Users add tags when pushing or pulling an image to a repository to specify the version of an image. An image can have one or multiple tags, or no tags at all. If you push an image twice with the same tag, the tag is removed from the first image and moved to the second, leaving the first image without a tag. The un-tagged image is still accessible via its manifest digests.

The latest tag is a special tag appended when images are pushed without a tag.

For example:

docker push us-west1-docker.pkg.dev/my-project/my-repo/hello-app

pushes the image to hello-app:latest

docker pull us-west1-docker.pkg.dev/my-project/my-repo/hello-app

pulls the image hello-app:latest.

It is important to note that when an image is pushed to a repository with a tag other than latest, the latest tag is not added, therefore it is possible for the latest image to be behind the most up to date changes. We recommended using tags other than latest for releases.

Manifests

Image Manifests uniquely identify and specify the layers within each image. Manifests are identified by unique SHA-256 hashes called manifest digests. Manifest digests are more reliable and secure than tags because multiple versions of the same image may be pushed to the same tag, leaving some images without tags, while each image is uniquely specified by its manifest digest.

If you use tools to scan or analyze images, results from these tools are only valid for the image scanned. To ensure that you deploy the image that was scanned, you cannot rely on the tag because the image referred by the tag may change.

To learn more about Artifact Registry specific tagging and manifests, read Managing Images and Using container Images.

What's next