diff --git a/_data/tasks.yml b/_data/tasks.yml index 1bf102676f..14c0dafc29 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -129,6 +129,7 @@ toc: - docs/tasks/administer-cluster/running-cloud-controller.md - docs/tasks/administer-cluster/highly-available-master.md - docs/tasks/administer-cluster/configure-multiple-schedulers.md + - docs/tasks/administer-cluster/ip-masq-agent.md - title: Change Cluster Size path: https://github.com/kubernetes/kubernetes/wiki/User-FAQ#how-do-i-change-the-size-of-my-cluster/ diff --git a/docs/admin/authentication.md b/docs/admin/authentication.md index b5d2d77ad6..ea5e6ac591 100644 --- a/docs/admin/authentication.md +++ b/docs/admin/authentication.md @@ -54,7 +54,7 @@ You can enable multiple authentication methods at once. You should usually use a - service account tokens for service accounts - at least one other method for user authentication. -When multiple are enabled, the first authenticator module +When multiple authenticator modules are enabled, the first module to successfully authenticate the request short-circuits evaluation. The API server does not guarantee the order authenticators run in. diff --git a/docs/getting-started-guides/scratch.md b/docs/getting-started-guides/scratch.md index eb5b37752b..3fdd726319 100644 --- a/docs/getting-started-guides/scratch.md +++ b/docs/getting-started-guides/scratch.md @@ -167,6 +167,8 @@ You can use a Kubernetes binary release (recommended) or build your Kubernetes b [Developer Documentation](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/). Only using a binary release is covered in this guide. Download the [latest binary release](https://github.com/kubernetes/kubernetes/releases/latest) and unzip it. +Server binary tarballs are no longer included in the Kubernetes final tarball, so you will need to locate and run +`./kubernetes/cluster/get-kube-binaries.sh` to download the client and server binaries. Then locate `./kubernetes/server/kubernetes-server-linux-amd64.tar.gz` and unzip *that*. Then, within the second set of unzipped files, locate `./kubernetes/server/bin`, which contains all the necessary binaries. diff --git a/docs/tasks/administer-cluster/ip-masq-agent.md b/docs/tasks/administer-cluster/ip-masq-agent.md new file mode 100644 index 0000000000..de7c7b9e69 --- /dev/null +++ b/docs/tasks/administer-cluster/ip-masq-agent.md @@ -0,0 +1,106 @@ +--- +title: IP Masquerade Agent User Guide +--- + +{% capture overview %} +This page shows how to configure and enable the ip-masq-agent. +{% endcapture %} + +{% capture prerequisites %} +Kubernetes 1.7 +{% include task-tutorial-prereqs.md %} + +{% endcapture %} + +{% capture discussion %} +## IP Masquerade Agent User Guide + +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. + +### **Key Terms** + +* **NAT (Network Address Translation)** + 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. +* **Masquerading** + 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. +* **CIDR (Classless Inter-Domain Routing)** + 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. +* **Link Local** + 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. + +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 GKE, 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. + +![masq/non-masq example](/images/docs/ip-masq.png) + +The agent configuration file must be written in yaml or json syntax, and may contain three optional keys: + +* **nonMasqueradeCIDRs:** A list of strings in [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) notation that specify the non-masquerade ranges. +* **masqLinkLocal:** A boolean (true / false) which indicates whether to masquerade traffic to the link local prefix 169.254.0.0/16. False by default. +* **resyncInterval:** An interval at which the agent attempts to reload config from disk. e.g. '30s' where 's' is seconds, 'ms' is milliseconds etc... + +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: + +``` +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 + +``` + +By default, in GCE/GKE starting with Kubernetes version 1.7.0, the ip-masq-agent will run in your cluster. If you are running in another environment, you can add the ip-masq-agent [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) to your cluster: + +{% endcapture %} + +{% capture steps %} + +## Create an ip-masq-agent +To create an ip-masq-agent, run the following kubectl command: + +` +kubectl create -f https://github.com/kubernetes-incubator/ip-masq-agent/blob/master/ip-masq-agent.yaml +` + +More information can be found in the ip-masq-agent documentation [here](https://github.com/kubernetes-incubator/ip-masq-agent) + +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](https://kubernetes.io/docs/tasks/configure-pod-container/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/configmap/) in a file called "config". +**Note:** 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: + +``` +nonMasqueradeCIDRs: + - 10.0.0.0/8 +resyncInterval: 60s + +``` + +Run the following command to add the config map to your cluster: + +``` +kubectl create configmap ip-masq-agent --from-file=config --namespace=kube-system +``` + +This will update a file located at */etc/config/ip-masq-agent* which is periodically checked every *resyscInterval* and applied to the cluster node. +After the resync interval has expired, you should see the iptables rules reflect your changes: + +``` +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 +``` + +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 config map. + +``` +nonMasqueradeCIDRs: + - 10.0.0.0/8 +resyncInterval: 60s +masqLinkLocal: true +``` +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/tasks/tools/install-kubectl.md b/docs/tasks/tools/install-kubectl.md index 0fd5514904..4c84c348fd 100644 --- a/docs/tasks/tools/install-kubectl.md +++ b/docs/tasks/tools/install-kubectl.md @@ -91,35 +91,45 @@ Here are a few methods to install kubectl. kubectl can be installed as part of the Google Cloud SDK. - 1. Install the [Google Cloud SDK](https://cloud.google.com/sdk/). - 2. Run the following command to install `kubectl`: - ```shell -gcloud components install kubectl -``` - 3. Run `kubectl version` to verify that the verison you've installed is sufficiently up-to-date. +1. Install the [Google Cloud SDK](https://cloud.google.com/sdk/). +2. Run the following command to install `kubectl`: + + gcloud components install kubectl + +3. Run `kubectl version` to verify that the verison you've installed is sufficiently up-to-date. + +## Install with snap on Ubuntu + +kubectl is available as a [snap](https://snapcraft.io/) application. + +1. If you are on Ubuntu or one of other Linux distributions that support [snap](https://snapcraft.io/docs/core/install) package manager, you can install with: + + sudo snap install kubectl --classic + +2. Run `kubectl version` to verify that the verison you've installed is sufficiently up-to-date. ## Install with Homebrew on macOS - 1. If you are on macOS and using [Homebrew](https://brew.sh/) package manager, you can install with: -```shell -brew install kubectl -``` - 2. Run `kubectl version` to verify that the verison you've installed is sufficiently up-to-date. +1. If you are on macOS and using [Homebrew](https://brew.sh/) package manager, you can install with: + + brew install kubectl + +2. Run `kubectl version` to verify that the verison you've installed is sufficiently up-to-date. ## Install with Chocolatey on Windows - 1. If you are on Windows and using [Chocolatey](https://chocolatey.org) package manager, you can install with: -```shell -choco install kubernetes-cli -``` - 2. Run `kubectl version` to verify that the verison you've installed is sufficiently up-to-date. - 3. Configure kubectl to use a remote kubernetes cluster: -```shell -cd C:\users\yourusername (Or wherever your %HOME% directory is) -mkdir .kube -cd .kube -touch config -``` +1. If you are on Windows and using [Chocolatey](https://chocolatey.org) package manager, you can install with: + + choco install kubernetes-cli + +2. Run `kubectl version` to verify that the verison you've installed is sufficiently up-to-date. +3. Configure kubectl to use a remote kubernetes cluster: + + cd C:\users\yourusername (Or wherever your %HOME% directory is) + mkdir .kube + cd .kube + touch config + Edit the config file with a text editor of your choice, such as Notepad for example. ## Configure kubectl @@ -136,9 +146,11 @@ $ kubectl cluster-info If you see a URL response, kubectl is correctly configured to access your cluster. If you see a message similar to the following, kubectl is not correctly configured: + ```shell The connection to the server was refused - did you specify the right host or port? ``` + ## Enabling shell autocompletion kubectl includes autocompletion support, which can save a lot of typing! diff --git a/images/docs/ip-masq.png b/images/docs/ip-masq.png new file mode 100644 index 0000000000..14a3fa631f Binary files /dev/null and b/images/docs/ip-masq.png differ