From dfd2fed09c0b064e458b89802d5f07037c9258ac Mon Sep 17 00:00:00 2001 From: Steve Perry Date: Wed, 29 Mar 2017 09:20:12 -0700 Subject: [PATCH] Move Guide topic: Master-Node Communication. (#3098) --- _data/concepts.yml | 1 + docs/admin/master-node-communication.md | 101 +---------------- .../master-node-communication.md | 106 ++++++++++++++++++ 3 files changed, 110 insertions(+), 98 deletions(-) create mode 100644 docs/concepts/cluster-administration/master-node-communication.md diff --git a/_data/concepts.yml b/_data/concepts.yml index ab8e1be0ea..a4394fb302 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -52,6 +52,7 @@ toc: - docs/concepts/cluster-administration/sysctl-cluster.md - docs/concepts/cluster-administration/access-cluster.md - docs/concepts/cluster-administration/authenticate-across-clusters-kubeconfig.md + - docs/concepts/cluster-administration/master-node-communication.md - title: Storage section: diff --git a/docs/admin/master-node-communication.md b/docs/admin/master-node-communication.md index d654fd5173..285c2812ed 100644 --- a/docs/admin/master-node-communication.md +++ b/docs/admin/master-node-communication.md @@ -3,104 +3,9 @@ assignees: - dchen1107 - roberthbailey - liggitt -title: Master-Node communication +title: Master-Node Communication --- -* TOC -{:toc} +{% include user-guide-content-moved.md %} -## Overview - -This document catalogs the communication paths between the master (really the -apiserver) and the Kubernetes cluster. The intent is to allow users to -customize their installation to harden the network configuration such that -the cluster can be run on an untrusted network (or on fully public IPs on a -cloud provider). - -## Cluster -> Master - -All communication paths from the cluster to the master terminate at the -apiserver (none of the other master components are designed to expose remote -services). In a typical deployment, the apiserver is configured to listen for -remote connections on a secure HTTPS port (443) with one or more forms of -client [authentication](/docs/admin/authentication/) enabled. One or more forms -of [authorization](/docs/admin/authorization/) should be enabled, especially -if [anonymous requests](/docs/admin/authentication/#anonymous-requests) or -[service account tokens](/docs/admin/authentication/#service-account-tokens) -are allowed. - -Nodes should be provisioned with the public root certificate for the cluster -such that they can connect securely to the apiserver along with valid client -credentials. For example, on a default GCE deployment, the client credentials -provided to the kubelet are in the form of a client certificate. See -[kubelet TLS bootstrapping](/docs/admin/kubelet-tls-bootstrapping/) for -automated provisioning of kubelet client certificates. - -Pods that wish to connect to the apiserver can do so securely by leveraging a -service account so that Kubernetes will automatically inject the public root -certificate and a valid bearer token into the pod when it is instantiated. -The `kubernetes` service (in all namespaces) is configured with a virtual IP -address that is redirected (via kube-proxy) to the HTTPS endpoint on the -apiserver. - -The master components communicate with the cluster apiserver over the -insecure (not encrypted or authenticated) port. This port is typically only -exposed on the localhost interface of the master machine, so that the master -components, all running on the same machine, can communicate with the -cluster apiserver. Over time, the master components will be migrated to use -the secure port with authentication and authorization (see -[#13598](https://github.com/kubernetes/kubernetes/issues/13598)). - -As a result, the default operating mode for connections from the cluster -(nodes and pods running on the nodes) to the master is secured by default -and can run over untrusted and/or public networks. - -## Master -> Cluster - -There are two primary communication paths from the master (apiserver) to the -cluster. The first is from the apiserver to the kubelet process which runs on -each node in the cluster. The second is from the apiserver to any node, pod, -or service through the apiserver's proxy functionality. - -### apiserver -> kubelet - -The connections from the apiserver to the kubelet are used for fetching logs -for pods, attaching (through kubectl) to running pods, and using the kubelet's -port-forwarding functionality. These connections terminate at the kubelet's -HTTPS endpoint. - -By default, the apiserver does not verify the kubelet's serving certificate, -which makes the connection subject to man-in-the-middle attacks, and -**unsafe** to run over untrusted and/or public networks. - -To verify this connection, use the `--kubelet-certificate-authority` flag to -provide the apiserver with a root certificates bundle to use to verify the -kubelet's serving certificate. - -If that is not possible, use [SSH tunneling](/docs/admin/master-node-communication/#ssh-tunnels) -between the apiserver and kubelet if required to avoid connecting over an -untrusted or public network. - -Finally, [Kubelet authentication and/or authorization](/docs/admin/kubelet-authentication-authorization/) -should be enabled to secure the kubelet API. - -### apiserver -> nodes, pods, and services - -The connections from the apiserver to a node, pod, or service default to plain -HTTP connections and are therefore neither authenticated nor encrypted. They -can be run over a secure HTTPS connection by prefixing `https:` to the node, -pod, or service name in the API URL, but they will not validate the certificate -provided by the HTTPS endpoint nor provide client credentials so while the -connection will be encrypted, it will not provide any guarantees of integrity. -These connections **are not currently safe** to run over untrusted and/or -public networks. - -### SSH Tunnels - -[Google Container Engine](https://cloud.google.com/container-engine/docs/) uses -SSH tunnels to protect the Master -> Cluster communication paths. In this -configuration, the apiserver initiates an SSH tunnel to each node in the -cluster (connecting to the ssh server listening on port 22) and passes all -traffic destined for a kubelet, node, pod, or service through the tunnel. -This tunnel ensures that the traffic is not exposed outside of the private -GCE network in which the cluster is running. +[Master-Node Communication](/docs/concepts/cluster-administration/master-node-communication/) diff --git a/docs/concepts/cluster-administration/master-node-communication.md b/docs/concepts/cluster-administration/master-node-communication.md new file mode 100644 index 0000000000..d654fd5173 --- /dev/null +++ b/docs/concepts/cluster-administration/master-node-communication.md @@ -0,0 +1,106 @@ +--- +assignees: +- dchen1107 +- roberthbailey +- liggitt +title: Master-Node communication +--- + +* TOC +{:toc} + +## Overview + +This document catalogs the communication paths between the master (really the +apiserver) and the Kubernetes cluster. The intent is to allow users to +customize their installation to harden the network configuration such that +the cluster can be run on an untrusted network (or on fully public IPs on a +cloud provider). + +## Cluster -> Master + +All communication paths from the cluster to the master terminate at the +apiserver (none of the other master components are designed to expose remote +services). In a typical deployment, the apiserver is configured to listen for +remote connections on a secure HTTPS port (443) with one or more forms of +client [authentication](/docs/admin/authentication/) enabled. One or more forms +of [authorization](/docs/admin/authorization/) should be enabled, especially +if [anonymous requests](/docs/admin/authentication/#anonymous-requests) or +[service account tokens](/docs/admin/authentication/#service-account-tokens) +are allowed. + +Nodes should be provisioned with the public root certificate for the cluster +such that they can connect securely to the apiserver along with valid client +credentials. For example, on a default GCE deployment, the client credentials +provided to the kubelet are in the form of a client certificate. See +[kubelet TLS bootstrapping](/docs/admin/kubelet-tls-bootstrapping/) for +automated provisioning of kubelet client certificates. + +Pods that wish to connect to the apiserver can do so securely by leveraging a +service account so that Kubernetes will automatically inject the public root +certificate and a valid bearer token into the pod when it is instantiated. +The `kubernetes` service (in all namespaces) is configured with a virtual IP +address that is redirected (via kube-proxy) to the HTTPS endpoint on the +apiserver. + +The master components communicate with the cluster apiserver over the +insecure (not encrypted or authenticated) port. This port is typically only +exposed on the localhost interface of the master machine, so that the master +components, all running on the same machine, can communicate with the +cluster apiserver. Over time, the master components will be migrated to use +the secure port with authentication and authorization (see +[#13598](https://github.com/kubernetes/kubernetes/issues/13598)). + +As a result, the default operating mode for connections from the cluster +(nodes and pods running on the nodes) to the master is secured by default +and can run over untrusted and/or public networks. + +## Master -> Cluster + +There are two primary communication paths from the master (apiserver) to the +cluster. The first is from the apiserver to the kubelet process which runs on +each node in the cluster. The second is from the apiserver to any node, pod, +or service through the apiserver's proxy functionality. + +### apiserver -> kubelet + +The connections from the apiserver to the kubelet are used for fetching logs +for pods, attaching (through kubectl) to running pods, and using the kubelet's +port-forwarding functionality. These connections terminate at the kubelet's +HTTPS endpoint. + +By default, the apiserver does not verify the kubelet's serving certificate, +which makes the connection subject to man-in-the-middle attacks, and +**unsafe** to run over untrusted and/or public networks. + +To verify this connection, use the `--kubelet-certificate-authority` flag to +provide the apiserver with a root certificates bundle to use to verify the +kubelet's serving certificate. + +If that is not possible, use [SSH tunneling](/docs/admin/master-node-communication/#ssh-tunnels) +between the apiserver and kubelet if required to avoid connecting over an +untrusted or public network. + +Finally, [Kubelet authentication and/or authorization](/docs/admin/kubelet-authentication-authorization/) +should be enabled to secure the kubelet API. + +### apiserver -> nodes, pods, and services + +The connections from the apiserver to a node, pod, or service default to plain +HTTP connections and are therefore neither authenticated nor encrypted. They +can be run over a secure HTTPS connection by prefixing `https:` to the node, +pod, or service name in the API URL, but they will not validate the certificate +provided by the HTTPS endpoint nor provide client credentials so while the +connection will be encrypted, it will not provide any guarantees of integrity. +These connections **are not currently safe** to run over untrusted and/or +public networks. + +### SSH Tunnels + +[Google Container Engine](https://cloud.google.com/container-engine/docs/) uses +SSH tunnels to protect the Master -> Cluster communication paths. In this +configuration, the apiserver initiates an SSH tunnel to each node in the +cluster (connecting to the ssh server listening on port 22) and passes all +traffic destined for a kubelet, node, pod, or service through the tunnel. +This tunnel ensures that the traffic is not exposed outside of the private +GCE network in which the cluster is running.