While Azure Container Registry (ACR) is prevalent as an Azure service, the corresponding Az.ContainerRegistry Azure PowerShell module wasn’t fully featured. Sometimes, PowerShell users had to take advantage of the Az CLI. We want to allow PowerShell user to be able to fully manage container images. Starting with Az.ContainerRegistry version 2.2.1, we will gradually be rolling out new cmdlets and new parameters. In this release, you can now fully manage (Get-, Remove-, Update-) repositories, manifests, and tags with increased performance.
ACR overview
The graph below shows resources and the structure under an Azure container registry. We’ll dive into more details later in this article.
Authentication
After login into your Azure account in Azure-PowerShell with
PS:> Connect-AzAccount
You can now simply run
PS:> Connect-AzContainerRegistry -Name $RegistryName
Alternatively, you can also use service principal authentication
PS:> Connect-AzContainerRegistry -Name $RegistryName -UserName $ApplicationId -Password $ClientSecret
If you happened to have the registry admin user enabled
PS:> $secret = Get-AzContainerRegistryCredential -ResourceGroupName $RGName -Name $RegistryName
PS:> Connect-AzContainerRegistry -Name $RegistryName
-UserName $secret.UserName
-Password $secret.Password
Repositories
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:
- acr-helloworld:latest
- acr-helloworld:v1
- acr-helloworld:v2
A JSON format repository could look like the following
{
"registry": "xxx.azurecr.io",
"imageName": "test/busybox",
"createdTime": "2021-02-02T04:11:14.4504049Z",
"lastUpdateTime": "2021-02-02T05:02:14.2671834Z",
"manifestCount": 1,
"tagCount": 150,
"changeableAttributes": {
"deleteEnabled": true,
"writeEnabled": true,
"readEnabled": true,
"listEnabled": true
}
To get repositories via Az.ContainerRegistry
PS:> $repository = Get-AzContainerRegistryRepository -RegistryName xxx -Name test/busybox
PS:> $repository
Registry : xxx.azurecr.io
ImageName : test/busybox
CreatedTime : 2021-02-02T04:11:14.4504049Z
LastUpdateTime : 2021-02-02T05:02:14.2671834Z
ManifestCount : 1
TagCount : 150
ChangeableAttributes : Microsoft.Azure.Commands.ContainerRegistry.Models.PSChangeableAttribute
PS:> $repository.ChangeableAttributes | ft
DeleteEnabled WriteEnabled ListEnabled ReadEnabled
------------- ------------ ----------- -----------
True True True True
You can also list all repository names under your registry
PS:> Get-AzContainerRegistryRepository -RegistryName xxx
alpine
test/busybox
test/busybox1
test/busybox10
test/busybox11
test/busybox12
To delete an existing repository
PS:> Update-AzContainerRegistryRepository -RegistryName xxx -Name test/busybox -DeleteEnabled $true
PS:> Remove- AzContainerRegistryRepository -RegistryName xxx -Name test/busybox
Images
Grouped in a repository, each image or artifact is a read-only multi-layer snapshot of a Docker-compatible container.
An artifact can be represented as either one of
- manifest
- $repository_name:$tag
Manifest
Each image or other artifact pushed to a registry is associated with a JSON format manifest. The manifest, generated by the registry when the content is pushed, uniquely identifies the artifact.
"manifests": [
{
"digest": "sha256:31a54a0cf86d7354788a8265f60ae6acb4b348a67efbcf7c1007dd3cf7af05ab",
"imageSize": 764633,
"createdTime": "2020-12-11T09:17:20.4959715Z",
"lastUpdateTime": "2020-12-11T09:17:20.4959715Z",
"architecture": "amd64",
"os": "linux",
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"configMediaType": "application/vnd.docker.container.image.v1+json",
"tags": [
"latest"
],
"changeableAttributes": {
"deleteEnabled": false,
"writeEnabled": true,
"readEnabled": true,
"listEnabled": true
}
}
Manifests are identified by a unique SHA-256 hash, 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.
Similarly, to get, list, update, or remove a manifest under a repository
PS:> Get-AzContainerRegistryManifest -RegistryName xxx
-RepositoryName test/busybox50
-Name sha256:31a54a0cf86d7354788a8265f60ae6acb4b348a67efbcf7c1007dd3cf7af05ab
Registry : xxx.azurecr.io
ImageName : test/busybox50
Attributes : Microsoft.Azure.Commands.ContainerRegistry.Models.PSManifestAttributeBase
PS:> Get-AzContainerRegistryManifest -RegistryName xxx -RepositoryName test/busybox50
PS:> Update-AzContainerRegistryManifest -RegistryName xxx
-RepositoryName test/busybox50
-Manifest sha256:31a54a0cf86d7354788a8265f60ae6acb4b348a67efbcf7c1007dd3cf7af05ab
-DeleteEnabled $true
PS:> Remove-AzContainerRegistryManifest -RegistryName xxx
-RepositoryName test/busybox50
-Manifest sha256:31a54a0cf86d7354788a8265f60ae6acb4b348a67efbcf7c1007dd3cf7af05ab
Please be aware that to delete a repository, all manifests under it should have
"deleteEnabled": true
Tag
Tags for an image or other artifact specifies its version. A single artifact within a repository can be assigned one or many tags, this artifact may also be "untagged." That is, you can delete all tags from an image, while the image's data (its layers) remain in the registry.
"tag": {
"name": "latest",
"digest": "sha256:31a54a0cf86d7354788a8265f60ae6acb4b348a67efbcf7c1007dd3cf7af05ab",
"createdTime": "2020-12-11T09:17:20.6865195Z",
"lastUpdateTime": "2020-12-11T09:17:20.6865195Z",
"signed": false,
"changeableAttributes": {
"deleteEnabled": true,
"writeEnabled": true,
"readEnabled": true,
"listEnabled": true
}
}
The repository plus a tag defines an image name. You can push and pull an image by specifying its name in the push or pull operation. The tag latest is used by default if you don't provide one in your Docker commands. As you can see in the ACR Overview section, “repository3:latest” and “repository3:v2” both represent the same image “artifact3”.
Similarly, to get, list, update, or remove a tag for one artifact
PS:> Get-AzContainerRegistryTag -RegistryName xxx
-RepositoryName test/busybox50
-Name latest
Registry : xxx.azurecr.io
ImageName : test/busybox50
Attributes : Microsoft.Azure.Commands.ContainerRegistry.Models.PSTagAttributeBase
PS:> Get-AzContainerRegistryTag -RegistryName xxx -RepositoryName test/busybox50
PS:> Update-AzContainerRegistryTag -RegistryName xxx
-RepositoryName test/busybox50
-Name latest
-DeleteEnabled $true
Notice that after
PS:> Remove-AzContainerRegistryTag -RegistryName xxx
-RepositoryName test/busybox50
-Name latest
The tag “latest” was removed (untagged), means you cannot find
“test/busybox50:latest”. In this repository anymore, but the corresponding artifact remained (get manifest)
PS:> $digest = (Get-AzContainerRegistryTag -RegistryName xxx
-RepositoryName test/busybox50
-Name latest). Attributes.Digest
PS:> Get-AzContainerRegistryManifest -RegistryName xxx
-RepositoryName test/busybox50
-Name $digest
Registry : xxx.azurecr.io
ImageName : test/busybox50
Attributes : Microsoft.Azure.Commands.ContainerRegistry.Models.PSManifestAttributeBase
It’s also possible to update or delete a manifest by tag, it’s easier since it’s more recognizable to use a meaningful tag than series SHA256 hash code
PS:> Update-AzContainerRegistryManifest -RegistryName xxx
-RepositoryName test/busybox50
-Tag latest
-DeleteEnabled $true
PS:> Remove-AzContainerRegistryManifest -RegistryName xxx
-RepositoryName test/busybox50
-Tag latest
In this way, not only the tag, but the artifact itself would also be deleted.
Performance
We found there are performance issues in each repository, manifest, and tag manipulating operation. They were all relatively slow because ACR categorized each operation with different scopes.
A typical scope is in below format:
“$resource_type:$resource_name:$permission”
For example, to list all tags under repository “alpine”, the scope for this operation would be
“repository:alpine:metadata_read”
The specific token required for this request is assigned based on the exact scope.
For these kinds of operations, there will be 2 more extra HTTP requests sent out for token exchange before your actual operation.
HTTP Method:
POST
Absolute Uri:
https://xxx.azurecr.io/oauth2/token
HTTP Method:
POST
Absolute Uri:
https://xxx.azurecr.io/oauth2/Exchange
To reduce these costly requests, we implemented a token cache in your current PowerShell session, it will cache all ACR tokens. For operations that used existing tokens (operations with same scope), the previously referenced token exchange won’t happen until tokens in the cache expire. For repetitive operations, the total number of requests is now only one instead of three.
You can clear this token cache in your current PowerShell session by running
PS:> Clear-AzContext
This cmdlet also terminates the login state for Azure. Remember to re-connect.
PS:> Connect-AzAccount
Conclusion & Feedback
With these features added, Az.ContainerRegistry is now much more usable. It's highly recommended to download the latest module at
https://www.powershellgallery.com/packages?q=az.containerregistry
and give a shot.
We also look forward to your feedback. Report issues at:
https://github.com/Azure/azure-powershell/issues
Yabo Hu
Software Engineer
Azure-PowerShell Team