azure-containerregistry-py

Azure Container Registry Python SDK

管理 Azure Container Registry 中的容器映像、制品和存储库。

安装

pip install azure-containerregistry

环境变量

AZURE_CONTAINERREGISTRY_ENDPOINT=https://<registry-name>.azurecr.io

身份验证

Entra ID（推荐）

import os
from azure.containerregistry import ContainerRegistryClient
from azure.identity import DefaultAzureCredential

client = ContainerRegistryClient(
    endpoint=os.environ["AZURE_CONTAINERREGISTRY_ENDPOINT"],
    credential=DefaultAzureCredential()
)

匿名访问（公共注册表）

from azure.containerregistry import ContainerRegistryClient

client = ContainerRegistryClient(
    endpoint="https://mcr.microsoft.com",
    credential=None,
    audience="https://mcr.microsoft.com"
)

列出存储库

client = ContainerRegistryClient(endpoint, DefaultAzureCredential())

for repository in client.list_repository_names():
    print(repository)

存储库操作

获取存储库属性

properties = client.get_repository_properties("my-image")
print(f"Created: {properties.created_on}")
print(f"Modified: {properties.last_updated_on}")
print(f"Manifests: {properties.manifest_count}")
print(f"Tags: {properties.tag_count}")

更新存储库属性

from azure.containerregistry import RepositoryProperties

client.update_repository_properties(
    "my-image",
    properties=RepositoryProperties(
        can_delete=False,
        can_write=False
    )
)

删除存储库

client.delete_repository("my-image")

列出标记

for tag in client.list_tag_properties("my-image"):
    print(f"{tag.name}: {tag.created_on}")

按顺序筛选

from azure.containerregistry import ArtifactTagOrder

# Most recent first
for tag in client.list_tag_properties(
    "my-image",
    order_by=ArtifactTagOrder.LAST_UPDATED_ON_DESCENDING
):
    print(f"{tag.name}: {tag.last_updated_on}")

清单操作

列出清单

from azure.containerregistry import ArtifactManifestOrder

for manifest in client.list_manifest_properties(
    "my-image",
    order_by=ArtifactManifestOrder.LAST_UPDATED_ON_DESCENDING
):
    print(f"Digest: {manifest.digest}")
    print(f"Tags: {manifest.tags}")
    print(f"Size: {manifest.size_in_bytes}")

获取清单属性

manifest = client.get_manifest_properties("my-image", "latest")
print(f"Digest: {manifest.digest}")
print(f"Architecture: {manifest.architecture}")
print(f"OS: {manifest.operating_system}")

更新清单属性

from azure.containerregistry import ArtifactManifestProperties

client.update_manifest_properties(
    "my-image",
    "latest",
    properties=ArtifactManifestProperties(
        can_delete=False,
        can_write=False
    )
)

删除清单

# Delete by digest
client.delete_manifest("my-image", "sha256:abc123...")

# Delete by tag
manifest = client.get_manifest_properties("my-image", "old-tag")
client.delete_manifest("my-image", manifest.digest)

标记操作

获取标记属性

tag = client.get_tag_properties("my-image", "latest")
print(f"Digest: {tag.digest}")
print(f"Created: {tag.created_on}")

删除标记

client.delete_tag("my-image", "old-tag")

上传和下载制品

from azure.containerregistry import ContainerRegistryClient

client = ContainerRegistryClient(endpoint, DefaultAzureCredential())

# Download manifest
manifest = client.download_manifest("my-image", "latest")
print(f"Media type: {manifest.media_type}")
print(f"Digest: {manifest.digest}")

# Download blob
blob = client.download_blob("my-image", "sha256:abc123...")
with open("layer.tar.gz", "wb") as f:
    for chunk in blob:
        f.write(chunk)

异步客户端

from azure.containerregistry.aio import ContainerRegistryClient
from azure.identity.aio import DefaultAzureCredential

async def list_repos():
    credential = DefaultAzureCredential()
    client = ContainerRegistryClient(endpoint, credential)
    
    async for repo in client.list_repository_names():
        print(repo)
    
    await client.close()
    await credential.close()

清理旧映像

不要仅依据映像年龄或缺少标记直接执行删除：无标记的摘要仍可能已部署，或被多架构清单引用。请清点依赖项和当前工作负载，列出确切的候选摘要，并根据保留/恢复策略获得删除授权。在执行下方的变更循环前，请先使用试运行生成候选报告。

from datetime import datetime, timedelta, timezone

cutoff = datetime.now(timezone.utc) - timedelta(days=30)

for manifest in client.list_manifest_properties("my-image"):
    if manifest.last_updated_on < cutoff and not manifest.tags:
        print(f"Deleting {manifest.digest}")
        client.delete_manifest("my-image", manifest.digest)

客户端操作

操作	说明
list_repository_names	列出所有存储库
get_repository_properties	获取存储库元数据
delete_repository	删除存储库及其所有映像
list_tag_properties	列出存储库中的标记
get_tag_properties	获取标记元数据
delete_tag	删除指定标记
list_manifest_properties	列出存储库中的清单
get_manifest_properties	获取清单元数据
delete_manifest	按摘要删除清单
download_manifest	下载清单内容
download_blob	下载层 Blob

最佳实践

1. 在生产环境中使用 Entra ID 进行身份验证
2. 按摘要而非标记删除，以避免产生孤立映像
3. 使用 can_delete=False 锁定生产映像
4. 定期清理无标记清单
5. 对高吞吐量操作使用异步客户端
6. 按 last_updated 排序，查找较新或较旧的映像
7. 删除前检查 manifest.tags，以避免移除带标记的映像

适用场景

当需要执行概述中所述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。