feat(client-docdb): This release adds Global Cluster Failover capability which enables you to change your global cluster's primary AWS region, the region that serves writes, during a regional outage. Performing a failover action preserves your Global Cluster setup.

awstools · awstools · commit 62c6973ca51b · 2024-08-15T18:16:05.000Z
diff --git a/clients/client-docdb/README.md b/clients/client-docdb/README.md
@@ -492,6 +492,14 @@ FailoverDBCluster
 
 [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/docdb/command/FailoverDBClusterCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/FailoverDBClusterCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/FailoverDBClusterCommandOutput/)
 
+</details>
+<details>
+<summary>
+FailoverGlobalCluster
+</summary>
+
+[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/docdb/command/FailoverGlobalClusterCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/FailoverGlobalClusterCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/FailoverGlobalClusterCommandOutput/)
+
 </details>
 <details>
 <summary>
diff --git a/clients/client-docdb/src/DocDB.ts b/clients/client-docdb/src/DocDB.ts
@@ -182,6 +182,11 @@ import {
   FailoverDBClusterCommandInput,
   FailoverDBClusterCommandOutput,
 } from "./commands/FailoverDBClusterCommand";
+import {
+  FailoverGlobalClusterCommand,
+  FailoverGlobalClusterCommandInput,
+  FailoverGlobalClusterCommandOutput,
+} from "./commands/FailoverGlobalClusterCommand";
 import {
   ListTagsForResourceCommand,
   ListTagsForResourceCommandInput,
@@ -311,6 +316,7 @@ const commands = {
   DescribeOrderableDBInstanceOptionsCommand,
   DescribePendingMaintenanceActionsCommand,
   FailoverDBClusterCommand,
+  FailoverGlobalClusterCommand,
   ListTagsForResourceCommand,
   ModifyDBClusterCommand,
   ModifyDBClusterParameterGroupCommand,
@@ -948,6 +954,23 @@ export interface DocDB {
     cb: (err: any, data?: FailoverDBClusterCommandOutput) => void
   ): void;
 
+  /**
+   * @see {@link FailoverGlobalClusterCommand}
+   */
+  failoverGlobalCluster(
+    args: FailoverGlobalClusterCommandInput,
+    options?: __HttpHandlerOptions
+  ): Promise<FailoverGlobalClusterCommandOutput>;
+  failoverGlobalCluster(
+    args: FailoverGlobalClusterCommandInput,
+    cb: (err: any, data?: FailoverGlobalClusterCommandOutput) => void
+  ): void;
+  failoverGlobalCluster(
+    args: FailoverGlobalClusterCommandInput,
+    options: __HttpHandlerOptions,
+    cb: (err: any, data?: FailoverGlobalClusterCommandOutput) => void
+  ): void;
+
   /**
    * @see {@link ListTagsForResourceCommand}
    */
diff --git a/clients/client-docdb/src/DocDBClient.ts b/clients/client-docdb/src/DocDBClient.ts
@@ -173,6 +173,10 @@ import {
   DescribePendingMaintenanceActionsCommandOutput,
 } from "./commands/DescribePendingMaintenanceActionsCommand";
 import { FailoverDBClusterCommandInput, FailoverDBClusterCommandOutput } from "./commands/FailoverDBClusterCommand";
+import {
+  FailoverGlobalClusterCommandInput,
+  FailoverGlobalClusterCommandOutput,
+} from "./commands/FailoverGlobalClusterCommand";
 import {
   ListTagsForResourceCommandInput,
   ListTagsForResourceCommandOutput,
@@ -281,6 +285,7 @@ export type ServiceInputTypes =
   | DescribeOrderableDBInstanceOptionsCommandInput
   | DescribePendingMaintenanceActionsCommandInput
   | FailoverDBClusterCommandInput
+  | FailoverGlobalClusterCommandInput
   | ListTagsForResourceCommandInput
   | ModifyDBClusterCommandInput
   | ModifyDBClusterParameterGroupCommandInput
@@ -340,6 +345,7 @@ export type ServiceOutputTypes =
   | DescribeOrderableDBInstanceOptionsCommandOutput
   | DescribePendingMaintenanceActionsCommandOutput
   | FailoverDBClusterCommandOutput
+  | FailoverGlobalClusterCommandOutput
   | ListTagsForResourceCommandOutput
   | ModifyDBClusterCommandOutput
   | ModifyDBClusterParameterGroupCommandOutput
diff --git a/clients/client-docdb/src/commands/FailoverGlobalClusterCommand.ts b/clients/client-docdb/src/commands/FailoverGlobalClusterCommand.ts
@@ -0,0 +1,120 @@
+// smithy-typescript generated code
+import { getEndpointPlugin } from "@smithy/middleware-endpoint";
+import { getSerdePlugin } from "@smithy/middleware-serde";
+import { Command as $Command } from "@smithy/smithy-client";
+import { MetadataBearer as __MetadataBearer } from "@smithy/types";
+
+import { DocDBClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../DocDBClient";
+import { commonParams } from "../endpoint/EndpointParameters";
+import { FailoverGlobalClusterMessage, FailoverGlobalClusterResult } from "../models/models_0";
+import { de_FailoverGlobalClusterCommand, se_FailoverGlobalClusterCommand } from "../protocols/Aws_query";
+
+/**
+ * @public
+ */
+export type { __MetadataBearer };
+export { $Command };
+/**
+ * @public
+ *
+ * The input for {@link FailoverGlobalClusterCommand}.
+ */
+export interface FailoverGlobalClusterCommandInput extends FailoverGlobalClusterMessage {}
+/**
+ * @public
+ *
+ * The output of {@link FailoverGlobalClusterCommand}.
+ */
+export interface FailoverGlobalClusterCommandOutput extends FailoverGlobalClusterResult, __MetadataBearer {}
+
+/**
+ * <p>Promotes the specified secondary DB cluster to be the primary DB cluster in the global cluster when failing over a global cluster occurs.</p>
+ *          <p>Use this operation to respond to an unplanned event, such as a regional disaster in the primary region.
+ *             Failing over can result in a loss of write transaction data that wasn't replicated to the chosen secondary before the failover event occurred.
+ *             However, the recovery process that promotes a DB instance on the chosen seconday DB cluster to be the primary writer DB instance guarantees that the data is in a transactionally consistent state.</p>
+ * @example
+ * Use a bare-bones client and the command you need to make an API call.
+ * ```javascript
+ * import { DocDBClient, FailoverGlobalClusterCommand } from "@aws-sdk/client-docdb"; // ES Modules import
+ * // const { DocDBClient, FailoverGlobalClusterCommand } = require("@aws-sdk/client-docdb"); // CommonJS import
+ * const client = new DocDBClient(config);
+ * const input = { // FailoverGlobalClusterMessage
+ *   GlobalClusterIdentifier: "STRING_VALUE", // required
+ *   TargetDbClusterIdentifier: "STRING_VALUE", // required
+ *   AllowDataLoss: true || false,
+ *   Switchover: true || false,
+ * };
+ * const command = new FailoverGlobalClusterCommand(input);
+ * const response = await client.send(command);
+ * // { // FailoverGlobalClusterResult
+ * //   GlobalCluster: { // GlobalCluster
+ * //     GlobalClusterIdentifier: "STRING_VALUE",
+ * //     GlobalClusterResourceId: "STRING_VALUE",
+ * //     GlobalClusterArn: "STRING_VALUE",
+ * //     Status: "STRING_VALUE",
+ * //     Engine: "STRING_VALUE",
+ * //     EngineVersion: "STRING_VALUE",
+ * //     DatabaseName: "STRING_VALUE",
+ * //     StorageEncrypted: true || false,
+ * //     DeletionProtection: true || false,
+ * //     GlobalClusterMembers: [ // GlobalClusterMemberList
+ * //       { // GlobalClusterMember
+ * //         DBClusterArn: "STRING_VALUE",
+ * //         Readers: [ // ReadersArnList
+ * //           "STRING_VALUE",
+ * //         ],
+ * //         IsWriter: true || false,
+ * //       },
+ * //     ],
+ * //   },
+ * // };
+ *
+ * ```
+ *
+ * @param FailoverGlobalClusterCommandInput - {@link FailoverGlobalClusterCommandInput}
+ * @returns {@link FailoverGlobalClusterCommandOutput}
+ * @see {@link FailoverGlobalClusterCommandInput} for command's `input` shape.
+ * @see {@link FailoverGlobalClusterCommandOutput} for command's `response` shape.
+ * @see {@link DocDBClientResolvedConfig | config} for DocDBClient's `config` shape.
+ *
+ * @throws {@link DBClusterNotFoundFault} (client fault)
+ *  <p>
+ *             <code>DBClusterIdentifier</code> doesn't refer to an existing cluster. </p>
+ *
+ * @throws {@link GlobalClusterNotFoundFault} (client fault)
+ *  <p>The <code>GlobalClusterIdentifier</code> doesn't refer to an existing global cluster.</p>
+ *
+ * @throws {@link InvalidDBClusterStateFault} (client fault)
+ *  <p>The cluster isn't in a valid state.</p>
+ *
+ * @throws {@link InvalidGlobalClusterStateFault} (client fault)
+ *  <p>The requested operation can't be performed while the cluster is in this state.</p>
+ *
+ * @throws {@link DocDBServiceException}
+ * <p>Base exception class for all service exceptions from DocDB service.</p>
+ *
+ * @public
+ */
+export class FailoverGlobalClusterCommand extends $Command
+  .classBuilder<
+    FailoverGlobalClusterCommandInput,
+    FailoverGlobalClusterCommandOutput,
+    DocDBClientResolvedConfig,
+    ServiceInputTypes,
+    ServiceOutputTypes
+  >()
+  .ep({
+    ...commonParams,
+  })
+  .m(function (this: any, Command: any, cs: any, config: DocDBClientResolvedConfig, o: any) {
+    return [
+      getSerdePlugin(config, this.serialize, this.deserialize),
+      getEndpointPlugin(config, Command.getEndpointParameterInstructions()),
+    ];
+  })
+  .s("AmazonRDSv19", "FailoverGlobalCluster", {})
+  .n("DocDBClient", "FailoverGlobalClusterCommand")
+  .f(void 0, void 0)
+  .ser(se_FailoverGlobalClusterCommand)
+  .de(de_FailoverGlobalClusterCommand)
+  .build() {}
diff --git a/clients/client-docdb/src/commands/index.ts b/clients/client-docdb/src/commands/index.ts
@@ -35,6 +35,7 @@ export * from "./DescribeGlobalClustersCommand";
 export * from "./DescribeOrderableDBInstanceOptionsCommand";
 export * from "./DescribePendingMaintenanceActionsCommand";
 export * from "./FailoverDBClusterCommand";
+export * from "./FailoverGlobalClusterCommand";
 export * from "./ListTagsForResourceCommand";
 export * from "./ModifyDBClusterCommand";
 export * from "./ModifyDBClusterParameterGroupCommand";
diff --git a/clients/client-docdb/src/models/models_0.ts b/clients/client-docdb/src/models/models_0.ts
@@ -5041,6 +5041,84 @@ export interface FailoverDBClusterResult {
   DBCluster?: DBCluster;
 }
 
+/**
+ * @public
+ */
+export interface FailoverGlobalClusterMessage {
+  /**
+   * <p>The identifier of the Amazon DocumentDB global cluster to apply this operation.
+   *             The identifier is the unique key assigned by the user when the cluster is created.
+   *             In other words, it's the name of the global cluster.</p>
+   *          <p>Constraints:</p>
+   *          <ul>
+   *             <li>
+   *                <p>Must match the identifier of an existing global cluster.</p>
+   *             </li>
+   *             <li>
+   *                <p>Minimum length of 1. Maximum length of 255.</p>
+   *             </li>
+   *          </ul>
+   *          <p>Pattern: <code>[A-Za-z][0-9A-Za-z-:._]*</code>
+   *          </p>
+   * @public
+   */
+  GlobalClusterIdentifier: string | undefined;
+
+  /**
+   * <p>The identifier of the secondary Amazon DocumentDB cluster that you want to promote to the primary for the global cluster.
+   *             Use the Amazon Resource Name (ARN) for the identifier so that Amazon DocumentDB can locate the cluster in its Amazon Web Services region.</p>
+   *          <p>Constraints:</p>
+   *          <ul>
+   *             <li>
+   *                <p>Must match the identifier of an existing secondary cluster.</p>
+   *             </li>
+   *             <li>
+   *                <p>Minimum length of 1. Maximum length of 255.</p>
+   *             </li>
+   *          </ul>
+   *          <p>Pattern: <code>[A-Za-z][0-9A-Za-z-:._]*</code>
+   *          </p>
+   * @public
+   */
+  TargetDbClusterIdentifier: string | undefined;
+
+  /**
+   * <p>Specifies whether to allow data loss for this global cluster operation. Allowing data loss triggers a global failover operation.</p>
+   *          <p>If you don't specify <code>AllowDataLoss</code>, the global cluster operation defaults to a switchover.</p>
+   *          <p>Constraints:</p>
+   *          <ul>
+   *             <li>
+   *                <p>Can't be specified together with the <code>Switchover</code> parameter.</p>
+   *             </li>
+   *          </ul>
+   * @public
+   */
+  AllowDataLoss?: boolean;
+
+  /**
+   * <p>Specifies whether to switch over this global database cluster.</p>
+   *          <p>Constraints:</p>
+   *          <ul>
+   *             <li>
+   *                <p>Can't be specified together with the <code>AllowDataLoss</code> parameter.</p>
+   *             </li>
+   *          </ul>
+   * @public
+   */
+  Switchover?: boolean;
+}
+
+/**
+ * @public
+ */
+export interface FailoverGlobalClusterResult {
+  /**
+   * <p>A data type representing an Amazon DocumentDB global cluster.</p>
+   * @public
+   */
+  GlobalCluster?: GlobalCluster;
+}
+
 /**
  * <p>Represents the input to <a>ListTagsForResource</a>.</p>
  * @public
diff --git a/clients/client-docdb/src/protocols/Aws_query.ts b/clients/client-docdb/src/protocols/Aws_query.ts
diff --git a/codegen/sdk-codegen/aws-models/docdb.json b/codegen/sdk-codegen/aws-models/docdb.json
