Manage BYOC Cloud Accounts¶

View and manage your customers' BYOC Cloud Accounts for BYOC deployments.

What is BYOC?¶

BYOC (Bring Your Own Cloud) is a deployment model where your customers' applications are deployed and managed within their own cloud accounts rather than in your infrastructure. This approach addresses critical customer requirements around data sovereignty, security compliance, and cost control while still providing a fully-managed SaaS experience.

BYOC Operations¶

Self-served BYOC Setup¶

The Customer Portal can be used by customers to connect and manage their BYOC cloud accounts.

Setup Customer Accounts on behalf of customer¶

You can also work with your customer to perform an assisted setup of their Cloud Account.

Responsibility model¶

In a BYOC deployment, responsibilities are split across three parties:

• Customer account owner: Runs the onboarding flow in the target account, approves IAM and identity setup, and owns cloud quotas, organization policies, and network constraints in that account.
• SaaS provider: Enables BYOC for the service, guides or assists the customer through onboarding, and operates the resulting instances through Omnistrate.
• Omnistrate: Provides the onboarding artifacts, bootstraps the deployment cell, installs platform components, and orchestrates lifecycle operations in the connected account.

Lifecycle of a BYOC account¶

For most BYOC services, the lifecycle looks like this:

1. The customer connects their cloud account from the Customer Portal or through an assisted flow.
2. The first instance in a given account and region bootstraps the deployment cell for that location.
3. Later instances in the same account and region typically reuse that deployment cell instead of creating a new cluster every time.
4. The account can only be offboarded after all instances in that account are deleted.

For more background on deployment cells, see Deployment Cells.

Self-serve vs assisted onboarding¶

Both patterns are supported:

• Self-serve: The customer runs the onboarding flow directly from the Customer Portal.
• Assisted: Your team coordinates with the customer and helps execute the onboarding steps in their cloud account.

The underlying Omnistrate bootstrap flow is the same in both cases. The main difference is who drives the cloud-console or Cloud Shell steps.

CTL workflow for BYOA cloud accounts¶

If you prefer to onboard customer accounts from the CLI, use the provider-specific getting-started guides:

• AWS account onboarding with CTL
• GCP account onboarding with CTL
• Azure account onboarding with CTL
• Nebius account onboarding with CTL
• BYOC On-Premise for customer-owned Kubernetes clusters

The common BYOA lifecycle commands are:

# Create a customer onboarding instance
omnistrate-ctl account customer create [provider flags] --service <service> --environment <environment> --plan <byoa-plan>

# List and inspect customer onboarding instances
omnistrate-ctl account customer list [flags]
omnistrate-ctl account customer describe <customer-account-instance-id>

# Update or delete a customer onboarding instance
omnistrate-ctl account customer update <customer-account-instance-id> [flags]
omnistrate-ctl account customer delete <customer-account-instance-id>

# Create a BYOA deployment with that onboarding instance
omnistrate-ctl instance create ... --customer-account-id <customer-account-instance-id>

In production environments, account customer create defaults to the calling user's subscription unless you explicitly pass --subscription-id or --customer-email.

Account Tags¶

Cloud accounts support custom tags — free-form key/value pairs stored on the account configuration. The account configuration is the definitive store for these tags: every deployment cell running in the account exposes them as the $sys.deploymentCell.accountTags system parameter, which can steer conditional amenities, amenity Helm chart values, and service plan configuration.

Setting tags with CTL¶

All account command sets accept a --tags flag with comma-separated key=value pairs:

# Tag your own cloud account at onboarding time
omnistrate-ctl account create my-account --aws-account-id=123456789012 \
  --tags "env=prod,team=platform"

# Replace the tag set on an existing account
omnistrate-ctl account update my-account --tags "env=prod,omnistrate.com/cost-center=cc-1234"

# Tag a customer BYOA account at onboarding time — the tags flow through the
# onboarding instance to the customer's backing account configuration
omnistrate-ctl account customer create --service <service> --environment <environment> \
  --plan <byoa-plan> --aws-account-id=<customer-account> --tags "tier=enterprise"

# Replace the tag set on a customer's backing account configuration
omnistrate-ctl account customer update <customer-account-instance-id> --tags "tier=enterprise,region-pref=eu"

