Events
Mar 31, 11 PM - Apr 2, 11 PM
The ultimate Microsoft Fabric, Power BI, SQL, and AI community-led event. March 31 to April 2, 2025.
Register todayThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
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:
Source code | Package (Maven) | Product documentation | Samples
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>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-containers-containerregistry</artifactId>
<version>1.2.14</version>
</dependency>
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.
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));
To authenticate with a registry in a National Cloud, you will need to make the following additions to your client configuration:
authorityHost
in the credential builder following Identity client library documentationContainerRegistryClient 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));
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();
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.
This section contains ContainerRegistryClient
samples.
Iterate through the collection of repositories in the registry.
registryClient.listRepositoryNames().forEach(repository -> System.out.println(repository));
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()));
}
RegistryArtifact image = registryClient.getArtifact(repositoryName, digest);
image.updateTagProperties(
tag,
new ArtifactTagProperties()
.setWriteEnabled(false)
.setDeleteEnabled(false));
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();
});
}
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");
}
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();
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());
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());
}
GetManifestResult manifestResult = contentClient.getManifest("latest");
OciImageManifest manifest = manifestResult.getManifest().toObject(OciImageManifest.class);
for (OciDescriptor layer : manifest.getLayers()) {
contentClient.deleteBlob(layer.getDigest());
}
GetManifestResult manifestResult = contentClient.getManifest("latest");
contentClient.deleteManifest(manifestResult.getDigest());
See our troubleshooting guide for details on how to diagnose various failure scenarios.
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.
Azure SDK for Java feedback
Azure SDK for Java is an open source project. Select a link to provide feedback:
Events
Mar 31, 11 PM - Apr 2, 11 PM
The ultimate Microsoft Fabric, Power BI, SQL, and AI community-led event. March 31 to April 2, 2025.
Register today