.. 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) `_ | `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* 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.6 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("Deleting {}:{}".format(repository, manifest.digest)) client.delete_manifest(repository, manifest.digest) Troubleshooting --------------- 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