Setting Up a BYOC Provider Account Using Terraform 

Use the Instaclustr Terraform provider alongside the AWS provider to provision your entire BYOC setup as infrastructure as code — from registering the provider account to deploying AWS resources and validating the connection in a single terraform apply.

Step 1 – Configure the providers 

Declare both the Instaclustr and AWS providers. The Instaclustr provider authenticates using a terraform_key in the format Instaclustr-Terraform <username>:<api_key>.

Note: The AWS provider region must be a real AWS region string (e.g. us-east-1), which is different from the Instaclustr data center name used later (US_EAST_1). Don’t put the Instaclustr DC name in the AWS provider block. 

Step 2 – Define your variables 

Create a variables.tf file. Supply sensitive values — particularly instaclustr_api_key — via environment variables, a *.tfvars file excluded from version control, or your secrets manager. Never commit credentials to source control.

About key_pair_name:

The CloudFormation template creates an EC2 key pair named with your Instaclustr Account ID. The data source substitutes this server-side (@@KEY_PAIR_NAME@@ → your Instaclustr Account ID), so you do not need a separate key_pair_name variable unless you reference it elsewhere.

• First BYOC provider account in a given AWS account + region: leave create_key_pair = true (default).

• Additional provider accounts in the same AWS account + region: set create_key_pair = false. EC2 key pair names must be unique per AWS account/region, and the name is tied to your Instaclustr Account ID (not the provider account), so only the first stack should create it.

If you skip this on a second setup, AWS returns InvalidKeyPair.Duplicate and the stack fails.

You can find your Instaclustr Account ID in the Console under Account Settings.

Step 3 – Retrieve and customise the CloudFormation template 

The Instaclustr provider exposes a data source that returns the CloudFormation template with Instaclustr-side values already substituted. You only need to replace the two customer-side placeholders: the backup bucket name and the IAM role name.

The following placeholders are substituted automatically by Instaclustr:

You substitute the remaining two placeholders in the locals block below:

Important – values must match: The s3_backup_bucket_name and iam_role_name you substitute into the template must exactly match the backup_bucket_name and iam_role_name you provide to the instaclustr_byoc_aws_provider_account_setup_v1 resource in Step 5. If they differ, validation will fail because Instaclustr won’t find the expected bucket/role in your account. 

Step 4 – Deploy the CloudFormation stack in AWS

Deploy the processed template into your AWS account. The stack creates the S3 backup bucket, EC2 key pair, cross-account IAM role, and the trust policy that allows Instaclustr’s InstaclustrProvisioning role to assume it — scoped by your Instaclustr account ID as the ExternalId .

The CAPABILITY_NAMED_IAM capability is required because the stack creates a named IAM role.

When CreateKeyPair = “false”: The stack skips creating AWS::EC2::KeyPair, but the KeyPairName output still returns your Instaclustr Account ID (the expected key pair name). Instaclustr validation assumes the key pair already exists from a prior BYOC setup in that AWS account/region.

Step 5 – Register and validate the provider account 

Create the Instaclustr provider account resource. The depends_on ensures the CloudFormation stack is fully deployed before Instaclustr attempts validation.

Unlike the API flow, there is no separate “validate” step here — validation is triggered automatically when this resource is created. Instaclustr assumes the cross-account role, verifies the S3 bucket, EC2 key pair, and IAM role permissions, and transitions the account to RUNNING.

Step 6 — Apply

On a successful apply, the provider account reaches RUNNING status and is ready to use. A default organisation is created for your account during validation if one does not already exist. You can confirm the result in the Console under Account Settings → BYOC Provider Accounts, where the status displays as Validated.

If apply fails:

The most common causes are: a bucket name or IAM role name mismatch between the template substitution (Step 3) and the provider account resource (Step 5), or create_key_pair = true on a second setup in the same AWS account/region. Review the Terraform error output and check the CloudFormation stack events in the AWS Console for details.

Step 7 – Add additional AWS regions 

A single BYOC provider account can cover up to 30 AWS regions. You do not need to create a second provider account or modify Steps 1–6. Adding an additional region is an in-place update of the instaclustr_byoc_aws_provider_account_setup_v1 resource you already created, plus one new CloudFormation stack for the target region. 

Prerequisites Per Region 

• S3 Backup Bucket: A globally unique bucket created in the new AWS region. 

• EC2 Key Pair: Provisioned in the new AWS region. 

• Cross-Account IAM Role: The IAM role created during your initial setup (Region 1) is reused across all regions. The regional CloudFormation stack simply attaches a new bucket-scoped policy to this existing role. 

The five code updates below demonstrate adding US_WEST_2 (us-west-2) to an existing setup. 

7.1 – Add an Aliased AWS Provider for the New Region  

Note: The Instaclustr data centre name (US_WEST_2) and the AWS region string (us-west-2) are not interchangeable. 

Leave your unaliased provider “aws” block from Step 1 as your primary region provider, and add one aliased provider per additional AWS region: 

7.2 – Add a Bucket Variable for the New Region 

