Azure Container Registry CLI

Linux Build	Windows Build	Go Report

This repository contains the source code for CLI components for Azure Container Registry. The CLI consists of a new way to interact with Container Registries, the currently supported commands include

• Tag: to view all the tags of a repository and individually untag them.
• Manifest: to view the manifest of a given repository and delete them if necessary.
• Purge: to be able to delete all tags that are older than a certain date and that match a regex specified filter.

Getting Started

Before running the ACR-CLI project make sure the following prerequisites are installed.

Prerequisites

• Go version greater than 1.11 (any version that has go mod support)
• Docker installed (for running this project as a container image, not needed for local development)
• Azure CLI installed (only for running this project as a Task)
• An Azure Container Registry
• Autorest installed (if there are going to be modifications on the ACR SDK)

Installation

For just building the application binaries, execute the following commands:

Linux (at repository root):

make binaries

Windows (inside /cmd/acr folder):

go build ./...

If using Docker:

docker build -t acr .

Optional

For regenerating the ACR SDK for Go run (inside the docs folder):

autorest autorest.md --output-sdk-folder=../acr --go

For updating the vendor folder run (at repository root):

make vendor

Usage

The following are examples of commands that the CLI currently supports.

Login Command

If you are currently logged into an Azure Container Registry the program should be able to read your stored credentials, if not you can do:

acr login <registry name>

This login will also work with the Docker CLI.

Tag Command

To list all the tags inside a repository

acr tag list -r <Registry Name> --repository <Repository Name>

To delete a single tag from a repository

acr tag delete -r <Registry Name> --repository <Repository Name> <Tag Names>

Manifest Command

To list all the manifests inside a repository

acr manifest list -r <Registry Name> --repository <Repository Name>

To delete a single manifest from a repository (and all the tags that are linked to it)

acr manifest delete -r <Registry Name> --repository <Repository Name> <Manifest digests>

Purge Command

To delete all the tags that are older than a certain duration:

acr purge \
    --registry <Registry Name> \
    --filter <Repository Filter/Name>:<Regex Filter> \
    --ago <Go Style Duration>

Filter flag

The filter flag is used to specify the repository and a regex filter, if a tag is older than the duration specified by the ago flag and matches the regex filter then it is untagged, for example:

Examples of filters

Intention	Flag
Untag all tags that begin with hello in app repository	--filter "app:^hello.*"
Untag tags that end with world in app repository	--filter "app:\w*world\b"
Untag tags that include hello-world in their name in app repository	--filter "app:hello-world"
Untag all tags that are older than the duration in repositories ending in /cache	--filter ".*/cache:.*"
Untag all tags that are older than the duration in app repository	--filter "app:.*"
Untag all tags that are older than the duration in all repositories	--filter ".*:.*"

Ago flag

The ago flag can be used to change the default expiration time of a tag, for example, the following command would purge all tags that are older than 30 days:

acr purge \
    --registry <Registry Name> \
    --filter <Repository Filter/Name>:<Regex Filter> \
    --ago 30d

The following table further explains the functionality of this flag.

Intention	Flag
To delete all images that were last modified before yesterday	--ago 1d
To delete all images that were last modified before 10 minutes ago	--ago 10m
To delete all images that were last modified before 1 hour and 15 minutes ago	--ago 1h15m

The duration should be of the form [integer]d[string] where the first integer specifies the number of days and the string is in a go style duration (can be omitted)

Optional purge flags

Untagged flag

To delete all the manifests that do not have any tags linked to them, the --untagged flag should be set.

acr purge \
    --registry <Registry Name> \
    --filter <Repository Filter/Name>:<Regex Filter> \
    --ago 30d \
    --untagged

Keep flag

To keep the latest x number of to-be-deleted tags, the --keep flag should be set.

acr purge \
    --registry <Registry Name> \
    --filter <Repository Filter/Name>:<Regex Filter> \
    --ago 30d \
    --keep 3

Dry run flag

To know which tags and manifests would be deleted the dry-run flag can be set, nothing will be deleted and the output would be the same as if the purge command was executed normally. An example of this would be:

acr purge \
    --registry <Registry Name> \
    --filter <Repository Filter/Name>:<Regex Filter> \
    --ago 30d \
    --dry-run

Concurrency flag

To control the number of concurrent purge tasks, the --concurrency flag should be set, the allowed range is [1, 32]. A default value will be used if --concurrency is not specified.

acr purge \
    --registry <Registry Name> \
    --filter <Repository Filter/Name>:<Regex Filter> \
    --ago 30d \
    --concurrency 4

Repository page size flag

To control the number of repositories fetched in a single page, the --repository-page-size flag should be set. A default value of 100 will be used if --repository-page-size is not specified. This is useful when the number of artifacts in the registry is very large and listing too many repositories at once can timeout.

acr purge \
    --registry <Registry Name> \
    --filter <Repository Filter/Name>:<Regex Filter> \
    --ago 30d \
    --repository-page-size 10

Integration with ACR Tasks

To run a locally built version of the ACR-CLI using ACR Tasks follow these steps:

1. Build the docker image and push to an Azure Container Registry Either build and push manually:

docker build -t <Registry Name>/acr:latest .
docker push <Registry Name>/acr:latest

Or using ACR Build

az acr build -t acr:latest .

2. Run it inside an ACR task (authentication is obtained through the task itself) by executing

az acr run \
    --registry <Registry Name> \
    --cmd "{{ .Run.Registry }}/acr:latest <ACR-CLI command>" \
    /dev/null

For example to run the tag list command

az acr run \
    --registry <Registry Name> \
    --cmd "{{ .Run.Registry }}/acr:latest tag list -r {{ .Run.Registry }}
            --filter <Repository Filter/Name>:<Regex Filter>" \
    /dev/null

OR. Schedule a periodically repeating task using ACR Scheduled Tasks

az acr task create \
    --name purgeTask \
    --registry <Registry Name> \
    --cmd "{{ .Run.Registry }}/acr:latest <ACR-CLI command>" \
    --context /dev/null \
    --schedule <CRON expression>

For example to have a task that executes every day and purges tags older than 7 days one can execute:

az acr task create \
    --name purgeTask \
    --registry <Registry Name> \
    --cmd "{{ .Run.Registry }}/acr:latest purge -r {{ .Run.Registry }}
            --filter <Repository Filter/Name>:<Regex Filter> --ago 7d" \
    --context /dev/null \
    --schedule "0 0 * * *"

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.