Azure Container Registry biblioteca de cliente para Python – versão 1.2.0

Azure Container Registry permite-lhe armazenar e gerir imagens e artefactos de contentor num registo privado para todos os tipos de implementações de contentores.

Utilize a biblioteca de cliente para Azure Container Registry para:

• Listar imagens ou artefactos num registo
• Obter metadados para imagens e artefactos, repositórios e etiquetas
• Definir propriedades de leitura/escrita/eliminação em itens de registo
• Eliminar imagens e artefactos, repositórios e etiquetas

Código fonte | Pacote (Pypi) | Pacote (Conda) | Documentação | de referência da APIDocumentação | da API RESTDocumentação do produto

Exclusão de Responsabilidade

O suporte de pacotes Python do SDK do Azure para Python 2.7 terminou a 01 de janeiro de 2022. Para obter mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691O Python 3.7 ou posterior é necessário para utilizar este pacote. Para obter mais detalhes, veja Azure SDK for Python version support policy (Política de suporte de versões do Azure SDK para Python).

Introdução

Instalar o pacote

Instale a biblioteca de cliente Azure Container Registry para Python com pip:

pip install --pre azure-containerregistry

Pré-requisitos

• O Python 3.7 ou posterior é necessário para utilizar este pacote.
• Precisa de uma subscrição do Azure e de uma conta do Container Registry para utilizar este pacote.

Para criar um novo Container Registry, pode utilizar o Portal do Azure, o Azure PowerShell ou a CLI do Azure. Eis um exemplo com a CLI do Azure:

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

Autenticar o cliente

A biblioteca de Identidades do Azure fornece suporte fácil do Azure Active Directory para autenticação. Assume DefaultAzureCredential que as AZURE_CLIENT_IDvariáveis de ambiente , AZURE_TENANT_IDe AZURE_CLIENT_SECRET estão definidas, para obter mais informações, veja a secção Variáveis de ambiente da Identidade do 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)

Conceitos-chave

Um registo armazena imagens do Docker e Artefactos OCI. Uma imagem ou artefacto consiste num manifesto e camadas. O manifesto de uma imagem descreve as camadas que compõem a imagem e é identificado exclusivamente pelo seu resumo. Uma imagem também pode ser "etiquetada" para lhe dar um alias legível por humanos. Uma imagem ou artefacto pode ter zero ou mais etiquetas associadas à mesma e cada etiqueta identifica exclusivamente a imagem. Uma coleção de imagens que partilham o mesmo nome, mas que têm etiquetas diferentes, é referida como um repositório.

Para obter mais informações, veja Container Registry Concepts (Conceitos do Container Registry).

Exemplos

As secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas mais comuns do ACR Service, incluindo:

• Operações de registo:
  • Listar repositórios
  • Listar etiquetas com acesso anónimo
  • Definir propriedades do artefacto
  • Eliminar imagens
• Operações de blobs e manifestos:
  • Carregar imagens
  • Transferir imagens
  • Eliminar manifesto
  • Eliminar blob

Tenha em atenção que cada exemplo pressupõe que existe uma CONTAINERREGISTRY_ENDPOINT variável de ambiente definida para uma cadeia que contém o https:// prefixo e o nome do servidor de início de sessão, por exemplo "https://myregistry.azurecr.io". Os exemplos de acesso anónimo estão a obter o valor do ponto final da variávelCONTAINERREGISTRY_ANONREGISTRY_ENDPOINT de ambiente.

Listar repositórios

Iterar através da coleção de repositórios no registo.

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

Listar etiquetas com acesso anónimo

Iterar através da coleção de etiquetas no repositório com acesso anónimo.

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)

Definir propriedades do artefacto

Definir propriedades de um artefacto.

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
    )

Eliminar imagens

Elimine imagens mais antigas do que as três primeiras no repositório.

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)

Carregar imagens

Para carregar uma imagem completa, precisamos de carregar camadas e configurações individuais. Depois disso, podemos carregar um manifesto que descreve uma imagem ou artefacto e atribuir-lhe uma etiqueta.

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}")

Transferir imagens

Para transferir uma imagem completa, temos de transferir o respetivo manifesto e, em seguida, transferir camadas e configurações individuais.

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}")

Eliminar manifesto

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)

Eliminar 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"])

Resolução de problemas

Para obter informações sobre a resolução de problemas, veja o guia de resolução de problemas.

Geral

A biblioteca de cliente do ACR irá gerar exceções definidas no Azure Core.

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registo.

As informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao INFO nível.

O registo de nível detalhado DEBUG , incluindo os corpos de pedido/resposta e os cabeçalhos não retotados , pode ser ativado no cliente ou por operação com o logging_enable argumento de palavra-chave.

Veja a documentação completa do registo do SDK com exemplos aqui.

Configuração opcional

Os argumentos de palavra-chave opcionais podem ser transmitidos ao nível do cliente e por operação. A documentação de referência azure-core descreve as configurações disponíveis para repetições, registo, protocolos de transporte e muito mais.

Passos seguintes

• Vá mais longe com azure.containerregistry e os nossos exemplos.
• Veja um vídeo de demonstração ou de mergulho profundo.
• Leia mais sobre o serviço Azure Container Registry.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.