IP Masquerade Agent

This page explains how Container Engine's IP masquerade agent works.

IP masquerading is a form of network address translation (NAT) used to perform many-to-one IP address translations. Masquerading masks multiple source IP addresses behind a single address.

Using IP masquerading in your clusters increases their security by preventing individual Pod IP addresses from being exposed to traffic outside link-local and additional arbitrary IP ranges. Additionally, it allows you configure communication between IP ranges without masquerade, such as a Pod in the 192.168.0.0/16 range interacting with networking resources in the 10.0.0.0/8 range.

How ip-masq-agent works

IP masquerading in Container Engine is handled by ip-masq-agent, a tool which runs in clusters that run Kubernetes version 1.7.0 if network policy is enabled or you are using a cluster CIDR not in the 10.0.0.0/8 range .

ip-masq-agent configures iptables rules to handle masquerading Node/Pod IP addresses when sending traffic to destinations outside the Node’s IP and the cluster IP range. Pod IP addresses are masked behind their Node's address.

By default, the agent is configured to treat the three private IP ranges specified by RFC1918 as non-masquerade CIDRs. These ranges are 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. The agent will also treat the link-local range (169.254.0.0/16) as a non-masquerade CIDR by default.

By default, the agent reloads its configuration file from the /etc/config/ip-masq-agent file in its container every 60 seconds.

Below are the default set of iptables rules applied by ip-masq-agent:

iptables -t nat -L ip-masq-agent
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
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
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
RETURN     all  --  anywhere             192.168.0.0/16       /* ip-masq-agent: cluster-local traffic should not be subject to MASQUERADE */ ADDRTYPE match dst-type !LOCAL
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

Configuring the agent using a ConfigMap file

If the default set of rules shown above are not sufficient for your cluster, you can create and apply a ConfigMap to customize the affected IP ranges.

The ConfigMap file must be written in YAML or JSON syntax, and must be named config. The file may contain three keys, all of which are optional:

  • nonMasqueradeCIDRs: A list of strings in CIDR notation that specify the non-masquerade ranges.
  • masqLinkLocal: A boolean value which indicates whether to masquerade traffic to the link-local prefix (169.254.0.0/16). Default is false.
  • resyncInterval: An integer value representing the interval at which the agent attempts to sync its ConfigMap file from the disk. The format is Nx, where N is an integer and x is a time unit such as s or ms.

The example ConfigMap file below allows 10.0.0.0/8 to be considered by ip-masq-agent:

config.yaml

nonMasqueradeCIDRs:
  - 10.0.0.0/8
resyncInterval: 60s

config.json

{
  "nonMasqueradeCIDRs": [
    "10.0.0.0/8"
  ],
  "resyncInterval": "60s"
}

By default, the link-local range (169.254.0.0/16) is also handled by ip-masq-agent.

To have ip-masq-agent ignore the link-local range, set the value of the masqLinkLocal key to true in the ConfigMap. For example:

config.yaml

nonMasqueradeCIDRs:
  - 10.0.0.0/8
resyncInterval: 60s
masqLinkLocal: true

config.json

{
  "nonMasqueradeCIDRs": [
    "10.0.0.0/8"
  ],
  "resyncInterval": "60s",
  "masqLinkLocal": true
}

Adding a ConfigMap to your cluster

To add a ConfigMap to your cluster, run the following command from your shell or terminal window:

kubectl create configmap ip-masq-agent --from-file=config --namespace=kube-system

In the case of the example above, the change will take 60 seconds to apply. After the sync is complete, you should see the changes in iptables:

iptables -t nat -L IP-MASQ-AGENT
Chain IP-MASQ-AGENT (1 references)
target     prot opt source               destination
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
RETURN     all  --  anywhere             10.0.0.0/8           /* ip-masq-agent: cluster-local */
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

Manually creating an ip-masq-agent resource (optional)

You may need to manually create and configure ip-masq-agent.

To manually create an ip-masq-agent resource, run the following command;

kubectl create -f https://raw.githubusercontent.com/kubernetes-incubator/ip-masq-agent/master/ip-masq-agent.yaml

This command uses a configuration file provided by Kubernetes.

Next, apply the masq-agent-ds-ready label to Nodes and DaemonSets which will use ip-masq-agent resource you created:

kubectl label nodes [NAME] beta.kubernetes.io/masq-agent-ds-ready=true
kubectl label daemonsets [NAME] beta.kubernetes.io/masq-agent-ds-ready=true

where [NAME] is the name of the resource(s).

To deploy the ip-masq-agent resource, follow the steps in the sections above to write and apply a ConfigMap file.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Container Engine