From b7817fd7f6319cbf25bd0747dbbc6eff9c1e2caf Mon Sep 17 00:00:00 2001 From: awstools Date: Wed, 3 Apr 2024 18:16:21 +0000 Subject: [PATCH] feat(client-docdb): This release adds Global Cluster Switchover capability which enables you to change your global cluster's primary AWS Region, the region that serves writes, while preserving the replication between all regions in the global cluster. --- clients/client-docdb/README.md | 8 ++ clients/client-docdb/src/DocDB.ts | 23 ++++ clients/client-docdb/src/DocDBClient.ts | 10 +- .../SwitchoverGlobalClusterCommand.ts | 114 ++++++++++++++++++ clients/client-docdb/src/commands/index.ts | 1 + clients/client-docdb/src/models/models_0.ts | 54 +++++++++ .../client-docdb/src/protocols/Aws_query.ts | 70 +++++++++++ codegen/sdk-codegen/aws-models/docdb.json | 64 ++++++++++ 8 files changed, 342 insertions(+), 2 deletions(-) create mode 100644 clients/client-docdb/src/commands/SwitchoverGlobalClusterCommand.ts diff --git a/clients/client-docdb/README.md b/clients/client-docdb/README.md index 0d5eeca2c55f..316906de7d3f 100644 --- a/clients/client-docdb/README.md +++ b/clients/client-docdb/README.md @@ -629,3 +629,11 @@ StopDBCluster [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/docdb/command/StopDBClusterCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/StopDBClusterCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/StopDBClusterCommandOutput/) +
+ +SwitchoverGlobalCluster + + +[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/docdb/command/SwitchoverGlobalClusterCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/SwitchoverGlobalClusterCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/SwitchoverGlobalClusterCommandOutput/) + +
diff --git a/clients/client-docdb/src/DocDB.ts b/clients/client-docdb/src/DocDB.ts index f9d40cc0814f..da859b0142ed 100644 --- a/clients/client-docdb/src/DocDB.ts +++ b/clients/client-docdb/src/DocDB.ts @@ -267,6 +267,11 @@ import { StopDBClusterCommandInput, StopDBClusterCommandOutput, } from "./commands/StopDBClusterCommand"; +import { + SwitchoverGlobalClusterCommand, + SwitchoverGlobalClusterCommandInput, + SwitchoverGlobalClusterCommandOutput, +} from "./commands/SwitchoverGlobalClusterCommand"; import { DocDBClient, DocDBClientConfig } from "./DocDBClient"; const commands = { @@ -323,6 +328,7 @@ const commands = { RestoreDBClusterToPointInTimeCommand, StartDBClusterCommand, StopDBClusterCommand, + SwitchoverGlobalClusterCommand, }; export interface DocDB { @@ -1218,6 +1224,23 @@ export interface DocDB { options: __HttpHandlerOptions, cb: (err: any, data?: StopDBClusterCommandOutput) => void ): void; + + /** + * @see {@link SwitchoverGlobalClusterCommand} + */ + switchoverGlobalCluster( + args: SwitchoverGlobalClusterCommandInput, + options?: __HttpHandlerOptions + ): Promise; + switchoverGlobalCluster( + args: SwitchoverGlobalClusterCommandInput, + cb: (err: any, data?: SwitchoverGlobalClusterCommandOutput) => void + ): void; + switchoverGlobalCluster( + args: SwitchoverGlobalClusterCommandInput, + options: __HttpHandlerOptions, + cb: (err: any, data?: SwitchoverGlobalClusterCommandOutput) => void + ): void; } /** diff --git a/clients/client-docdb/src/DocDBClient.ts b/clients/client-docdb/src/DocDBClient.ts index 6ed3b5d70afa..28371a41dd2f 100644 --- a/clients/client-docdb/src/DocDBClient.ts +++ b/clients/client-docdb/src/DocDBClient.ts @@ -226,6 +226,10 @@ import { } from "./commands/RestoreDBClusterToPointInTimeCommand"; import { StartDBClusterCommandInput, StartDBClusterCommandOutput } from "./commands/StartDBClusterCommand"; import { StopDBClusterCommandInput, StopDBClusterCommandOutput } from "./commands/StopDBClusterCommand"; +import { + SwitchoverGlobalClusterCommandInput, + SwitchoverGlobalClusterCommandOutput, +} from "./commands/SwitchoverGlobalClusterCommand"; import { ClientInputEndpointParameters, ClientResolvedEndpointParameters, @@ -293,7 +297,8 @@ export type ServiceInputTypes = | RestoreDBClusterFromSnapshotCommandInput | RestoreDBClusterToPointInTimeCommandInput | StartDBClusterCommandInput - | StopDBClusterCommandInput; + | StopDBClusterCommandInput + | SwitchoverGlobalClusterCommandInput; /** * @public @@ -351,7 +356,8 @@ export type ServiceOutputTypes = | RestoreDBClusterFromSnapshotCommandOutput | RestoreDBClusterToPointInTimeCommandOutput | StartDBClusterCommandOutput - | StopDBClusterCommandOutput; + | StopDBClusterCommandOutput + | SwitchoverGlobalClusterCommandOutput; /** * @public diff --git a/clients/client-docdb/src/commands/SwitchoverGlobalClusterCommand.ts b/clients/client-docdb/src/commands/SwitchoverGlobalClusterCommand.ts new file mode 100644 index 000000000000..bdecb96e7e17 --- /dev/null +++ b/clients/client-docdb/src/commands/SwitchoverGlobalClusterCommand.ts @@ -0,0 +1,114 @@ +// 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 { SwitchoverGlobalClusterMessage, SwitchoverGlobalClusterResult } from "../models/models_0"; +import { de_SwitchoverGlobalClusterCommand, se_SwitchoverGlobalClusterCommand } from "../protocols/Aws_query"; + +/** + * @public + */ +export { __MetadataBearer, $Command }; +/** + * @public + * + * The input for {@link SwitchoverGlobalClusterCommand}. + */ +export interface SwitchoverGlobalClusterCommandInput extends SwitchoverGlobalClusterMessage {} +/** + * @public + * + * The output of {@link SwitchoverGlobalClusterCommand}. + */ +export interface SwitchoverGlobalClusterCommandOutput extends SwitchoverGlobalClusterResult, __MetadataBearer {} + +/** + *

Switches over the specified secondary Amazon DocumentDB cluster to be the new primary Amazon DocumentDB cluster in the global database cluster.

+ * @example + * Use a bare-bones client and the command you need to make an API call. + * ```javascript + * import { DocDBClient, SwitchoverGlobalClusterCommand } from "@aws-sdk/client-docdb"; // ES Modules import + * // const { DocDBClient, SwitchoverGlobalClusterCommand } = require("@aws-sdk/client-docdb"); // CommonJS import + * const client = new DocDBClient(config); + * const input = { // SwitchoverGlobalClusterMessage + * GlobalClusterIdentifier: "STRING_VALUE", // required + * TargetDbClusterIdentifier: "STRING_VALUE", // required + * }; + * const command = new SwitchoverGlobalClusterCommand(input); + * const response = await client.send(command); + * // { // SwitchoverGlobalClusterResult + * // 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 SwitchoverGlobalClusterCommandInput - {@link SwitchoverGlobalClusterCommandInput} + * @returns {@link SwitchoverGlobalClusterCommandOutput} + * @see {@link SwitchoverGlobalClusterCommandInput} for command's `input` shape. + * @see {@link SwitchoverGlobalClusterCommandOutput} for command's `response` shape. + * @see {@link DocDBClientResolvedConfig | config} for DocDBClient's `config` shape. + * + * @throws {@link DBClusterNotFoundFault} (client fault) + *

+ * DBClusterIdentifier doesn't refer to an existing cluster.

+ * + * @throws {@link GlobalClusterNotFoundFault} (client fault) + *

The GlobalClusterIdentifier doesn't refer to an existing global cluster.

+ * + * @throws {@link InvalidDBClusterStateFault} (client fault) + *

The cluster isn't in a valid state.

+ * + * @throws {@link InvalidGlobalClusterStateFault} (client fault) + *

The requested operation can't be performed while the cluster is in this state.

+ * + * @throws {@link DocDBServiceException} + *

Base exception class for all service exceptions from DocDB service.

+ * + * @public + */ +export class SwitchoverGlobalClusterCommand extends $Command + .classBuilder< + SwitchoverGlobalClusterCommandInput, + SwitchoverGlobalClusterCommandOutput, + 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", "SwitchoverGlobalCluster", {}) + .n("DocDBClient", "SwitchoverGlobalClusterCommand") + .f(void 0, void 0) + .ser(se_SwitchoverGlobalClusterCommand) + .de(de_SwitchoverGlobalClusterCommand) + .build() {} diff --git a/clients/client-docdb/src/commands/index.ts b/clients/client-docdb/src/commands/index.ts index 162940cace80..2ca263b6e8e5 100644 --- a/clients/client-docdb/src/commands/index.ts +++ b/clients/client-docdb/src/commands/index.ts @@ -52,3 +52,4 @@ export * from "./RestoreDBClusterFromSnapshotCommand"; export * from "./RestoreDBClusterToPointInTimeCommand"; export * from "./StartDBClusterCommand"; export * from "./StopDBClusterCommand"; +export * from "./SwitchoverGlobalClusterCommand"; diff --git a/clients/client-docdb/src/models/models_0.ts b/clients/client-docdb/src/models/models_0.ts index 18bf01270535..4b55f9cb94d9 100644 --- a/clients/client-docdb/src/models/models_0.ts +++ b/clients/client-docdb/src/models/models_0.ts @@ -6351,3 +6351,57 @@ export interface StopDBClusterResult { */ DBCluster?: DBCluster; } + +/** + * @public + */ +export interface SwitchoverGlobalClusterMessage { + /** + *

The identifier of the Amazon DocumentDB global database cluster to switch over. + * 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. + * This parameter isn’t case-sensitive.

+ *

Constraints:

+ * + *

Pattern: [A-Za-z][0-9A-Za-z-:._]* + *

+ * @public + */ + GlobalClusterIdentifier: string | undefined; + + /** + *

The identifier of the secondary Amazon DocumentDB cluster to promote to the new primary for the global database cluster. + * Use the Amazon Resource Name (ARN) for the identifier so that Amazon DocumentDB can locate the cluster in its Amazon Web Services region.

+ *

Constraints:

+ * + *

Pattern: [A-Za-z][0-9A-Za-z-:._]* + *

+ * @public + */ + TargetDbClusterIdentifier: string | undefined; +} + +/** + * @public + */ +export interface SwitchoverGlobalClusterResult { + /** + *

A data type representing an Amazon DocumentDB global cluster.

+ * @public + */ + GlobalCluster?: GlobalCluster; +} diff --git a/clients/client-docdb/src/protocols/Aws_query.ts b/clients/client-docdb/src/protocols/Aws_query.ts index 921c8621aa26..a98a4d130bdc 100644 --- a/clients/client-docdb/src/protocols/Aws_query.ts +++ b/clients/client-docdb/src/protocols/Aws_query.ts @@ -193,6 +193,10 @@ import { } from "../commands/RestoreDBClusterToPointInTimeCommand"; import { StartDBClusterCommandInput, StartDBClusterCommandOutput } from "../commands/StartDBClusterCommand"; import { StopDBClusterCommandInput, StopDBClusterCommandOutput } from "../commands/StopDBClusterCommand"; +import { + SwitchoverGlobalClusterCommandInput, + SwitchoverGlobalClusterCommandOutput, +} from "../commands/SwitchoverGlobalClusterCommand"; import { DocDBServiceException as __BaseException } from "../models/DocDBServiceException"; import { AddSourceIdentifierToSubscriptionMessage, @@ -382,6 +386,8 @@ import { SubscriptionAlreadyExistFault, SubscriptionCategoryNotFoundFault, SubscriptionNotFoundFault, + SwitchoverGlobalClusterMessage, + SwitchoverGlobalClusterResult, Tag, TagListMessage, UpgradeTarget, @@ -1289,6 +1295,23 @@ export const se_StopDBClusterCommand = async ( return buildHttpRpcRequest(context, headers, "/", undefined, body); }; +/** + * serializeAws_querySwitchoverGlobalClusterCommand + */ +export const se_SwitchoverGlobalClusterCommand = async ( + input: SwitchoverGlobalClusterCommandInput, + context: __SerdeContext +): Promise<__HttpRequest> => { + const headers: __HeaderBag = SHARED_HEADERS; + let body: any; + body = buildFormUrlencodedString({ + ...se_SwitchoverGlobalClusterMessage(input, context), + [_A]: _SGC, + [_V]: _, + }); + return buildHttpRpcRequest(context, headers, "/", undefined, body); +}; + /** * deserializeAws_queryAddSourceIdentifierToSubscriptionCommand */ @@ -2343,6 +2366,26 @@ export const de_StopDBClusterCommand = async ( return response; }; +/** + * deserializeAws_querySwitchoverGlobalClusterCommand + */ +export const de_SwitchoverGlobalClusterCommand = async ( + output: __HttpResponse, + context: __SerdeContext +): Promise => { + if (output.statusCode >= 300) { + return de_CommandError(output, context); + } + const data: any = await parseBody(output.body, context); + let contents: any = {}; + contents = de_SwitchoverGlobalClusterResult(data.SwitchoverGlobalClusterResult, context); + const response: SwitchoverGlobalClusterCommandOutput = { + $metadata: deserializeMetadata(output), + ...contents, + }; + return response; +}; + /** * deserialize_Aws_queryCommandError */ @@ -5257,6 +5300,20 @@ const se_SubnetIdentifierList = (input: string[], context: __SerdeContext): any return entries; }; +/** + * serializeAws_querySwitchoverGlobalClusterMessage + */ +const se_SwitchoverGlobalClusterMessage = (input: SwitchoverGlobalClusterMessage, context: __SerdeContext): any => { + const entries: any = {}; + if (input[_GCI] != null) { + entries[_GCI] = input[_GCI]; + } + if (input[_TDCI] != null) { + entries[_TDCI] = input[_TDCI]; + } + return entries; +}; + /** * serializeAws_queryTag */ @@ -7830,6 +7887,17 @@ const de_SubscriptionNotFoundFault = (output: any, context: __SerdeContext): Sub return contents; }; +/** + * deserializeAws_querySwitchoverGlobalClusterResult + */ +const de_SwitchoverGlobalClusterResult = (output: any, context: __SerdeContext): SwitchoverGlobalClusterResult => { + const contents: any = {}; + if (output[_GC] != null) { + contents[_GC] = de_GlobalCluster(output[_GC], context); + } + return contents; +}; + /** * deserializeAws_queryTag */ @@ -8214,6 +8282,7 @@ const _SDBCSI = "SourceDBClusterSnapshotIdentifier"; const _SDBCt = "StopDBCluster"; const _SE = "StorageEncrypted"; const _SFS = "SkipFinalSnapshot"; +const _SGC = "SwitchoverGlobalCluster"; const _SGS = "SubnetGroupStatus"; const _SI = "SourceIdentifier"; const _SIL = "SourceIdsList"; @@ -8240,6 +8309,7 @@ const _TDBCPGD = "TargetDBClusterParameterGroupDescription"; const _TDBCPGI = "TargetDBClusterParameterGroupIdentifier"; const _TDBCSI = "TargetDBClusterSnapshotIdentifier"; const _TDBII = "TargetDBInstanceIdentifier"; +const _TDCI = "TargetDbClusterIdentifier"; const _TK = "TagKeys"; const _TL = "TagList"; const _Ta = "Tag"; diff --git a/codegen/sdk-codegen/aws-models/docdb.json b/codegen/sdk-codegen/aws-models/docdb.json index e6f39b69a7ee..b7df58ff4dff 100644 --- a/codegen/sdk-codegen/aws-models/docdb.json +++ b/codegen/sdk-codegen/aws-models/docdb.json @@ -295,6 +295,9 @@ }, { "target": "com.amazonaws.docdb#StopDBCluster" + }, + { + "target": "com.amazonaws.docdb#SwitchoverGlobalCluster" } ], "traits": { @@ -8387,6 +8390,67 @@ "smithy.api#httpError": 404 } }, + "com.amazonaws.docdb#SwitchoverGlobalCluster": { + "type": "operation", + "input": { + "target": "com.amazonaws.docdb#SwitchoverGlobalClusterMessage" + }, + "output": { + "target": "com.amazonaws.docdb#SwitchoverGlobalClusterResult" + }, + "errors": [ + { + "target": "com.amazonaws.docdb#DBClusterNotFoundFault" + }, + { + "target": "com.amazonaws.docdb#GlobalClusterNotFoundFault" + }, + { + "target": "com.amazonaws.docdb#InvalidDBClusterStateFault" + }, + { + "target": "com.amazonaws.docdb#InvalidGlobalClusterStateFault" + } + ], + "traits": { + "smithy.api#documentation": "

Switches over the specified secondary Amazon DocumentDB cluster to be the new primary Amazon DocumentDB cluster in the global database cluster.

" + } + }, + "com.amazonaws.docdb#SwitchoverGlobalClusterMessage": { + "type": "structure", + "members": { + "GlobalClusterIdentifier": { + "target": "com.amazonaws.docdb#GlobalClusterIdentifier", + "traits": { + "smithy.api#clientOptional": {}, + "smithy.api#documentation": "

The identifier of the Amazon DocumentDB global database cluster to switch over. \n The identifier is the unique key assigned by the user when the cluster is created. \n In other words, it's the name of the global cluster.\n This parameter isn’t case-sensitive.

\n

Constraints:

\n
    \n
  • \n

    Must match the identifier of an existing global cluster (Amazon DocumentDB global database).

    \n
    • \n
  • \n

    Minimum length of 1. Maximum length of 255.

    \n
    • \n
\n

Pattern: [A-Za-z][0-9A-Za-z-:._]*\n

", + "smithy.api#required": {} + } + }, + "TargetDbClusterIdentifier": { + "target": "com.amazonaws.docdb#String", + "traits": { + "smithy.api#clientOptional": {}, + "smithy.api#documentation": "

The identifier of the secondary Amazon DocumentDB cluster to promote to the new primary for the global database cluster. \n Use the Amazon Resource Name (ARN) for the identifier so that Amazon DocumentDB can locate the cluster in its Amazon Web Services region.

\n

Constraints:

\n
    \n
  • \n

    Must match the identifier of an existing secondary cluster.

    \n
    • \n
  • \n

    Minimum length of 1. Maximum length of 255.

    \n
    • \n
\n

Pattern: [A-Za-z][0-9A-Za-z-:._]*\n

", + "smithy.api#required": {} + } + } + }, + "traits": { + "smithy.api#input": {} + } + }, + "com.amazonaws.docdb#SwitchoverGlobalClusterResult": { + "type": "structure", + "members": { + "GlobalCluster": { + "target": "com.amazonaws.docdb#GlobalCluster" + } + }, + "traits": { + "smithy.api#output": {} + } + }, "com.amazonaws.docdb#TStamp": { "type": "timestamp" },