Azure Container Registry client library for Java - version 1.2.14

Azure Container Registry allows you to store and manage container images and artifacts in a private registry for all types of container deployments.

Use the client library for Azure Container Registry to:

• List images or artifacts in a registry
• Obtain metadata for images and artifacts, repositories and tags
• Set read/write/delete properties on registry items
• Delete images and artifacts, repositories and tags

Source code | Package (Maven) | Product documentation | Samples

Getting started

Prerequisites

• A Java Development Kit (JDK), version 8 or later.
• Azure Subscription
• Container Registry Create

Include the package

Include the BOM file

Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number. To learn more about the BOM, see the AZURE SDK BOM README.

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

and then include the direct dependency in the dependencies section without the version tag as shown below.

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

Include direct dependency

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

Authenticate clients

The Azure Identity library provides easy Azure Active Directory support for authentication. Note all the below samples assume you have an endpoint, which is the URL including the name of the login server and the https:// prefix. More information at 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();

For more information on using AAD with Azure Container Registry, please see the service's Authentication Overview.

Authenticating with ARM AAD token

By default, Container Registry SDK for Java uses ACR access tokens. If you want to authenticate with ARM AAD token and have corresponding policy enabled, make sure to set audience when building container Registry client. Please refer to ACR CLI reference for information on how to check ARM authentication policy configuration.

ContainerRegistryAudience value is specific to the cloud:

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

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

National Clouds

To authenticate with a registry in a National Cloud, you will need to make the following additions to your client configuration:

• Set the authorityHost in the credential builder following Identity client library documentation
• If ACR access token authentication is disabled for yourcontainer Registry resource, you need to configure the audience on the Container Registry client builder.

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

Anonymous access support

If the builder is instantiated without any credentials, the SDK creates the service client for the anonymous pull mode. The user must use this setting on a registry that has been enabled for anonymous pull. In this mode, the user can only call listRepositoryNames method and its overload. All the other calls will fail. For more information please read Anonymous Pull Access

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

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

Key concepts

A registry stores Docker images and OCI Artifacts. An image or artifact consists of a manifest and layers. An image's manifest describes the layers that make up the image, and is uniquely identified by its digest. An image can also be "tagged" to give it a human-readable alias. An image or artifact can have zero or more tags associated with it, and each tag uniquely identifies the image. A collection of images that share the same name but have different tags, is referred to as a repository.

For more information please see Container Registry Concepts.

Examples

Sync examples

• Registry operations:
  • List repository names
  • List artifact tags with anonymous access
  • Set artifact properties
  • Delete images
  • Delete repository with anonymous access throws
• Blob and manifest operations:
  • Upload images
  • Download images
  • Delete manifest
  • Delete blob

Registry operations

This section contains ContainerRegistryClient samples.

List repository names

Iterate through the collection of repositories in the registry.

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

List artifact tags with anonymous access

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

Set artifact properties

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

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

Delete Images

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

Delete a repository with anonymous access throws

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

Blob and manifest operations

This section contains samples for ContainerRegistryContentClient that show how to upload and download images.

First, we need to create blob client.

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

Upload Images

To upload a full image, we need to upload individual layers and configuration. After that we can upload a manifest which describes an image or artifact and assign it a tag.

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

Download Images

To download a full image, we need to download its manifest and then download individual layers and configuration.

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

Delete blob

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

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

Delete manifest

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

Troubleshooting

See our troubleshooting guide for details on how to diagnose various failure scenarios.

Next steps

• Go further with azure-containers-containerregistry and our samples
• Watch a demo or deep dive video
• Read more about the Azure Container Registry service

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.