diff --git a/docs/user-guide/gateway.md b/docs/user-guide/gateway.md index f302659c..73ec6880 100644 --- a/docs/user-guide/gateway.md +++ b/docs/user-guide/gateway.md @@ -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 @@ -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. @@ -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: @@ -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 @@ -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 @@ -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.