bibliothèque cliente Azure Container Registry pour Python - version 1.2.0

  • Article

Azure Container Registry vous permet de stocker et de gérer des images conteneur et des artefacts dans un registre privé pour tous les types de déploiements de conteneurs.

Utilisez la bibliothèques de client pour Azure Container Registry afin de :

  • Lister des images ou des artefacts dans un registre.
  • Obtenir des métadonnées pour les images et les artefacts, les référentiels et les étiquettes
  • Définir les propriétés de lecture/écriture/suppression sur des éléments du registre.
  • Supprimer des images et des artefacts, des référentiels et des étiquettes

| Code sourcePackage (Pypi) | Package (Conda) | Documentation de référence sur les | APIDocumentation | sur l’API RESTDocumentation produit

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour plus d’informations et de questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 ou version ultérieure nécessaire pour utiliser ce package. Pour plus d’informations, reportez-vous à la stratégie de prise en charge des versions du Kit de développement logiciel (SDK) Azure pour Python.

Prise en main

Installer le package

Installez la bibliothèque de client Azure Container Registry pour Python avec pip :

pip install --pre azure-containerregistry

Prérequis

Pour créer un registre de conteneurs, vous pouvez utiliser le portail Azure, Azure PowerShell ou Azure CLI. Voici un exemple utilisant Azure CLI :

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

Authentifier le client

La bibliothèque Azure Identity fournit une prise en charge facile d’Azure Active Directory pour l’authentification. suppose DefaultAzureCredential que les AZURE_CLIENT_IDvariables d’environnement , AZURE_TENANT_IDet AZURE_CLIENT_SECRET sont définies. Pour plus d’informations, consultez la section Variables d’environnement Azure Identity

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

Concepts clés

Un registre stocke les images Docker et les artefacts OCI. Une image ou un artefact se compose d’un manifeste et de couches. Le manifeste d’une image décrit les couches qui composent l’image et est identifié de manière unique par son condensé. Une image peut également être « étiquetée » pour lui donner un alias lisible par l’homme. Une image ou un artefact peut avoir zéro ou plusieurs balises associées , et chaque balise identifie l’image de manière unique. Une collection d’images qui partagent le même nom, mais qui ont des balises différentes, est appelée dépôt.

Pour plus d’informations, consultez Concepts de Container Registry.

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches les plus courantes du service ACR, notamment :

Notez que chaque exemple suppose qu’il existe une variable d’environnement CONTAINERREGISTRY_ENDPOINT définie sur une chaîne contenant le https:// préfixe et le nom du serveur de connexion, par exemple « https://myregistry.azurecr.io". Les exemples d’accès anonyme obtiennent la valeur de point de terminaison de la variable d’environnementCONTAINERREGISTRY_ANONREGISTRY_ENDPOINT.

Répertorier les référentiels

Itérez au sein de la collection de référentiels dans le registre.

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

Répertorier les étiquettes avec accès anonyme

Effectuez une itération au sein de la collection d’étiquettes dans le dépôt avec un accès anonyme.

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)

Définir les propriétés des artefacts

Définir les propriétés d’un artefact.

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
    )

Supprimer des images

Supprimez les images antérieures aux trois premiers dans le référentiel.

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)

Charger des images

Pour charger une image complète, nous devons charger des couches et une configuration individuelles. Après cela, nous pouvons charger un manifeste qui décrit une image ou un artefact et lui attribuer une balise.

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

Télécharger des images

Pour télécharger une image complète, nous devons télécharger son manifeste, puis télécharger les couches et la configuration individuelles.

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

Supprimer le manifeste

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)

Supprimer un objet 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"])

Dépannage

Pour plus d’informations sur la résolution des problèmes, reportez-vous au guide de résolution des problèmes.

Général

La bibliothèque cliente ACR déclenche des exceptions définies dans Azure Core.

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation.

Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au INFO niveau.

La journalisation détaillée DEBUG au niveau, y compris les corps de requête/réponse et les en-têtes non expurgées, peut être activée sur le client ou par opération avec l’argument logging_enable mot clé.

Consultez la documentation complète sur la journalisation du KIT de développement logiciel (SDK) avec des exemples ici.

Configuration facultative

Les arguments mot clé facultatifs peuvent être passés au niveau du client et par opération. La documentation de référence azure-core décrit les configurations disponibles pour les nouvelles tentatives, la journalisation, les protocoles de transport, etc.

Étapes suivantes

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions