Skip to content

Gateway: Document "default" expose blocks for external peerings #251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Frostman merged 4 commits into from
Jan 23, 2026
Merged

Gateway: Document "default" expose blocks for external peerings #251

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
13ae29a
gateway: Remove unnecessary white space
qmonnet Jan 21, 2026
3a1e42e
gateway: Fix grammar and style for peering to external connections
qmonnet Jan 21, 2026
f0223c5
gateway: Move note on "ext." prefix, clarify requirement
qmonnet Jan 21, 2026
99531cb
gateway: Document overlap rules, "default" destination expose
qmonnet Jan 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 37 additions & 18 deletions docs/user-guide/gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,10 +139,18 @@ spec:
- cidr: 192.168.0.0/16 # Expose all IP addresses in the 192.168.0.0/16 CIDR block to vpc-1
```

Note that multiple VPCs cannot expose overlapping prefixes to a given VPC. For
example, if `vpc-1` and `vpc-3` are both peered with `vpc-2`, and `vpc-1`
exposes subnet `10.1.1.0/24` to `vpc-2`, then `vpc-3` cannot expose overlapping
prefix `10.1.0.0/16` to `vpc-2`. There is one exception to this rule: exposed
prefixes can overlap with an expose block marked as `default`, see section on
[peering for external connections](#gateway-peering-for-external-connections)
for details.

### Gateway Peering with Stateless NAT

Stateless NAT translates source and/or destination IP addresses for all packets that traverse
the peering, but it does not maintain any flow state for the connection. A
the peering, but it does not maintain any flow state for the connection. A
one-to-one mapping is established between the addresses exposed in the CIDRs for
`ips` and the addresses to use represented by the CIDRs in
`as`: each address from the first group is consistently mapped to a single
Expand Down Expand Up @@ -175,18 +183,15 @@ spec:
as:
- cidr: 10.22.22.0/25 # and exposed back to vpc-1.
- cidr: 10.22.22.128/25


```


### Gateway Peering with Stateful Source NAT

Stateful source NAT uses a flow table to track established connections.
When traffic is initiated from `vpc-1` to `vpc-2`, the flow table is updated
When traffic is initiated from `vpc-1` to `vpc-2`, the flow table is updated
with the connection details. In the return direction (from `vpc-2` to `vpc-1`
in the following example), the flow table is consulted to determine if the packet
is part of an established connection. If it is, the packet is allowed to pass
is part of an established connection. If it is, the packet is allowed to pass
through the peering. If it is not, the packet is dropped.
This behavior allows use of stateful NAT as a simple firewall.

Expand All @@ -208,9 +213,9 @@ spec:
as:
- cidr: 10.0.1.0/31 # but, NAT those addresses using the addresses in 10.0.1.0/31
nat: # Contains the NAT configuration
# Make NAT stateful, connections initiated from vpc-1 to vpc-2 will be added to the flow table.
# Make NAT stateful, connections initiated from vpc-1 to vpc-2 will be added to the flow table.
# An entry for the reverse direction will be added too, so that the receiving endpoint in vpc-2 can reply.
stateful:
stateful:
idleTimeout: 5m # Timeout connections after 5 minutes of inactivity (no packets received)
vpc-2:
expose:
Expand All @@ -222,14 +227,15 @@ spec:
# This restriction will be lifted in a future release.
```


### Gateway Peering for External Connections

The following YAML listings show how to expose a default route to the
`10.50.2.0/24` subnet inside of `vpc-02`. In this example the name of the
external is `example-ext`. Assuming this external is representing the WAN, this will
allow hosts inside of the `10.50.2.0/24` to the WAN. The following is an
example YAML file to create an external.
The following YAML listings show how to create an external and expose a default
route to the `10.50.2.0/24` subnet inside of `vpc-02`. In this example, the
name of the external is `example-ext`. Assuming this external represents the
WAN, this configuration allows hosts inside of the `10.50.2.0/24` subnet to
reach the WAN.

Here is the YAML fragment for creating the external:

```{.yaml .annotate linenums="1" title="example-external.yaml"}
apiVersion: vpc.githedgehog.com/v1beta1
Expand All @@ -241,12 +247,11 @@ spec:
inboundCommunity: 65102:5001
ipv4Namespace: default
outboundCommunity: 5001:65102

```

Once the external is created, the gateway can be used to create a peering
between the external and a VPC. The following YAML is an example of this
configuration. Note that the name of the external is prefixed with `ext.`.
configuration:

```{.yaml .annotate linenums="1" title="gw-peer-external.yaml"}
apiVersion: gateway.githedgehog.com/v1alpha1
Expand All @@ -257,10 +262,24 @@ spec:
peering:
ext.example-ext: # NOTE the name of the external is prefixed with "ext."
expose:
- ips:
- cidr: 0.0.0.0/0
- default: true # Fallback destination when no other expose matches
vpc-02:
expose:
- ips:
- cidr: 10.50.2.0/24
```

Note that the name of the external is prefixed with `ext.`: this is a
requirement.

Also, note how the external uses `default: true` instead of specifying the root
IPv4 prefix `0.0.0.0/0`. An `expose` block marked as `default: true` serves as
a default destination for all addresses _that do not otherwise match any of the
other prefixes exposed to the VPC_, whether or not these prefixes are from the
same peering. In our example, if `vpc-02` is additionally peered with `vpc-03`
which exposes `10.50.3.0/24`, all packets from `vpc-02` towards this subnet are
sent to `vpc-03`, and packets addressed to all other subnets from the IPv4
space are sent to the external `example-ext`.

For any given VPC, at most one remote `expose` block, among all peerings for
this VPC, can act as a `default` destination.