Tags appear in account describe, account list, and account customer describe output, and in the corresponding API responses (customTags).

Semantics¶

• Update replaces the whole tag set. --tags on account update and account customer update is a full replacement, not a merge — include every tag you want to keep.
• BYOA instance tags write to the account. For BYOA account onboarding instances, custom tags set through the instance APIs (create or metadata update) are written to the backing account configuration, and reads return the account configuration's tags — the instance never keeps a separate tag set. An account shared by multiple onboarding instances has one tag set; the last write wins.
• Key format. Tag keys may contain dots and slashes (for example omnistrate.com/cost-center); reference such keys with bracket notation in system parameter expressions. Keys used to filter layered chart values scopes must use only letters, digits, underscores, and dots.
• Duplicate keys are rejected, both by the CLI and the API.

BYOC On-Premise Kubernetes Accounts¶

BYOC On-Premise connects a customer-owned Kubernetes cluster instead of a cloud account. For the full setup flow, see BYOC On-Premise.

Retrying onboarding safely¶

When onboarding fails partway through, or when bootstrap resources are deleted manually later, avoid trying to stitch old and new bootstrap state together.

Recommended approach:

• Re-run the current onboarding flow for the exact target account and cloud provider.
• If the connected account was partially onboarded and then manually modified, disconnect or offboard it and onboard again cleanly.
• For GCP, treat deleted-and-recreated projects, removed workload identity pools/providers, or mismatched onboarding kits as fresh onboarding events.
• Do not assume a previous bootstrap in another region, another environment, or another cloud account can be reused automatically.

CloudFormation Controls¶

For AWS BYOC accounts, the customer account owner can use the customer-owned CloudFormation onboarding stack to manage Omnistrate access. AgentInfrastructureMutationEnabled controls AWS infrastructure mutation permissions. For BYOC PrivateLink host clusters, DataplaneKubernetesAccessRole switches the dataplane agent between administrative and read-only Kubernetes access, while K8sDebugAccessEnabled controls the network path for Kubernetes debug access. DataplaneKubernetesAccessTargets and K8sDebugAccessTargets independently scope the Kubernetes controls by region or host cluster. See AWS CloudFormation Account Controls.

BYOC PrivateLink Accounts¶

Management traffic uses AWS PrivateLink. The private-registry artifact delivery and no-internet topology described below require the corresponding features to be enabled for the SaaS Provider organization and deployment cell.

Omnistrate-managed VPC¶

The simplest topology: Omnistrate provisions the VPC, subnets, security group, and the management VPC Endpoint inside the customer's account on first deployment, including a NAT gateway for networks with outbound egress. The customer only grants the bootstrap role via CloudFormation — no manual VPC or VPCE setup is required.

For deployments without internet access, workload private subnets reach AWS services and the configured private Amazon ECR registry through VPC endpoints, without a NAT gateway or default Internet route.

For managed VPCs without internet access, Omnistrate creates the required endpoints and private DNS. For customer-owned VPCs, the customer supplies them before deployment.

Managed endpoint-only networks include Route53 API access for external-dns. After bootstrap is updated to a version with Route53 endpoint support, existing eligible deployment cells receive the endpoint on their next VPC infrastructure reconcile; restarting a pod or syncing only amenities does not update VPC endpoints.

The Allow new cloud-native network creation account setting permits Omnistrate to create VPCs on demand. If network creation is disabled, deployments must reuse an existing customer-supplied VPC.

• Customer Portal: enable Allow new cloud-native network creation on the AWS account form.

• omnistrate-ctl: pass --allow-create-new-cloud-native-network on account customer create:

  omnistrate-ctl account customer create \
    --service=<service> \
    --environment=<environment> \
    --plan=<plan> \
    --customer-email=<[email protected]> \
    --aws-account-id=<AWS_ACCOUNT_ID> \
    --allow-create-new-cloud-native-network
  

With network creation allowed, the first instance in each region triggers Omnistrate to create the deployment cell's VPC and network resources. Later instances in the same region reuse the same network.

Imported VPC requirements for BYOC PrivateLink¶

Customers typically bring their own VPC when they need to comply with internal network governance — for example, reusing an existing CIDR plan that fits Transit Gateway / Direct Connect routing, attaching the dataplane to a pre-approved security group and firewall posture, sharing a NAT gateway or egress proxy with other workloads, or operating under a policy that prohibits the SaaS provider from creating new VPCs in their account.

