Setting Up a BYOC Provider Account via 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.