клиентская библиотека Реестр контейнеров Azure для Python версии 1.2.0

Реестр контейнеров Azure позволяет хранить образы контейнеров и артефакты и управлять ими в частном реестре для всех типов развертываний контейнеров.

Используйте клиентскую библиотеку для Реестра контейнеров Azure, чтоб выполнить следующие действия:

• Составить список образов или артефактов в реестре.
• Получение метаданных для изображений и артефактов, репозиториев и тегов
• Задать свойства чтения, записи и удаления для элементов реестра.
• Удаление изображений и артефактов, репозиториев и тегов

Исходный код | Пакет (Pypi) | Пакет (Conda) | Справочная документация по | APIДокументация по | REST APIДокументация по продукту

Заявление об отказе

Поддержка пакетов Python пакета Azure SDK для Python 2.7 завершилась 1 января 2022 г. Дополнительные сведения и вопросы см. в https://github.com/Azure/azure-sdk-for-python/issues/20691 статье Python 3.7 или более поздней версии, необходимой для использования этого пакета. Дополнительные сведения см. в статье Политика поддержки версий пакета Azure SDK для Python.

Начало работы

Установка пакета

Установите клиентскую библиотеку Реестра контейнеров Azure для Python с помощью pip:

pip install --pre azure-containerregistry

Предварительные требования

• Для использования этого пакета требуется Python 3.7 или более поздней версии.
• Для использования этого пакета вам потребуется подписка Azure и учетная запись Реестра контейнеров .

Чтобы создать реестр контейнеров, можно использовать портал Azure, Azure PowerShell или Azure CLI. Ниже приведен пример с использованием Azure CLI:

az acr create --name MyContainerRegistry --resource-group MyResourceGroup --location westus --sku Basic

Аутентификация клиента

Библиотека удостоверений Azure обеспечивает простую поддержку azure Active Directory для проверки подлинности. Предполагается DefaultAzureCredentialAZURE_CLIENT_ID, что переменные среды , AZURE_TENANT_IDи AZURE_CLIENT_SECRET заданы. Дополнительные сведения см. в разделе Переменные среды удостоверений Azure.

# 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)

Основные понятия

В реестре хранятся образы Docker и артефакты OCI. Образ или артефакт состоит из манифеста и слоев. Манифест изображения описывает слои, составляющие изображение, и однозначно определяется его дайджестом. Изображение также можно пометить тегом, чтобы присвоить ему удобочитаемый псевдоним. С изображением или артефактом может быть связано ноль или несколько тегов , и каждый тег однозначно идентифицирует изображение. Коллекция образов с одинаковым именем, но с разными тегами называется репозиторием.

Дополнительные сведения см. в разделе Основные понятия реестра контейнеров.

Примеры

В следующих разделах представлено несколько фрагментов кода, охватывающих некоторые из наиболее распространенных задач службы ACR, в том числе:

• Операции с реестром:
  • Вывод списка репозиториев
  • Вывод списка тегов с анонимным доступом
  • Задание свойств артефакта
  • Удаление изображений
• Операции с большими двоичными объектами и манифестами:
  • Отправка изображений
  • Скачивание изображений
  • Удаление манифеста
  • Удаление BLOB-объекта

Обратите внимание, что в каждом примере предполагается, что для переменной CONTAINERREGISTRY_ENDPOINT среды задана строка, https:// содержащая префикс и имя сервера входа, например "https://myregistry.azurecr.io"". Примеры анонимного доступа получают значение конечной точки из переменнойCONTAINERREGISTRY_ANONREGISTRY_ENDPOINT среды.

Вывод списка репозиториев

Выполните итерацию по коллекции репозиториев в реестре.

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    # Iterate through all the repositories
    for repository_name in client.list_repository_names():
        print(repository_name)

Вывод списка тегов с анонимным доступом

Выполните итерацию по коллекции тегов в репозитории с анонимным доступом.

with ContainerRegistryClient(endpoint) as anon_client:
    manifest = anon_client.get_manifest_properties("library/hello-world", "latest")
    print(f"Tags of {manifest.repository_name}: ")
    # Iterate through all the tags
    for tag in manifest.tags:
        print(tag)

Задание свойств артефакта

Задание свойств артефакта.

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    # Set permissions on image "library/hello-world:v1"
    client.update_manifest_properties(
        "library/hello-world",
        "v1",
        can_write=False,
        can_delete=False
    )

Удаление изображений

Удалите образы старше первых трех в репозитории.

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    for repository in client.list_repository_names():
        # Keep the three most recent images, delete everything else
        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:
                # Make sure will have the permission to delete the manifest later
                client.update_manifest_properties(
                    repository,
                    manifest.digest,
                    can_write=True,
                    can_delete=True
                )
                print(f"Deleting {repository}:{manifest.digest}")
                client.delete_manifest(repository, manifest.digest)

