Set Up a BYOC Provider Account Using the API
Prerequisites
- API Provisioning Key
- API documentation for BYOC endpoints
Setting up BYOC provider in a few simple steps using API.
- Step 1 – Create the Provider Account setup (POST /cluster-management/v2/resources/byoc-setups/aws/v1/)
Register a new BYOC provider account with Instaclustr. This call records your AWS account details and the names of the resources that will be created in the next steps. The provider account is created in a pending state until validation completes.
The response includes a providerAccountId. You will need this in Steps 4 and 5.
- Step 2 – Download the template
Download the pre-populated infrastructure template for your provider account. Instaclustr substitutes your account-specific values (external ID, key pair name, Instaclustr AWS account ARN) automatically. Choose the format that matches your preferred deployment method.
- CloudFormation JSON (GET cluster-management/v2/data-sources/byoc-setups/template/aws/download-json)
- Terraform ZIP (GET cluster-management/v2/data-sources/byoc-setups/template/aws/download-terraform)
- Step 3 – Apply the template in AWS (the manual console step, automated)
Deploy the downloaded template into your AWS account. This creates the S3 backup bucket, EC2 key pair, cross-account IAM role, and trust policy that allows Instaclustr to manage your infrastructure.
|
1 2 3 4 |
aws cloudformation deploy --region us-east-1 \ --stack-name instaclustr-byoc-setup \ --template-file cloudformation.json \ --capabilities CAPABILITY_NAMED_IAM |
For Terraform it runs terraform init + apply -auto-approve
- Step 4 – Validate (POST /cluster-management/v2/resources/byoc-setups/aws/v1/{providerAccountId}, no body)
Once the AWS resources are deployed, trigger validation. Instaclustr assumes the cross-account IAM role (using your Instaclustr account ID as the ExternalId), then verifies that the S3 bucket, EC2 key pair, and IAM permissions are all correctly configured.
- Step 5 – Poll until RUNNING (GET /cluster-management/v2/resources/byoc-setups/aws/v1/{providerAccountId})
Validation runs asynchronously. Poll the provider account until it reaches RUNNING status. Treat FAILED or ERROR as terminal states.
When the status is RUNNING , your BYOC provider account is validated and ready. You can now create clusters using this provider account. A default organisation is created for your Instaclustr account during validation if one does not already exist.
The most common causes are: missing IAM permissions, a bucket name mismatch, or the CloudFormation stack not yet reaching CREATE_COMPLETE before validation was triggered. Verify the stack status in the AWS Console, then re-trigger validation (Step 4).