When the customer brings their own VPC for a PrivateLink account, Omnistrate validates its connectivity but does not create its routes, VPC endpoints, or DNS zones.

The following requirements apply before any instance is deployed:

With outbound egress¶

Every selected workload private subnet must have a 0.0.0.0/0 route through a NAT gateway, NAT instance, transit gateway, VPN gateway, or AWS Network Firewall or Gateway Load Balancer endpoint. The egress firewall or proxy must allow HTTPS and DNS access to:

• the regional Auto Scaling, EC2, EKS, EKS Auth, Elastic Load Balancing, CloudWatch Logs, and STS services;
• the selected private ECR registry's API and registry hostnames;
• the S3 URLs returned by ECR for image and OCI Helm chart layers;
• the fixed us-west-2 deployment-artifact S3 path.

If workloads manage DNS records, also allow HTTPS access to the Route53 API at route53.amazonaws.com, used by external-dns and cert-manager DNS-01 challenges.

AWS service VPC Endpoints are optional with this model. The provisioner management VPC Endpoint remains mandatory.

Without internet access¶

If any selected workload private subnet does not have the supported outbound route described above, create the complete endpoint set. A partial combination of subnet egress and endpoints does not pass validation.

S3 endpoint policies must allow ECR layer downloads and, when used, uploaded deployment-artifact downloads. A restrictive policy can pass topology checks but still fail image, OCI chart, and uploaded-artifact downloads.

For each cross-region interface endpoint, associate a private hosted zone with the VPC and create aliases for the canonical AWS names:

• api.ecr.<region>.amazonaws.com for ECR API;
• dkr.ecr.<region>.amazonaws.com and *.dkr.ecr.<region>.amazonaws.com for ECR DKR;
• s3.<region>.amazonaws.com and *.s3.<region>.amazonaws.com for S3; and
• route53.amazonaws.com for the Route53 API outside us-east-1. Create a private hosted zone named route53.amazonaws.com and an A alias at the zone apex targeting the interface endpoint's DNS name and hosted-zone ID.

Endpoint-only preflight verifies the service names, endpoint types and regions, available state, same-region private DNS, interface endpoint subnet attachments, TCP 443 security-group coverage, S3 route-table associations, and cross-region private DNS aliases. Validation reports the missing service or property without changing the imported VPC.

Route53 connectivity is a workload requirement, not part of imported-VPC artifact endpoint preflight. Passing preflight does not guarantee that external-dns can reach Route53 or create DNS records. Verify Route53 API access from the component that manages DNS records; missing connectivity can leave ingress hostnames unresolved even when the ingress controller and load balancer are healthy.

How workloads access the private registry¶

Workloads use the canonical <account-id>.dkr.ecr.<registry-region>.amazonaws.com hostname, with the endpoint DNS and routing configured above. Omnistrate handles authorization for its managed artifacts. For your own charts, images, and Terraform sources, see Private Registries for BYOC PrivateLink.

Account Offboarding¶

When a customer no longer needs your SaaS Product or wants to disconnect their cloud account, you can offboard their BYOC account. This removes all Omnistrate-managed resources from the customer's cloud account and severs the trust relationship.

Prerequisites¶

Before a BYOC account can be offboarded:

1. The customer must delete all deployment instances running in their cloud account. Active instances must be terminated before the account can be offboarded.

Offboarding Steps¶

Offboarding from the Customer Portal¶

Customers offboard their BYOC account directly from the Customer Portal:

1. Navigate to your cloud account settings in the Customer Portal.
2. Delete the cloud account configuration.
3. Confirm the offboarding operation.
4. Wait for Omnistrate to automatically remove all managed resources from your account.

What offboarding cleans up¶

When you offboard a customer's BYOC account, Omnistrate removes the following resources from the customer's cloud:

• Control plane agents and system nodes
• Monitoring infrastructure
• Networking resources (VPCs, subnets, and security groups created by Omnistrate) — only if you are not using a Bring Your Own Network deployment model
• Deployment cells and their underlying Kubernetes clusters

Customer-side cleanup¶

After the offboarding process completes, the customer should remove the onboarding permissions from their cloud account. For cloud-specific cleanup steps, see Offboarding.