You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/container-registry/container-registry-concepts.md
+24-26Lines changed: 24 additions & 26 deletions
Original file line number
Diff line number
Diff line change
@@ -1,29 +1,26 @@
1
1
---
2
-
title: About repositories & images
3
-
description: Introduction to key concepts of Azure container registries, repositories, and container images.
2
+
title: About registries, repositories, images, and artifacts
3
+
description: Introduction to key concepts of Azure container registries, repositories, container images, and other artifacts.
4
4
ms.topic: article
5
-
ms.date: 01/05/2021
5
+
ms.date: 01/29/2021
6
6
---
7
7
8
-
# About registries, repositories, and images
8
+
# About registries, repositories, and artifacts
9
9
10
10
This article introduces the key concepts of container registries, repositories, and container images and related artifacts.
11
11
12
-
:::image type="content" source="media/container-registry-concepts/registry-elements.png" alt-text="Registry, repositories, and images":::
12
+
:::image type="content" source="media/container-registry-concepts/registry-elements.png" alt-text="Registry, repositories, and artifacts":::
13
13
14
14
## Registry
15
15
16
-
A container *registry* is a service that stores and distributes container images. Docker Hub is an example of a public container registry that serves as a general catalog of images. Azure Container Registry provides users with direct control of their images, with integrated authentication, [geo-replication](container-registry-geo-replication.md) supporting global distribution and reliability for network-close deployments, [virtual network configuration with Private Link](container-registry-private-link.md), [tag locking](container-registry-image-lock.md), and many other enhanced features.
16
+
A container *registry* is a service that stores and distributes container images and related artifacts. Docker Hub is an example of a public container registry that serves as a general catalog of Docker container images. Azure Container Registry provides users with direct control of their container content, with integrated authentication, [geo-replication](container-registry-geo-replication.md) supporting global distribution and reliability for network-close deployments, [virtual network configuration with Private Link](container-registry-private-link.md), [tag locking](container-registry-image-lock.md), and many other enhanced features.
17
17
18
-
In addition to Docker container images, Azure Container Registry supports related [content artifacts](container-registry-image-formats.md) including Open Container Initiative (OCI) image formats.
18
+
In addition to Docker-compatible container images, Azure Container Registry supports a range of [content artifacts](container-registry-image-formats.md) including Helm charts and Open Container Initiative (OCI) image formats.
19
19
20
-
When using Docker or other client tools to pull or push artifacts to an Azure container registry, use the registry's fully qualified name, also called the *login server* name. In the Azure cloud, the fully qualified name of an Azure container registry is in the format `myregistry.azurecr.io` (all lowercase).
21
-
22
20
## Repository
23
21
24
22
A *repository* is a collection of container images or other artifacts in a registry that have the same name, but different tags. For example, the following three images are in the `acr-helloworld` repository:
25
23
26
-
27
24
-*acr-helloworld:latest*
28
25
-*acr-helloworld:v1*
29
26
-*acr-helloworld:v2*
@@ -40,7 +37,7 @@ Repository names can only include lowercase alphanumeric characters, periods, da
40
37
41
38
For complete repository naming rules, see the [Open Container Initiative Distribution Specification](https://github.com/docker/distribution/blob/master/docs/spec/api.md#overview).
42
39
43
-
## Image
40
+
## Artifact
44
41
45
42
A container image or other artifact within a registry is associated with one or more tags, has one or more layers, and is identified by a manifest. Understanding how these components relate to each other can help you manage your registry effectively.
46
43
@@ -56,17 +53,17 @@ For tag naming rules, see the [Docker documentation](https://docs.docker.com/eng
56
53
57
54
### Layer
58
55
59
-
Container images are made up of one or more *layers*, each corresponding to a line in the Dockerfile that defines the image. Images in a registry share common layers, increasing storage efficiency. For example, several images in different repositories might have a common ASP.NET Core base layer, but only one copy of that layer is stored in the registry.
56
+
Container images and artifacts are made up of one or more *layers*. Different artifact types define layers differently. For example, in a Docker container image, each layer corresponds to a line in the Dockerfile that defines the image:
60
57
61
58
:::image type="content" source="media/container-registry-concepts/container-image-layers.png" alt-text="Layers of a container image":::
62
59
63
-
Layer sharing also optimizes layer distribution to nodes, with multiple images sharing common layers. For example, if an image already on a node includes the ASP.NET Core layer as its base, the subsequent pull of a different image referencing the same layer doesn't transfer the layer to the node. Instead, it references the layer already existing on the node.
60
+
Artifacts in a registry share common layers, increasing storage efficiency. For example, several images in different repositories might have a common ASP.NET Core base layer, but only one copy of that layer is stored in the registry. Layer sharing also optimizes layer distribution to nodes, with multiple artifacts sharing common layers. If an image already on a node includes the ASP.NET Core layer as its base, the subsequent pull of a different image referencing the same layer doesn't transfer the layer to the node. Instead, it references the layer already existing on the node.
64
61
65
62
To provide secure isolation and protection from potential layer manipulation, layers are not shared across registries.
66
63
67
64
### Manifest
68
65
69
-
Each container image or artifact pushed to a container registry is associated with a *manifest*. The manifest, generated by the registry when the image is pushed, uniquely identifies the image and specifies its layers. You can list the manifests for a repository with the Azure CLI command [az acr repository show-manifests][az-acr-repository-show-manifests]:
66
+
Each container image or artifact pushed to a container registry is associated with a *manifest*. The manifest, generated by the registry when the content is pushed, uniquely identifies the artifacts and specifies the layers. You can list the manifests for a repository with the Azure CLI command [az acr repository show-manifests][az-acr-repository-show-manifests]:
70
67
71
68
```azurecli
72
69
az acr repository show-manifests --name <acrName> --repository <repositoryName>
Manifests are identified by a unique SHA-256 hash, or *manifest digest*. Each image or artifact--whether tagged or not--is identified by its digest. The digest value is unique even if the image's layer data is identical to that of another image. This mechanism is what allows you to repeatedly push identically tagged images to a registry. For example, you can repeatedly push `myimage:latest` to your registry without error because each image is identified by its unique digest.
107
+
Manifests are identified by a unique SHA-256 hash, or *manifest digest*. Each image or artifact--whether tagged or not--is identified by its digest. The digest value is unique even if the artifact's layer data is identical to that of another artifact. This mechanism is what allows you to repeatedly push identically tagged images to a registry. For example, you can repeatedly push `myimage:latest` to your registry without error because each image is identified by its unique digest.
111
108
112
-
You can pull an image from a registry by specifying its digest in the pull operation. Some systems may be configured to pull by digest because it guarantees the image version being pulled, even if an identically tagged image is pushed later to the registry.
109
+
You can pull an artifact from a registry by specifying its digest in the pull operation. Some systems may be configured to pull by digest because it guarantees the image version being pulled, even if an identically tagged image is pushed later to the registry.
113
110
114
111
> [!IMPORTANT]
115
-
> If you repeatedly push modified images with identical tags, you might create orphaned images--images that are untagged, but still consume space in your registry. Untagged images are not shown in the Azure CLI or in the Azure portal when you list or view images by tag. However, their layers still exist and consume space in your registry. Deleting an untagged image frees registry space when the manifest is the only one, or the last one, pointing to a particular layer. For information about freeing space used by untagged images, see [Delete container images in Azure Container Registry](container-registry-delete.md).
112
+
> If you repeatedly push modified artifacts with identical tags, you might create "orphans"--artifacts that are untagged, but still consume space in your registry. Untagged images are not shown in the Azure CLI or in the Azure portal when you list or view images by tag. However, their layers still exist and consume space in your registry. Deleting an untagged image frees registry space when the manifest is the only one, or the last one, pointing to a particular layer. For information about freeing space used by untagged images, see [Delete container images in Azure Container Registry](container-registry-delete.md).
116
113
117
114
## Addressing an artifact
118
115
119
-
To address a registry artifact for push and pull operations with Docker or other client tools, combine the fully qualified registry name, repository name (including namespace path if applicable), and an image tag or manifest digest. See previous sections for explanations of these terms.
116
+
To address a registry artifact for push and pull operations with Docker or other client tools, combine the fully qualified registry name, repository name (including namespace path if applicable), and an artifact tag or manifest digest. See previous sections for explanations of these terms.
117
+
118
+
**Address by tag**: `[loginServerUrl]/[repository][:tag]`
119
+
120
+
**Address by digest**: `[loginServerUrl]/[repository@sha256][:digest]`
121
+
122
+
When using Docker or other client tools to pull or push artifacts to an Azure container registry, use the registry's fully qualified URL, also called the *login server* name. In the Azure cloud, the fully qualified URL of an Azure container registry is in the format `myregistry.azurecr.io` (all lowercase).
120
123
121
124
> [!NOTE]
125
+
> * You can't specify a port number in the registry login server URL, such as `myregistry.azurecr.io:443`.
122
126
> * The tag `latest` is used by default if you don't provide a tag in your command.
123
-
> * You can't specify a port number in the registry login server URL, such as `myregistry.azurecr.io:443`.
Learn more about [image storage](container-registry-storage.md) and [supported content formats](container-registry-image-formats.md) in Azure Container Registry.
154
+
Learn more about [registry storage](container-registry-storage.md) and [supported content formats](container-registry-image-formats.md) in Azure Container Registry.
157
155
158
156
Learn how to [push and pull images](container-registry-get-started-docker-cli.md) from Azure Container Registry.
0 commit comments