Learn the basics of Amazon ECR with an AWS SDK - AWS SDK Code Examples

There are more AWS SDK examples available in the AWS Doc SDK Examples GitHub repo.

Learn the basics of Amazon ECR with an AWS SDK

The following code examples show how to:

  • Create an Amazon ECR repository.

  • Set repository policies.

  • Retrieve repository URIs.

  • Get Amazon ECR authorization tokens.

  • Set lifecycle policies for Amazon ECR repositories.

  • Push a Docker image to an Amazon ECR repository.

  • Verify the existence of an image in an Amazon ECR repository.

  • List Amazon ECR repositories for your account and get details about them.

  • Delete Amazon ECR repositories.

Java
SDK for Java 2.x
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

Run an interactive scenario demonstrating Amazon ECR features.

import software.amazon.awssdk.services.ecr.model.EcrException; import software.amazon.awssdk.services.ecr.model.RepositoryPolicyNotFoundException; import java.util.Scanner; /** * Before running this Java V2 code example, set up your development * environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html * * This Java code example requires an IAM Role that has permissions to interact with the Amazon ECR service. * * To create an IAM role, see: * * https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html * * This Java scenario example requires a local docker image named echo-text. Without a local image, * this Java program will not successfully run. For more information including how to create the local * image, see: * * /getting_started_scenarios/ecr_scenario/README * */ public class ECRScenario { public static final String DASHES = new String(new char[80]).replace("\0", "-"); public static void main(String[] args) { final String usage = """ Usage: <iamRoleARN> <accountId> Where: iamRoleARN - The IAM role ARN that has the necessary permissions to access and manage the Amazon ECR repository. accountId - Your AWS account number. """; if (args.length != 2) { System.out.println(usage); return; } ECRActions ecrActions = new ECRActions(); String iamRole = args[0]; String accountId = args[1]; String localImageName; Scanner scanner = new Scanner(System.in); System.out.println(""" The Amazon Elastic Container Registry (ECR) is a fully-managed Docker container registry service provided by AWS. It allows developers and organizations to securely store, manage, and deploy Docker container images. ECR provides a simple and scalable way to manage container images throughout their lifecycle, from building and testing to production deployment.\s The `EcrAsyncClient` interface in the AWS SDK for Java 2.x provides a set of methods to programmatically interact with the Amazon ECR service. This allows developers to automate the storage, retrieval, and management of container images as part of their application deployment pipelines. With ECR, teams can focus on building and deploying their applications without having to worry about the underlying infrastructure required to host and manage a container registry. This scenario walks you through how to perform key operations for this service. Let's get started... You have two choices: 1 - Run the entire program. 2 - Delete an existing Amazon ECR repository named echo-text (created from a previous execution of this program that did not complete). """); while (true) { String input = scanner.nextLine(); if (input.trim().equalsIgnoreCase("1")) { System.out.println("Continuing with the program..."); System.out.println(""); break; } else if (input.trim().equalsIgnoreCase("2")) { String repoName = "echo-text"; ecrActions.deleteECRRepository(repoName); return; } else { // Handle invalid input. System.out.println("Invalid input. Please try again."); } } waitForInputToContinue(scanner); System.out.println(DASHES); System.out.println(""" 1. Create an ECR repository. The first task is to ensure we have a local Docker image named echo-text. If this image exists, then an Amazon ECR repository is created. An ECR repository is a private Docker container repository provided by Amazon Web Services (AWS). It is a managed service that makes it easy to store, manage, and deploy Docker container images.\s """ ); // Ensure that a local docker image named echo-text exists. boolean doesExist = ecrActions.isEchoTextImagePresent(); String repoName; if (!doesExist){ System.out.println("The local image named echo-text does not exist"); return; } else { localImageName = "echo-text"; repoName = "echo-text"; } try { String repoArn = ecrActions.createECRRepository(repoName); System.out.println("The ARN of the ECR repository is " + repoArn); } catch (IllegalArgumentException e) { System.err.println("Invalid repository name: " + e.getMessage()); return; } catch (RuntimeException e) { System.err.println("An error occurred while creating the ECR repository: " + e.getMessage()); e.printStackTrace(); return; } waitForInputToContinue(scanner); System.out.println(DASHES); System.out.println(""" 2. Set an ECR repository policy. Setting an ECR repository policy using the `setRepositoryPolicy` function is crucial for maintaining the security and integrity of your container images. The repository policy allows you to define specific rules and restrictions for accessing and managing the images stored within your ECR repository. """); waitForInputToContinue(scanner); try { ecrActions.setRepoPolicy(repoName, iamRole); } catch (RepositoryPolicyNotFoundException e) { System.err.println("Invalid repository name: " + e.getMessage()); return; } catch (EcrException e) { System.err.println("An ECR exception occurred: " + e.getMessage()); return; } catch (RuntimeException e) { System.err.println("An error occurred while creating the ECR repository: " + e.getMessage()); return; } waitForInputToContinue(scanner); System.out.println(DASHES); System.out.println(""" 3. Display ECR repository policy. Now we will retrieve the ECR policy to ensure it was successfully set. """); waitForInputToContinue(scanner); try { String policyText = ecrActions.getRepoPolicy(repoName); System.out.println("Policy Text:"); System.out.println(policyText); } catch (EcrException e) { System.err.println("An ECR exception occurred: " + e.getMessage()); return; } catch (RuntimeException e) { System.err.println("An error occurred while creating the ECR repository: " + e.getMessage()); return; } waitForInputToContinue(scanner); System.out.println(DASHES); System.out.println(""" 4. Retrieve an ECR authorization token. You need an authorization token to securely access and interact with the Amazon ECR registry. The `getAuthorizationToken` method of the `EcrAsyncClient` is responsible for securely accessing and interacting with an Amazon ECR repository. This operation is responsible for obtaining a valid authorization token, which is required to authenticate your requests to the ECR service. Without a valid authorization token, you would not be able to perform any operations on the ECR repository, such as pushing, pulling, or managing your Docker images. """); waitForInputToContinue(scanner); try { ecrActions.getAuthToken(); } catch (EcrException e) { System.err.println("An ECR exception occurred: " + e.getMessage()); return; } catch (RuntimeException e) { System.err.println("An error occurred while retrieving the authorization token: " + e.getMessage()); return; } waitForInputToContinue(scanner); System.out.println(DASHES); System.out.println(""" 5. Get the ECR Repository URI. The URI of an Amazon ECR repository is important. When you want to deploy a container image to a container orchestration platform like Amazon Elastic Kubernetes Service (EKS) or Amazon Elastic Container Service (ECS), you need to specify the full image URI, which includes the ECR repository URI. This allows the container runtime to pull the correct container image from the ECR repository. """); waitForInputToContinue(scanner); try { ecrActions.getRepositoryURI(repoName); } catch (EcrException e) { System.err.println("An ECR exception occurred: " + e.getMessage()); return; } catch (RuntimeException e) { System.err.println("An error occurred while retrieving the URI: " + e.getMessage()); return; } waitForInputToContinue(scanner); System.out.println(DASHES); System.out.println(""" 6. Set an ECR Lifecycle Policy. An ECR Lifecycle Policy is used to manage the lifecycle of Docker images stored in your ECR repositories. These policies allow you to automatically remove old or unused Docker images from your repositories, freeing up storage space and reducing costs. This example policy helps to maintain the size and efficiency of the container registry by automatically removing older and potentially unused images, ensuring that the storage is optimized and the registry remains up-to-date. """); waitForInputToContinue(scanner); try { ecrActions.setLifeCyclePolicy(repoName); } catch (RuntimeException e) { System.err.println("An error occurred while setting the lifecycle policy: " + e.getMessage()); e.printStackTrace(); return; } waitForInputToContinue(scanner); System.out.println(DASHES); System.out.println(""" 7. Push a docker image to the Amazon ECR Repository. The `pushImageCmd()` method pushes a local Docker image to an Amazon ECR repository. It sets up the Docker client by connecting to the local Docker host using the default port. It then retrieves the authorization token for the ECR repository by making a call to the AWS SDK. The method uses the authorization token to create an `AuthConfig` object, which is used to authenticate the Docker client when pushing the image. Finally, the method tags the Docker image with the specified repository name and image tag, and then pushes the image to the ECR repository using the Docker client. If the push operation is successful, the method prints a message indicating that the image was pushed to ECR. """); waitForInputToContinue(scanner); try { ecrActions.pushDockerImage(repoName, localImageName); } catch (RuntimeException e) { System.err.println("An error occurred while pushing a local Docker image to Amazon ECR: " + e.getMessage()); e.printStackTrace(); return; } waitForInputToContinue(scanner); System.out.println(DASHES); System.out.println("8. Verify if the image is in the ECR Repository."); waitForInputToContinue(scanner); try { ecrActions.verifyImage(repoName, localImageName); } catch (EcrException e) { System.err.println("An ECR exception occurred: " + e.getMessage()); return; } catch (RuntimeException e) { System.err.println("An error occurred " + e.getMessage()); e.printStackTrace(); return; } waitForInputToContinue(scanner); System.out.println(DASHES); System.out.println("9. As an optional step, you can interact with the image in Amazon ECR by using the CLI."); System.out.println("Would you like to view instructions on how to use the CLI to run the image? (y/n)"); String ans = scanner.nextLine().trim(); if (ans.equalsIgnoreCase("y")) { String instructions = """ 1. Authenticate with ECR - Before you can pull the image from Amazon ECR, you need to authenticate with the registry. You can do this using the AWS CLI: aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin %s.dkr.ecr.us-east-1.amazonaws.com 2. Describe the image using this command: aws ecr describe-images --repository-name %s --image-ids imageTag=%s 3. Run the Docker container and view the output using this command: docker run --rm %s.dkr.ecr.us-east-1.amazonaws.com/%s:%s """; instructions = String.format(instructions, accountId, repoName, localImageName, accountId, repoName, localImageName); System.out.println(instructions); } waitForInputToContinue(scanner); System.out.println(DASHES); System.out.println("10. Delete the ECR Repository."); System.out.println( """ If the repository isn't empty, you must either delete the contents of the repository or use the force option (used in this scenario) to delete the repository and have Amazon ECR delete all of its contents on your behalf. """); System.out.println("Would you like to delete the Amazon ECR Repository? (y/n)"); String delAns = scanner.nextLine().trim(); if (delAns.equalsIgnoreCase("y")) { System.out.println("You selected to delete the AWS ECR resources."); try { ecrActions.deleteECRRepository(repoName); } catch (EcrException e) { System.err.println("An ECR exception occurred: " + e.getMessage()); return; } catch (RuntimeException e) { System.err.println("An error occurred while deleting the Docker image: " + e.getMessage()); e.printStackTrace(); return; } } System.out.println(DASHES); System.out.println("This concludes the Amazon ECR SDK scenario"); System.out.println(DASHES); } private static void waitForInputToContinue(Scanner scanner) { while (true) { System.out.println(""); System.out.println("Enter 'c' followed by <ENTER> to continue:"); String input = scanner.nextLine(); if (input.trim().equalsIgnoreCase("c")) { System.out.println("Continuing with the program..."); System.out.println(""); break; } else { // Handle invalid input. System.out.println("Invalid input. Please try again."); } } } }

A wrapper class for Amazon ECR SDK methods.

import com.github.dockerjava.api.DockerClient; import com.github.dockerjava.api.exception.DockerClientException; import com.github.dockerjava.api.model.AuthConfig; import com.github.dockerjava.api.model.Image; import com.github.dockerjava.core.DockerClientBuilder; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration; import software.amazon.awssdk.http.async.SdkAsyncHttpClient; import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.ecr.EcrAsyncClient; import software.amazon.awssdk.services.ecr.model.AuthorizationData; import software.amazon.awssdk.services.ecr.model.CreateRepositoryRequest; import software.amazon.awssdk.services.ecr.model.CreateRepositoryResponse; import software.amazon.awssdk.services.ecr.model.DeleteRepositoryRequest; import software.amazon.awssdk.services.ecr.model.DeleteRepositoryResponse; import software.amazon.awssdk.services.ecr.model.DescribeImagesRequest; import software.amazon.awssdk.services.ecr.model.DescribeImagesResponse; import software.amazon.awssdk.services.ecr.model.DescribeRepositoriesRequest; import software.amazon.awssdk.services.ecr.model.DescribeRepositoriesResponse; import software.amazon.awssdk.services.ecr.model.EcrException; import software.amazon.awssdk.services.ecr.model.GetAuthorizationTokenResponse; import software.amazon.awssdk.services.ecr.model.GetRepositoryPolicyRequest; import software.amazon.awssdk.services.ecr.model.GetRepositoryPolicyResponse; import software.amazon.awssdk.services.ecr.model.ImageIdentifier; import software.amazon.awssdk.services.ecr.model.Repository; import software.amazon.awssdk.services.ecr.model.RepositoryPolicyNotFoundException; import software.amazon.awssdk.services.ecr.model.SetRepositoryPolicyRequest; import software.amazon.awssdk.services.ecr.model.SetRepositoryPolicyResponse; import software.amazon.awssdk.services.ecr.model.StartLifecyclePolicyPreviewRequest; import software.amazon.awssdk.services.ecr.model.StartLifecyclePolicyPreviewResponse; import com.github.dockerjava.api.command.DockerCmdExecFactory; import com.github.dockerjava.netty.NettyDockerCmdExecFactory; import java.time.Duration; import java.util.Base64; import java.util.List; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionException; public class ECRActions { private static EcrAsyncClient ecrClient; private static DockerClient dockerClient; private static Logger logger = LoggerFactory.getLogger(ECRActions.class); /** * Creates an Amazon Elastic Container Registry (Amazon ECR) repository. * * @param repoName the name of the repository to create. * @return the Amazon Resource Name (ARN) of the created repository, or an empty string if the operation failed. * @throws IllegalArgumentException If repository name is invalid. * @throws RuntimeException if an error occurs while creating the repository. */ public String createECRRepository(String repoName) { if (repoName == null || repoName.isEmpty()) { throw new IllegalArgumentException("Repository name cannot be null or empty"); } CreateRepositoryRequest request = CreateRepositoryRequest.builder() .repositoryName(repoName) .build(); CompletableFuture<CreateRepositoryResponse> response = getAsyncClient().createRepository(request); try { CreateRepositoryResponse result = response.join(); if (result != null) { System.out.println("The " + repoName + " repository was created successfully."); return result.repository().repositoryArn(); } else { throw new RuntimeException("Unexpected response type"); } } catch (CompletionException e) { Throwable cause = e.getCause(); if (cause instanceof EcrException ex) { if ("RepositoryAlreadyExistsException".equals(ex.awsErrorDetails().errorCode())) { System.out.println("The Amazon ECR repository already exists, moving on..."); DescribeRepositoriesRequest describeRequest = DescribeRepositoriesRequest.builder() .repositoryNames(repoName) .build(); DescribeRepositoriesResponse describeResponse = getAsyncClient().describeRepositories(describeRequest).join(); return describeResponse.repositories().get(0).repositoryArn(); } else { throw new RuntimeException(ex); } } else { throw new RuntimeException(e); } } } /** * Deletes an ECR (Elastic Container Registry) repository. * * @param repoName the name of the repository to delete. * @throws IllegalArgumentException if the repository name is null or empty. * @throws EcrException if there is an error deleting the repository. * @throws RuntimeException if an unexpected error occurs during the deletion process. */ public void deleteECRRepository(String repoName) { if (repoName == null || repoName.isEmpty()) { throw new IllegalArgumentException("Repository name cannot be null or empty"); } DeleteRepositoryRequest repositoryRequest = DeleteRepositoryRequest.builder() .force(true) .repositoryName(repoName) .build(); CompletableFuture<DeleteRepositoryResponse> response = getAsyncClient().deleteRepository(repositoryRequest); response.whenComplete((deleteRepositoryResponse, ex) -> { if (deleteRepositoryResponse != null) { System.out.println("You have successfully deleted the " + repoName + " repository"); } else { Throwable cause = ex.getCause(); if (cause instanceof EcrException) { throw (EcrException) cause; } else { throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause); } } }); // Wait for the CompletableFuture to complete response.join(); } private static DockerClient getDockerClient() { String osName = System.getProperty("os.name"); if (osName.startsWith("Windows")) { // Make sure Docker Desktop is running. String dockerHost = "tcp://localhost:2375"; // Use the Docker Desktop default port. DockerCmdExecFactory dockerCmdExecFactory = new NettyDockerCmdExecFactory().withReadTimeout(20000).withConnectTimeout(20000); dockerClient = DockerClientBuilder.getInstance(dockerHost).withDockerCmdExecFactory(dockerCmdExecFactory).build(); } else { dockerClient = DockerClientBuilder.getInstance().build(); } return dockerClient; } /** * Retrieves an asynchronous Amazon Elastic Container Registry (ECR) client. * * @return the configured ECR asynchronous client. */ private static EcrAsyncClient getAsyncClient() { /* The `NettyNioAsyncHttpClient` class is part of the AWS SDK for Java, version 2, and it is designed to provide a high-performance, asynchronous HTTP client for interacting with AWS services. It uses the Netty framework to handle the underlying network communication and the Java NIO API to provide a non-blocking, event-driven approach to HTTP requests and responses. */ SdkAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder() .maxConcurrency(50) // Adjust as needed. .connectionTimeout(Duration.ofSeconds(60)) // Set the connection timeout. .readTimeout(Duration.ofSeconds(60)) // Set the read timeout. .writeTimeout(Duration.ofSeconds(60)) // Set the write timeout. .build(); ClientOverrideConfiguration overrideConfig = ClientOverrideConfiguration.builder() .apiCallTimeout(Duration.ofMinutes(2)) // Set the overall API call timeout. .apiCallAttemptTimeout(Duration.ofSeconds(90)) // Set the individual call attempt timeout. .build(); if (ecrClient == null) { ecrClient = EcrAsyncClient.builder() .region(Region.US_EAST_1) .httpClient(httpClient) .overrideConfiguration(overrideConfig) .build(); } return ecrClient; } /** * Sets the lifecycle policy for the specified repository. * * @param repoName the name of the repository for which to set the lifecycle policy. */ public void setLifeCyclePolicy(String repoName) { /* This policy helps to maintain the size and efficiency of the container registry by automatically removing older and potentially unused images, ensuring that the storage is optimized and the registry remains up-to-date. */ String polText = """ { "rules": [ { "rulePriority": 1, "description": "Expire images older than 14 days", "selection": { "tagStatus": "any", "countType": "sinceImagePushed", "countUnit": "days", "countNumber": 14 }, "action": { "type": "expire" } } ] } """; StartLifecyclePolicyPreviewRequest lifecyclePolicyPreviewRequest = StartLifecyclePolicyPreviewRequest.builder() .lifecyclePolicyText(polText) .repositoryName(repoName) .build(); CompletableFuture<StartLifecyclePolicyPreviewResponse> response = getAsyncClient().startLifecyclePolicyPreview(lifecyclePolicyPreviewRequest); response.whenComplete((lifecyclePolicyPreviewResponse, ex) -> { if (lifecyclePolicyPreviewResponse != null) { System.out.println("Lifecycle policy preview started successfully."); } else { if (ex.getCause() instanceof EcrException) { throw (EcrException) ex.getCause(); } else { String errorMessage = "Unexpected error occurred: " + ex.getMessage(); throw new RuntimeException(errorMessage, ex); } } }); // Wait for the CompletableFuture to complete. response.join(); } /** * Verifies the existence of an image in an Amazon Elastic Container Registry (Amazon ECR) repository asynchronously. * * @param repositoryName The name of the Amazon ECR repository. * @param imageTag The tag of the image to verify. * @throws EcrException if there is an error retrieving the image information from Amazon ECR. * @throws CompletionException if the asynchronous operation completes exceptionally. */ public void verifyImage(String repositoryName, String imageTag) { DescribeImagesRequest request = DescribeImagesRequest.builder() .repositoryName(repositoryName) .imageIds(ImageIdentifier.builder().imageTag(imageTag).build()) .build(); CompletableFuture<DescribeImagesResponse> response = getAsyncClient().describeImages(request); response.whenComplete((describeImagesResponse, ex) -> { if (ex != null) { if (ex instanceof CompletionException) { Throwable cause = ex.getCause(); if (cause instanceof EcrException) { throw (EcrException) cause; } else { throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause); } } else { throw new RuntimeException("Unexpected error: " + ex.getCause()); } } else if (describeImagesResponse != null && !describeImagesResponse.imageDetails().isEmpty()) { System.out.println("Image is present in the repository."); } else { System.out.println("Image is not present in the repository."); } }); // Wait for the CompletableFuture to complete. response.join(); } /** * Retrieves the repository URI for the specified repository name. * * @param repoName the name of the repository to retrieve the URI for. * @return the repository URI for the specified repository name. * @throws EcrException if there is an error retrieving the repository information. * @throws CompletionException if the asynchronous operation completes exceptionally. */ public void getRepositoryURI(String repoName) { DescribeRepositoriesRequest request = DescribeRepositoriesRequest.builder() .repositoryNames(repoName) .build(); CompletableFuture<DescribeRepositoriesResponse> response = getAsyncClient().describeRepositories(request); response.whenComplete((describeRepositoriesResponse, ex) -> { if (ex != null) { Throwable cause = ex.getCause(); if (cause instanceof InterruptedException) { Thread.currentThread().interrupt(); String errorMessage = "Thread interrupted while waiting for asynchronous operation: " + cause.getMessage(); throw new RuntimeException(errorMessage, cause); } else if (cause instanceof EcrException) { throw (EcrException) cause; } else { String errorMessage = "Unexpected error: " + cause.getMessage(); throw new RuntimeException(errorMessage, cause); } } else { if (describeRepositoriesResponse != null) { if (!describeRepositoriesResponse.repositories().isEmpty()) { String repositoryUri = describeRepositoriesResponse.repositories().get(0).repositoryUri(); System.out.println("Repository URI found: " + repositoryUri); } else { System.out.println("No repositories found for the given name."); } } else { System.err.println("No response received from describeRepositories."); } } }); response.join(); } /** * Retrieves the authorization token for Amazon Elastic Container Registry (ECR). * This method makes an asynchronous call to the ECR client to retrieve the authorization token. * If the operation is successful, the method prints the token to the console. * If an exception occurs, the method handles the exception and prints the error message. * * @throws EcrException if there is an error retrieving the authorization token from ECR. * @throws RuntimeException if there is an unexpected error during the operation. */ public void getAuthToken() { CompletableFuture<GetAuthorizationTokenResponse> response = getAsyncClient().getAuthorizationToken(); response.whenComplete((authorizationTokenResponse, ex) -> { if (authorizationTokenResponse != null) { AuthorizationData authorizationData = authorizationTokenResponse.authorizationData().get(0); String token = authorizationData.authorizationToken(); if (!token.isEmpty()) { System.out.println("The token was successfully retrieved."); } } else { if (ex.getCause() instanceof EcrException) { throw (EcrException) ex.getCause(); } else { String errorMessage = "Unexpected error occurred: " + ex.getMessage(); throw new RuntimeException(errorMessage, ex); // Rethrow the exception } } }); response.join(); } /** * Gets the repository policy for the specified repository. * * @param repoName the name of the repository. * @throws EcrException if an AWS error occurs while getting the repository policy. */ public String getRepoPolicy(String repoName) { if (repoName == null || repoName.isEmpty()) { throw new IllegalArgumentException("Repository name cannot be null or empty"); } GetRepositoryPolicyRequest getRepositoryPolicyRequest = GetRepositoryPolicyRequest.builder() .repositoryName(repoName) .build(); CompletableFuture<GetRepositoryPolicyResponse> response = getAsyncClient().getRepositoryPolicy(getRepositoryPolicyRequest); response.whenComplete((resp, ex) -> { if (resp != null) { System.out.println("Repository policy retrieved successfully."); } else { if (ex.getCause() instanceof EcrException) { throw (EcrException) ex.getCause(); } else { String errorMessage = "Unexpected error occurred: " + ex.getMessage(); throw new RuntimeException(errorMessage, ex); } } }); GetRepositoryPolicyResponse result = response.join(); return result != null ? result.policyText() : null; } /** * Sets the repository policy for the specified ECR repository. * * @param repoName the name of the ECR repository. * @param iamRole the IAM role to be granted access to the repository. * @throws RepositoryPolicyNotFoundException if the repository policy does not exist. * @throws EcrException if there is an unexpected error setting the repository policy. */ public void setRepoPolicy(String repoName, String iamRole) { /* This example policy document grants the specified AWS principal the permission to perform the `ecr:BatchGetImage` action. This policy is designed to allow the specified principal to retrieve Docker images from the ECR repository. */ String policyDocumentTemplate = """ { "Version" : "2012-10-17", "Statement" : [ { "Sid" : "new statement", "Effect" : "Allow", "Principal" : { "AWS" : "%s" }, "Action" : "ecr:BatchGetImage" } ] } """; String policyDocument = String.format(policyDocumentTemplate, iamRole); SetRepositoryPolicyRequest setRepositoryPolicyRequest = SetRepositoryPolicyRequest.builder() .repositoryName(repoName) .policyText(policyDocument) .build(); CompletableFuture<SetRepositoryPolicyResponse> response = getAsyncClient().setRepositoryPolicy(setRepositoryPolicyRequest); response.whenComplete((resp, ex) -> { if (resp != null) { System.out.println("Repository policy set successfully."); } else { Throwable cause = ex.getCause(); if (cause instanceof RepositoryPolicyNotFoundException) { throw (RepositoryPolicyNotFoundException) cause; } else if (cause instanceof EcrException) { throw (EcrException) cause; } else { String errorMessage = "Unexpected error: " + cause.getMessage(); throw new RuntimeException(errorMessage, cause); } } }); response.join(); } /** * Pushes a Docker image to an Amazon Elastic Container Registry (ECR) repository. * * @param repoName the name of the ECR repository to push the image to. * @param imageName the name of the Docker image. */ public void pushDockerImage(String repoName, String imageName) { System.out.println("Pushing " + imageName + " to Amazon ECR will take a few seconds."); CompletableFuture<AuthConfig> authResponseFuture = getAsyncClient().getAuthorizationToken() .thenApply(response -> { String token = response.authorizationData().get(0).authorizationToken(); String decodedToken = new String(Base64.getDecoder().decode(token)); String password = decodedToken.substring(4); DescribeRepositoriesResponse descrRepoResponse = getAsyncClient().describeRepositories(b -> b.repositoryNames(repoName)).join(); Repository repoData = descrRepoResponse.repositories().stream().filter(r -> r.repositoryName().equals(repoName)).findFirst().orElse(null); assert repoData != null; String registryURL = repoData.repositoryUri().split("/")[0]; AuthConfig authConfig = new AuthConfig() .withUsername("AWS") .withPassword(password) .withRegistryAddress(registryURL); return authConfig; }) .thenCompose(authConfig -> { DescribeRepositoriesResponse descrRepoResponse = getAsyncClient().describeRepositories(b -> b.repositoryNames(repoName)).join(); Repository repoData = descrRepoResponse.repositories().stream().filter(r -> r.repositoryName().equals(repoName)).findFirst().orElse(null); getDockerClient().tagImageCmd(imageName + ":latest", repoData.repositoryUri() + ":latest", imageName).exec(); try { getDockerClient().pushImageCmd(repoData.repositoryUri()).withTag("echo-text").withAuthConfig(authConfig).start().awaitCompletion(); System.out.println("The " + imageName + " was pushed to ECR"); } catch (InterruptedException e) { throw (RuntimeException) e.getCause(); } return CompletableFuture.completedFuture(authConfig); }); authResponseFuture.join(); } // Make sure local image echo-text exists. public boolean isEchoTextImagePresent() { try { List<Image> images = getDockerClient().listImagesCmd().exec(); boolean helloWorldFound = false; for (Image image : images) { String[] repoTags = image.getRepoTags(); if (repoTags != null) { for (String tag : repoTags) { if (tag.startsWith("echo-text")) { System.out.println(tag); helloWorldFound = true; } } } } if (helloWorldFound) { System.out.println("The local image named echo-text exists."); return true; } else { System.out.println("The local image named echo-text does not exist."); return false; } } catch (DockerClientException ex) { logger.error("ERROR: " + ex.getMessage()); return false; } } }
Kotlin
SDK for Kotlin
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

Run an interactive scenario demonstrating Amazon ECR features.

import java.util.Scanner /** * Before running this Kotlin code example, set up your development environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-kotlin/latest/developer-guide/setup.html * * This code example requires an IAM Role that has permissions to interact with the Amazon ECR service. * * To create an IAM role, see: * * https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html * * This code example requires a local docker image named echo-text. Without a local image, * this program will not successfully run. For more information including how to create the local * image, see: * * /getting_started_scenarios/ecr_scenario/README * */ val DASHES = String(CharArray(80)).replace("\u0000", "-") suspend fun main(args: Array<String>) { val usage = """ Usage: <iamRoleARN> <accountId> Where: iamRoleARN - The IAM role ARN that has the necessary permissions to access and manage the Amazon ECR repository. accountId - Your AWS account number. """.trimIndent() // if (args.size != 2) { // println(usage) // return // } var iamRole = "arn:aws:iam::814548047983:role/Admin" var localImageName: String var accountId = "814548047983" val ecrActions = ECRActions() val scanner = Scanner(System.`in`) println( """ The Amazon Elastic Container Registry (ECR) is a fully-managed Docker container registry service provided by AWS. It allows developers and organizations to securely store, manage, and deploy Docker container images. ECR provides a simple and scalable way to manage container images throughout their lifecycle, from building and testing to production deployment. The `EcrClient` service client that is part of the AWS SDK for Kotlin provides a set of methods to programmatically interact with the Amazon ECR service. This allows developers to automate the storage, retrieval, and management of container images as part of their application deployment pipelines. With ECR, teams can focus on building and deploying their applications without having to worry about the underlying infrastructure required to host and manage a container registry. This scenario walks you through how to perform key operations for this service. Let's get started... You have two choices: 1 - Run the entire program. 2 - Delete an existing Amazon ECR repository named echo-text (created from a previous execution of this program that did not complete). """.trimIndent(), ) while (true) { val input = scanner.nextLine() if (input.trim { it <= ' ' }.equals("1", ignoreCase = true)) { println("Continuing with the program...") println("") break } else if (input.trim { it <= ' ' }.equals("2", ignoreCase = true)) { val repoName = "echo-text" ecrActions.deleteECRRepository(repoName) return } else { // Handle invalid input. println("Invalid input. Please try again.") } } waitForInputToContinue(scanner) println(DASHES) println( """ 1. Create an ECR repository. The first task is to ensure we have a local Docker image named echo-text. If this image exists, then an Amazon ECR repository is created. An ECR repository is a private Docker container repository provided by Amazon Web Services (AWS). It is a managed service that makes it easy to store, manage, and deploy Docker container images. """.trimIndent(), ) // Ensure that a local docker image named echo-text exists. val doesExist = ecrActions.listLocalImages() val repoName: String if (!doesExist) { println("The local image named echo-text does not exist") return } else { localImageName = "echo-text" repoName = "echo-text" } val repoArn = ecrActions.createECRRepository(repoName).toString() println("The ARN of the ECR repository is $repoArn") waitForInputToContinue(scanner) println(DASHES) println( """ 2. Set an ECR repository policy. Setting an ECR repository policy using the `setRepositoryPolicy` function is crucial for maintaining the security and integrity of your container images. The repository policy allows you to define specific rules and restrictions for accessing and managing the images stored within your ECR repository. """.trimIndent(), ) waitForInputToContinue(scanner) ecrActions.setRepoPolicy(repoName, iamRole) waitForInputToContinue(scanner) println(DASHES) println( """ 3. Display ECR repository policy. Now we will retrieve the ECR policy to ensure it was successfully set. """.trimIndent(), ) waitForInputToContinue(scanner) val policyText = ecrActions.getRepoPolicy(repoName) println("Policy Text:") println(policyText) waitForInputToContinue(scanner) println(DASHES) println( """ 4. Retrieve an ECR authorization token. You need an authorization token to securely access and interact with the Amazon ECR registry. The `getAuthorizationToken` method of the `EcrAsyncClient` is responsible for securely accessing and interacting with an Amazon ECR repository. This operation is responsible for obtaining a valid authorization token, which is required to authenticate your requests to the ECR service. Without a valid authorization token, you would not be able to perform any operations on the ECR repository, such as pushing, pulling, or managing your Docker images. """.trimIndent(), ) waitForInputToContinue(scanner) ecrActions.getAuthToken() waitForInputToContinue(scanner) println(DASHES) println( """ 5. Get the ECR Repository URI. The URI of an Amazon ECR repository is important. When you want to deploy a container image to a container orchestration platform like Amazon Elastic Kubernetes Service (EKS) or Amazon Elastic Container Service (ECS), you need to specify the full image URI, which includes the ECR repository URI. This allows the container runtime to pull the correct container image from the ECR repository. """.trimIndent(), ) waitForInputToContinue(scanner) val repositoryURI: String? = ecrActions.getRepositoryURI(repoName) println("The repository URI is $repositoryURI") waitForInputToContinue(scanner) println(DASHES) println( """ 6. Set an ECR Lifecycle Policy. An ECR Lifecycle Policy is used to manage the lifecycle of Docker images stored in your ECR repositories. These policies allow you to automatically remove old or unused Docker images from your repositories, freeing up storage space and reducing costs. """.trimIndent(), ) waitForInputToContinue(scanner) val pol = ecrActions.setLifeCyclePolicy(repoName) println(pol) waitForInputToContinue(scanner) println(DASHES) println( """ 7. Push a docker image to the Amazon ECR Repository. The `pushImageCmd()` method pushes a local Docker image to an Amazon ECR repository. It sets up the Docker client by connecting to the local Docker host using the default port. It then retrieves the authorization token for the ECR repository by making a call to the AWS SDK. The method uses the authorization token to create an `AuthConfig` object, which is used to authenticate the Docker client when pushing the image. Finally, the method tags the Docker image with the specified repository name and image tag, and then pushes the image to the ECR repository using the Docker client. If the push operation is successful, the method prints a message indicating that the image was pushed to ECR. """.trimIndent(), ) waitForInputToContinue(scanner) ecrActions.pushDockerImage(repoName, localImageName) waitForInputToContinue(scanner) println(DASHES) println("8. Verify if the image is in the ECR Repository.") waitForInputToContinue(scanner) ecrActions.verifyImage(repoName, localImageName) waitForInputToContinue(scanner) println(DASHES) println("9. As an optional step, you can interact with the image in Amazon ECR by using the CLI.") println("Would you like to view instructions on how to use the CLI to run the image? (y/n)") val ans = scanner.nextLine().trim() if (ans.equals("y", true)) { val instructions = """ 1. Authenticate with ECR - Before you can pull the image from Amazon ECR, you need to authenticate with the registry. You can do this using the AWS CLI: aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $accountId.dkr.ecr.us-east-1.amazonaws.com 2. Describe the image using this command: aws ecr describe-images --repository-name $repoName --image-ids imageTag=$localImageName 3. Run the Docker container and view the output using this command: docker run --rm $accountId.dkr.ecr.us-east-1.amazonaws.com/$repoName:$localImageName """ println(instructions) } waitForInputToContinue(scanner) println(DASHES) println("10. Delete the ECR Repository.") println( """ If the repository isn't empty, you must either delete the contents of the repository or use the force option (used in this scenario) to delete the repository and have Amazon ECR delete all of its contents on your behalf. """.trimIndent(), ) println("Would you like to delete the Amazon ECR Repository? (y/n)") val delAns = scanner.nextLine().trim { it <= ' ' } if (delAns.equals("y", ignoreCase = true)) { println("You selected to delete the AWS ECR resources.") waitForInputToContinue(scanner) ecrActions.deleteECRRepository(repoName) } println(DASHES) println("This concludes the Amazon ECR SDK scenario") println(DASHES) } private fun waitForInputToContinue(scanner: Scanner) { while (true) { println("") println("Enter 'c' followed by <ENTER> to continue:") val input = scanner.nextLine() if (input.trim { it <= ' ' }.equals("c", ignoreCase = true)) { println("Continuing with the program...") println("") break } else { // Handle invalid input. println("Invalid input. Please try again.") } } }

A wrapper class for Amazon ECR SDK methods.

import aws.sdk.kotlin.services.ecr.EcrClient import aws.sdk.kotlin.services.ecr.model.CreateRepositoryRequest import aws.sdk.kotlin.services.ecr.model.DeleteRepositoryRequest import aws.sdk.kotlin.services.ecr.model.DescribeImagesRequest import aws.sdk.kotlin.services.ecr.model.DescribeRepositoriesRequest import aws.sdk.kotlin.services.ecr.model.EcrException import aws.sdk.kotlin.services.ecr.model.GetRepositoryPolicyRequest import aws.sdk.kotlin.services.ecr.model.ImageIdentifier import aws.sdk.kotlin.services.ecr.model.RepositoryAlreadyExistsException import aws.sdk.kotlin.services.ecr.model.SetRepositoryPolicyRequest import aws.sdk.kotlin.services.ecr.model.StartLifecyclePolicyPreviewRequest import com.github.dockerjava.api.DockerClient import com.github.dockerjava.api.command.DockerCmdExecFactory import com.github.dockerjava.api.model.AuthConfig import com.github.dockerjava.core.DockerClientBuilder import com.github.dockerjava.netty.NettyDockerCmdExecFactory import java.io.IOException import java.util.Base64 class ECRActions { private var dockerClient: DockerClient? = null private fun getDockerClient(): DockerClient? { val osName = System.getProperty("os.name") if (osName.startsWith("Windows")) { // Make sure Docker Desktop is running. val dockerHost = "tcp://localhost:2375" // Use the Docker Desktop default port. val dockerCmdExecFactory: DockerCmdExecFactory = NettyDockerCmdExecFactory().withReadTimeout(20000).withConnectTimeout(20000) dockerClient = DockerClientBuilder.getInstance(dockerHost).withDockerCmdExecFactory(dockerCmdExecFactory).build() } else { dockerClient = DockerClientBuilder.getInstance().build() } return dockerClient } /** * Sets the lifecycle policy for the specified repository. * * @param repoName the name of the repository for which to set the lifecycle policy. */ suspend fun setLifeCyclePolicy(repoName: String): String? { val polText = """ { "rules": [ { "rulePriority": 1, "description": "Expire images older than 14 days", "selection": { "tagStatus": "any", "countType": "sinceImagePushed", "countUnit": "days", "countNumber": 14 }, "action": { "type": "expire" } } ] } """.trimIndent() val lifecyclePolicyPreviewRequest = StartLifecyclePolicyPreviewRequest { lifecyclePolicyText = polText repositoryName = repoName } // Execute the request asynchronously. EcrClient { region = "us-east-1" }.use { ecrClient -> val response = ecrClient.startLifecyclePolicyPreview(lifecyclePolicyPreviewRequest) return response.lifecyclePolicyText } } /** * Retrieves the repository URI for the specified repository name. * * @param repoName the name of the repository to retrieve the URI for. * @return the repository URI for the specified repository name. */ suspend fun getRepositoryURI(repoName: String?): String? { require(!(repoName == null || repoName.isEmpty())) { "Repository name cannot be null or empty" } val request = DescribeRepositoriesRequest { repositoryNames = listOf(repoName) } EcrClient { region = "us-east-1" }.use { ecrClient -> val describeRepositoriesResponse = ecrClient.describeRepositories(request) if (!describeRepositoriesResponse.repositories?.isEmpty()!!) { return describeRepositoriesResponse?.repositories?.get(0)?.repositoryUri } else { println("No repositories found for the given name.") return "" } } } /** * Retrieves the authorization token for Amazon Elastic Container Registry (ECR). * */ suspend fun getAuthToken() { EcrClient { region = "us-east-1" }.use { ecrClient -> // Retrieve the authorization token for ECR. val response = ecrClient.getAuthorizationToken() val authorizationData = response.authorizationData?.get(0) val token = authorizationData?.authorizationToken if (token != null) { println("The token was successfully retrieved.") } } } /** * Gets the repository policy for the specified repository. * * @param repoName the name of the repository. */ suspend fun getRepoPolicy(repoName: String?): String? { require(!(repoName == null || repoName.isEmpty())) { "Repository name cannot be null or empty" } // Create the request val getRepositoryPolicyRequest = GetRepositoryPolicyRequest { repositoryName = repoName } EcrClient { region = "us-east-1" }.use { ecrClient -> val response = ecrClient.getRepositoryPolicy(getRepositoryPolicyRequest) val responseText = response.policyText return responseText } } /** * Sets the repository policy for the specified ECR repository. * * @param repoName the name of the ECR repository. * @param iamRole the IAM role to be granted access to the repository. */ suspend fun setRepoPolicy( repoName: String?, iamRole: String?, ) { val policyDocumentTemplate = """ { "Version" : "2012-10-17", "Statement" : [ { "Sid" : "new statement", "Effect" : "Allow", "Principal" : { "AWS" : "$iamRole" }, "Action" : "ecr:BatchGetImage" } ] } """.trimIndent() val setRepositoryPolicyRequest = SetRepositoryPolicyRequest { repositoryName = repoName policyText = policyDocumentTemplate } EcrClient { region = "us-east-1" }.use { ecrClient -> val response = ecrClient.setRepositoryPolicy(setRepositoryPolicyRequest) if (response != null) { println("Repository policy set successfully.") } } } /** * Creates an Amazon Elastic Container Registry (Amazon ECR) repository. * * @param repoName the name of the repository to create. * @return the Amazon Resource Name (ARN) of the created repository, or an empty string if the operation failed. * @throws RepositoryAlreadyExistsException if the repository exists. * @throws EcrException if an error occurs while creating the repository. */ suspend fun createECRRepository(repoName: String?): String? { val request = CreateRepositoryRequest { repositoryName = repoName } return try { EcrClient { region = "us-east-1" }.use { ecrClient -> val response = ecrClient.createRepository(request) response.repository?.repositoryArn } } catch (e: RepositoryAlreadyExistsException) { println("Repository already exists: $repoName") repoName?.let { getRepoARN(it) } } catch (e: EcrException) { println("An error occurred: ${e.message}") null } } suspend fun getRepoARN(repoName: String): String? { // Fetch the existing repository's ARN. val describeRequest = DescribeRepositoriesRequest { repositoryNames = listOf(repoName) } EcrClient { region = "us-east-1" }.use { ecrClient -> val describeResponse = ecrClient.describeRepositories(describeRequest) return describeResponse.repositories?.get(0)?.repositoryArn } } fun listLocalImages(): Boolean = try { val images = getDockerClient()?.listImagesCmd()?.exec() images?.any { image -> image.repoTags?.any { tag -> tag.startsWith("echo-text") } ?: false } ?: false } catch (ex: Exception) { println("ERROR: ${ex.message}") false } /** * Pushes a Docker image to an Amazon Elastic Container Registry (ECR) repository. * * @param repoName the name of the ECR repository to push the image to. * @param imageName the name of the Docker image. */ suspend fun pushDockerImage( repoName: String, imageName: String, ) { println("Pushing $imageName to $repoName will take a few seconds") val authConfig = getAuthConfig(repoName) EcrClient { region = "us-east-1" }.use { ecrClient -> val desRequest = DescribeRepositoriesRequest { repositoryNames = listOf(repoName) } val describeRepoResponse = ecrClient.describeRepositories(desRequest) val repoData = describeRepoResponse.repositories?.firstOrNull { it.repositoryName == repoName } ?: throw RuntimeException("Repository not found: $repoName") val tagImageCmd = getDockerClient()?.tagImageCmd("$imageName", "${repoData.repositoryUri}", imageName) if (tagImageCmd != null) { tagImageCmd.exec() } val pushImageCmd = repoData.repositoryUri?.let { dockerClient?.pushImageCmd(it) // ?.withTag("latest") ?.withAuthConfig(authConfig) } try { if (pushImageCmd != null) { pushImageCmd.start().awaitCompletion() } println("The $imageName was pushed to Amazon ECR") } catch (e: IOException) { throw RuntimeException(e) } } } /** * Verifies the existence of an image in an Amazon Elastic Container Registry (Amazon ECR) repository asynchronously. * * @param repositoryName The name of the Amazon ECR repository. * @param imageTag The tag of the image to verify. */ suspend fun verifyImage( repoName: String?, imageTagVal: String?, ) { require(!(repoName == null || repoName.isEmpty())) { "Repository name cannot be null or empty" } require(!(imageTagVal == null || imageTagVal.isEmpty())) { "Image tag cannot be null or empty" } val imageId = ImageIdentifier { imageTag = imageTagVal } val request = DescribeImagesRequest { repositoryName = repoName imageIds = listOf(imageId) } EcrClient { region = "us-east-1" }.use { ecrClient -> val describeImagesResponse = ecrClient.describeImages(request) if (describeImagesResponse != null && !describeImagesResponse.imageDetails?.isEmpty()!!) { println("Image is present in the repository.") } else { println("Image is not present in the repository.") } } } /** * Deletes an ECR (Elastic Container Registry) repository. * * @param repoName the name of the repository to delete. */ suspend fun deleteECRRepository(repoName: String) { if (repoName.isNullOrEmpty()) { throw IllegalArgumentException("Repository name cannot be null or empty") } val repositoryRequest = DeleteRepositoryRequest { force = true repositoryName = repoName } EcrClient { region = "us-east-1" }.use { ecrClient -> ecrClient.deleteRepository(repositoryRequest) println("You have successfully deleted the $repoName repository") } } // Return an AuthConfig. private suspend fun getAuthConfig(repoName: String): AuthConfig { EcrClient { region = "us-east-1" }.use { ecrClient -> // Retrieve the authorization token for ECR. val response = ecrClient.getAuthorizationToken() val authorizationData = response.authorizationData?.get(0) val token = authorizationData?.authorizationToken val decodedToken = String(Base64.getDecoder().decode(token)) val password = decodedToken.substring(4) val request = DescribeRepositoriesRequest { repositoryNames = listOf(repoName) } val descrRepoResponse = ecrClient.describeRepositories(request) val repoData = descrRepoResponse.repositories?.firstOrNull { it.repositoryName == repoName } val registryURL: String = repoData?.repositoryUri?.split("/")?.get(0) ?: "" return AuthConfig() .withUsername("AWS") .withPassword(password) .withRegistryAddress(registryURL) } } }