> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use your own VPC

By default, Superblocks creates the VPCs your Managed BYOC instance runs in. If your organization needs to use networks it already owns, such as VPCs already connected to your data sources, Superblocks can deploy into your VPCs instead.

You can use your own VPC for the control plane, for any data plane, or for both, and you set each one up in the [bootstrap](https://docs.superblocks.com/enterprise/cloud-prem/deployment-guide.md#the-bootstrap).

Decide before your initial deployment

Choose whether Managed BYOC builds a VPC or uses yours before Superblocks first deploys that part of your instance. You can't switch an existing control plane or data plane between the two later, because switching would delete the VPC Managed BYOC built along with its NAT gateways and egress IP addresses.

## VPC layout

A Managed BYOC instance needs one VPC for the control plane and one for each data plane, all in your Managed BYOC AWS account. You can use your own VPC for any of them; Managed BYOC builds the rest.

* **Control plane VPC.** One, in a [supported control plane region](https://docs.superblocks.com/enterprise/cloud-prem/supported-regions.md#control-plane-regions). It holds the control plane's EKS cluster, its database, the deployer, Superblocks agents, and the internet-facing load balancer for your instance.
* **Data plane VPCs.** One for each data plane, in a [supported data plane region](https://docs.superblocks.com/enterprise/cloud-prem/supported-regions.md#data-plane-regions). Two data planes can't share a VPC.

## VPC requirements

Every VPC you use, for the control plane or a data plane, must meet these requirements. The bootstrap checks most of them when you run it, and stops with a message naming the VPC or subnet that fails the requirement check. Routing isn't checked until deployment.

* **DNS is turned on.** The VPC must have both DNS resolution and DNS hostnames turned on.
* **At least two availability zones.** We recommend three for the control plane, the same number Superblocks uses when it creates the control plane VPC. Identify zones by AZ ID, such as `usw2-az1`, not by AZ name, such as `us-west-2a`, and avoid the [AZ IDs that aren't supported](https://docs.superblocks.com/enterprise/cloud-prem/supported-regions.md#availability-zones). Each subnet must be in the VPC and in the zone it's listed under.
* **Subnets in the primary CIDR.** Every subnet must be inside the VPC's primary IPv4 CIDR. Subnets in a secondary CIDR aren't supported.
* **Separate database, public, and agent subnets.** A database or public subnet can't serve any other purpose, and an agent subnet can only be shared between agent types. The node, EKS control plane, and private subnets can be one subnet. See [Subnets](#subnets).
* **Tagged node subnets.** Each node subnet must have the `karpenter.sh/discovery` tag, or Managed BYOC can't launch cluster nodes. If nodes share your private subnet, tag the private subnet; Managed BYOC can then launch nodes anywhere in it. The tag value is your cluster name for the control plane, and `<cluster name>-dp-<data plane ID>` for each data plane, using the cluster name and data plane IDs you set in the bootstrap.
* **Large enough data plane node subnets.** A data plane's node subnet must be a `/22` or larger, because nodes and their pods take their IP addresses from it. If nodes share your private subnet, the private subnet must be a `/22` or larger.
* **An outbound path.** Managed BYOC must reach the [required outbound domains](https://docs.superblocks.com/enterprise/cloud-prem/configure/network-firewall.md#required-outbound-domains) from your VPC, through a NAT gateway, a transit gateway, or a proxy. A NAT gateway in the VPC sits in a public subnet that routes to an internet gateway. In a data plane VPC, that public subnet is your own: Managed BYOC doesn't use it.
* **An internet gateway on each data plane VPC.** Users reach a data plane through AWS Global Accelerator, which delivers traffic over the AWS network to an internal load balancer in your node subnets. [AWS requires an internet gateway attached to the VPC](https://docs.aws.amazon.com/global-accelerator/latest/dg/secure-vpc-connections.html) to show that it accepts internet traffic, but Global Accelerator doesn't route through it. Your subnets don't need routes to the internet gateway, and nothing needs a public IP address.
* **A path to AWS APIs and container images.** Cluster nodes and the deployer call AWS APIs and pull container images through your outbound path or through [VPC endpoints](#vpc-endpoints).

Managed BYOC doesn't manage routing in your VPC, so the [AWS Network Firewall](https://docs.superblocks.com/enterprise/cloud-prem/configure/network-firewall.md) setups don't apply. To filter outbound traffic, route it through your own firewall in your VPC's routing.

## Subnets

Your private subnet can also hold your nodes and the EKS control plane's network interfaces. Database, public, and [agent subnets](#agent-subnets) must each be their own subnet, so at a minimum the control plane needs public, private, and agent subnets, and each data plane needs private and database subnets.

Each VPC uses at least two availability zones, with these subnets in every zone. [Agent subnets](#agent-subnets) only need to be in zones that AgentCore supports, at least two.

### Control plane

![Control plane VPC subnets in each availability zone: public, private, node, and EKS control plane subnets, plus agent subnets for the builder agent, the Superblocks agent, and customer-defined agents. Inbound traffic arrives through an internet gateway, and the private and node subnets leave through your outbound path](https://mintcdn.com/superblocks/D16HqRuTvcU16fjp/images/enterprise-deployment/byo-vpc-control-plane.webp?fit=max\&auto=format\&n=D16HqRuTvcU16fjp\&q=85\&s=3ed6f1a263edc472f5a89d0d117beddc)

Set these subnets in each availability zone:

| Subnet | What it holds | Required |
| - | - | - |
| Public | The internet-facing load balancer for your instance. Must route to an internet gateway | Yes. Its own subnet |
| Private | VPC endpoints, internal load balancers, and other private workloads | Yes |
| Node | EKS cluster nodes. Must have the `karpenter.sh/discovery` tag | Yes. Can be your private subnet |
| EKS control plane | The EKS control plane's network interfaces | Yes. Can be your private subnet |
| Agent | Network interfaces for Superblocks agents: the builder agent, the Superblocks agent, and customer-defined agents. No route to the internet | Yes. One per agent type, or one shared agent subnet. Can't be your private subnet. See [Agent subnets](#agent-subnets) |

#### Agent subnets

The control plane VPC also needs subnets for Superblocks agents. Agents run on [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) in your Managed BYOC account. Each agent session runs in its own AWS-managed microVM, with its network interface in your agent subnets.

* **A subnet for each agent type.** In at least two availability zones that AgentCore supports, give the builder agent, the Superblocks agent, and customer-defined agents each their own subnet. Separate subnets let Superblocks apply network ACLs to each agent type, and let you capture each agent type's traffic separately with your own VPC Flow Logs.
* **Or one shared agent subnet.** You can use a single agent subnet in each availability zone for all three agent types instead. It must be its own subnet: it can't be your private subnet.
* **Availability zones that AgentCore supports.** AgentCore runs only in certain availability zones in each region. Create agent subnets only in zones it supports, so they may not cover every zone your VPC uses. See the [AZ IDs AgentCore doesn't support](https://docs.superblocks.com/enterprise/cloud-prem/supported-regions.md#availability-zones) in each control plane region.
* **No route to the internet.** Agent subnets can't route to a NAT gateway, an internet gateway, or any other outbound path, so they can't be your private or node subnets. Agents reach only the Superblocks internal load balancer and [VPC endpoints](#vpc-endpoints), and accept no inbound traffic.

Superblocks creates the security groups and the internal load balancer that agents use. Agents' built-in Browser and Code Interpreter tools run in AWS-managed sandboxes, so agents don't need an internet route to use them.

### Data planes

![Data plane VPC subnets in each availability zone: an optional public subnet of your own for a NAT gateway, then private, database, node, and EKS control plane subnets. AWS Global Accelerator delivers inbound traffic to the internal load balancer in the node subnets, an internet gateway is attached to the VPC, and the private and node subnets leave through your outbound path](https://mintcdn.com/superblocks/D16HqRuTvcU16fjp/images/enterprise-deployment/byo-vpc-data-plane.webp?fit=max\&auto=format\&n=D16HqRuTvcU16fjp\&q=85\&s=52939f0fe16a46e35ca1ce0442b6c4f9)

Set these subnets in each availability zone:

| Subnet | What it holds | Required |
| - | - | - |
| Private | VPC endpoints and other private workloads | Yes |
| Database | The data plane's App Databases | Yes. Its own subnet, in at least two availability zones |
| Node | EKS cluster nodes. Must have the `karpenter.sh/discovery` tag and be a `/22` or larger | No. Uses your private subnet if you don't set one |
| EKS control plane | The EKS control plane's network interfaces | No. Uses your private subnet if you don't set one |

Use a dedicated node subnet when you can

Managed BYOC nodes run isolated sandbox environments. A dedicated node subnet lets you write firewall, routing, and network ACL rules that apply to Managed BYOC's nodes alone. It also keeps a spike in sandbox demand from using up the IP addresses your load balancers, VPC endpoints, and EKS upgrades need.

### Subnet sizes

Each subnet must be at least the minimum size in every availability zone.

| Subnet | Minimum | Recommended |
| - | - | - |
| Public | `/27` | `/24` |
| Private | `/27` | `/24` |
| Node, control plane | None | `/20` |
| Node, data planes | `/22` | `/20` |
| EKS control plane | `/28` | `/28` |
| Agent | `/28` | `/26` |
| Database | None | `/28` |

* Subnets with a load balancer (public and private) need at least eight free IP addresses.
* Node subnets hold your nodes and their pods, so they need the most room.
* If your nodes or EKS control plane share your private subnet, size it for everything in it.

## VPC endpoints

The control plane VPC needs the endpoints marked required below, even if it has a NAT gateway, because [agent subnets](#agent-subnets) have no internet route. The rest are optional: create them to keep AWS traffic off your outbound path.

| Endpoint | Type | Needed for |
| - | - | - |
| `s3` | Gateway | Control plane (required) and data planes |
| `ecr.api` | Interface | Control plane (required) and data planes |
| `ecr.dkr` | Interface | Control plane (required) and data planes |
| `logs` | Interface | Control plane (required) and data planes |
| `bedrock-agentcore` | Interface | Control plane (required) |
| `sts` | Interface | Control plane and data planes |
| `ec2` | Interface | Data planes |
| `elasticloadbalancing` | Interface | Data planes |

Endpoints only reach AWS services in your VPC's own region. Without [image mirroring](https://docs.superblocks.com/enterprise/cloud-prem/configure/index.md), Superblocks container images come from the Superblocks registry in `us-east-1`, so outside `us-east-1` they're pulled over your outbound path.

Interface endpoints and App Databases

Each data plane's App Databases call AWS STS and EC2. If your VPC has interface endpoints for those services with private DNS, the calls resolve to the endpoints' private addresses, and Managed BYOC's network policy blocks them unless you set those addresses in the bootstrap.

## Egress IP addresses

Managed BYOC publishes the public IP addresses its outbound traffic leaves from, so you can add them to the allowlists of databases and APIs your apps connect to. With your own VPC, Managed BYOC finds these addresses from the available public NAT gateways in the VPC.

Set your egress IP addresses in the bootstrap instead when:

* **Outbound traffic doesn't leave through a NAT gateway in the VPC.** For example, it goes through a transit gateway, a shared egress VPC, or a proxy.
* **The VPC is shared with other workloads.** Some of its NAT gateways may not be used by Managed BYOC.

List each address as a `/32` CIDR, such as `203.0.113.10/32`.

## Use your VPC

1. Set up your VPC to meet the [VPC requirements](#vpc-requirements), tag each node subnet, and add [agent subnets](#agent-subnets) to the control plane VPC.
2. Run the [bootstrap](https://docs.superblocks.com/enterprise/cloud-prem/deployment-guide.md#the-bootstrap)'s setup script. It creates the bootstrap's settings file, `superblocks.tfvars`.
3. In `superblocks.tfvars`, add the VPC settings for the [control plane](#control-plane-settings) and for each [data plane](#data-plane-settings) that uses your VPC.
4. Run the bootstrap. It checks each VPC against the requirements and fails, naming the VPC or subnet, if one isn't met.
5. Tell your deployment team. Superblocks deploys into your VPC at the next deployment.

## Bootstrap settings

### Control plane settings

The setup script writes a `network` setting with a `subnets` block that describes a VPC for Managed BYOC to build. Replace `subnets` with an `existing` block that describes your VPC, and set `vpc_cidr` to your VPC's primary CIDR. Keep your `tags` value. For example:

```hcl theme={null}
network = {
  vpc_cidr = "10.0.0.0/16" # Your VPC's primary IPv4 CIDR
  tags     = {}            # Keep the value the setup script wrote

  existing = {
    vpc_id = "vpc-0123456789abcdef0"

    subnets = {
      "usw2-az1" = {
        public        = "subnet-0a1b2c3d4e5f60001"
        private       = "subnet-0a1b2c3d4e5f60002"
        eks_nodes     = "subnet-0a1b2c3d4e5f60003" # A dedicated node subnet
        control_plane = "subnet-0a1b2c3d4e5f60002" # Your private subnet
      }
      "usw2-az2" = {
        public        = "subnet-0a1b2c3d4e5f60004"
        private       = "subnet-0a1b2c3d4e5f60005"
        eks_nodes     = "subnet-0a1b2c3d4e5f60006"
        control_plane = "subnet-0a1b2c3d4e5f60005"
      }
      # Recommended: a third availability zone, such as "usw2-az3", with the same four subnets
    }

    # Optional. Only when you set your egress IP addresses explicitly.
    # nat_egress_cidrs = ["203.0.113.10/32", "203.0.113.11/32"]
  }
}
```

| Setting | Type | Description |
| - | - | - |
| `network.vpc_cidr` | String | Your VPC's primary IPv4 CIDR |
| `network.existing.vpc_id` | String | Your VPC's ID |
| `network.existing.subnets` | Map of AZ ID to subnet IDs | For each availability zone: `public`, `private`, `eks_nodes`, and `control_plane`. All four are required. `eks_nodes` and `control_plane` can be your private subnet |
| `network.existing.nat_egress_cidrs` | List of `/32` CIDRs | Optional. Your [egress IP addresses](#egress-ip-addresses), when you set them explicitly |

Set either `subnets` or `existing`, not both, or the bootstrap fails.

### Data plane settings

The setup script writes a `dataplanes` setting with each data plane's region and data tags. Add a `network` block to each data plane that uses your VPC. For example:

```hcl theme={null}
dataplanes = {
  "dp-prod" = {
    region    = "us-west-2"
    data_tags = ["production"]

    network = {
      vpc_cidr = "10.20.0.0/16" # This VPC's primary IPv4 CIDR

      existing = {
        vpc_id = "vpc-0fedcba9876543210"

        subnets = {
          "usw2-az1" = {
            private  = "subnet-0f1e2d3c4b5a60001"
            database = "subnet-0f1e2d3c4b5a60002"
            # eks_nodes and control_plane are optional and default to private
          }
          "usw2-az2" = {
            private  = "subnet-0f1e2d3c4b5a60003"
            database = "subnet-0f1e2d3c4b5a60004"
          }
        }

        # Optional. Only when you set your egress IP addresses explicitly.
        # nat_egress_cidrs = ["203.0.113.20/32"]

        # Optional. Only when the VPC has sts and ec2 interface endpoints with private DNS.
        # vpc_endpoint_interface_cidrs = ["10.20.8.11/32", "10.20.8.12/32"]
      }
    }
  }
}
```

| Setting | Type | Description |
| - | - | - |
| `network.vpc_cidr` | String | The VPC's primary IPv4 CIDR |
| `network.existing.vpc_id` | String | The VPC's ID |
| `network.existing.subnets` | Map of AZ ID to subnet IDs | For each availability zone: `private` (required), `database` (required in at least two availability zones), and `eks_nodes` and `control_plane` (optional, default to `private`) |
| `network.existing.nat_egress_cidrs` | List of `/32` CIDRs | Optional. Your [egress IP addresses](#egress-ip-addresses), when you set them explicitly |
| `network.existing.vpc_endpoint_interface_cidrs` | List of `/32` CIDRs | Optional. The private IP addresses of the `sts` and `ec2` interface endpoints, if the VPC has them with private DNS |

Re-running the setup script removes data plane network settings

The setup script rewrites the whole `dataplanes` setting each time it runs. If you run it again, add each data plane's `network` block back before you run the bootstrap.

## Related

* [Optional configurations](https://docs.superblocks.com/enterprise/cloud-prem/configure/index.md)
* [AWS Network Firewall](https://docs.superblocks.com/enterprise/cloud-prem/configure/network-firewall.md)
* [Managed BYOC deployment guide](https://docs.superblocks.com/enterprise/cloud-prem/deployment-guide.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.