README
¶
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
Integration with ACR Tasks
To run a locally built version of the ACR-CLI using ACR Tasks follow these steps:
- 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 .
- 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 opencode@microsoft.com with any additional questions or comments.
Directories