Registro de Contêiner do Azure biblioteca de clientes para Java – versão 1.2.2

  • Artigo

Registro de Contêiner do Azure permite armazenar e gerenciar imagens e artefatos de contêiner em um registro privado para todos os tipos de implantações de contêiner.

Use a biblioteca de clientes do Registro de Contêiner do Azure para:

  • Listar imagens ou artefatos em um registro
  • Obter metadados para imagens e artefatos, repositórios e marcas
  • Definir propriedades de leitura/gravação/exclusão em itens do registro
  • Excluir imagens e artefatos, repositórios e marcas

Código-fonte | Pacote (Maven) | Documentação do produto | Amostras

Introdução

Pré-requisitos

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre a BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

e inclua a dependência direta na seção dependências sem a marca de versão, conforme mostrado abaixo.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-containers-containerregistry</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-containers-containerregistry</artifactId>
  <version>1.2.2</version>
</dependency>

Autenticar clientes

A biblioteca de Identidade do Azure fornece suporte fácil ao Azure Active Directory para autenticação. Observe que todos os exemplos abaixo pressupõem que você tenha um ponto de extremidade, que é a URL, incluindo o nome do servidor de logon e o https:// prefixo. Mais informações no portal do Registro de Contêiner do Azure

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryAsyncClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildAsyncClient();

Para obter mais informações sobre como usar o AAD com Registro de Contêiner do Azure, consulte a Visão geral de autenticação do serviço.

Autenticação com o token do ARM AAD

Por padrão, o SDK do Registro de Contêiner para Java usa tokens de acesso do ACR. Se você quiser autenticar com o token do ARM AAD e tiver a política correspondente habilitada, certifique-se de definir o público-alvo ao criar o cliente do Registro de contêiner. Consulte a referência da CLI do ACR para obter informações sobre como marcar configuração da política de autenticação do ARM.

ContainerRegistryAudience value é específico para a nuvem:

ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(getEndpoint())
    .credential(credential)
    .audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
    .buildClient();

registryClient
    .listRepositoryNames()
    .forEach(name -> System.out.println(name));

Nuvens nacionais

Para autenticar com um registro em uma nuvem nacional, você precisará fazer as seguintes adições à configuração do cliente:

  • Defina o authorityHost no construtor de credenciais seguindo a documentação da biblioteca de clientes de identidade
  • Se a autenticação de token de acesso do ACR estiver desabilitada para o recurso do Registro de Contêiner, você precisará configurar o público-alvo no construtor de clientes do Registro de Contêiner.
ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(getEndpoint())
    .credential(credential)
    // only if ACR access tokens are disabled or not supported
    .audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_CHINA)
    .buildClient();

registryClient
    .listRepositoryNames()
    .forEach(name -> System.out.println(name));

Suporte de acesso anônimo

Se o construtor for instanciado sem credenciais, o SDK criará o cliente de serviço para o modo de pull anônimo. O usuário deve usar essa configuração em um registro que tenha sido habilitado para pull anônimo. Nesse modo, o usuário só pode chamar o método listRepositoryNames e sua sobrecarga. Todas as outras chamadas falharão. Para obter mais informações, leia Acesso de Pull Anônimo

ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .buildClient();

ContainerRegistryAsyncClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .buildAsyncClient();

Principais conceitos

Um registro armazena imagens do Docker e artefatos OCI. Uma imagem ou um artefato consiste em um manifesto e em camadas. O manifesto de uma imagem descreve as camadas que compõem a imagem e é identificado exclusivamente por seu resumo. Uma imagem também pode ser "marcada" para dar a ela um alias legível por humanos. Uma imagem ou artefato pode ter zero ou mais marcas associadas a ela e cada marca identifica exclusivamente a imagem. Uma coleção de imagens que compartilham o mesmo nome, mas têm marcas diferentes, é conhecida como um repositório.

Para obter mais informações, consulte Conceitos do Registro de Contêiner.

Exemplos

Exemplos de sincronização

Operações de registro

Esta seção contém ContainerRegistryClient exemplos.

Listar nomes de repositório

Itere na coleção de repositórios no registro.

registryClient.listRepositoryNames().forEach(repository -> System.out.println(repository));

Listar marcas de artefato com acesso anônimo

RegistryArtifact image = anonymousClient.getArtifact(repositoryName, digest);

PagedIterable<ArtifactTagProperties> tags = image.listTagProperties();

System.out.printf(String.format("%s has the following aliases:", image.getFullyQualifiedReference()));