Define a variable for the S3 bucket to be created in the new region: 

7.3 – Process the Template for the New Region 

Reuse the template data source (data.instaclustr_byoc_aws_cloudformation_template_v1.byoc_template) from Step 3. Add a local value that substitutes the new region’s bucket name while retaining the same iam_role_name from your primary region: 

7.4 – Deploy a Regional CloudFormation Stack 

Deploy one CloudFormation stack per additional region, targeting that region’s provider alias:

Parameter Requirements: 

• CreateIAMRole = “false” (Required): Reuses the role created in your first region instead of attempting to recreate it. The template default is “true”, so omitting this will cause the stack to fail with a duplicate role error. 
• IAMRoleName (Required): Must match the role created in Step 4. When CreateIAMRole is “false”, the stack attaches a bucket-scoped policy (Instaclustr-<region>-<bucket>) to this existing role. 
• CreateKeyPair = “true”: EC2 key pairs are region-scoped in AWS. A new region requires its own key pair even though the name matches the Instaclustr Account ID. Set to “false” only if this key pair already exists in the target region.
• BucketName: The S3 backup bucket name for the new region. 
• depends_on (Required): Ensures the primary stack (and the IAM role) exists before this regional stack attempts to attach policies to it. 

7.5 – Update the Provider Account Resource 

Add an additional data_centre_backup_buckets block to your existing instaclustr_byoc_aws_provider_account_setup_v1 resource, and update depends_on to reference all regional stacks:

7.6 – Apply the Configuration 

Run terraform apply to register and validate the new region: 

What Happens During Apply: 

1. Terraform updates the existing provider account resource in place. 
2. Instaclustr validates only the newly added region (assumes the cross-account IAM role and verifies the new S3 bucket and EC2 key pair). 
3. Previously validated regions and any running clusters remain completely unaffected. 

Setting Up Multiple Regions from Day 1:
You can also provision multiple regions on your initial terraform apply. Include all regional stacks and all data_centre_backup_buckets blocks in your initial configuration. The rules remain identical: the primary region stack sets CreateIAMRole = “true”, and every additional regional stack sets CreateIAMRole = “false”. 

Troubleshooting: If Adding a Region Fails 

In addition to the standard validation checks from Step 6, verify the following: 

Common Failure	Root Cause	Resolution
EntityAlreadyExists (IAM Role)	CreateIAMRole was left at “true” (or omitted) in the additional region’s stack.	Explicitly set CreateIAMRole = “false” in the additional region’s parameters map.
Policy Attachment Error	IAMRoleName was omitted from the additional region’s stack parameters.	Pass IAMRoleName = var.iam_role_name so the regional bucket policy knows which role to attach to.
Role Not Found on Stack Create	Missing depends_on between the additional regional stack and the initial stack.	Add depends_on = [aws_cloudformation_stack.instaclustr_byoc_stack] to ensure the role exists before attaching policies.
InvalidKeyPair.Duplicate	CreateKeyPair = “true” was passed, but a key pair with the same name already exists in that specific AWS region.	Set CreateKeyPair = “false” for that regional stack.
Validation Mismatch Error	The backup_bucket_name in data_centre_backup_buckets does not match the bucket created by the CloudFormation stack.	Ensure the bucket name string passed to the stack matches the string in the provider resource.

Legacy/Manual Accounts: 
Provider accounts originally provisioned through the legacy manual setup flow (rather than the Console self-service or Terraform workflow) may fail validation due to missing IAM permissions or older template divergence. If the regional CloudFormation stack deploys successfully but Instaclustr validation fails, please Contact Support. 

Removing a Region 

When you decide that you no longer need to provision or run clusters in a region, you can remove an already added region from a BYOC provider account as follows: 

To remove a region from an existing BYOC provider account: 

1. Remove from Provider Resource: Delete that region’s data_centre_backup_buckets block from instaclustr_byoc_aws_provider_account_setup_v1. 
2. Remove CloudFormation Resource: Delete that region’s aws_cloudformation_stack resource and remove it from the depends_on list. 
3. Keep the Provider Alias Temporarily: Do not remove the aliased provider “aws” block in the same step. Terraform requires the provider configuration in state to destroy the stack resources cleanly. 
4. Apply Destruction: Run terraform apply to destroy the CloudFormation stack and update the provider account. 
5. Clean Up Provider Alias: Once apply completes, remove the unused provider “aws” alias block from your .tf files. 

Constraints & Considerations: 

• Active Clusters: A region currently in use by an active cluster cannot be removed. You must delete or migrate all cluster data centres in that region first. 
• Minimum Region Requirement: You cannot remove the last remaining region on a provider account. To remove the final region, destroy the entire provider account resource instead. 
• Immutable Bucket Names: You cannot edit the backup_bucket_name of an already-validated region in place. To change a bucket name, remove the region and re-add it with the new bucket name. 
• S3 Data Retention: Instaclustr does not automatically delete your S3 backup buckets. Manually delete the S3 bucket in AWS if the backup data is no longer required.