Azure Container Registry client library for Java
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 {bomversionto_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.1.0-beta.1</version>
</dependency>
Authenticate the client
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 client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
.credential(credential)
.buildClient();
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryAsyncClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
.credential(credential)
.buildAsyncClient();
For more information on using AAD with Azure Container Registry, please see the service's Authentication Overview.
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. - Set the authenticationScope in ContainerRegistryClientBuilder.
ContainerRegistryClient containerRegistryClient = new ContainerRegistryClientBuilder()
.endpoint(getEndpoint())
.credential(credentials)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_CHINA)
.buildClient();
containerRegistryClient
.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 client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
.buildClient();
ContainerRegistryAsyncClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
.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
- List repository names
- List tags with anonymous access
- Set artifact properties
- Delete images
- Delete repository with anonymous access throws
Async examples
- List repository names asynchronously
- List tags with anonymous access asynchronously
- Set artifact properties asynchronously
- Delete images asynchronously
- Delete repository with anonymous access asynchronously throws
List repository names
Iterate through the collection of repositories in the registry.
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
.credential(credential)
.buildClient();
client.listRepositoryNames().forEach(repository -> System.out.println(repository));
List tags with anonymous access
ContainerRegistryClient anonymousClient = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
.buildClient();
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
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
.credential(defaultCredential)
.buildClient();
RegistryArtifact image = client.getArtifact(repositoryName, digest);
image.updateTagProperties(
tag,
new ArtifactTagProperties()
.setWriteEnabled(false)
.setDeleteEnabled(false));
Delete Images
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
.credential(defaultCredential)
.buildClient();
final int imagesCountToKeep = 3;
for (String repositoryName : client.listRepositoryNames()) {
final ContainerRepository repository = client.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)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
.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");
}
Troubleshooting
All container registry service operations will throw a HttpResponseException on failure.
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRepository containerRepository = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
.credential(credential)
.buildClient()
.getRepository(repositoryName);
try {
containerRepository.getProperties();
} catch (HttpResponseException exception) {
// Do something with the exception.
}
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.
Package | Description |
---|---|
com.azure.containers.containerregistry |
Package containing the classes for ContainerRegistry.
|
com.azure.containers.containerregistry.models |
Package containing classes for AzureContainerRegistry.
|
com.azure.containers.containerregistry.specialized |
Package containing the implementations for AzureContainerRegistry.
|