AWS account onboarding with CTL¶

Use this guide when your hosted plan or BYOA plan deploys to AWS.

Region model¶

AWS account configs do not use bindings. Once the account is verified and READY, the same account config can be used across supported AWS regions. Pick the target region at deployment time with --region.

Prerequisites¶

An AWS account ID.
Permission to run the Omnistrate onboarding bootstrap in that AWS account.
omnistrate-ctl installed and logged in.

Hosted flow¶

1. Register the hosted account config¶

For AWS, use --skip-wait because the account will not become READY until you complete the bootstrap step in AWS.

omnistrate-ctl account create aws-hosted \
  --aws-account-id 123456789012 \
  --skip-wait

2. Open the bootstrap action¶

omnistrate-ctl account describe aws-hosted

In the account TUI:

Select Actions -> Bootstrap and press o to open the CloudFormation URL.
If you need the alternate flow without the load-balancer policy, select Bootstrap (No LB).
Press c to copy the selected URL instead of opening it.

3. Wait for the account to become ready¶

After the CloudFormation or Terraform bootstrap completes, rerun:

omnistrate-ctl account describe aws-hosted

Continue until the account status is READY.

4. Create the first hosted deployment¶

omnistrate-ctl instance create \
  --service <service> \
  --environment <environment> \
  --plan <hosted-plan> \
  --resource <resource> \
  --cloud-provider aws \
  --region us-east-1 \
  --param-file ./params.json

BYOA flow¶

1. Create the customer onboarding instance¶

Use --skip-wait here for the same reason: the customer-facing bootstrap must run in AWS before the backing account can become READY.

omnistrate-ctl account customer create \
  --service <service> \
  --environment <environment> \
  --plan <byoa-plan> \
  --aws-account-id 123456789012 \
  --skip-wait

In production environments, the command uses the calling user's subscription by default. Add --subscription-id or --customer-email only if you need to onboard on behalf of a different production subscription.

2. Find the backing account config and complete bootstrap¶

omnistrate-ctl account customer describe <customer-account-instance-id> -o json

Copy summary.accountConfigID, then open the backing account config:

omnistrate-ctl account describe <account-config-id>

Use the Actions -> Bootstrap entry in the hosted account TUI to open or copy the AWS bootstrap URL, then complete the bootstrap in the customer AWS account.

3. Verify the customer onboarding instance¶

omnistrate-ctl account customer describe <customer-account-instance-id>
omnistrate-ctl account customer list --cloud-provider aws

Continue until the onboarding instance and the backing account are both ready to use.

4. Create the BYOA deployment¶

omnistrate-ctl instance create \
  --service <service> \
  --environment <environment> \
  --plan <byoa-plan> \
  --resource <resource> \
  --cloud-provider aws \
  --region us-east-1 \
  --customer-account-id <customer-account-instance-id> \
  --param-file ./params.json

Update and delete¶

AWS does not require account-level updates to add regions. To reuse the same account in another AWS region, deploy with a different --region.

Useful lifecycle commands:

# Inspect all customer AWS onboarding instances
omnistrate-ctl account customer list --cloud-provider aws

# Delete a customer onboarding instance
omnistrate-ctl account customer delete <customer-account-instance-id>