---
title: "Route tables"
description: "Where traffic leaving a VPC subnet goes. Each VPC's main table, custom tables, subnet associations, default routes to the Network Gateway, and private subnets."
---

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

# Route tables

A **route table** decides where traffic leaving a [VPC](/private-networks/vpcs) subnet goes. Each
subnet uses exactly one table. A subnet whose table has no route to the VPC's
[Network Gateway](/private-networks/network-gateways) is a **private subnet**: nothing in it
reaches the internet or is reached from it, even with public addresses. In the console, open
**Private Networks**, then **Route tables**.

- **The main table.** Every VPC has one, called `main`, made with the VPC and deleted with it. A
  subnet uses it unless it's associated with another table.
- **Custom tables.** Create more in a VPC and associate subnets with them, for example a table
  without internet routes for the subnets that shouldn't have any.
- **Local routes.** Every table has a `local` route for each of the VPC's ranges (IPv4 and IPv6):
  traffic between the VPC's subnets always stays in the VPC. They can't be changed or removed.
- **Routes to the gateway.** `0.0.0.0/0` and `::/0` to the VPC's Network Gateway give a subnet its
  internet path, one family each.
- **Attaching a gateway adds no routes.** Add them to the table, or let the console's attach dialog
  or the CLI add them to the main table.
- **Free.** Route tables aren't billed.

A VPC that had a Network Gateway attached when route tables arrived has both default routes to it
in its main table, so its subnets kept their internet path.

## Route tables

| Field | Meaning |
| --- | --- |
| `vpc` | Its VPC (`vpc_…`). Fixed |
| `main` | `true` for the VPC's main table. Fixed |
| `routes` | Its routes, `local` first: `{ destination, target: { type, id }, state }` |
| `subnets` | The subnets that use it (for the main table, every subnet not associated with another) |

| Action | Console | API | CLI |
| --- | --- | --- | --- |
| List (by VPC) | **Route tables**, the **VPC** filter | [ListRouteTables](/network-api/ListRouteTables/) `?vpc=` | `ezgh compute route-tables list --vpc <vpc>` |
| Create | **Create route table** | [CreateRouteTable](/network-api/CreateRouteTable/) `{ name, vpc, description?, tags? }` | `ezgh compute route-tables create <name> --vpc <vpc>` |
| Rename, describe, tag | **Edit** | [UpdateRouteTable](/network-api/UpdateRouteTable/) | `ezgh compute route-tables update <table>` |
| Delete | **Delete** | [DeleteRouteTable](/network-api/DeleteRouteTable/) | `ezgh compute route-tables delete <table>` |

A new table has only its local routes. Every VPC's main table is called `main`, so give tables by
ID (`rtb_…`) where a name would be ambiguous.

| Refusal | When |
| --- | --- |
| `409 route_table_is_main` | Delete: the VPC's main table goes with the VPC |
| `409 route_table_in_use` | Delete: subnets are associated with it. Associate them with another table first |
| `409 vpc_in_use` | Deleting a VPC that still has custom route tables. Delete them first |

## Routes

A route sends traffic for a destination to a target. Today a table holds, besides its local
routes:

| Destination | Target |
| --- | --- |
| `0.0.0.0/0` | The VPC's Network Gateway (`ngw_…`): IPv4 internet |
| `::/0` | The VPC's Network Gateway: IPv6 internet |
| `0.0.0.0/0`, or any IPv4 range outside the VPC | A [NAT Gateway](/private-networks/nat-gateways) (`nat_…`): outbound IPv4 internet for a private subnet |

A route can also send traffic to one of your own instances: see
[Routing through instances](/private-networks/routing-through-instances).

Each route's `state` is `active`, or `blackhole` while its target is gone: the gateway is detached
from the VPC or deleted. A blackhole route drops its traffic; re-attaching the same gateway makes it
`active` again. Routes are never removed for you: remove one yourself.

Edit routes one destination at a time. Setting a destination creates its route or replaces its
target; removing one that isn't there does nothing. Neither touches other routes, so two people or
scripts editing different destinations of one table don't undo each other.

