.. role:: raw-html-m2r(raw)
:format: html
Azure Container Registry client library for Python
==================================================
Azure Container Registry allows you to store and manage container images and artifacts in a private registry for all types of container deployments.
Use the client library for Azure Container Registry to:
* List images or artifacts in a registry
* Obtain metadata for images and artifacts, repositories and tags
* Set read/write/delete properties on registry items
* Delete images and artifacts, repositories and tags
`Source code `_
| `Package (Pypi) `_
| `Package (Conda) `_
| `API reference documentation `_
| `REST API documentation `_
| `Product documentation `_
*Disclaimer*
----------------
*Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691*
*Python 3.7 or later is required to use this package. For more details, please refer to `Azure SDK for Python version support policy `_.*
Getting started
---------------
Install the package
^^^^^^^^^^^^^^^^^^^
Install the Azure Container Registry client library for Python with `pip `_\ :
.. code-block:: bash
pip install --pre azure-containerregistry
Prerequisites
^^^^^^^^^^^^^
* Python 3.7 or later is required to use this package.
* You need an `Azure subscription `_ and a `Container Registry account `_ to use this package.
To create a new Container Registry, you can use the `Azure Portal `_\ ,
`Azure PowerShell `_\ , or the `Azure CLI `_.
Here's an example using the Azure CLI:
.. code-block:: Powershell
az acr create --name MyContainerRegistry --resource-group MyResourceGroup --location westus --sku Basic
Authenticate the client
^^^^^^^^^^^^^^^^^^^^^^^
The `Azure Identity library `_ provides easy Azure Active Directory support for authentication. The ``DefaultAzureCredential`` assumes the ``AZURE_CLIENT_ID``\ , ``AZURE_TENANT_ID``\ , and ``AZURE_CLIENT_SECRET`` environment variables are set, for more information refer to the `Azure Identity environment variables section `_
.. code-block:: python
# Create a ContainerRegistryClient that will authenticate through Active Directory
from azure.containerregistry import ContainerRegistryClient
from azure.identity import DefaultAzureCredential
endpoint = "https://mycontainerregistry.azurecr.io"
audience = "https://management.azure.com"
client = ContainerRegistryClient(endpoint, DefaultAzureCredential(), audience=audience)
Key concepts
------------
A **registry** stores Docker images and `OCI Artifacts `_. An image or artifact consists of a **manifest** and **layers**. An image's manifest describes the layers that make up the image, and is uniquely identified by its **digest**. An image can also be "tagged" to give it a human-readable alias. An image or artifact can have zero or more **tags** associated with it, and each tag uniquely identifies the image. A collection of images that share the same name but have different tags, is referred to as a **repository**.
For more information please see `Container Registry Concepts `_.
Examples
--------
The following sections provide several code snippets covering some of the most common ACR Service tasks, including:
* `List repositories <#list-repositories>`_
* `List tags with anonymous access <#list-tags-with-anonymous-access>`_
* `Set artifact properties <#set-artifact-properties>`_
* `Delete images <#delete-images>`_
Please note that each sample assumes there is a ``CONTAINERREGISTRY_ENDPOINT`` environment variable set to a string containing the ``https://`` prefix and the name of the login server, for example "https://myregistry.azurecr.io".
List repositories
^^^^^^^^^^^^^^^^^
Iterate through the collection of repositories in the registry.
.. code-block:: python
endpoint = os.environ["CONTAINERREGISTRY_ENDPOINT"]
with ContainerRegistryClient(endpoint, DefaultAzureCredential(), audience="https://management.azure.com") as client:
# Iterate through all the repositories
for repository_name in client.list_repository_names():
print(repository_name)
List tags with anonymous access
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Iterate through the collection of tags in the repository with anonymous access.
.. code-block:: python
endpoint = os.environ["CONTAINERREGISTRY_ENDPOINT"]
with ContainerRegistryClient(endpoint, DefaultAzureCredential(), audience="https://management.azure.com") as client:
manifest = client.get_manifest_properties("library/hello-world", "latest")
print(manifest.repository_name + ": ")
for tag in manifest.tags:
print(tag + "\n")
Set artifact properties
^^^^^^^^^^^^^^^^^^^^^^^
Set properties of an artifact.
.. code-block:: python
endpoint = os.environ["CONTAINERREGISTRY_ENDPOINT"]
with ContainerRegistryClient(endpoint, DefaultAzureCredential(), audience="https://management.azure.com") as client:
# Set permissions on the v1 image's "latest" tag
client.update_manifest_properties(
"library/hello-world",
"latest",
can_write=False,
can_delete=False
)
Delete images
^^^^^^^^^^^^^
Delete images older than the first three in the repository.
.. code-block:: python
endpoint = os.environ["CONTAINERREGISTRY_ENDPOINT"]
with ContainerRegistryClient(endpoint, DefaultAzureCredential(), audience="https://management.azure.com") as client:
for repository in client.list_repository_names():
manifest_count = 0
for manifest in client.list_manifest_properties(repository, order_by=ArtifactManifestOrder.LAST_UPDATED_ON_DESCENDING):
manifest_count += 1
if manifest_count > 3:
print(f"Deleting {repository}:{manifest.digest}")
client.delete_manifest(repository, manifest.digest)
Troubleshooting
---------------
For infomation about troubleshooting, refer to the `troubleshooting guide `_.
General
^^^^^^^
ACR client library will raise exceptions defined in `Azure Core `_.
Logging
^^^^^^^
This library uses the standard
`logging `_ library for logging.
Basic information about HTTP sessions (URLs, headers, etc.) is logged at ``INFO`` level.
Detailed ``DEBUG`` level logging, including request/response bodies and **unredacted**
headers, can be enabled on the client or per-operation with the ``logging_enable`` keyword argument.
See full SDK logging documentation with examples `here `_.
Optional Configuration
^^^^^^^^^^^^^^^^^^^^^^
Optional keyword arguments can be passed in at the client and per-operation level.
The azure-core `reference documentation `_
describes available configurations for retries, logging, transport protocols, and more.
Next steps
----------
* Go further with azure.containerregistry and our `samples `_.
* Watch a `demo or deep dive video `_.
* Read more about the `Azure Container Registry service `_.
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 `cla.microsoft.com `_.
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.
.. image:: https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Fcontainerregistry%2Fazure-containerregistry%2FREADME.png
:target: https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Fcontainerregistry%2Fazure-containerregistry%2FREADME.png
:alt: Impressions
:raw-html-m2r:``
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. toctree::
:maxdepth: 5
:glob:
:caption: Developer Documentation
azure.containerregistry.rst