Skip to main content

Managed BYOC

In a managed BYOC region, the Catalyst data plane runs in your own cloud account and Diagrid provisions and operates it for you. You grant Diagrid scoped access to your account through a cloud connection, and from there the experience is the same as Dedicated Cloud — one command, no infrastructure to build or maintain.

If you'd rather run the Catalyst data plane on a Kubernetes cluster you operate yourself, use self-managed BYOC instead.

How it works​

  1. You create a cloud connection — an organization-level resource that records how Diagrid accesses your cloud account: an IAM role on AWS, or a federated app identity on Azure.
  2. You create a region through that connection. Diagrid's provisioner uses the connection's identity to create the region's infrastructure in your account — networking, a Kubernetes cluster, a database, and the region's own IAM roles — then deploys the Catalyst data plane and joins the region to your organization.
  3. Diagrid operates the region from then on: upgrades, scaling within the tier, and lifecycle management, all inside your account.

Managed BYOC regions are available on AWS and Azure.

Grant Diagrid access​

On AWS, the cloud connection points to an IAM role in your account that Diagrid's provisioner assumes.

  1. Create the cloud connection:

    diagrid cloudconnection create my-aws-account --provider aws

  2. In the Catalyst console, go to Cloud providers and open the connection you just created. The console displays ready-to-run AWS CLI and Terraform snippets with the exact trust policy pre-filled for your environment. Run the snippet in a terminal signed in to the AWS account you want Diagrid to provision into.

    The snippet creates an IAM role named exactly diagrid-dedicated-region-provisioner with permissions scoped to what Diagrid provisions: EC2 networking, the EKS cluster, the RDS database, and the region's own IAM roles — not administrator access. It also creates a second, customer-owned role, diagrid-cluster-operator, so your platform team can inspect the region's EKS cluster with kubectl without going through Diagrid.

  3. Record the role on the connection:

    diagrid cloudconnection update my-aws-account \
      --role-arn arn:aws:iam::123456789012:role/diagrid-dedicated-region-provisioner

The role name must match exactly — Diagrid's provisioner is only permitted to assume a role with this name in your account, so a differently named role can never be assumed.

Every customer's role has the same name and trusts the same Diagrid principal, so the name alone doesn't link a role to your connection. An external ID does. When you create an AWS connection, Diagrid generates a unique external ID and sends it each time it assumes the role. The role's trust policy allows sts:AssumeRole only when sts:ExternalId matches that value, so no other organization can use your role.

The console snippets already include this condition. If you create the role some other way, such as with your own Terraform or CloudFormation, copy the value from External ID on the connection's page in the console and add the condition yourself:

"Condition": { "StringEquals": { "sts:ExternalId": "<external-id>" } }

You can't set or change the external ID. It stays the same for as long as the connection exists.

Connections created before external IDs. Older AWS connections don't have an external ID. They keep working, and Diagrid assumes their role without one. These connections show a status message asking you to add one. To add it:

  1. Update the connection. Any update gives it an external ID, so you can pass the role ARN it already has:

    diagrid cloudconnection update my-aws-account \
      --role-arn arn:aws:iam::123456789012:role/diagrid-dedicated-region-provisioner

    In the console, you can edit the connection and save it without changing anything.

  2. Copy the new value from External ID on the connection's page and add the sts:ExternalId condition shown above to the role's trust policy.

Your regions keep working the whole time. Until you add the condition, AWS ignores the external ID that Diagrid sends, and the role can still be assumed.

You can't create a region through a connection until its identity is recorded.

Create the region​

Create the region through the console — under Regions, select Create region, choose BYOC, then Managed — or with the CLI:

diagrid region create my-region \
  --byoc \
  --cloud-connection my-aws-account \
  --cloud aws \
  --region eu-west-1 \
  --tier small

The --cloud value must match the cloud connection's provider. The sizing tiers (small, medium, large, xlarge) and networking postures (public, private) work the same way as for Dedicated Cloud.

Track provisioning​

Provisioning typically takes 20–40 minutes and moves through the same phases as a dedicated region — Pending, Provisioning, Deploying, Joining, Ready:

diagrid region get my-region

If Diagrid can't provision into your account — for example, the provisioner role can't be assumed or is missing a permission — the region fails fast and its status message tells you why, so you can fix the connection and retry.

Start using the region​

Once the region reports Ready, create a project in it:

diagrid project create my-project --region my-region

To make it the default region for every new project in your organization, use diagrid region use.

From here, run any quickstart against your new project to verify the region end to end.

Operate the region​

Day-to-day, a managed BYOC region behaves like a dedicated region that happens to live in your account:

  • Diagrid runs and upgrades the data plane and the underlying infrastructure.
  • Your team keeps independent access to the cluster through the diagrid-cluster-operator role on AWS.
  • Resize or change networking with diagrid region update.

Support plans​

A managed BYOC region can be purchased with the select or premium support plan, set with the --support-plan flag on diagrid region create. Regions running on your own infrastructure start at select. The region's price reflects its sizing tier and support plan together.

See Dedicated and BYOC regions for how regions are priced and billed.

What's next​

Last updated on