Отправка изображений

Чтобы отправить полный образ, необходимо передать отдельные слои и конфигурацию. После этого можно отправить манифест, описывающий изображение или артефакт, и назначить ему тег.

self.repository_name = "sample-oci-image"
layer = BytesIO(b"Sample layer")
config = BytesIO(json.dumps(
    {
        "sample config": "content",
    }).encode())
with ContainerRegistryClient(self.endpoint, self.credential) as client:
    # Upload a layer
    layer_digest, layer_size = client.upload_blob(self.repository_name, layer)
    print(f"Uploaded layer: digest - {layer_digest}, size - {layer_size}")
    # Upload a config
    config_digest, config_size = client.upload_blob(self.repository_name, config)
    print(f"Uploaded config: digest - {config_digest}, size - {config_size}")
    # Create an oci image with config and layer info
    oci_manifest = {
        "config": {
            "mediaType": "application/vnd.oci.image.config.v1+json",
            "digest": config_digest,
            "sizeInBytes": config_size,
        },
        "schemaVersion": 2,
        "layers": [
            {
                "mediaType": "application/vnd.oci.image.layer.v1.tar",
                "digest": layer_digest,
                "size": layer_size,
                "annotations": {
                    "org.opencontainers.image.ref.name": "artifact.txt",
                },
            },
        ],
    }
    # Set the image with tag "latest"
    manifest_digest = client.set_manifest(self.repository_name, oci_manifest, tag="latest")
    print(f"Uploaded manifest: digest - {manifest_digest}")

Скачивание изображений

Чтобы скачать полный образ, необходимо скачать его манифест, а затем скачать отдельные слои и конфигурацию.

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    # Get the image
    get_manifest_result = client.get_manifest(self.repository_name, "latest")
    received_manifest = get_manifest_result.manifest
    print(f"Got manifest:\n{received_manifest}")
    
    # Download and write out the layers
    for layer in received_manifest["layers"]:
        # Remove the "sha256:" prefix from digest
        layer_file_name = layer["digest"].split(":")[1]
        try:
            stream = client.download_blob(self.repository_name, layer["digest"])
            with open(layer_file_name, "wb") as layer_file:
                for chunk in stream:
                    layer_file.write(chunk)
        except DigestValidationError:
            print(f"Downloaded layer digest value did not match. Deleting file {layer_file_name}.")
            os.remove(layer_file_name)
        print(f"Got layer: {layer_file_name}")
    # Download and write out the config
    config_file_name = "config.json"
    try:
        stream = client.download_blob(self.repository_name, received_manifest["config"]["digest"])
        with open(config_file_name, "wb") as config_file:
            for chunk in stream:
                config_file.write(chunk)
    except DigestValidationError:
        print(f"Downloaded config digest value did not match. Deleting file {config_file_name}.")
        os.remove(config_file_name)
    print(f"Got config: {config_file_name}")

Удаление манифеста

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    get_manifest_result = client.get_manifest(self.repository_name, "latest")
    # Delete the image
    client.delete_manifest(self.repository_name, get_manifest_result.digest)

Удаление BLOB-объекта

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    get_manifest_result = client.get_manifest(self.repository_name, "latest")
    received_manifest = get_manifest_result.manifest
    # Delete the layers
    for layer in received_manifest["layers"]:
        client.delete_blob(self.repository_name, layer["digest"])
    # Delete the config
    client.delete_blob(self.repository_name, received_manifest["config"]["digest"])

Устранение неполадок

Сведения об устранении неполадок см. в руководстве по устранению неполадок.

Общие сведения

Клиентская библиотека ACR будет вызывать исключения, определенные в Azure Core.

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала.

Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на INFO уровне.

Подробное DEBUG ведение журнала на уровне, включая тексты запросов и ответов и неотредактированные заголовки, можно включить на клиенте или для каждой операции с помощью аргумента logging_enable ключевое слово.

См. полную документацию по ведению журнала пакета SDK с примерами здесь.

Дополнительная настройка

Необязательные аргументы ключевое слово можно передавать на уровне клиента и для каждой операции. В справочной документации по azure-core описаны доступные конфигурации для повторных попыток, ведения журнала, транспортных протоколов и многого другого.

Дальнейшие действия

• Ознакомьтесь с azure.containerregistry и нашими примерами.
• Посмотрите демонстрацию или видео с подробным погружением.
• Узнайте больше о службе Реестр контейнеров Azure.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Дополнительные сведения см. на странице cla.microsoft.com.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.