| Action | Console | API | CLI |
| --- | --- | --- | --- |
| Add or change a route | **Add route**, or a route's **Change** | [SetRoutes](/network-api/SetRoutes/) `{ routes: [{ destination, target: { type, id } }] }` | `ezgh compute route-tables routes set <table> <destination> --target <ngw_…>` |
| Remove routes | A route's **Remove** | [RemoveRoutes](/network-api/RemoveRoutes/) `{ destinations }` | `ezgh compute route-tables routes delete <table> <destination>…` |
| Replace the whole set | | [ReplaceRoutes](/network-api/ReplaceRoutes/) `{ routes }`, `If-Match` optional | `ezgh compute route-tables routes replace <table> --file <routes.json>` |

```sh
ezgh compute route-tables routes set rtb_8k2m0x7qpe4a 0.0.0.0/0 --target ngw_3dg3k9m2x0qa
ezgh compute route-tables routes set rtb_8k2m0x7qpe4a ::/0 --target ngw_3dg3k9m2x0qa
```

**Replacing the whole set** writes exactly the routes you send. The `local` routes may be included
as a read shows them; they're kept as they are. A read answers an `ETag` that changes with every
route write: send it as `If-Match` and the replace is refused (`412 precondition_failed`) if the
routes changed since. From a `get -o json` document, `routes replace` refuses when the table changed
after the document was read.

| Refusal | When |
| --- | --- |
| `409 vpc_has_no_gateway` | The target isn't the Network Gateway attached to the table's VPC |
| `412 precondition_failed` | Replace: the `If-Match` is stale |
| `400 invalid_request` | A destination that isn't a canonical CIDR, a `local` route, or the same destination twice |

## Associate a subnet

A subnet's `routeTable` is the table it uses: its own, or the VPC's main table. Associate it with
another table of its VPC, or put it back on the main table:

| Console | API | CLI |
| --- | --- | --- |
| The subnet's **Change route table** | [UpdateSubnet](/network-api/UpdateSubnet/) `{ routeTable: "rtb_…" }`, or `{ routeTable: null }` for the main table | `ezgh compute subnets update <subnet> --route-table <table>`, or `--route-table main` |

The subnet's interfaces follow the new table's routes from their next packet.

## Private subnets

A subnet whose table has no `active` route to the gateway in a family has no internet path in that
family, in either direction:

- A public IPv4 address associated with one of its interfaces stays associated, but carries no
  traffic until the subnet's table routes `0.0.0.0/0` to the gateway. The same holds for an
  interface's public IPv6 `/64` and `::/0`.
- Traffic to the VPC's other subnets is unaffected: the `local` routes cover it.

To make a subnet private, associate it with a table that has no route to the gateway:

```sh
ezgh compute route-tables create private --vpc main
ezgh compute subnets update db --route-table private
```

## Attaching a Network Gateway

Attaching a gateway changes no routes: until a table routes to it, it carries no traffic.

- **Console:** the attach dialog's **Add a default route to the main table**, on by default, adds
  `0.0.0.0/0` and `::/0` to the main table after the attach, where the table lacks them or they
  point at a gateway that's gone. It shows which before you attach.
- **CLI:** `ezgh compute network-gateways attach <gateway> --vpc <vpc>` does the same
  (`--add-default-route`, on by default; ezgh 0.38.0 or later), and says on stderr what it added.
  `--add-default-route=false` leaves the routes alone.
- **API:** [AttachNetworkGateway](/network-api/AttachNetworkGateway/) adds no routes. Call
  [SetRoutes](/network-api/SetRoutes/) on the main table after it.

## Limits

| Limit | Value | |
| --- | --- | --- |
| Route tables per VPC, its main table included | 20 | [Quota](/quotas/default-quotas#network) `network.routeTablesPerVpc`, up to 200 |
| Routes per route table, not counting `local` routes | 50 | Quota `network.routes.perRouteTable`, up to 200 |
| Route tables per subnet | 1 | Fixed |

## IAM

| Action | On |
| --- | --- |
| `network.routeTables.list`, `network.routeTables.create` | The project |
| `network.routeTables.get`, `network.routeTables.update`, `network.routeTables.delete` | The route table |
| `network.routeTables.updateRoutes` | The route table: add, change, remove and replace its routes |
| `network.routeTables.associate` | The route table a subnet is associated with, and `network.subnets.update` on the subnet |

`NetworkFullAccess` has them all; `NetworkReadOnlyAccess` and `ReadOnlyAccess` have the list and
view actions. See [IAM](/compute/iam).

Source: https://docs.ezghcloud.com/private-networks/route-tables/index.mdx
