feat(client-ecr): Documentation and operational updates for Amazon ECR, adding support for pull through cache rules for upstream registries that require authentication.

Author: awstools

clients/client-ecr/README.md

@@ -531,6 +531,14 @@ UntagResource
 
 [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/classes/untagresourcecommand.html) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/interfaces/untagresourcecommandinput.html) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/interfaces/untagresourcecommandoutput.html)
 
+</details>
+<details>
+<summary>
+UpdatePullThroughCacheRule
+</summary>
+
+[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/classes/updatepullthroughcacherulecommand.html) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/interfaces/updatepullthroughcacherulecommandinput.html) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/interfaces/updatepullthroughcacherulecommandoutput.html)
+
 </details>
 <details>
 <summary>
@@ -540,3 +548,11 @@ UploadLayerPart
 [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/classes/uploadlayerpartcommand.html) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/interfaces/uploadlayerpartcommandinput.html) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/interfaces/uploadlayerpartcommandoutput.html)
 
 </details>
+<details>
+<summary>
+ValidatePullThroughCacheRule
+</summary>
+
+[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/classes/validatepullthroughcacherulecommand.html) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/interfaces/validatepullthroughcacherulecommandinput.html) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ecr/interfaces/validatepullthroughcacherulecommandoutput.html)
+
+</details>

clients/client-ecr/src/ECR.ts

@@ -190,11 +190,21 @@ import {
   UntagResourceCommandInput,
   UntagResourceCommandOutput,
 } from "./commands/UntagResourceCommand";
+import {
+  UpdatePullThroughCacheRuleCommand,
+  UpdatePullThroughCacheRuleCommandInput,
+  UpdatePullThroughCacheRuleCommandOutput,
+} from "./commands/UpdatePullThroughCacheRuleCommand";
 import {
   UploadLayerPartCommand,
   UploadLayerPartCommandInput,
   UploadLayerPartCommandOutput,
 } from "./commands/UploadLayerPartCommand";
