Skip to content

Commit 57d3612

Browse files
committed
Improvement: Tweak line wrapping for the ip-masq-agent task page.
1 parent 2f334e2 commit 57d3612

File tree

1 file changed

+48
-15
lines changed

1 file changed

+48
-15
lines changed

content/en/docs/tasks/administer-cluster/ip-masq-agent.md

Lines changed: 48 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,39 +14,65 @@ This page shows how to configure and enable the `ip-masq-agent`.
1414
<!-- discussion -->
1515
## IP Masquerade Agent User Guide
1616

17-
The `ip-masq-agent` configures iptables rules to hide a pod's IP address behind the cluster node's IP address. This is typically done when sending traffic to destinations outside the cluster's pod [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) range.
17+
The `ip-masq-agent` configures iptables rules to hide a pod's IP address behind the cluster
18+
node's IP address. This is typically done when sending traffic to destinations outside the
19+
cluster's pod [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) range.
1820

1921
### **Key Terms**
2022

2123
* **NAT (Network Address Translation)**
22-
Is a method of remapping one IP address to another by modifying either the source and/or destination address information in the IP header. Typically performed by a device doing IP routing.
24+
Is a method of remapping one IP address to another by modifying either the source and/or
25+
destination address information in the IP header. Typically performed by a device doing IP routing.
2326
* **Masquerading**
24-
A form of NAT that is typically used to perform a many to one address translation, where multiple source IP addresses are masked behind a single address, which is typically the device doing the IP routing. In Kubernetes this is the Node's IP address.
27+
A form of NAT that is typically used to perform a many to one address translation, where
28+
multiple source IP addresses are masked behind a single address, which is typically the
29+
device doing the IP routing. In Kubernetes this is the Node's IP address.
2530
* **CIDR (Classless Inter-Domain Routing)**
26-
Based on the variable-length subnet masking, allows specifying arbitrary-length prefixes. CIDR introduced a new method of representation for IP addresses, now commonly known as **CIDR notation**, in which an address or routing prefix is written with a suffix indicating the number of bits of the prefix, such as 192.168.2.0/24.
31+
Based on the variable-length subnet masking, allows specifying arbitrary-length prefixes.
32+
CIDR introduced a new method of representation for IP addresses, now commonly known as
33+
**CIDR notation**, in which an address or routing prefix is written with a suffix indicating
34+
the number of bits of the prefix, such as 192.168.2.0/24.
2735
* **Link Local**
28-
A link-local address is a network address that is valid only for communications within the network segment or the broadcast domain that the host is connected to. Link-local addresses for IPv4 are defined in the address block 169.254.0.0/16 in CIDR notation.
29-
30-
The ip-masq-agent configures iptables rules to handle masquerading node/pod IP addresses when sending traffic to destinations outside the cluster node's IP and the Cluster IP range. This essentially hides pod IP addresses behind the cluster node's IP address. In some environments, traffic to "external" addresses must come from a known machine address. For example, in Google Cloud, any traffic to the internet must come from a VM's IP. When containers are used, as in Google Kubernetes Engine, the Pod IP will be rejected for egress. To avoid this, we must hide the Pod IP behind the VM's own IP address - generally known as "masquerade". By default, the agent is configured to treat the three private IP ranges specified by [RFC 1918](https://tools.ietf.org/html/rfc1918) as non-masquerade [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). These ranges are 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. The agent will also treat link-local (169.254.0.0/16) as a non-masquerade CIDR by default. The agent is configured to reload its configuration from the location */etc/config/ip-masq-agent* every 60 seconds, which is also configurable.
36+
A link-local address is a network address that is valid only for communications within the
37+
network segment or the broadcast domain that the host is connected to. Link-local addresses
38+
for IPv4 are defined in the address block 169.254.0.0/16 in CIDR notation.
39+
40+
The ip-masq-agent configures iptables rules to handle masquerading node/pod IP addresses when
41+
sending traffic to destinations outside the cluster node's IP and the Cluster IP range. This
42+
essentially hides pod IP addresses behind the cluster node's IP address. In some environments,
43+
traffic to "external" addresses must come from a known machine address. For example, in Google
44+
Cloud, any traffic to the internet must come from a VM's IP. When containers are used, as in
45+
Google Kubernetes Engine, the Pod IP will be rejected for egress. To avoid this, we must hide
46+
the Pod IP behind the VM's own IP address - generally known as "masquerade". By default, the
47+
agent is configured to treat the three private IP ranges specified by [RFC 1918](https://tools.ietf.org/html/rfc1918) as non-masquerade [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). These ranges are `10.0.0.0/8`, `172.16.0.0/12`, and
48+
`192.168.0.0 16`. The agent will also treat link-local (169.254.0.0/16) as a non-masquerade
49+
CIDR by default. The agent is configured to reload its configuration from the location */etc/config/ip-masq-agent* every 60 seconds, which is also configurable.
3150

3251
![masq/non-masq example](/images/docs/ip-masq.png)
3352

34-
The agent configuration file must be written in YAML or JSON syntax, and may contain three optional keys:
53+
The agent configuration file must be written in YAML or JSON syntax, and may contain three
54+
optional keys:
3555

3656
* `nonMasqueradeCIDRs`: A list of strings in
37-
[CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) notation that specify the non-masquerade ranges.
57+
[CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) notation that specify
58+
the non-masquerade ranges.
3859
* `masqLinkLocal`: A Boolean (true/false) which indicates whether to masquerade traffic to the
3960
link local prefix `169.254.0.0/16`. False by default.
4061
* `resyncInterval`: A time interval at which the agent attempts to reload config from disk.
4162
For example: '30s', where 's' means seconds, 'ms' means milliseconds.
4263

43-
Traffic to 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16) ranges will NOT be masqueraded. Any other traffic (assumed to be internet) will be masqueraded. An example of a local destination from a pod could be its Node's IP address as well as another node's address or one of the IP addresses in Cluster's IP range. Any other traffic will be masqueraded by default. The below entries show the default set of rules that are applied by the ip-masq-agent:
64+
Traffic to 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16 ranges will NOT be masqueraded. Any
65+
other traffic (assumed to be internet) will be masqueraded. An example of a local destination
66+
from a pod could be its Node's IP address as well as another node's address or one of the IP
67+
addresses in Cluster's IP range. Any other traffic will be masqueraded by default. The
68+
below entries show the default set of rules that are applied by the ip-masq-agent:
4469

4570
```shell
4671
iptables -t nat -L IP-MASQ-AGENT
4772
```
4873

4974
```none
75+
target prot opt source destination
5076
RETURN all -- anywhere 169.254.0.0/16 /* ip-masq-agent: cluster-local traffic should not be subject to MASQUERADE */ ADDRTYPE match dst-type !LOCAL
5177
RETURN all -- anywhere 10.0.0.0/8 /* ip-masq-agent: cluster-local traffic should not be subject to MASQUERADE */ ADDRTYPE match dst-type !LOCAL
5278
RETURN all -- anywhere 172.16.0.0/12 /* ip-masq-agent: cluster-local traffic should not be subject to MASQUERADE */ ADDRTYPE match dst-type !LOCAL
@@ -70,18 +96,22 @@ To create an ip-masq-agent, run the following kubectl command:
7096
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/ip-masq-agent/master/ip-masq-agent.yaml
7197
```
7298

73-
You must also apply the appropriate node label to any nodes in your cluster that you want the agent to run on.
99+
You must also apply the appropriate node label to any nodes in your cluster that you want the
100+
agent to run on.
74101

75102
```shell
76103
kubectl label nodes my-node node.kubernetes.io/masq-agent-ds-ready=true
77104
```
78105

79106
More information can be found in the ip-masq-agent documentation [here](https://github.com/kubernetes-sigs/ip-masq-agent)
80107

81-
In most cases, the default set of rules should be sufficient; however, if this is not the case for your cluster, you can create and apply a [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/) to customize the IP ranges that are affected. For example, to allow only 10.0.0.0/8 to be considered by the ip-masq-agent, you can create the following [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/) in a file called "config".
108+
In most cases, the default set of rules should be sufficient; however, if this is not the case
109+
for your cluster, you can create and apply a [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/) to customize the IP ranges that are affected. For example, to allow
110+
only 10.0.0.0/8 to be considered by the ip-masq-agent, you can create the following [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/) in a file called "config".
82111

83112
{{< note >}}
84-
It is important that the file is called config since, by default, that will be used as the key for lookup by the `ip-masq-agent`:
113+
It is important that the file is called config since, by default, that will be used as the key
114+
for lookup by the `ip-masq-agent`:
85115

86116
```yaml
87117
nonMasqueradeCIDRs:
@@ -96,7 +126,8 @@ Run the following command to add the config map to your cluster:
96126
kubectl create configmap ip-masq-agent --from-file=config --namespace=kube-system
97127
```
98128

99-
This will update a file located at `/etc/config/ip-masq-agent` which is periodically checked every `resyncInterval` and applied to the cluster node.
129+
This will update a file located at `/etc/config/ip-masq-agent` which is periodically checked
130+
every `resyncInterval` and applied to the cluster node.
100131
After the resync interval has expired, you should see the iptables rules reflect your changes:
101132

102133
```shell
@@ -111,7 +142,9 @@ RETURN all -- anywhere 10.0.0.0/8 /* ip-masq-agent:
111142
MASQUERADE all -- anywhere anywhere /* ip-masq-agent: outbound traffic should be subject to MASQUERADE (this match must come after cluster-local CIDR matches) */ ADDRTYPE match dst-type !LOCAL
112143
```
113144

114-
By default, the link local range (169.254.0.0/16) is also handled by the ip-masq agent, which sets up the appropriate iptables rules. To have the ip-masq-agent ignore link local, you can set `masqLinkLocal` to true in the ConfigMap.
145+
By default, the link local range (169.254.0.0/16) is also handled by the ip-masq agent, which
146+
sets up the appropriate iptables rules. To have the ip-masq-agent ignore link local, you can
147+
set `masqLinkLocal` to true in the ConfigMap.
115148

116149
```yaml
117150
nonMasqueradeCIDRs:

0 commit comments

Comments
 (0)