Краткое руководство. Использование клиентских библиотек Реестра контейнеров Azure
Ознакомьтесь со сведениями этой статьи, чтобы начать работу с клиентской библиотекой для Реестра контейнеров Azure. Выполните указанные ниже действия, чтобы опробовать пример кода для операций плоскости данных на изображениях и артефактах.
Используйте клиентскую библиотеку для Реестра контейнеров Azure, чтоб выполнить следующие действия:
- Составить список образов или артефактов в реестре.
- Получить метаданные для изображений и артефактов, репозиториев и тегов.
- Задать свойства чтения, записи и удаления для элементов реестра.
- Удалить образы, артефакты, репозитории и теги.
Реестр контейнеров Azure также содержит библиотеку управления для операций уровня управления, включая создание и обновление реестра.
Необходимые компоненты
Чтобы воспользоваться этой библиотекой, необходимо иметь подписку Azure и реестр контейнеров.
Для создания группы ресурсов Azure можно использовать портал Azure, Azure PowerShell или Azure CLI. Ниже приведен пример с использованием Azure CLI:
az acr create --name MyContainerRegistry --resource-group MyResourceGroup \ --location westus --sku Basic
Отправьте один или несколько образов контейнера в реестр. Описание шагов см. в статье Отправка образов в реестр контейнеров Azure с помощью интерфейса командной строки Docker.
Основные понятия
- В реестре контейнеров Azure хранятся образы контейнеров и артефакты OCI.
- Образ или артефакт состоит из манифеста и слоев.
- Манифест описывает слои, составляющие образ или артефакт. Он идентифицируется исключительно по хэш-коду.
- Образ или артефакт можно также пометить тегом, чтобы дать ему понятный псевдоним. С образом или артефактом может быть не связано ни одного тега или связано сразу несколько, и каждый тег уникально идентифицирует образ.
- Коллекция образов или артефактов, имеющих одно и то же имя, но разные тэги, является репозиторием.
Дополнительные сведения см. в статье о реестрах, репозиториях и артефактах.
Начало работы
Исходный код | Пакет (NuGet) | Справочник по API | Примеры
Для разработки кода приложения .NET, который может подключаться к экземпляру Реестра контейнеров Azure, потребуется библиотека Azure.Containers.ContainerRegistry
.
Установка пакета
Установите клиентскую библиотеку Реестра контейнеров Azure для .NET с помощью NuGet:
dotnet add package Azure.Containers.ContainerRegistry --prerelease
аутентификация клиента;
Для подключения приложения к реестру необходимо создать элемент ContainerRegistryClient
, который может пройти проверку подлинности. Используйте библиотеку удостоверений Azure, чтобы добавить поддержку идентификатора Microsoft Entra для проверки подлинности клиентов Azure SDK с соответствующими службами Azure.
При локальной разработке и отладке приложения можно использовать собственного пользователя для проверки подлинности в реестре. Один из способов это сделать — выполнить проверку подлинности пользователя с помощью Azure CLI и запустить приложение из этого окружения. Если приложение использует клиент, созданный для проверки подлинности с помощью DefaultAzureCredential
, он будет правильно проходить проверку подлинности в реестре в указанной конечной точке.
// Create a ContainerRegistryClient that will authenticate to your registry through Azure Active Directory
Uri endpoint = new Uri("https://myregistry.azurecr.io");
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(),
new ContainerRegistryClientOptions()
{
Audience = ContainerRegistryAudience.AzureResourceManagerPublicCloud
});
Дополнительные подходы выполнения проверки подлинности с помощью DefaultAzureCredential
как локально, так и в средах развертывания см. в файле сведений об удостоверении Azure. Сведения о подключении к реестрам в облаках Azure, не являющихся общедоступными, см. в справочнике по API.
Дополнительные сведения об использовании идентификатора Microsoft Entra с Реестр контейнеров Azure см. в обзоре проверки подлинности.
Примеры
В каждом примере предполагается, что существует переменная среды REGISTRY_ENDPOINT
, заданная в строке, содержащей префикс https://
, и имя сервера входа, например "https://myregistry.azurecr.io"".
В следующих примерах используются асинхронные API-интерфейсы, возвращающие задачу. Доступны также синхронные API-интерфейсы.
Асинхронное составление списка репозиториев
Выполните итерацию по коллекции репозиториев в реестре.
// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
// Create a new ContainerRegistryClient
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(),
new ContainerRegistryClientOptions()
{
Audience = ContainerRegistryAudience.AzureResourceManagerPublicCloud
});
// Get the collection of repository names from the registry
AsyncPageable<string> repositories = client.GetRepositoryNamesAsync();
await foreach (string repository in repositories)
{
Console.WriteLine(repository);
}
Асинхронное задание свойств артефакта
// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
// Create a new ContainerRegistryClient
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(),
new ContainerRegistryClientOptions()
{
Audience = ContainerRegistryAudience.AzureResourceManagerPublicCloud
});
// Get the collection of repository names from the registry
AsyncPageable<string> repositories = client.GetRepositoryNamesAsync();
await foreach (string repository in repositories)
{
Console.WriteLine(repository);
}
Асинхронное удаление образов
using System.Linq;
using Azure.Containers.ContainerRegistry;
using Azure.Identity;
// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
// Create a new ContainerRegistryClient
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(),
new ContainerRegistryClientOptions()
{
Audience = ContainerRegistryAudience.AzureResourceManagerPublicCloud
});
// Iterate through repositories
AsyncPageable<string> repositoryNames = client.GetRepositoryNamesAsync();
await foreach (string repositoryName in repositoryNames)
{
ContainerRepository repository = client.GetRepository(repositoryName);
// Obtain the images ordered from newest to oldest
AsyncPageable<ArtifactManifestProperties> imageManifests =
repository.GetManifestPropertiesCollectionAsync(orderBy: ArtifactManifestOrderBy.LastUpdatedOnDescending);
// Delete images older than the first three.
await foreach (ArtifactManifestProperties imageManifest in imageManifests.Skip(3))
{
RegistryArtifact image = repository.GetArtifact(imageManifest.Digest);
Console.WriteLine($"Deleting image with digest {imageManifest.Digest}.");
Console.WriteLine($" Deleting the following tags from the image: ");
foreach (var tagName in imageManifest.Tags)
{
Console.WriteLine($" {imageManifest.RepositoryName}:{tagName}");
await image.DeleteTagAsync(tagName);
}
await image.DeleteAsync();
}
}
Начало работы
Исходный код | Пакет (Maven) | Справочник по API | Примеры
Поддерживаемые в настоящее время среды
- Пакет средств разработки для Java (JDK) версии 8 или более поздней.
Включение пакета
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-containers-containerregistry</artifactId>
<version>1.0.0-beta.3</version>
</dependency>
аутентификация клиента;
Библиотека удостоверений Azure предоставляет поддержку идентификатора Microsoft Entra для проверки подлинности.
В следующих примерах предполагается, что у вас есть строка конечной точки реестра, содержащая префикс https://
и имя сервера входа, например "https://myregistry.azurecr.io"".
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(credential)
.buildClient();
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryAsyncClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(credential)
.buildAsyncClient();
Дополнительные сведения об использовании идентификатора Microsoft Entra с Реестр контейнеров Azure см. в обзоре проверки подлинности.
Примеры
В каждом примере предполагается, что у вас есть строка конечной точки реестра, содержащая префикс https://
и имя сервера входа, например "https://myregistry.azurecr.io"".
Составление списка имен репозиториев
Выполните итерацию по коллекции репозиториев в реестре.
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(credential)
.buildClient();
client.listRepositoryNames().forEach(repository -> System.out.println(repository));
Задание свойств артефакта
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(defaultCredential)
.buildClient();
RegistryArtifact image = client.getArtifact(repositoryName, digest);
image.updateTagProperties(
tag,
new ArtifactTagProperties()
.setWriteEnabled(false)
.setDeleteEnabled(false));
Удаление изображений
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(defaultCredential)
.buildClient();
final int imagesCountToKeep = 3;
for (String repositoryName : client.listRepositoryNames()) {
final ContainerRepository repository = client.getRepository(repositoryName);
// Obtain the images ordered from newest to oldest
PagedIterable<ArtifactManifestProperties> imageManifests =
repository.listManifestProperties(
ArtifactManifestOrderBy.LAST_UPDATED_ON_DESCENDING,
Context.NONE);
imageManifests.stream().skip(imagesCountToKeep)
.forEach(imageManifest -> {
System.out.printf(String.format("Deleting image with digest %s.%n", imageManifest.getDigest()));
System.out.printf(" This image has the following tags: ");
for (String tagName : imageManifest.getTags()) {
System.out.printf(" %s:%s", imageManifest.getRepositoryName(), tagName);
}
repository.getArtifact(imageManifest.getDigest()).delete();
});
}
Начало работы
Исходный код | Пакет (npm) | Справочник по API | Примеры
Поддерживаемые в настоящее время среды
Чтобы получить дополнительные сведения, ознакомьтесь с нашей политикой поддержки.
Установите пакет @azure/container-registry
.
Установите клиентскую библиотеку Реестра контейнеров для JavaScript с помощью npm
:
npm install @azure/container-registry
аутентификация клиента;
Библиотека удостоверений Azure предоставляет поддержку идентификатора Microsoft Entra для проверки подлинности.
const { ContainerRegistryClient } = require("@azure/container-registry");
const { DefaultAzureCredential } = require("@azure/identity");
const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT;
// Create a ContainerRegistryClient that will authenticate through Active Directory
const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
Дополнительные сведения об использовании идентификатора Microsoft Entra с Реестр контейнеров Azure см. в обзоре проверки подлинности.
Примеры
В каждом примере предполагается, что существует переменная среды CONTAINER_REGISTRY_ENDPOINT
, заданная в строке, содержащей префикс https://
, и имя сервера входа, например "https://myregistry.azurecr.io"".
Асинхронное составление списка репозиториев
Выполните итерацию по коллекции репозиториев в реестре.
const { ContainerRegistryClient } = require("@azure/container-registry");
const { DefaultAzureCredential } = require("@azure/identity");
async function main() {
// endpoint should be in the form of "https://myregistryname.azurecr.io"
// where "myregistryname" is the actual name of your registry
const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
console.log("Listing repositories");
const iterator = client.listRepositoryNames();
for await (const repository of iterator) {
console.log(` repository: ${repository}`);
}
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
Асинхронное задание свойств артефакта
const { ContainerRegistryClient } = require("@azure/container-registry");
const { DefaultAzureCredential } = require("@azure/identity");
async function main() {
// Get the service endpoint from the environment
const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
// Create a new ContainerRegistryClient and RegistryArtifact to access image operations
const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
const image = client.getArtifact("library/hello-world", "v1");
// Set permissions on the image's "latest" tag
await image.updateTagProperties("latest", { canWrite: false, canDelete: false });
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
Асинхронное удаление образов
const { ContainerRegistryClient } = require("@azure/container-registry");
const { DefaultAzureCredential } = require("@azure/identity");
async function main() {
// Get the service endpoint from the environment
const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
// Create a new ContainerRegistryClient
const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
// Iterate through repositories
const repositoryNames = client.listRepositoryNames();
for await (const repositoryName of repositoryNames) {
const repository = client.getRepository(repositoryName);
// Obtain the images ordered from newest to oldest by passing the `orderBy` option
const imageManifests = repository.listManifestProperties({
orderBy: "LastUpdatedOnDescending"
});
const imagesToKeep = 3;
let imageCount = 0;
// Delete images older than the first three.
for await (const manifest of imageManifests) {
imageCount++;
if (imageCount > imagesToKeep) {
const image = repository.getArtifact(manifest.digest);
console.log(`Deleting image with digest ${manifest.digest}`);
console.log(` Deleting the following tags from the image:`);
for (const tagName of manifest.tags) {
console.log(` ${manifest.repositoryName}:${tagName}`);
image.deleteTag(tagName);
}
await image.delete();
}
}
}
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
Начало работы
Исходный код | Пакет (Pypi) | Справочник по API | Примеры
Установка пакета
Установите клиентскую библиотеку Реестра контейнеров Azure для Python с помощью pip:
pip install --pre azure-containerregistry
аутентификация клиента;
Библиотека удостоверений Azure предоставляет поддержку идентификатора Microsoft Entra для проверки подлинности. В DefaultAzureCredential
предполагается, что переменные среды AZURE_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
account_url = "https://mycontainerregistry.azurecr.io"
client = ContainerRegistryClient(account_url, DefaultAzureCredential())
Примеры
В каждом примере предполагается, что существует переменная среды CONTAINERREGISTRY_ENDPOINT
, заданная в строке, содержащей префикс https://
, и имя сервера входа, например "https://myregistry.azurecr.io"".
Асинхронное составление списка тегов
В этом примере предполагается, что в реестре есть репозиторий hello-world
.
import asyncio
from dotenv import find_dotenv, load_dotenv
import os
from azure.containerregistry.aio import ContainerRegistryClient
from azure.identity.aio import DefaultAzureCredential
class ListTagsAsync(object):
def __init__(self):
load_dotenv(find_dotenv())
async def list_tags(self):
# Create a new ContainerRegistryClient
audience = "https://management.azure.com"
account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
credential = DefaultAzureCredential()
client = ContainerRegistryClient(account_url, credential, audience=audience)
manifest = await client.get_manifest_properties("library/hello-world", "latest")
print(manifest.repository_name + ": ")
for tag in manifest.tags:
print(tag + "\n")
Асинхронное задание свойств артефакта
В этом примере предполагается, что в реестре есть репозиторий hello-world
с образом, помеченным тегом v1
.
import asyncio
from dotenv import find_dotenv, load_dotenv
import os
from azure.containerregistry.aio import ContainerRegistryClient
from azure.identity.aio import DefaultAzureCredential
class SetImagePropertiesAsync(object):
def __init__(self):
load_dotenv(find_dotenv())
async def set_image_properties(self):
# Create a new ContainerRegistryClient
account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
audience = "https://management.azure.com"
credential = DefaultAzureCredential()
client = ContainerRegistryClient(account_url, credential, audience=audience)
# [START update_manifest_properties]
# Set permissions on the v1 image's "latest" tag
await client.update_manifest_properties(
"library/hello-world",
"latest",
can_write=False,
can_delete=False
)
# [END update_manifest_properties]
# After this update, if someone were to push an update to "myacr.azurecr.io\hello-world:v1", it would fail.
# It's worth noting that if this image also had another tag, such as "latest", and that tag did not have
# permissions set to prevent reads or deletes, the image could still be overwritten. For example,
# if someone were to push an update to "myacr.azurecr.io\hello-world:latest"
# (which references the same image), it would succeed.
Асинхронное удаление образов
import asyncio
from dotenv import find_dotenv, load_dotenv
import os
from azure.containerregistry import ManifestOrder
from azure.containerregistry.aio import ContainerRegistryClient
from azure.identity.aio import DefaultAzureCredential
class DeleteImagesAsync(object):
def __init__(self):
load_dotenv(find_dotenv())
async def delete_images(self):
# [START list_repository_names]
audience = "https://management.azure.com"
account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
credential = DefaultAzureCredential()
client = ContainerRegistryClient(account_url, credential, audience=audience)
async with client:
async for repository in client.list_repository_names():
print(repository)
# [END list_repository_names]
# [START list_manifest_properties]
# Keep the three most recent images, delete everything else
manifest_count = 0
async for manifest in client.list_manifest_properties(repository, order_by=ManifestOrder.LAST_UPDATE_TIME_DESCENDING):
manifest_count += 1
if manifest_count > 3:
await client.delete_manifest(repository, manifest.digest)
# [END list_manifest_properties]
Начало работы
Справочник по REST API исходного кода | (pkg.go.dev) | REST API
Установка пакета
Установка клиентской библиотеки Реестр контейнеров Azure для Go с помощьюgo get
:
go get github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry
аутентификация клиента;
При локальной разработке и отладке приложения можно использовать azidentity. NewDefaultAzureCredential для проверки подлинности. Рекомендуется использовать управляемое удостоверение в рабочей среде.
import (
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry"
"log"
)
func main() {
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("failed to obtain a credential: %v", err)
}
client, err := azcontainerregistry.NewClient("https://myregistry.azurecr.io", cred, nil)
if err != nil {
log.Fatalf("failed to create client: %v", err)
}
}
Дополнительные сведения о других подходах проверки подлинности см. в документации по azidentity .
Примеры
Каждый пример предполагает, что URL-адрес конечной точки реестра контейнеров имеет значение "https://myregistry.azurecr.io".
Вывод списка тегов
В этом примере предполагается, что в реестре есть репозиторий hello-world
.
import (
"context"
"fmt"
"github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry"
"log"
)
func Example_listTagsWithAnonymousAccess() {
client, err := azcontainerregistry.NewClient("https://myregistry.azurecr.io", nil, nil)
if err != nil {
log.Fatalf("failed to create client: %v", err)
}
ctx := context.Background()
pager := client.NewListTagsPager("library/hello-world", nil)
for pager.More() {
page, err := pager.NextPage(ctx)
if err != nil {
log.Fatalf("failed to advance page: %v", err)
}
for _, v := range page.Tags {
fmt.Printf("tag: %s\n", *v.Name)
}
}
}
Задание свойств артефакта
В этом примере предполагается, что в реестре есть репозиторий hello-world
с образом, помеченным тегом latest
.
package azcontainerregistry_test
import (
"context"
"fmt"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry"
"log"
)
func Example_setArtifactProperties() {
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("failed to obtain a credential: %v", err)
}
client, err := azcontainerregistry.NewClient("https://myregistry.azurecr.io", cred, nil)
if err != nil {
log.Fatalf("failed to create client: %v", err)
}
ctx := context.Background()
res, err := client.UpdateTagProperties(ctx, "library/hello-world", "latest", &azcontainerregistry.ClientUpdateTagPropertiesOptions{
Value: &azcontainerregistry.TagWriteableProperties{
CanWrite: to.Ptr(false),
CanDelete: to.Ptr(false),
}})
if err != nil {
log.Fatalf("failed to finish the request: %v", err)
}
fmt.Printf("repository library/hello-world - tag latest: 'CanWrite' property: %t, 'CanDelete' property: %t\n", *res.Tag.ChangeableAttributes.CanWrite, *res.Tag.ChangeableAttributes.CanDelete)
}
Удаление изображений
package azcontainerregistry_test
import (
"context"
"fmt"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry"
"log"
)
func Example_deleteImages() {
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("failed to obtain a credential: %v", err)
}
client, err := azcontainerregistry.NewClient("https://myregistry.azurecr.io", cred, nil)
if err != nil {
log.Fatalf("failed to create client: %v", err)
}
ctx := context.Background()
repositoryPager := client.NewListRepositoriesPager(nil)
for repositoryPager.More() {
repositoryPage, err := repositoryPager.NextPage(ctx)
if err != nil {
log.Fatalf("failed to advance repository page: %v", err)
}
for _, r := range repositoryPage.Repositories.Names {
manifestPager := client.NewListManifestsPager(*r, &azcontainerregistry.ClientListManifestsOptions{
OrderBy: to.Ptr(azcontainerregistry.ArtifactManifestOrderByLastUpdatedOnDescending),
})
for manifestPager.More() {
manifestPage, err := manifestPager.NextPage(ctx)
if err != nil {
log.Fatalf("failed to advance manifest page: %v", err)
}
imagesToKeep := 3
for i, m := range manifestPage.Manifests.Attributes {
if i >= imagesToKeep {
for _, t := range m.Tags {
fmt.Printf("delete tag from image: %s", *t)
_, err := client.DeleteTag(ctx, *r, *t, nil)
if err != nil {
log.Fatalf("failed to delete tag: %v", err)
}
}
_, err := client.DeleteManifest(ctx, *r, *m.Digest, nil)
if err != nil {
log.Fatalf("failed to delete manifest: %v", err)
}
fmt.Printf("delete image with digest: %s", *m.Digest)
}
}
}
}
}
}
Очистка ресурсов
Если вы хотите очистить и удалить ресурс Реестра контейнеров Azure, вы можете удалить ресурс или группу ресурсов. При удалении группы ресурсов также удаляются все связанные с ней ресурсы.
Следующие шаги
Из этого краткого руководства вы узнали, как использовать клиентскую библиотеку Реестра контейнеров Azure для выполнения операций с образами и артефактами в реестре контейнеров.
Дополнительные сведения см. в справочной документации по API:
Дополнительные сведения о REST API Реестра контейнеров Azure.