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

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

• Um Java Development Kit (JDK) versão 8 ou posterior.
• Assinatura do Azure
• Criação do Registro de Contêiner

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 do Registro:
  • Listar nomes de repositório
  • Listar marcas de artefato com acesso anônimo
  • Definir propriedades do artefato
  • Excluir imagens
  • Excluir repositório com lançamentos de acesso anônimo
• Operações de blob e manifesto:
  • Carregar imagens
  • Baixar imagens
  • Excluir manifesto
  • Excluir Blob

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

• Vá além com azure-containers-containerregistry e nossos exemplos
• Assista a um vídeo de demonstração ou aprofundamento
• Leia mais sobre o serviço Registro de Contêiner do Azure

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.