+import {
+  ValidatePullThroughCacheRuleCommand,
+  ValidatePullThroughCacheRuleCommandInput,
+  ValidatePullThroughCacheRuleCommandOutput,
+} from "./commands/ValidatePullThroughCacheRuleCommand";
 import { ECRClient, ECRClientConfig } from "./ECRClient";
 
 const commands = {
@@ -238,7 +248,9 @@ const commands = {
   StartLifecyclePolicyPreviewCommand,
   TagResourceCommand,
   UntagResourceCommand,
+  UpdatePullThroughCacheRuleCommand,
   UploadLayerPartCommand,
+  ValidatePullThroughCacheRuleCommand,
 };
 
 export interface ECR {
@@ -886,6 +898,23 @@ export interface ECR {
     cb: (err: any, data?: UntagResourceCommandOutput) => void
   ): void;
 
+  /**
+   * @see {@link UpdatePullThroughCacheRuleCommand}
+   */
+  updatePullThroughCacheRule(
+    args: UpdatePullThroughCacheRuleCommandInput,
+    options?: __HttpHandlerOptions
+  ): Promise<UpdatePullThroughCacheRuleCommandOutput>;
+  updatePullThroughCacheRule(
+    args: UpdatePullThroughCacheRuleCommandInput,
+    cb: (err: any, data?: UpdatePullThroughCacheRuleCommandOutput) => void
+  ): void;
+  updatePullThroughCacheRule(
+    args: UpdatePullThroughCacheRuleCommandInput,
+    options: __HttpHandlerOptions,
+    cb: (err: any, data?: UpdatePullThroughCacheRuleCommandOutput) => void
+  ): void;
+
   /**
    * @see {@link UploadLayerPartCommand}
    */
@@ -899,6 +928,23 @@ export interface ECR {
     options: __HttpHandlerOptions,
     cb: (err: any, data?: UploadLayerPartCommandOutput) => void
   ): void;
+
+  /**
+   * @see {@link ValidatePullThroughCacheRuleCommand}
+   */
+  validatePullThroughCacheRule(
+    args: ValidatePullThroughCacheRuleCommandInput,
+    options?: __HttpHandlerOptions
+  ): Promise<ValidatePullThroughCacheRuleCommandOutput>;
+  validatePullThroughCacheRule(
+    args: ValidatePullThroughCacheRuleCommandInput,
+    cb: (err: any, data?: ValidatePullThroughCacheRuleCommandOutput) => void
+  ): void;
+  validatePullThroughCacheRule(
+    args: ValidatePullThroughCacheRuleCommandInput,
+    options: __HttpHandlerOptions,
+    cb: (err: any, data?: ValidatePullThroughCacheRuleCommandOutput) => void
+  ): void;
 }
 
 /**

clients/client-ecr/src/ECRClient.ts

@@ -165,7 +165,15 @@ import {
 } from "./commands/StartLifecyclePolicyPreviewCommand";
 import { TagResourceCommandInput, TagResourceCommandOutput } from "./commands/TagResourceCommand";
 import { UntagResourceCommandInput, UntagResourceCommandOutput } from "./commands/UntagResourceCommand";
+import {
+  UpdatePullThroughCacheRuleCommandInput,
+  UpdatePullThroughCacheRuleCommandOutput,
+} from "./commands/UpdatePullThroughCacheRuleCommand";
 import { UploadLayerPartCommandInput, UploadLayerPartCommandOutput } from "./commands/UploadLayerPartCommand";
+import {
+  ValidatePullThroughCacheRuleCommandInput,
+  ValidatePullThroughCacheRuleCommandOutput,
+} from "./commands/ValidatePullThroughCacheRuleCommand";
 import {
   ClientInputEndpointParameters,
   ClientResolvedEndpointParameters,
@@ -221,7 +229,9 @@ export type ServiceInputTypes =
   | StartLifecyclePolicyPreviewCommandInput
   | TagResourceCommandInput
   | UntagResourceCommandInput
-  | UploadLayerPartCommandInput;
+  | UpdatePullThroughCacheRuleCommandInput
+  | UploadLayerPartCommandInput
+  | ValidatePullThroughCacheRuleCommandInput;
 
 /**
  * @public
@@ -267,7 +277,9 @@ export type ServiceOutputTypes =
   | StartLifecyclePolicyPreviewCommandOutput
   | TagResourceCommandOutput
   | UntagResourceCommandOutput
-  | UploadLayerPartCommandOutput;
+  | UpdatePullThroughCacheRuleCommandOutput
+  | UploadLayerPartCommandOutput
+  | ValidatePullThroughCacheRuleCommandOutput;
 
 /**
  * @public

clients/client-ecr/src/commands/BatchDeleteImageCommand.ts

@@ -74,7 +74,7 @@ export interface BatchDeleteImageCommandOutput extends BatchDeleteImageResponse,
  * //         imageDigest: "STRING_VALUE",
  * //         imageTag: "STRING_VALUE",
  * //       },
- * //       failureCode: "InvalidImageDigest" || "InvalidImageTag" || "ImageTagDoesNotMatchDigest" || "ImageNotFound" || "MissingDigestAndTag" || "ImageReferencedByManifestList" || "KmsError",
+ * //       failureCode: "InvalidImageDigest" || "InvalidImageTag" || "ImageTagDoesNotMatchDigest" || "ImageNotFound" || "MissingDigestAndTag" || "ImageReferencedByManifestList" || "KmsError" || "UpstreamAccessDenied" || "UpstreamTooManyRequests" || "UpstreamUnavailable",
  * //       failureReason: "STRING_VALUE",
  * //     },
  * //   ],

clients/client-ecr/src/commands/BatchGetImageCommand.ts

@@ -81,7 +81,7 @@ export interface BatchGetImageCommandOutput extends BatchGetImageResponse, __Met
  * //         imageDigest: "STRING_VALUE",
  * //         imageTag: "STRING_VALUE",
  * //       },
- * //       failureCode: "InvalidImageDigest" || "InvalidImageTag" || "ImageTagDoesNotMatchDigest" || "ImageNotFound" || "MissingDigestAndTag" || "ImageReferencedByManifestList" || "KmsError",
+ * //       failureCode: "InvalidImageDigest" || "InvalidImageTag" || "ImageTagDoesNotMatchDigest" || "ImageNotFound" || "MissingDigestAndTag" || "ImageReferencedByManifestList" || "KmsError" || "UpstreamAccessDenied" || "UpstreamTooManyRequests" || "UpstreamUnavailable",
  * //       failureReason: "STRING_VALUE",
  * //     },
  * //   ],
@@ -99,13 +99,23 @@ export interface BatchGetImageCommandOutput extends BatchGetImageResponse, __Met
  *  <p>The specified parameter is invalid. Review the available parameters for the API
  *             request.</p>
  *
+ * @throws {@link LimitExceededException} (client fault)
+ *  <p>The operation did not succeed because it would have exceeded a service limit for your
+ *             account. For more information, see <a href="https://docs.aws.amazon.com/AmazonECR/latest/userguide/service-quotas.html">Amazon ECR service quotas</a> in
+ *             the Amazon Elastic Container Registry User Guide.</p>
+ *
  * @throws {@link RepositoryNotFoundException} (client fault)
  *  <p>The specified repository could not be found. Check the spelling of the specified
  *             repository and ensure that you are performing operations on the correct registry.</p>
  *
  * @throws {@link ServerException} (server fault)
  *  <p>These errors are usually caused by a server-side issue.</p>
  *
+ * @throws {@link UnableToGetUpstreamImageException} (client fault)
+ *  <p>The image or images were unable to be pulled using the pull through cache rule. This
+ *             is usually caused because of an issue with the Secrets Manager secret containing the credentials
+ *             for the upstream registry.</p>
+ *
  * @throws {@link ECRServiceException}
  * <p>Base exception class for all service exceptions from ECR service.</p>
  *

clients/client-ecr/src/commands/CreatePullThroughCacheRuleCommand.ts

@@ -38,7 +38,9 @@ export interface CreatePullThroughCacheRuleCommandOutput extends CreatePullThrou
 /**
  * @public
  * <p>Creates a pull through cache rule. A pull through cache rule provides a way to cache
- *             images from an external public registry in your Amazon ECR private registry.</p>
+ *             images from an upstream registry source in your Amazon ECR private registry. For more
+ *             information, see <a href="https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache.html">Using pull through cache
+ *                 rules</a> in the <i>Amazon Elastic Container Registry User Guide</i>.</p>
  * @example
  * Use a bare-bones client and the command you need to make an API call.
  * ```javascript
@@ -49,6 +51,8 @@ export interface CreatePullThroughCacheRuleCommandOutput extends CreatePullThrou
  *   ecrRepositoryPrefix: "STRING_VALUE", // required
  *   upstreamRegistryUrl: "STRING_VALUE", // required
  *   registryId: "STRING_VALUE",
+ *   upstreamRegistry: "ecr-public" || "quay" || "k8s" || "docker-hub" || "github-container-registry" || "azure-container-registry",
+ *   credentialArn: "STRING_VALUE",
  * };
  * const command = new CreatePullThroughCacheRuleCommand(input);
  * const response = await client.send(command);
@@ -57,6 +61,8 @@ export interface CreatePullThroughCacheRuleCommandOutput extends CreatePullThrou
  * //   upstreamRegistryUrl: "STRING_VALUE",
  * //   createdAt: new Date("TIMESTAMP"),
  * //   registryId: "STRING_VALUE",
+ * //   upstreamRegistry: "ecr-public" || "quay" || "k8s" || "docker-hub" || "github-container-registry" || "azure-container-registry",
+ * //   credentialArn: "STRING_VALUE",
  * // };
  *
  * ```
@@ -80,9 +86,21 @@ export interface CreatePullThroughCacheRuleCommandOutput extends CreatePullThrou
  *  <p>A pull through cache rule with these settings already exists for the private
  *             registry.</p>
  *
+ * @throws {@link SecretNotFoundException} (client fault)
+ *  <p>The ARN of the secret specified in the pull through cache rule was not found. Update
+ *             the pull through cache rule with a valid secret ARN and try again.</p>
+ *
  * @throws {@link ServerException} (server fault)
  *  <p>These errors are usually caused by a server-side issue.</p>
  *
+ * @throws {@link UnableToAccessSecretException} (client fault)
+ *  <p>The secret is unable to be accessed. Verify the resource permissions for the secret
+ *             and try again.</p>
+ *
+ * @throws {@link UnableToDecryptSecretValueException} (client fault)
+ *  <p>The secret is accessible but is unable to be decrypted. Verify the resource
+ *             permisisons and try again.</p>
+ *
  * @throws {@link UnsupportedUpstreamRegistryException} (client fault)
  *  <p>The specified upstream registry isn't supported.</p>
  *

clients/client-ecr/src/commands/DeletePullThroughCacheRuleCommand.ts

@@ -55,6 +55,7 @@ export interface DeletePullThroughCacheRuleCommandOutput extends DeletePullThrou
  * //   upstreamRegistryUrl: "STRING_VALUE",
  * //   createdAt: new Date("TIMESTAMP"),
  * //   registryId: "STRING_VALUE",
+ * //   credentialArn: "STRING_VALUE",
  * // };
  *
  * ```

clients/client-ecr/src/commands/DeleteRepositoryCommand.ts

@@ -37,9 +37,9 @@ export interface DeleteRepositoryCommandOutput extends DeleteRepositoryResponse,
 
 /**
  * @public
- * <p>Deletes a repository. If the repository contains images, you must either delete all
- *             images in the repository or use the <code>force</code> option to delete the
- *             repository.</p>
+ * <p>Deletes a repository. If the repository isn't empty, you must either delete the
+ *             contents of the repository or use the <code>force</code> option to delete the repository
+ *             and have Amazon ECR delete all of its contents on your behalf.</p>
  * @example
  * Use a bare-bones client and the command you need to make an API call.
  * ```javascript

clients/client-ecr/src/commands/DescribePullThroughCacheRulesCommand.ts

@@ -66,6 +66,9 @@ export interface DescribePullThroughCacheRulesCommandOutput
  * //       upstreamRegistryUrl: "STRING_VALUE",
  * //       createdAt: new Date("TIMESTAMP"),
  * //       registryId: "STRING_VALUE",
+ * //       credentialArn: "STRING_VALUE",
+ * //       upstreamRegistry: "ecr-public" || "quay" || "k8s" || "docker-hub" || "github-container-registry" || "azure-container-registry",
+ * //       updatedAt: new Date("TIMESTAMP"),
  * //     },
  * //   ],
  * //   nextToken: "STRING_VALUE",

clients/client-ecr/src/commands/GetDownloadUrlForLayerCommand.ts

@@ -90,6 +90,10 @@ export interface GetDownloadUrlForLayerCommandOutput extends GetDownloadUrlForLa
  * @throws {@link ServerException} (server fault)
  *  <p>These errors are usually caused by a server-side issue.</p>
  *
+ * @throws {@link UnableToGetUpstreamLayerException} (client fault)
+ *  <p>There was an issue getting the upstream layer matching the pull through cache
+ *             rule.</p>
+ *
  * @throws {@link ECRServiceException}
  * <p>Base exception class for all service exceptions from ECR service.</p>
  *