diff --git a/calico-cloud/networking/egress/egress-gateway-host-ip.mdx b/calico-cloud/networking/egress/egress-gateway-host-ip.mdx new file mode 100644 index 0000000000..a63d87fb51 --- /dev/null +++ b/calico-cloud/networking/egress/egress-gateway-host-ip.mdx @@ -0,0 +1,128 @@ +--- +description: Configure egress gateways to use the host node IP as the source address for traffic leaving the cluster. +--- + +# Configure egress gateways with host IP support + +## Big picture + +Configure an existing egress gateway deployment so that traffic exiting through it appears to come +from the **host address** of the host running the gateway pod, rather than the gateway's pod IP. + +## Value + +External firewalls and services often allowlist traffic by source IP. When egress gateway pod IPs +are not routable outside the cluster or simply not convenient to manage using the gateway's +**host address** as the source address gives external systems a stable, well-known set of IPs to +allowlist. + +Any number of application pods can multiplex their outbound traffic through a small fixed set of +egress gateways, and all of those connections will appear to come from the gateways' host address. + +:::note + +Host IP mode is most commonly used with the [on-premises setup](egress-gateway-on-prem.mdx), where +the alternative source IP would be a non-routable pod IP. On [AWS](egress-gateway-aws.mdx) and +[Azure](egress-gateway-azure.mdx) setups, gateways already use native VPC/VNet IPs that are +routable on the underlying network - enabling host IP mode there replaces those native IPs with +the host address. + +::: + +## Concepts + +### Source IP and `natOutgoing` + +When an outbound application flow leaves the cluster through an egress gateway, the source IP seen +by external services depends on the `natOutgoing` setting of the egress gateway's +[IP pool](../../reference/resources/ippool.mdx): + +- `natOutgoing: false` - the flow's source IP is the egress gateway's **pod IP**. This + is the default for all egress gateway setup guides. +- `natOutgoing: true` - the flow's source IP is the **host address** of the node where the egress + gateway pod is running. + +## Before you begin + +These instructions require a functioning egress gateway deployment. +For setup, see [our egress gateway guides](index.mdx). + +## How to + +- [Enable natOutgoing on the egress IP pool](#enable-host-ip-mode-on-the-egress-ip-pool) +- [Pin egress gateways to specific nodes](#pin-egress-gateways-to-specific-nodes) +- [Affine client pods to a specific node](#affine-client-pods-to-a-specific-node) +- [Verify the source IP](#verify-the-source-ip) + +### Enable natOutgoing on the egress IP pool + +Set `natOutgoing: true` on the IP pool used by your egress gateways: + +```bash +kubectl patch ippool egress-ippool-1 --type='merge' -p '{"spec":{"natOutgoing":true}}' +``` + +Outbound traffic leaving the cluster through a gateway in this pool will now be SNAT'd to the node +IP of the gateway's host, instead of the gateway's pod IP. + +### Pin egress gateways to specific nodes + +The source IP that external services see depends on which node the gateway pod is +scheduled to. To make this deterministic, set a `nodeSelector` on the gateway template: + +```bash +kubectl patch egressgateway egress-gateway -n default --type='merge' -p \ + '{"spec":{"template":{"spec":{"nodeSelector":{"kubernetes.io/hostname":""}}}}}' +``` + +Traffic passing through this gateway will exit the cluster with that node's IP as the +source address. + +Without pinning, the source IP will still be a node IP, but it could be any node the gateway +happens to land on. + +### Affine client pods to a specific node + +This step is optional. If you want a particular client's traffic to deterministically exit through +a particular node's IP, schedule the client to the same node as a gateway and apply an +[EgressGatewayPolicy](egress-gateway-on-prem.mdx#configure-a-namespace-or-pod-to-use-an-egress-gateway-egress-gateway-policy-method) +with `gatewayPreference: PreferNodeLocal`. The client will then prefer the gateway on its own node, +ensuring traffic exits with that node's IP. + +For example, to pin a workload to a specific node, add a `nodeSelector` to its pod spec: + +```yaml +spec: + nodeSelector: + kubernetes.io/hostname: +``` + +### Verify the source IP + +Identify the node hosting the egress gateway: + +```bash +kubectl get pod -l egress-code=red -o wide +``` + +Note the value in the `NODE` column, then look up that node's InternalIP: + +```bash +kubectl get node -o jsonpath='{.status.addresses[?(@.type=="InternalIP")].address}' +``` + +Initiate an outbound connection from one of your client pods to a server outside the cluster, and +observe the source IP on the server. With host IP mode, it should match the node's InternalIP +above -- not the egress gateway's pod IP or any IP from the egress IP pool. + +:::note + +For return traffic to reach the gateway, the external server must know how to route to the egress +gateway's node IP. + +::: + +## Additional resources + +- [Egress gateway maintenance](egress-gateway-maintenance.mdx) +- [FelixConfiguration `egressIP...` fields](../../reference/resources/felixconfig.mdx#spec) diff --git a/calico-enterprise/networking/egress/egress-gateway-host-ip.mdx b/calico-enterprise/networking/egress/egress-gateway-host-ip.mdx new file mode 100644 index 0000000000..a63d87fb51 --- /dev/null +++ b/calico-enterprise/networking/egress/egress-gateway-host-ip.mdx @@ -0,0 +1,128 @@ +--- +description: Configure egress gateways to use the host node IP as the source address for traffic leaving the cluster. +--- + +# Configure egress gateways with host IP support + +## Big picture + +Configure an existing egress gateway deployment so that traffic exiting through it appears to come +from the **host address** of the host running the gateway pod, rather than the gateway's pod IP. + +## Value + +External firewalls and services often allowlist traffic by source IP. When egress gateway pod IPs +are not routable outside the cluster or simply not convenient to manage using the gateway's +**host address** as the source address gives external systems a stable, well-known set of IPs to +allowlist. + +Any number of application pods can multiplex their outbound traffic through a small fixed set of +egress gateways, and all of those connections will appear to come from the gateways' host address. + +:::note + +Host IP mode is most commonly used with the [on-premises setup](egress-gateway-on-prem.mdx), where +the alternative source IP would be a non-routable pod IP. On [AWS](egress-gateway-aws.mdx) and +[Azure](egress-gateway-azure.mdx) setups, gateways already use native VPC/VNet IPs that are +routable on the underlying network - enabling host IP mode there replaces those native IPs with +the host address. + +::: + +## Concepts + +### Source IP and `natOutgoing` + +When an outbound application flow leaves the cluster through an egress gateway, the source IP seen +by external services depends on the `natOutgoing` setting of the egress gateway's +[IP pool](../../reference/resources/ippool.mdx): + +- `natOutgoing: false` - the flow's source IP is the egress gateway's **pod IP**. This + is the default for all egress gateway setup guides. +- `natOutgoing: true` - the flow's source IP is the **host address** of the node where the egress + gateway pod is running. + +## Before you begin + +These instructions require a functioning egress gateway deployment. +For setup, see [our egress gateway guides](index.mdx). + +## How to + +- [Enable natOutgoing on the egress IP pool](#enable-host-ip-mode-on-the-egress-ip-pool) +- [Pin egress gateways to specific nodes](#pin-egress-gateways-to-specific-nodes) +- [Affine client pods to a specific node](#affine-client-pods-to-a-specific-node) +- [Verify the source IP](#verify-the-source-ip) + +### Enable natOutgoing on the egress IP pool + +Set `natOutgoing: true` on the IP pool used by your egress gateways: + +```bash +kubectl patch ippool egress-ippool-1 --type='merge' -p '{"spec":{"natOutgoing":true}}' +``` + +Outbound traffic leaving the cluster through a gateway in this pool will now be SNAT'd to the node +IP of the gateway's host, instead of the gateway's pod IP. + +### Pin egress gateways to specific nodes + +The source IP that external services see depends on which node the gateway pod is +scheduled to. To make this deterministic, set a `nodeSelector` on the gateway template: + +```bash +kubectl patch egressgateway egress-gateway -n default --type='merge' -p \ + '{"spec":{"template":{"spec":{"nodeSelector":{"kubernetes.io/hostname":""}}}}}' +``` + +Traffic passing through this gateway will exit the cluster with that node's IP as the +source address. + +Without pinning, the source IP will still be a node IP, but it could be any node the gateway +happens to land on. + +### Affine client pods to a specific node + +This step is optional. If you want a particular client's traffic to deterministically exit through +a particular node's IP, schedule the client to the same node as a gateway and apply an +[EgressGatewayPolicy](egress-gateway-on-prem.mdx#configure-a-namespace-or-pod-to-use-an-egress-gateway-egress-gateway-policy-method) +with `gatewayPreference: PreferNodeLocal`. The client will then prefer the gateway on its own node, +ensuring traffic exits with that node's IP. + +For example, to pin a workload to a specific node, add a `nodeSelector` to its pod spec: + +```yaml +spec: + nodeSelector: + kubernetes.io/hostname: +``` + +### Verify the source IP + +Identify the node hosting the egress gateway: + +```bash +kubectl get pod -l egress-code=red -o wide +``` + +Note the value in the `NODE` column, then look up that node's InternalIP: + +```bash +kubectl get node -o jsonpath='{.status.addresses[?(@.type=="InternalIP")].address}' +``` + +Initiate an outbound connection from one of your client pods to a server outside the cluster, and +observe the source IP on the server. With host IP mode, it should match the node's InternalIP +above -- not the egress gateway's pod IP or any IP from the egress IP pool. + +:::note + +For return traffic to reach the gateway, the external server must know how to route to the egress +gateway's node IP. + +::: + +## Additional resources + +- [Egress gateway maintenance](egress-gateway-maintenance.mdx) +- [FelixConfiguration `egressIP...` fields](../../reference/resources/felixconfig.mdx#spec) diff --git a/sidebars-calico-cloud.js b/sidebars-calico-cloud.js index eeb0e0105f..8eb1d11923 100644 --- a/sidebars-calico-cloud.js +++ b/sidebars-calico-cloud.js @@ -371,6 +371,7 @@ module.exports = { link: { type: 'doc', id: 'networking/egress/index' }, items: [ 'networking/egress/egress-gateway-on-prem', + 'networking/egress/egress-gateway-host-ip', 'networking/egress/egress-gateway-aws', 'networking/egress/egress-gateway-azure', 'networking/egress/egress-gateway-maintenance', diff --git a/sidebars-calico-enterprise.js b/sidebars-calico-enterprise.js index 1f4a792134..6296d3a831 100644 --- a/sidebars-calico-enterprise.js +++ b/sidebars-calico-enterprise.js @@ -191,6 +191,7 @@ module.exports = { link: { type: 'doc', id: 'networking/egress/index' }, items: [ 'networking/egress/egress-gateway-on-prem', + 'networking/egress/egress-gateway-host-ip', 'networking/egress/egress-gateway-azure', 'networking/egress/egress-gateway-aws', 'networking/egress/egress-gateway-maintenance',