This guide shows how to provision a MongoDB replica set primary node through 123Cluster using AWS CloudFormation. The template uses a Lambda-backed custom resource to call the 123Cluster REST API — the same API the UI calls when you click Create.

Once deployed, the stack can be version-controlled, replicated across AWS accounts, and integrated into CI/CD pipelines like any other CloudFormation resource.

Prerequisites

•       AWS CLI configured with permissions to create CloudFormation stacks, IAM roles, and Lambda functions

•       A valid 123Cluster JWT token

•       Network connectivity from the Lambda execution environment to the 123Cluster API endpoint

‍

 Architecture

CloudFormation does not have a native resource type for 123Cluster. The template bridges that gap with a Lambda-backed custom resource that handles Create lifecycle events by calling the 123Cluster REST API.

CloudFormation Stack
  |
  +-- LambdaExecutionRole      	(IAM role, CloudWatch Logs only)
  +-- ProvisionClusterFunction 	(Python 3.11, 300s timeout)
  +-- DBCluster (Custom::DBCluster)
    	|
    	+---> 123Cluster REST API ---> Target host provisioning

Directory structure

cloudformation/
+-- template.yaml	# CloudFormation stack definition
+-- params.json  	# Parameter values (one file per environment)
+-- run.sh       	# Optional CLI shortcut for stack creation

‍

Step 1: Configure parameters

All environment-specific values go into params.json. Copy the file and replace every placeholder with values from the 123Cluster UI — use the { REST API } button on the cluster creation screen to get the endpoint URL and a pre-filled payload.

// params.json
[
  { "ParameterKey": "ApiBaseUrl",       "ParameterValue": "<API_BASE_URL>" },
  { "ParameterKey": "JwtToken",         "ParameterValue": "<YOUR_JWT_TOKEN>" },
  { "ParameterKey": "HostName",         "ParameterValue": "<HOST_NAME>" },
  { "ParameterKey": "SshUser",          "ParameterValue": "<SSH_USERNAME>" },
  { "ParameterKey": "SshPassword",      "ParameterValue": "<SSH_PASSWORD>" },
  { "ParameterKey": "OsDistributor",    "ParameterValue": "<OS_DISTRIBUTOR>" },
  { "ParameterKey": "OSRelease",        "ParameterValue": "<OS_VERSION>" },
  { "ParameterKey": "ClusterName",      "ParameterValue": "<CLUSTER_NAME>" },
  { "ParameterKey": "ReplicasetName",   "ParameterValue": "<REPLICASET_NAME>" },
  { "ParameterKey": "DbVersion",        "ParameterValue": "<DB_VERSION>" },
  { "ParameterKey": "Port",             "ParameterValue": "<DB_PORT>" },
  { "ParameterKey": "Sizing",           "ParameterValue": "<SIZING>" },
  { "ParameterKey": "DataDirectory",    "ParameterValue": "<DATA_DIRECTORY>" },
  { "ParameterKey": "DatabaseUser",     "ParameterValue": "<DB_ADMIN_USER>" },
  { "ParameterKey": "DatabasePassword", "ParameterValue": "<DB_ADMIN_PASSWORD>" },
  { "ParameterKey": "EnableSsl",        "ParameterValue": "false" }
]

‍

Parameter reference

‍

Step 2: The Lambda handler

The Lambda function is embedded in the CloudFormation template under ProvisionClusterFunction. It handles one lifecycle event from CloudFormation:

Create — calls the 123Cluster API to provision the cluster and reports SUCCESS or FAILED.

NOTE  The Lambda timeout is set to 300 seconds. Provisioning typically takes 2–5 minutes. If your environment has higher latency, increase the Timeout value in the template before deploying.

‍

Step 3: Deploy the stack

# Validate the template syntax before deploying
aws cloudformation validate-template \
  --template-body file://template.yaml
 
# Create the stack
aws cloudformation create-stack \
  --capabilities CAPABILITY_IAM \
  --stack-name mongodb-replicaset-master \
  --template-body file://template.yaml \
  --parameters file://params.json
 
# Wait for completion
aws cloudformation wait stack-create-complete \
  --stack-name mongodb-replicaset-master
 
# Retrieve stack outputs
aws cloudformation describe-stacks \
  --stack-name mongodb-replicaset-master \
  --query "Stacks[0].Outputs"

‍

Expected outcome

When the stack reaches CREATE_COMPLETE, three outputs are available:

•       ClusterId — the cluster name passed to the API, usable as a reference in downstream stacks.

•       ApiResponse — the raw JSON response from 123Cluster, containing node addresses and connection details.

•       LambdaFunctionArn — the ARN of the provisioning Lambda, useful for debugging via CloudWatch Logs.

The cluster also appears in the 123Cluster UI under Status immediately after provisioning completes.

TIP  If the stack creation fails, check the CloudWatch Logs group for ProvisionClusterFunction. The Lambda logs the full API response body, including error messages from 123Cluster.

Security considerations

•       Parameters marked NoEcho (JwtToken, SshPassword, DatabasePassword, PrivateKey) are not displayed in the console. For production, reference them from AWS Secrets Manager: {{resolve:secretsmanager:secret-name:SecretString:key}}.

•       The Lambda execution role grants only CloudWatch Logs permissions, following least-privilege. Do not add broader permissions unless your environment explicitly requires them.

•       The Lambda function disables TLS certificate verification when calling the 123Cluster API. Remove cert_reqs and assert_hostname overrides if your instance uses a valid certificate.

•       Always verify endpoint URLs and payload fields against the latest 123Cluster API documentation after a platform upgrade.

‍