for (ArtifactTagProperties tag : tags) {
    System.out.printf(String.format("%s/%s:%s", anonymousClient.getEndpoint(), repositoryName, tag.getName()));
}

Definir propriedades do artefato

RegistryArtifact image = registryClient.getArtifact(repositoryName, digest);

image.updateTagProperties(
    tag,
    new ArtifactTagProperties()
        .setWriteEnabled(false)
        .setDeleteEnabled(false));

Excluir imagens

final int imagesCountToKeep = 3;
for (String repositoryName : registryClient.listRepositoryNames()) {
    final ContainerRepository repository = registryClient.getRepository(repositoryName);

    // Obtain the images ordered from newest to oldest
    PagedIterable<ArtifactManifestProperties> imageManifests =
        repository.listManifestProperties(
            ArtifactManifestOrder.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();
        });
}

Excluir um repositório com lançamentos de acesso anônimo

final String endpoint = getEndpoint();
final String repositoryName = getRepositoryName();

ContainerRegistryClient anonymousClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .buildClient();

try {
    anonymousClient.deleteRepository(repositoryName);
    System.out.println("Unexpected Success: Delete is not allowed on anonymous access");
} catch (ClientAuthenticationException ex) {
    System.out.println("Expected exception: Delete is not allowed on anonymous access");
}

Operações de blob e manifesto

Esta seção contém exemplos para ContainerRegistryContentClient que mostram como carregar e baixar imagens.

Primeiro, precisamos criar um cliente de blob.

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryContentClient contentClient = new ContainerRegistryContentClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .repositoryName(repository)
    .buildClient();

Carregar imagens

Para carregar uma imagem completa, precisamos carregar camadas e configurações individuais. Depois disso, podemos carregar um manifesto que descreve uma imagem ou artefato e atribuí-lo a uma marca.

BinaryData configContent = BinaryData.fromObject(Collections.singletonMap("hello", "world"));

UploadRegistryBlobResult configUploadResult = contentClient.uploadBlob(configContent);
System.out.printf("Uploaded config: digest - %s, size - %s\n", configUploadResult.getDigest(), configContent.getLength());

OciDescriptor configDescriptor = new OciDescriptor()
    .setMediaType("application/vnd.unknown.config.v1+json")
    .setDigest(configUploadResult.getDigest())
    .setSizeInBytes(configContent.getLength());

BinaryData layerContent = BinaryData.fromString("Hello Azure Container Registry");
UploadRegistryBlobResult layerUploadResult = contentClient.uploadBlob(layerContent);
System.out.printf("Uploaded layer: digest - %s, size - %s\n", layerUploadResult.getDigest(), layerContent.getLength());

OciImageManifest manifest = new OciImageManifest()
    .setConfiguration(configDescriptor)
    .setSchemaVersion(2)
    .setLayers(Collections.singletonList(
        new OciDescriptor()
            .setDigest(layerUploadResult.getDigest())
            .setSizeInBytes(layerContent.getLength())
            .setMediaType("application/octet-stream")));

SetManifestResult manifestResult = contentClient.setManifest(manifest, "latest");
System.out.printf("Uploaded manifest: digest - %s\n", manifestResult.getDigest());

Baixar imagens

Para baixar uma imagem completa, precisamos baixar seu manifesto e baixar camadas e configurações individuais.

GetManifestResult manifestResult = contentClient.getManifest("latest");

OciImageManifest manifest = manifestResult.getManifest().toObject(OciImageManifest.class);
System.out.printf("Got manifest:\n%s\n", PRETTY_PRINT.writeValueAsString(manifest));

String configFileName = manifest.getConfiguration().getDigest() + ".json";
contentClient.downloadStream(manifest.getConfiguration().getDigest(), createFileChannel(configFileName));
System.out.printf("Got config: %s\n", configFileName);

for (OciDescriptor layer : manifest.getLayers()) {
    contentClient.downloadStream(layer.getDigest(), createFileChannel(layer.getDigest()));
    System.out.printf("Got layer: %s\n", layer.getDigest());
}

Excluir Blob

GetManifestResult manifestResult = contentClient.getManifest("latest");

OciImageManifest manifest = manifestResult.getManifest().toObject(OciImageManifest.class);
for (OciDescriptor layer : manifest.getLayers()) {
    contentClient.deleteBlob(layer.getDigest());
}

Excluir manifesto

GetManifestResult manifestResult = contentClient.getManifest("latest");
contentClient.deleteManifest(manifestResult.getDigest());

Solução de problemas

Consulte nosso guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Próximas etapas

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões