biblioteca cliente de Azure Container Registry para Java: versión 1.2.2

Artículo
10/21/2023

Azure Container Registry permite almacenar y administrar imágenes y artefactos de contenedor en un registro privado para todos los tipos de implementaciones de contenedor.

Use la biblioteca cliente de Azure Container Registry para lo siguiente:

Enumeración de imágenes o artefactos en un registro
Obtención de metadatos para imágenes y artefactos, repositorios y etiquetas
Establecimiento de propiedades de lectura, escritura y eliminación en elementos del registro
Eliminación de imágenes y artefactos, repositorios y etiquetas

Código | fuentePaquete (Maven) | Documentación | del productoMuestras

Introducción

Requisitos previos

Un kit de desarrollo de Java (JDK), versión 8 o posterior.
Suscripción de Azure
Creación de Container Registry

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de 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>

y, a continuación, incluya la dependencia directa en la sección dependencias sin la etiqueta de versión, como se muestra a continuación.

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

Inclusión de dependencias directas

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

Autenticación de clientes

La biblioteca de identidades de Azure proporciona compatibilidad sencilla con Azure Active Directory para la autenticación. Tenga en cuenta que todos los ejemplos siguientes suponen que tiene un punto de conexión, que es la dirección URL, incluido el nombre del servidor de inicio de sesión y el https:// prefijo. Más información en Azure Container Registry portal

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 obtener más información sobre el uso de AAD con Azure Container Registry, consulte La información general sobre la autenticación del servicio.

Autenticación con el token de AAD de ARM

De forma predeterminada, el SDK de Container Registry para Java usa tokens de acceso de ACR. Si desea autenticarse con el token de AAD de ARM y tener habilitada la directiva correspondiente, asegúrese de establecer la audiencia al compilar el cliente de Container Registry. Consulte la referencia de la CLI de ACR para obtener información sobre cómo comprobar la configuración de directivas de autenticación de ARM.

ContainerRegistryAudience value es específico de la nube:

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

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

Nubes nacionales

Para autenticarse con un registro en una nube nacional, deberá realizar las siguientes adiciones a la configuración de cliente:

Establezca en authorityHost el generador de credenciales después de la documentación de la biblioteca cliente de identidad.
Si la autenticación de token de acceso de ACR está deshabilitada para el recurso del Registrocontainer, debe configurar la audiencia en el generador de cliente de Container Registry.

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

Compatibilidad con el acceso anónimo

Si se crea una instancia del generador sin credenciales, el SDK crea el cliente de servicio para el modo de extracción anónimo. El usuario debe usar esta configuración en un registro que se ha habilitado para la extracción anónima. En este modo, el usuario solo puede llamar al método listRepositoryNames y a su sobrecarga. Se producirá un error en todas las demás llamadas. Para obtener más información, lea Acceso de extracción anónimo.

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

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

Conceptos clave

Un registro almacena imágenes de Docker y artefactos de OCI. Una imagen o artefacto se compone de un manifiesto y capas. El manifiesto de una imagen describe las capas que componen la imagen y se identifica de forma única por su síntesis. Una imagen también se puede "etiquetar" para darle un alias legible. Una imagen o artefacto puede tener cero o más etiquetas asociadas y cada etiqueta identifica de forma única la imagen. Una colección de imágenes que comparten el mismo nombre, pero que tienen etiquetas diferentes, se conoce como repositorio.

Para más información, consulte Conceptos de Container Registry.

Ejemplos

Operaciones de registro

Esta sección contiene ContainerRegistryClient ejemplos.

Enumeración de nombres de repositorio

Recorra en iteración la colección de repositorios del registro.

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

Enumeración de etiquetas de artefacto con acceso 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()));
}

Establecimiento de propiedades de artefactos

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

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

Eliminar imágenes

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();
        });
}

Eliminación de un repositorio con inicios de acceso 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");
}

Operaciones de blob y manifiesto

Esta sección contiene ejemplos para ContainerRegistryContentClient que muestren cómo cargar y descargar imágenes.

En primer lugar, es necesario crear un cliente de blobs.

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

Carga de imágenes

Para cargar una imagen completa, es necesario cargar capas y configuraciones individuales. Después, podemos cargar un manifiesto que describa una imagen o artefacto y asígnele una etiqueta.

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());

Descargar imágenes

Para descargar una imagen completa, es necesario descargar su manifiesto y, a continuación, descargar capas individuales y configuración.

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());
}

Eliminación de un blob

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

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

Eliminar manifiesto

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

Solución de problemas

Consulte nuestra guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

Pasos siguientes

Vaya más allá con azure-containers-containerregistry y nuestros ejemplos
Ver un vídeo detallado o demostración
Más información sobre el servicio Azure Container Registry

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones