From 9a70cc979164c6035760d1cb111742a1e460fb96 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 31 Oct 2019 15:34:29 -0700 Subject: [PATCH 01/18] Change RKE master to EKS master for EKS cluster on architecture diagram --- static/img/rancher/rancher-architecture.svg | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/static/img/rancher/rancher-architecture.svg b/static/img/rancher/rancher-architecture.svg index 412283bfb9a..402e2a1da89 100644 --- a/static/img/rancher/rancher-architecture.svg +++ b/static/img/rancher/rancher-architecture.svg @@ -1,2 +1,3 @@ + -
Cluster Agent 1
[Not supported by viewer]
Cluster Agent 2
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Rancher UI
CLI
API
[Not supported by viewer]
kubectl
K8s API
[Not supported by viewer]
Cluster Controller
[Not supported by viewer]
Rancher API
Server
[Not supported by viewer]
Auth Proxy
[Not supported by viewer]
Rancher Server
[Not supported by viewer]
RKE Nodes
[Not supported by viewer]
AWS EKS Nodes
[Not supported by viewer]
etcd
[Not supported by viewer]
RKE
K8s Master
[Not supported by viewer]
RKE
K8s Master
[Not supported by viewer] \ No newline at end of file +
Cluster Agent 1
[Not supported by viewer]
Cluster Agent 2
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Rancher UI
CLI
API
[Not supported by viewer]
kubectl
K8s API
[Not supported by viewer]
Cluster Controller
[Not supported by viewer]
Rancher API
Server
[Not supported by viewer]
Auth Proxy
[Not supported by viewer]
Rancher Server
[Not supported by viewer]
RKE Nodes
[Not supported by viewer]
AWS EKS Nodes
[Not supported by viewer]
etcd
[Not supported by viewer]
RKE
K8s Master
[Not supported by viewer]
EKS
K8s Master
[Not supported by viewer] \ No newline at end of file From 2e1ae133e56f691820cac5e4f201e91375461d95 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 31 Oct 2019 17:46:58 -0700 Subject: [PATCH 02/18] Add section and diagram about HA vs. single node architecture --- .../v2.x/en/overview/architecture/_index.md | 20 +++++++++++++++++-- ...ncher-single-node-and-ha-installations.svg | 3 +++ 2 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 static/img/rancher/rancher-single-node-and-ha-installations.svg diff --git a/content/rancher/v2.x/en/overview/architecture/_index.md b/content/rancher/v2.x/en/overview/architecture/_index.md index a0f96765f89..6b12d1621c4 100644 --- a/content/rancher/v2.x/en/overview/architecture/_index.md +++ b/content/rancher/v2.x/en/overview/architecture/_index.md @@ -39,6 +39,22 @@ The figure below illustrates the high-level architecture of Rancher 2.x. The fig In this section we describe the functionalities of each Rancher server components. +#### Single Node and High-Availability Installations of Rancher + +You can install Rancher on a single node, or on a high-availability Kubernetes cluster. + +A single-node installation is recommended for development and testing purposes, and a high-availability installation is recommended for production. + +In a single-node installation of Rancher, the node running the Rancher server should be separate from your Kubernetes clusters. + +In high-availability installations of Rancher, it is important to note the following: + +- The Rancher server cluster should be separate from user clusters. A user cluster is a Kubernetes cluster that runs your apps and services. +- The Rancher server cluster and user clusters have separate requirements for hardware and networking. The requirements for the Rancher server can be found [here]({{}}/rancher/v2.x/en/installation/requirements) and the requirements for user clusters can be found [here.]({{}}/rancher/v2.x/en/cluster-provisioning/requirements}) +- We recommend installing Rancher on a Kubernetes cluster in which each node has all three Kubernetes roles: etcd, controlplane, and worker. However, when you set up the clusters that run your apps and services, we recommend that each node in the cluster should have a single role for stability and scalability. For details on the recommended best practices for user clusters, refer to the [production checklist]({{}}/rancher/v2.x/en/cluster-provisioning/production) or our [best practices guide.]({{}}/rancher/v2.x/en/best-practices/management/#tips-for-scaling-and-reliability) + +![Single Node vs. High-Availability Architecture]({{}}/img/rancher/rancher-single-node-and-ha-installations.svg) + #### Rancher API Server Rancher API server is built on top of an embedded Kubernetes API server and etcd database. It implements the following functionalities: @@ -51,11 +67,11 @@ Rancher API server is built on top of an embedded Kubernetes API server and etcd Rancher API server manages access control and security policies. -- **Projects** +- **Managing Projects** A _project_ is a group of multiple namespaces and access control policies within a cluster. -- **Nodes** +- **Tracking Nodes** Rancher API server tracks identities of all the nodes in all clusters. diff --git a/static/img/rancher/rancher-single-node-and-ha-installations.svg b/static/img/rancher/rancher-single-node-and-ha-installations.svg new file mode 100644 index 00000000000..ab321de6c40 --- /dev/null +++ b/static/img/rancher/rancher-single-node-and-ha-installations.svg @@ -0,0 +1,3 @@ + + +
Example User Kubernetes Cluster
<font style="font-size: 16px">Example User Kubernetes Cluster<br></font>
Single Node Installation of Rancher
<font style="font-size: 20px">Single Node Installation of Rancher</font>
High-Availability Installation of Rancher
<font style="font-size: 20px">High-Availability Installation of Rancher</font>
Rancher Server
[Not supported by viewer]
Load Balancer
[Not supported by viewer]
Rancher Users
Rancher Users
Kubernetes Master
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Node
etcd Node
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Worker Node
Worker Node
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Control-
plane Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Rancher Users
Rancher Users
Rancher Server Cluster
<font style="font-size: 16px">Rancher Server Cluster<br></font>
Kubernetes Master
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
etcd, Worker,
and
Controlplane
node
[Not supported by viewer]
etcd, Worker,
and
Controlplane
node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
etcd, Worker,
and
Controlplane
node
[Not supported by viewer]
Example User Cluster
<font style="font-size: 16px">Example User Cluster<br></font>
Kubernetes Master
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Node
etcd Node
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Worker Node
Worker Node
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Control-
plane Node
[Not supported by viewer]
Kubelet
[Not supported by viewer] \ No newline at end of file From e67ed2283dbf014e5c85be72ad0b6e21d5b53f9c Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Fri, 1 Nov 2019 16:37:52 -0700 Subject: [PATCH 03/18] Revise/expand architecture page and conceptual docs --- .../v2.x/en/cluster-provisioning/_index.md | 82 +++++-------- .../rancher/v2.x/en/installation/ha/_index.md | 6 +- content/rancher/v2.x/en/overview/_index.md | 2 +- .../architecture-recommendations/_index.md | 85 ++++++++++++++ .../v2.x/en/overview/architecture/_index.md | 109 +++++------------- .../v2.x/en/overview/concepts/_index.md | 74 ++++++++++++ .../overview/installation-options/_index.md | 41 +++++++ .../overview/rancher-and-downstream/_index.md | 96 +++++++++++++++ ...ancher-architecture-cluster-controller.svg | 3 + .../rancher-architecture-node-roles.svg | 3 + ...ancher-architecture-rancher-api-server.svg | 3 + ...ancher-architecture-rancher-components.svg | 3 + ...hitecture-separation-of-rancher-server.svg | 3 + ...ncher-single-node-and-ha-installations.svg | 3 - 14 files changed, 375 insertions(+), 138 deletions(-) create mode 100644 content/rancher/v2.x/en/overview/architecture-recommendations/_index.md create mode 100644 content/rancher/v2.x/en/overview/concepts/_index.md create mode 100644 content/rancher/v2.x/en/overview/installation-options/_index.md create mode 100644 content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md create mode 100644 static/img/rancher/rancher-architecture-cluster-controller.svg create mode 100644 static/img/rancher/rancher-architecture-node-roles.svg create mode 100644 static/img/rancher/rancher-architecture-rancher-api-server.svg create mode 100644 static/img/rancher/rancher-architecture-rancher-components.svg create mode 100644 static/img/rancher/rancher-architecture-separation-of-rancher-server.svg delete mode 100644 static/img/rancher/rancher-single-node-and-ha-installations.svg diff --git a/content/rancher/v2.x/en/cluster-provisioning/_index.md b/content/rancher/v2.x/en/cluster-provisioning/_index.md index 65e758ab1d9..1e7fd61f1db 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/_index.md @@ -8,44 +8,11 @@ aliases: - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/ --- -## What's a Kubernetes Cluster? +Rancher simplifies the creation of clusters by allowing you to create them through the Rancher UI rather than more complex alternatives. Rancher provides multiple options for launching a cluster. Use the option that best fits your use case. -A cluster is a group of computers that work together as a single system. - -A _Kubernetes Cluster_ is a cluster that uses the [Kubernetes container-orchestration system](https://kubernetes.io/) to deploy, maintain, and scale Docker containers, allowing your organization to automate application operations. - -### Kubernetes Cluster Node Components - -Each computing resource in a Kubernetes Cluster is called a _node_. Nodes can be either bare-metal servers or virtual machines. Kubernetes classifies nodes into three types: _etcd_ nodes, _control plane_ nodes, and _worker_ nodes. - -#### etcd Nodes - -[etcd](https://kubernetes.io/docs/concepts/overview/components/#etcd) nodes run the etcd database. The etcd database component is a key value store used as Kubernetes storage for all cluster data, such as cluster coordination and state management. - -etcd is a distributed key value store, meaning it runs on multiple nodes so that there's always a backup available for fail over. Even though you can run etcd on a single node, you should run it on multiple nodes. We recommend 3, 5, or 7 etcd nodes for redundancy. - -#### Control Plane Nodes - -[Control plane](https://kubernetes.io/docs/concepts/#kubernetes-control-plane) nodes run the Kubernetes API server, scheduler, and controller manager. These nodes take care of routine tasks to ensure that your cluster maintains your configuration. Because all cluster data is stored on your etcd nodes, control plane nodes are stateless. You can run control plane on a single node, although two or more nodes are recommended for redundancy. Additionally, a single node can share the control plane and etcd roles. - -#### Worker Nodes - -[Worker nodes](https://kubernetes.io/docs/concepts/architecture/nodes/) run: - -- _Kubelets_: An agent that monitors the state of the node, ensuring your containers are healthy. -- _Workloads_: The containers and pods that hold your apps, as well as other types of deployments. - -Worker nodes also run storage and networking drivers, and ingress controllers when required. You create as many worker nodes as necessary to run your workloads. - -## Cluster Creation in Rancher - -Now that you know what a Kubernetes Cluster is, how does Rancher fit in? - -Rancher simplifies creation of clusters by allowing you to create them through the Rancher UI rather than more complex alternatives. Rancher provides multiple options for launching a cluster. Use the option that best fits your use case. - -![Rancher diagram]({{< baseurl >}}/img/rancher/ranchercomponentsdiagram.svg)
-Rancher components used for provisioning/managing Kubernetes clusters. +This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{}}/rancher/v2.x/en/overview/concepts) page. +For a conceptual overview of how the Rancher server provisions clusters, refer to the [architecture]({{}}/rancher/v2.x/en/overview/rancher-and-downstream) section. ## Cluster Creation Options @@ -61,35 +28,46 @@ Options include: -### Hosted Kubernetes Cluster +# Hosted Kubernetes Cluster If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage a hosted cluster from the Rancher UI. -[Hosted Kubernetes Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters) +[Hosted Kubernetes Cluster]({{}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters) -### Rancher Launched Kubernetes +# Rancher Launched Kubernetes -Alternatively, you can use Rancher to create a cluster on your own nodes, using [Rancher Kubernetes Engine (RKE)]({{< baseurl >}}/rke/latest/en/). RKE is Rancher’s own lightweight Kubernetes installer. In RKE clusters, Rancher manages the deployment of Kubernetes. These clusters can be deployed on any bare metal server, cloud provider, or virtualization platform. These nodes can either: +The [Rancher Kubernetes Engine (RKE)]({{}}/rke/latest/en/) allows you to create a Kubernetes cluster on your own nodes. RKE is Rancher’s own lightweight Kubernetes installer. -- Be provisioned through Rancher's UI, which calls [Docker Machine](https://docs.docker.com/machine/) to launch nodes on various cloud providers. -- Be a prior existing node that's brought into the cluster by running a Rancher agent container on it. +In RKE clusters, Rancher manages the deployment of Kubernetes. These clusters can be deployed on any bare metal server, cloud provider, or virtualization platform. -[Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) +These nodes can be dynamically provisioned through Rancher's UI, which calls [Docker Machine](https://docs.docker.com/machine/) to launch nodes on various cloud providers. -#### Nodes Hosted by an Infrastructure Provider +If you already have a node that you want to add to an RKE cluster, you can add it to the cluster by running a Rancher agent container on it. -Using Rancher, you can create pools of nodes based on a [node template]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This template defines the parameters used to launch nodes in your cloud providers. The cloud providers available for creating a node template are decided based on the [node drivers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers) active in the Rancher UI. The benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher automatically replaces it, thus maintaining the expected cluster configuration. +For more information, refer to the section on [RKE clusters.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) -[Nodes Hosted by an Infrastructure Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) +### Nodes Hosted by an Infrastructure Provider -#### Custom Nodes +Using Rancher, you can create pools of nodes based on a [node template]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This template defines the parameters used to launch nodes in your cloud providers. -You can bring any nodes you want to Rancher and use them to create a cluster. These nodes include on-premise bare metal servers, cloud-hosted virtual machines, or on-premise virtual machines. +The benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher automatically replaces it, thus maintaining the expected cluster configuration. -[Custom Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) +The cloud providers available for creating a node template are decided based on the [node drivers]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers) active in the Rancher UI. -### Import Existing Cluster +For more information, refer to the section on [nodes hosted by an infrastructure provider]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) -Users can import an existing Kubernetes cluster into Rancher. Note that Rancher does not automate the provisioning, scaling, or upgrade of imported clusters. All other Rancher features, including management of cluster, policy, and workloads, are available for imported clusters. +### Custom Nodes -[Importing Existing Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) +You can bring any nodes you want to Rancher and use them to create a cluster. Clusters created with custom nodes are also called custom clusters. + +These nodes include on-premise bare metal servers, cloud-hosted virtual machines, or on-premise virtual machines. + +[Custom Nodes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) + +# Import Existing Cluster + +Users can import an existing Kubernetes cluster into Rancher. + +Note that Rancher does not automate the provisioning, scaling, or upgrade of imported clusters. All other Rancher features, including management of cluster, policy, and workloads, are available for imported clusters. + +For more information, refer to the section on [importing existing clusters.]({{}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) diff --git a/content/rancher/v2.x/en/installation/ha/_index.md b/content/rancher/v2.x/en/installation/ha/_index.md index 0a676d25807..60375e4b806 100644 --- a/content/rancher/v2.x/en/installation/ha/_index.md +++ b/content/rancher/v2.x/en/installation/ha/_index.md @@ -9,9 +9,9 @@ This procedure walks you through setting up a 3-node cluster with Rancher Kubern > **Important:** The Rancher management server can only be run on an RKE-managed Kubernetes cluster. Use of Rancher on hosted Kubernetes or other providers is not supported. -> **Important:** For the best performance, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads. +> **Important:** For the best performance and security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads. -## Recommended Architecture +We recommend the following configurations for the load balancer and Ingress controllers: * DNS for Rancher should resolve to a Layer 4 load balancer (TCP) * The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster. @@ -44,7 +44,7 @@ The following CLI tools are required for this install. Please make sure these to [RKE add-on install]({{< baseurl >}}/rancher/v2.x/en/installation/ha/rke-add-on/) -> ##### **Important: RKE add-on install is only supported up to Rancher v2.0.8** +> **Important: RKE add-on install is only supported up to Rancher v2.0.8** > >Please use the Rancher helm chart to install HA Rancher. For details, see the [HA Install - Installation Outline]({{< baseurl >}}/rancher/v2.x/en/installation/ha/#installation-outline). > diff --git a/content/rancher/v2.x/en/overview/_index.md b/content/rancher/v2.x/en/overview/_index.md index d07ec95ea39..11c5d0b07c8 100644 --- a/content/rancher/v2.x/en/overview/_index.md +++ b/content/rancher/v2.x/en/overview/_index.md @@ -22,4 +22,4 @@ Rancher provides an intuitive user interface for DevOps engineers to manage thei The following figure illustrates the role Rancher plays in IT and DevOps organizations. Each team deploys their applications on the public or private clouds they choose. IT administrators gain visibility and enforce policies across all users, clusters, and clouds. -![Platform]({{< baseurl >}}/img/rancher/platform.png) +![Platform]({{< baseurl >}}/img/rancher/platform.png) \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md b/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md new file mode 100644 index 00000000000..3dd8476a703 --- /dev/null +++ b/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md @@ -0,0 +1,85 @@ +--- +title: Architecture Recommendations +weight: 3 +--- + +This page describes our recommendations for how to install Rancher. + +These recommendations focus on how to set up Rancher on a high-availability (HA) cluster. If you are installing Rancher on a single node, the main architecture recommendation that applies to your installation is that the node running Rancher should be [separate from downstream clusters.](#separation-of-rancher-and-user-clusters) + +This section covers the following topics: + +- [Separation of Rancher and User Clusters](#separation-of-rancher-and-user-clusters) +- [Why HA is Better for Rancher in Production](#why-ha-is-better-for-rancher-in-production) +- [Recommended Load Balancer Configuration for HA Installations](#recommended-load-balancer-configuration-for-ha-installations) +- [Environment for HA Installations](#environment-for-ha-installations) +- [Recommended Node Roles for HA Installations](#recommended-node-roles-for-ha-installations) + +# Separation of Rancher and User Clusters + +A user cluster is a downstream Kubernetes cluster that runs your apps and services. + +If you have a single node installation of Rancher, the node running the Rancher server should be separate from your downstream clusters. + +In HA installations of Rancher, the Rancher server cluster should also be separate from the user clusters. + +![Separation of Rancher Server from User Clusters]({{}}/img/rancher/rancher-architecture-separation-of-rancher-server.svg) + +# Why HA is Better for Rancher in Production + +We recommend installing the Rancher server on a three-node Kubernetes cluster for production, primarily because it protects the data stored on etcd. The Rancher server stores its data in etcd in both single-node and HA installations. + +When Rancher is installed on a single node, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server. + +By contrast, in the high-availability installation, + +- The etcd data is replicated on three nodes in the cluster, providing redundancy and data duplication in case one of the nodes fails. +- A load balancer serves as the single point of contact for clients, distributing network traffic across multiple servers in the cluster and helping to prevent any one server from becoming a point of failure. +- When one application server fails or becomes unavailable, the load balancer directs traffic to available servers using an algorithm. For example, the least connection method directs traffic to the service with the fewest active connections. The least connection method is indicated with the `least_conn` option in this [example]({{}}/rancher/v2.x/en/installation/ha/create-nodes-lb/nginx/) of how to configure an NGINX server as a basic layer 4 load balancer (TCP). The load balancer handles traffic so that each server can receive a manageable load. + +# Recommended Load Balancer Configuration for HA Installations + +We recommend the following configurations for the load balancer and Ingress controllers: + +* The DNS for Rancher should resolve to a Layer 4 load balancer (TCP) +* The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster. +* The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443. +* The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment. + +
HA Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers
+![Rancher HA]({{< baseurl >}}/img/rancher/ha/rancher2ha.svg) +HA Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers + +# Environment for HA Installations + +It is strongly recommended to install Rancher on a Kubernetes cluster on hosted infrastructure such as Amazon's EC2 or Google Compute Engine, and the cluster should be dedicated only to run Rancher. + +It is not recommended to install Rancher on top of a managed Kubernetes service such as Amazon’s EKS or Google Kubernetes Engine. These hosted Kubernetes solutions do not expose etcd to a degree that is manageable for Rancher, and their customizations can interfere with Rancher operations. + +# Recommended Node Roles for HA Installations + +We recommend installing Rancher on a Kubernetes cluster in which each node has all three Kubernetes roles: etcd, controlplane, and worker. + +### Comparing Node Roles for the Rancher Server Cluster and User Clusters + +Our recommendation for node roles on the Rancher server cluster contrast with our recommendations for the downstream user clusters that run your apps and services. We recommend that each node in a user cluster should have a single role for stability and scalability. + +![Kubernetes Roles for Nodes in Rancher Server Cluster vs. User Clusters]({{}}/img/rancher/rancher-architecture-node-roles.svg) + +Kubernetes only requires at least one node with each role and does not require nodes to be restricted to one role. However, for the clusters that run your apps, we recommend separate roles for each node so that workloads on worker nodes don't interfere with the Kubernetes master or cluster data as your services scale. + +We recommend that downstream user clusters should have at least: + +- **Three nodes with only the etcd role** to maintain a quorum if one node is lost, making the state of your cluster highly available +- **Two nodes with only the controlplane role** to make the master component highly available +- **One or more nodes with only the worker role** to run the Kubernetes node components, as well as the workloads for your apps and services + +With that said, it is safe to use all three roles on three nodes when setting up the Rancher server because: + +* It allows one `etcd` node failure. +* It maintains multiple instances of the master components by having multiple `controlplane` nodes. +* No other workloads than Rancher itself should be created on this cluster. + +Because no additional workloads will be deployed on the Rancher server cluster, in most cases it is not necessary to use the same architecture that we recommend for the scalability and reliability of user clusters. + +For details on the recommended best practices for user clusters, refer to the [production checklist]({{}}/rancher/v2.x/en/cluster-provisioning/production) or our [best practices guide.]({{}}/rancher/v2.x/en/best-practices/management/#tips-for-scaling-and-reliability) \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/architecture/_index.md b/content/rancher/v2.x/en/overview/architecture/_index.md index 6b12d1621c4..eb0f915a12c 100644 --- a/content/rancher/v2.x/en/overview/architecture/_index.md +++ b/content/rancher/v2.x/en/overview/architecture/_index.md @@ -1,102 +1,53 @@ --- -title: Architecture +title: Rancher Server Architecture weight: 1 --- -This section explains how Rancher interacts with the two fundamental technologies Rancher is built on: Docker and Kubernetes. +This section focuses on the Rancher server and its components. The Rancher server includes all the software components used to manage the entire Rancher deployment. -## Docker +- For the different ways that Rancher can be installed, refer to the [installation options section.]({{}}/rancher/v2.x/en/overview/architecture/installation-options) +- For guidance about setting up the underlying infrastructure for the Rancher server, refer to the [architecture recommendations.]({{}}/rancher/v2.x/en/overview/architecture/architecture-recommendations) +- For an explanation of how Rancher communicates with downstream Kubernetes clusters, refer to the section on [Rancher and downstream user clusters.]({{}}/rancher/v2.x/en/overview/architecture/rancher-and-downstream) -Docker is the container packaging and runtime standard. Developers build container images from Dockerfiles and distribute container images from Docker registries. [Docker Hub](https://hub.docker.com) is the most popular public registry. Many organizations also setup private Docker registries. Docker is primarily used to manage containers on individual nodes. +> This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{}}/rancher/v2.x/en/overview/concepts) page. ->**Note:** Although Rancher 1.6 supported Docker Swarm clustering technology, it is no longer supported in Rancher 2.x due to the success of Kubernetes. +# Features of the Rancher API Server -## Kubernetes +The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: -Kubernetes is the container cluster management standard. YAML files specify containers and other resources that form an application. Kubernetes performs functions such as scheduling, scaling, service discovery, health check, secret management, and configuration management. +- **User management:** The Rancher API server manages user identities that correspond to external authentication providers like Active Directory or GitHub. +- **Authorization:** The Rancher API server manages access control and security policies. +- **Managing projects:** A _project_ is a group of multiple namespaces and access control policies within a cluster. +- **Tracking nodes:** The Rancher API server tracks identities of all the nodes in all clusters. +- **Provisioning Kubernetes Clusters:** The Rancher API server can provision Kubernetes clusters. Rancher can also set up Kubernetes on existing nodes, or import existing Kubernetes clusters into Rancher. +- **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision new nodes and persistent storage in the cloud. -A Kubernetes cluster consists of multiple nodes. +# Rancher Server Architecture -- **etcd database** +The majority of Rancher 2.x software runs on the Rancher Server. Rancher Server includes all the software components used to manage the entire Rancher deployment. - Although you can run etcd on just one node, it typically takes 3, 5 or more nodes to create a High Availability (HA) configuration. +The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service). -- **Master nodes** +For the best performance and security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads. - Master nodes are stateless and are used to run the API server, scheduler, and controllers. - -- **Worker nodes** - - The application workload runs on worker nodes. - -## Rancher - -The majority of Rancher 2.x software runs on the Rancher Server. Rancher Server includes all the software components used to manage the entire Rancher deployment. - -The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two Kubernetes clusters: one created by Rancher Kubernetes Engine (RKE) and another created by Amazon EKS (Elastic Kubernetes Service). - -![Architecture]({{< baseurl >}}/img/rancher/rancher-architecture.svg) - -In this section we describe the functionalities of each Rancher server components. - -#### Single Node and High-Availability Installations of Rancher +![Architecture]({{< baseurl >}}/img/rancher/rancher-architecture-rancher-api-server.svg) You can install Rancher on a single node, or on a high-availability Kubernetes cluster. A single-node installation is recommended for development and testing purposes, and a high-availability installation is recommended for production. -In a single-node installation of Rancher, the node running the Rancher server should be separate from your Kubernetes clusters. +### Rancher Server Components -In high-availability installations of Rancher, it is important to note the following: +This diagram shows each component that the Rancher server is composed of: -- The Rancher server cluster should be separate from user clusters. A user cluster is a Kubernetes cluster that runs your apps and services. -- The Rancher server cluster and user clusters have separate requirements for hardware and networking. The requirements for the Rancher server can be found [here]({{}}/rancher/v2.x/en/installation/requirements) and the requirements for user clusters can be found [here.]({{}}/rancher/v2.x/en/cluster-provisioning/requirements}) -- We recommend installing Rancher on a Kubernetes cluster in which each node has all three Kubernetes roles: etcd, controlplane, and worker. However, when you set up the clusters that run your apps and services, we recommend that each node in the cluster should have a single role for stability and scalability. For details on the recommended best practices for user clusters, refer to the [production checklist]({{}}/rancher/v2.x/en/cluster-provisioning/production) or our [best practices guide.]({{}}/rancher/v2.x/en/best-practices/management/#tips-for-scaling-and-reliability) +![Rancher Components]({{}}/img/rancher/rancher-architecture-rancher-components.svg) -![Single Node vs. High-Availability Architecture]({{}}/img/rancher/rancher-single-node-and-ha-installations.svg) +The GitHub repositories for each component of Rancher can be found at the following links: -#### Rancher API Server - -Rancher API server is built on top of an embedded Kubernetes API server and etcd database. It implements the following functionalities: - -- **User Management** - - Rancher API server manages user identities that correspond to external authentication providers like Active Directory or GitHub. - -- **Authorization** - - Rancher API server manages access control and security policies. - -- **Managing Projects** - - A _project_ is a group of multiple namespaces and access control policies within a cluster. - -- **Tracking Nodes** - - Rancher API server tracks identities of all the nodes in all clusters. - -#### Cluster Controller and Agents - -The cluster controller and cluster agents implement the business logic required to manage Kubernetes clusters. - -- The _cluster controller_ implements the logic required for the global Rancher install. It performs the following actions: - - - Configuration of access control policies to clusters and projects. - - - Provisioning of clusters by calling: - - - The required Docker machine drivers. - - Kubernetes engines like RKE and GKE. - - -- A separate _cluster agent_ instance implements the logic required for the corresponding cluster. It performs the following activities: - - - Workload Management, such as pod creation and deployment within each cluster. - - - Application of the roles and bindings defined in each cluster's global policies. - - - Communication between clusters and Rancher Server: events, stats, node info, and health. - -#### Authentication Proxy - -The _authentication proxy_ forwards all Kubernetes API calls. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters. Rancher communicates with Kubernetes clusters using a service account. +- [Main Rancher server repository](https://github.com/rancher/rancher) +- [Rancher UI](https://github.com/rancher/ui) +- [Rancher API UI](https://github.com/rancher/api-ui) +- [Norman,](https://github.com/rancher/norman) Rancher's API framework +- [Types](https://github.com/rancher/types) +- [Rancher CLI](https://github.com/rancher/cli) +- [Catalog applications](https://github.com/rancher/helm) \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/concepts/_index.md b/content/rancher/v2.x/en/overview/concepts/_index.md new file mode 100644 index 00000000000..636c39232e0 --- /dev/null +++ b/content/rancher/v2.x/en/overview/concepts/_index.md @@ -0,0 +1,74 @@ +--- +title: Kubernetes Concepts +weight: 4 +--- + +This section covers the following topics: + +- [About Docker](#about-docker) +- [About Kubernetes](#about-kubernetes) +- [What is a Kubernetes Cluster?](#what-is-a-kubernetes-cluster) +- [Roles for Nodes in Kubernetes Clusters](#roles-for-nodes-in-kubernetes-clusters) + - [etcd Nodes](#etcd-nodes) + - [Controlplane Nodes](#controlplane-nodes) + - [Worker Nodes](#worker-nodes) +- [About Helm](#about-helm) + +# About Docker + +Docker is the container packaging and runtime standard. Developers build container images from Dockerfiles and distribute container images from Docker registries. [Docker Hub](https://hub.docker.com) is the most popular public registry. Many organizations also set up private Docker registries. Docker is primarily used to manage containers on individual nodes. + +>**Note:** Although Rancher 1.6 supported Docker Swarm clustering technology, it is no longer supported in Rancher 2.x due to the success of Kubernetes. + +# About Kubernetes + +Kubernetes is the container cluster management standard. YAML files specify containers and other resources that form an application. Kubernetes performs functions such as scheduling, scaling, service discovery, health check, secret management, and configuration management. + +# What is a Kubernetes Cluster? + +A cluster is a group of computers that work together as a single system. + +A _Kubernetes Cluster_ is a cluster that uses the [Kubernetes container-orchestration system](https://kubernetes.io/) to deploy, maintain, and scale Docker containers, allowing your organization to automate application operations. + +# Roles for Nodes in Kubernetes Clusters + +Each computing resource in a Kubernetes cluster is called a _node_. Nodes can be either bare-metal servers or virtual machines. Kubernetes classifies nodes into three types: _etcd_ nodes, _control plane_ nodes, and _worker_ nodes. + +A Kubernetes cluster consists of at least one etcd, controlplane, and worker node. + +### etcd Nodes + +Rancher uses etcd as a data store in both single node and high-availability installations. In Kubernetes, etcd is also a role for nodes that store the cluster state. + +The state of a Kubernetes cluster is maintained in [etcd.](https://kubernetes.io/docs/concepts/overview/components/#etcd) The etcd nodes run the etcd database. + +The etcd database component is a distributed key-value store used as Kubernetes storage for all cluster data, such as cluster coordination and state management. It is recommended to run etcd on multiple nodes so that there's always a backup available for failover. + +Although you can run etcd on just one node, etcd requires a majority of nodes, a quorum, to agree on updates to the cluster state. The cluster should always contain enough healthy etcd nodes to form a quorum. For a cluster with n members, a quorum is (n/2)+1. For any odd-sized cluster, adding one node will always increase the number of nodes necessary for a quorum. + +Three etcd nodes is generally sufficient for smaller clusters and five etcd nodes for large clusters. + +### Controlplane Nodes + +Controlplane nodes run the Kubernetes API server, scheduler, and controller manager. These nodes take care of routine tasks to ensure that your cluster maintains your configuration. Because all cluster data is stored on your etcd nodes, control plane nodes are stateless. You can run control plane on a single node, although two or more nodes are recommended for redundancy. Additionally, a single node can share the control plane and etcd roles. + +### Worker Nodes + +Each [worker node](https://kubernetes.io/docs/concepts/architecture/nodes/) runs the following: + +- **Kubelets:** An agent that monitors the state of the node, ensuring your containers are healthy. +- **Workloads:** The containers and pods that hold your apps, as well as other types of deployments. + +Worker nodes also run storage and networking drivers, and ingress controllers when required. You create as many worker nodes as necessary to run your [workloads]({{}}/rancher/v2.x/en/k8s-in-rancher/workloads/). + +# About Helm + +For high-availability installations of Rancher, Helm is the tool used to install Rancher on a Kubernetes cluster. + +Helm is the package management tool of choice for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. With Helm we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at [https://helm.sh/](https://helm.sh). + +To be able to use Helm, the server-side component `tiller` needs to be installed on your cluster. Helm installs the `tiller` service on your cluster to manage charts because Helm cannot manipulate Kubernetes resources directly. + +Because Rancher Kubernetes Engine enables role-based access control by default, the `tiller` service needs to be given permission to manipulate Kubernetes resources. Therefore, the high-availability Rancher installation instructions show you how to use `kubectl` to create a `serviceaccount` and `clusterrolebinding` so that `tiller` has permission to deploy Rancher on the cluster. + +For more information on service accounts and cluster role binding, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/installation-options/_index.md b/content/rancher/v2.x/en/overview/installation-options/_index.md new file mode 100644 index 00000000000..e54fb488014 --- /dev/null +++ b/content/rancher/v2.x/en/overview/installation-options/_index.md @@ -0,0 +1,41 @@ +--- +title: Installation Options +weight: 2 +--- + +Rancher can be installed on a single node or a high-availability cluster. + +On a single node, Rancher is installed with Docker and many options are configured with Docker commands. + +On a Kubernetes cluster, Rancher is installed with Helm, and Helm commands are used to pass in configuration options. [Helm]({{}}/rancher/v2.x/en/overview/architecture/concepts/#about-helm) is a Kubernetes package manager. + +The simplest way to install Rancher is on a single node with direct access to the Internet. Other options require more steps: + +- For a high-availability installation, you need to first set up a Kubernetes cluster using the Rancher Kubernetes Engine, then install Rancher on the cluster. +- If the installation environment is behind an HTTP proxy or in an air gap environment, additional steps are required to work around the lack of direct access to DockerHub and GitHub. + +Depending on your environment, the result of of the extra steps is the increased security and reliability of Rancher. + +Basic options for installing Rancher include the following: + +Level of Internet Access | Single Node Instructions | HA Instructions +---------------------------|-----------------------------|------------------ +With direct access to the Internet | [Docs]({{}}/rancher/v2.x/en/installation/single-node/) | [Docs]({{}}/rancher/v2.x/en/installation/ha/) +Behind an HTTP proxy | [Docs]({{}}/rancher/v2.x/en/installation/single-node/proxy/) | [Docs]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#http-proxy) +In an air gap environment | [Docs]({{}}/rancher/v2.x/en/installation/air-gap/) | [Docs]({{}}/rancher/v2.x/en/installation/air-gap/) + +# More Options + +Refer to the [Helm chart options]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/) for details on installing HA Rancher with other configurations, including: + +- With [API auditing to record all transactions]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#api-audit-log) +- With [TLS termination on a load balancer]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#external-tls-termination) +- With a [custom Ingress]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#customizing-your-ingress) + +RKE also has many configuration options for customizing the Kubernetes cluster to suit your specific environment. Please see the [RKE Documentation]({{}}/rke/latest/en/config-options/) for the full list of options and capabilities. + +Refer to the [single node installation docs]({{}}/rancher/v2.x/en/installation/single-node/) for details other configurations including: + +- With [API auditing to record all transactions]({{}}/rancher/v2.x/en/installation/single-node/#api-audit-log) +- With an [external load balancer]({{}}/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/) +- With a [persistent data store]({{}}/rancher/v2.x/en/installation/single-node/#persistent-data) \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md b/content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md new file mode 100644 index 00000000000..99048477945 --- /dev/null +++ b/content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md @@ -0,0 +1,96 @@ +--- +title: Rancher and Downstream User Clusters +weight: 5 +--- + +This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. + +- [How Rancher Provisions Kubernetes Clusters](#how-rancher-provisions-kubernetes-clusters) +- [How Rancher Communicates with Downstream User Clusters](#how-rancher-communicates-with-downstream-user-clusters) +- [Authentication Proxy](#authentication-proxy) + - [Connecting to a Cluster without the Rancher UI](#connecting-to-a-cluster-without-the-rancher-ui) + +# How Rancher Provisions Kubernetes Clusters + +The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned. + +### Rancher Launched Kubernetes for Hodes Hosted in an Infrastructure Provider + +Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them. + +Rancher provisions this type of cluster using [RKE](https://github.com/rancher/rke) and [docker-machine.](https://github.com/rancher/machine) + +### Rancher Launched Kubernetes for Custom Nodes + +When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster. + +Rancher provisions this type of cluster using [RKE.](https://github.com/rancher/rke) + +### Hosted Kubernetes Providers + +When setting up this type of cluster, Kubernetes is installed by providers such as Google Kubernetes Engine, Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service. + +Rancher provisions this type of cluster using [kontainer-engine.](https://github.com/rancher/kontainer-engine) + +### Imported Kubernetes Clusters + +In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster. + +# How Rancher Communicates with Downstream User Clusters + +Rancher communicates with downstream user clusters by using three types of components: the cluster controller, the cluster agent, and the node agent. These components are used for provisioning and managing Kubernetes clusters. + +The cluster controller and cluster agents implement the business logic required to manage Kubernetes clusters. + +Rancher installs the `cattle-node-agent` on each node in downstream user clusters in order to manage them. + +
Cluster Controller, Cluster Agent, and Node Agents Allow Rancher to Control Downstream Clusters
+ +![Rancher Components]({{}}/img/rancher/rancher-architecture-cluster-controller.svg) + +### The Cluster Controller + +The _cluster controller_ implements the logic required for the global Rancher install. It performs the following actions: + +- Configures access control policies to clusters and projects +- Provisions clusters by calling the required Docker machine drivers and Kubernetes engines, such as RKE and GKE + +### The Cluster Agent + +The `cattle-cluster-agent` is used to connect to the Kubernetes API of Rancher Launched Kubernetes clusters. The `cattle-cluster-agent` is deployed on the Rancher server using a deployment resource. + +The cluster agent implements the logic required for the corresponding downstream user cluster. It performs the following activities: + +- Manages workloads, pod creation and deployment within each cluster +- Applies the roles and bindings defined in each cluster's global policies +- Communicates between clusters and Rancher server about events, stats, node info, and health + +### The Node Agent + +The `cattle-node-agent` is deployed using a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) resource to make sure it runs on every node in a Rancher-launched Kubernetes cluster. It is used to interact with the nodes when performing cluster operations. Examples of cluster operations include upgrading the Kubernetes version and creating or restoring etcd snapshots. + +The `cattle-node-agent` is also used as fallback option to connect to the Kubernetes API of Rancher Launched Kubernetes clusters when `cattle-cluster-agent` is unavailable. + +# Authentication Proxy + +The _authentication proxy_ forwards all Kubernetes API calls. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters. + +Rancher communicates with Kubernetes clusters using a [service account,](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), which provides an identity for processes that run in a pod. + +### Connecting to a Cluster without the Rancher UI + +By default, Rancher generates a kubeconfig file that will proxy through the Rancher server to connect to the Kubernetes API server on a cluster. + +For [Rancher launched Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters) clusters, which have an [authorized cluster endpoint]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#authorized-cluster-endpoint) enabled, Rancher generates extra context(s) in the kubeconfig file in order to connect directly to the cluster. The authorized cluster endpoint is enabled by default. + +When you want to use kubectl to access this cluster without Rancher, you will need to use a context defined in this kubeconfig file. This file has the credentials for `kubectl` and `helm`. + +The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint. + +The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster: + +- `rancher-cluster.yml`: The RKE cluster configuration file. +- `kube_config_rancher-cluster.yml`: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster. +- `rancher-cluster.rkestate`: The Kubernetes Cluster State file. This file contains credentials for full access to the cluster. Note: This state file is only created when using RKE v0.2.0 or higher. + +For more information on connecting to a cluster without the Rancher UI, refer to the [kubeconfig file]({{}}/rancher/v2.x/en/cluster-admin/kubeconfig/) documentation. \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-cluster-controller.svg b/static/img/rancher/rancher-architecture-cluster-controller.svg new file mode 100644 index 00000000000..bd86f1fdf6e --- /dev/null +++ b/static/img/rancher/rancher-architecture-cluster-controller.svg @@ -0,0 +1,3 @@ + + +
Cluster Agent 2
[Not supported by viewer]
Cluster Agent 1
[Not supported by viewer]
Cluster Controller
[Not supported by viewer]
Rancher Server Cluster
<font style="font-size: 20px">Rancher Server Cluster<br></font>
Cluster Agent 3
[Not supported by viewer]
User Cluster 3
[Not supported by viewer]
User Cluster 2
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]

K8s Master
[Not supported by viewer]
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
Authentication with
kube-api-auth
[Not supported by viewer] \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-node-roles.svg b/static/img/rancher/rancher-architecture-node-roles.svg new file mode 100644 index 00000000000..5819125b275 --- /dev/null +++ b/static/img/rancher/rancher-architecture-node-roles.svg @@ -0,0 +1,3 @@ + + +
Roles for Nodes in a High-Availability Rancher Server Cluster
<font style="font-size: 16px">Roles for Nodes in a High-Availability Rancher Server Cluster<br></font>
Roles for Nodes in a Downstream User Cluster
<font style="font-size: 16px">Roles for Nodes in a Downstream User Cluster<br></font>
Kubernetes Master
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Kubernetes Master
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Node with etcd role
Node with etcd role
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Node with controlplane role
Node with controlplane role
Kubelet
[Not supported by viewer]
Note: A kubelet is an agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
Note: A kubelet is an agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer] \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-rancher-api-server.svg b/static/img/rancher/rancher-architecture-rancher-api-server.svg new file mode 100644 index 00000000000..1fe663f730a --- /dev/null +++ b/static/img/rancher/rancher-architecture-rancher-api-server.svg @@ -0,0 +1,3 @@ + + +
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Rancher UI
CLI
API
[Not supported by viewer]
kubectl
K8s API
[Not supported by viewer]
RKE Nodes
[Not supported by viewer]
AWS EKS Nodes
[Not supported by viewer]
RKE
K8s Master
[Not supported by viewer]
EKS
K8s Master
[Not supported by viewer]
Downstream User Cluster 1,
controlled by Cluster Agent 1
[Not supported by viewer]
Downstream User Cluster 2,
controlled by Cluster Agent 2
[Not supported by viewer]
Cluster Agent 1
[Not supported by viewer]
Cluster Agent 2
[Not supported by viewer]
Cluster Controller
[Not supported by viewer]
Rancher API
Server
[Not supported by viewer]
Auth Proxy
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
etcd
[Not supported by viewer]
Rancher Server Data Store
<font style="font-size: 16px">Rancher Server Data Store<br></font> \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-rancher-components.svg b/static/img/rancher/rancher-architecture-rancher-components.svg new file mode 100644 index 00000000000..5762038ac3a --- /dev/null +++ b/static/img/rancher/rancher-architecture-rancher-components.svg @@ -0,0 +1,3 @@ + + +
API Framework
and Types
[Not supported by viewer]
Norman
[Not supported by viewer]
Types
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
User Interface
[Not supported by viewer]
Rancher UI
[Not supported by viewer]
Rancher API UI
[Not supported by viewer]
Utilities
[Not supported by viewer]
Rancher CLI
[Not supported by viewer]
Catalog Applications
[Not supported by viewer] \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-separation-of-rancher-server.svg b/static/img/rancher/rancher-architecture-separation-of-rancher-server.svg new file mode 100644 index 00000000000..a4f9fe3a36d --- /dev/null +++ b/static/img/rancher/rancher-architecture-separation-of-rancher-server.svg @@ -0,0 +1,3 @@ + + +
Separation of Single Node Rancher Server and User Clusters
<font style="font-size: 20px">Separation of Single Node Rancher Server and User Clusters<br></font>
Separation of High-availability Rancher Server and User Clusters
<font style="font-size: 20px">Separation of High-availability Rancher Server and User Clusters<br></font>
Rancher Server
[Not supported by viewer]
Load Balancer
[Not supported by viewer]
Rancher Users
Rancher Users
Rancher Users
Rancher Users
User
Kubernetes
Cluster
[Not supported by viewer]
User
Kubernetes
Cluster
[Not supported by viewer]
User
Kubernetes
Cluster
[Not supported by viewer]
Rancher Server Kubernetes Cluster
[Not supported by viewer]
User
Kubernetes
Cluster
[Not supported by viewer]
User
Kubernetes
Cluster
[Not supported by viewer]
User
Kubernetes
Cluster
[Not supported by viewer] \ No newline at end of file diff --git a/static/img/rancher/rancher-single-node-and-ha-installations.svg b/static/img/rancher/rancher-single-node-and-ha-installations.svg deleted file mode 100644 index ab321de6c40..00000000000 --- a/static/img/rancher/rancher-single-node-and-ha-installations.svg +++ /dev/null @@ -1,3 +0,0 @@ - - -
Example User Kubernetes Cluster
<font style="font-size: 16px">Example User Kubernetes Cluster<br></font>
Single Node Installation of Rancher
<font style="font-size: 20px">Single Node Installation of Rancher</font>
High-Availability Installation of Rancher
<font style="font-size: 20px">High-Availability Installation of Rancher</font>
Rancher Server
[Not supported by viewer]
Load Balancer
[Not supported by viewer]
Rancher Users
Rancher Users
Kubernetes Master
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Node
etcd Node
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Worker Node
Worker Node
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Control-
plane Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Rancher Users
Rancher Users
Rancher Server Cluster
<font style="font-size: 16px">Rancher Server Cluster<br></font>
Kubernetes Master
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
etcd, Worker,
and
Controlplane
node
[Not supported by viewer]
etcd, Worker,
and
Controlplane
node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
etcd, Worker,
and
Controlplane
node
[Not supported by viewer]
Example User Cluster
<font style="font-size: 16px">Example User Cluster<br></font>
Kubernetes Master
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Node
etcd Node
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Worker Node
Worker Node
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Control-
plane Node
[Not supported by viewer]
Kubelet
[Not supported by viewer] \ No newline at end of file From 721e188f4c59225145aded324ba70f493d46f616 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Tue, 5 Nov 2019 02:01:16 -0700 Subject: [PATCH 04/18] Rewrite section about how Rancher communicates with clusters --- .../overview/rancher-and-downstream/_index.md | 67 +++++++++++-------- ...ancher-architecture-cluster-controller.svg | 2 +- 2 files changed, 40 insertions(+), 29 deletions(-) diff --git a/content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md b/content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md index 99048477945..36a9868dfa4 100644 --- a/content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md +++ b/content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md @@ -5,36 +5,10 @@ weight: 5 This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. -- [How Rancher Provisions Kubernetes Clusters](#how-rancher-provisions-kubernetes-clusters) - [How Rancher Communicates with Downstream User Clusters](#how-rancher-communicates-with-downstream-user-clusters) - [Authentication Proxy](#authentication-proxy) - [Connecting to a Cluster without the Rancher UI](#connecting-to-a-cluster-without-the-rancher-ui) - -# How Rancher Provisions Kubernetes Clusters - -The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned. - -### Rancher Launched Kubernetes for Hodes Hosted in an Infrastructure Provider - -Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them. - -Rancher provisions this type of cluster using [RKE](https://github.com/rancher/rke) and [docker-machine.](https://github.com/rancher/machine) - -### Rancher Launched Kubernetes for Custom Nodes - -When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster. - -Rancher provisions this type of cluster using [RKE.](https://github.com/rancher/rke) - -### Hosted Kubernetes Providers - -When setting up this type of cluster, Kubernetes is installed by providers such as Google Kubernetes Engine, Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service. - -Rancher provisions this type of cluster using [kontainer-engine.](https://github.com/rancher/kontainer-engine) - -### Imported Kubernetes Clusters - -In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster. +- [How Rancher Provisions Kubernetes Clusters](#how-rancher-provisions-kubernetes-clusters) # How Rancher Communicates with Downstream User Clusters @@ -48,6 +22,17 @@ Rancher installs the `cattle-node-agent` on each node in downstream user cluster ![Rancher Components]({{}}/img/rancher/rancher-architecture-cluster-controller.svg) +The following descriptions correspond to the numbers in the diagram above: + +1. Let's say a user, Bob, wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a `kubectl` command to see +the pods. Bob is authenticated through Rancher's authentication proxy. + +2. Each downstream user cluster has a cluster agent, which opens a tunnel connecting the user cluster with Rancher's corresponding cluster controller. + +3. By default, the cluster controller connects to the cluster agent. If the cluster agent is not available, one of the node agents creates a tunnel to the cluster controller to communicate with Rancher. + +4. Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in China. A user, Alice, lives in China. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but she may experience latency due to the distance between US and China. To reduce latency, she can use Rancher's authorized cluster endpoint feature. By default, an authorized cluster endpoint is enabled, which allows Alice to be authenticated by calling the Kubernetes API server of the user cluster, without going through Rancher's authentication proxy. When Alice uses kubectl to access the user cluster, the cluster's Kubernetes API server authenticates Alice by using the `kube-api-auth` service as a webhook. The `kube-api-auth` authentication service and authorized cluster endpoint are only available for Rancher-launched Kubernetes clusters. + ### The Cluster Controller The _cluster controller_ implements the logic required for the global Rancher install. It performs the following actions: @@ -93,4 +78,30 @@ The files mentioned below are needed to maintain, troubleshoot and upgrade your - `kube_config_rancher-cluster.yml`: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster. - `rancher-cluster.rkestate`: The Kubernetes Cluster State file. This file contains credentials for full access to the cluster. Note: This state file is only created when using RKE v0.2.0 or higher. -For more information on connecting to a cluster without the Rancher UI, refer to the [kubeconfig file]({{}}/rancher/v2.x/en/cluster-admin/kubeconfig/) documentation. \ No newline at end of file +For more information on connecting to a cluster without the Rancher UI, refer to the [kubeconfig file]({{}}/rancher/v2.x/en/cluster-admin/kubeconfig/) documentation. + +# How Rancher Provisions Kubernetes Clusters + +The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned. + +### Rancher Launched Kubernetes for Hodes Hosted in an Infrastructure Provider + +Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them. + +Rancher provisions this type of cluster using [RKE](https://github.com/rancher/rke) and [docker-machine.](https://github.com/rancher/machine) + +### Rancher Launched Kubernetes for Custom Nodes + +When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster. + +Rancher provisions this type of cluster using [RKE.](https://github.com/rancher/rke) + +### Hosted Kubernetes Providers + +When setting up this type of cluster, Kubernetes is installed by providers such as Google Kubernetes Engine, Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service. + +Rancher provisions this type of cluster using [kontainer-engine.](https://github.com/rancher/kontainer-engine) + +### Imported Kubernetes Clusters + +In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster. \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-cluster-controller.svg b/static/img/rancher/rancher-architecture-cluster-controller.svg index bd86f1fdf6e..629e256d947 100644 --- a/static/img/rancher/rancher-architecture-cluster-controller.svg +++ b/static/img/rancher/rancher-architecture-cluster-controller.svg @@ -1,3 +1,3 @@ -
Cluster Agent 2
[Not supported by viewer]
Cluster Agent 1
[Not supported by viewer]
Cluster Controller
[Not supported by viewer]
Rancher Server Cluster
<font style="font-size: 20px">Rancher Server Cluster<br></font>
Cluster Agent 3
[Not supported by viewer]
User Cluster 3
[Not supported by viewer]
User Cluster 2
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]

K8s Master
[Not supported by viewer]
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
Authentication with
kube-api-auth
[Not supported by viewer] \ No newline at end of file +
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
kubectl get pods
[Not supported by viewer]
kube-api-auth
[Not supported by viewer]
Bob
[Not supported by viewer]
Alice
Alice
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
4
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
kubectl get pods
[Not supported by viewer]
Cluster Agent
[Not supported by viewer]
1
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
Cluster Controller 1
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Cluster Controller 3
[Not supported by viewer]
Authentication
Proxy
[Not supported by viewer]
2
[Not supported by viewer]
3
[Not supported by viewer]
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
User Cluster 2
[Not supported by viewer]
User Cluster 2
[Not supported by viewer] \ No newline at end of file From e4b94eedf0c39452d96e0ee85dea0ca2169d82fe Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Wed, 6 Nov 2019 18:38:34 -0700 Subject: [PATCH 05/18] Explain authorized cluster endpoints --- .../en/cluster-admin/kubeconfig/_index.md | 15 +- .../v2.x/en/cluster-provisioning/_index.md | 2 +- .../rancher-agents/_index.md | 2 + .../rke-clusters/options/_index.md | 10 +- content/rancher/v2.x/en/overview/_index.md | 3 +- .../architecture-recommendations/_index.md | 9 +- .../v2.x/en/overview/architecture/_index.md | 164 ++++++++++++++++-- .../v2.x/en/overview/concepts/_index.md | 2 + .../overview/installation-options/_index.md | 12 +- .../overview/rancher-and-downstream/_index.md | 107 ------------ ...ancher-architecture-cluster-controller.svg | 2 +- .../rancher-architecture-node-roles.svg | 2 +- ...ancher-architecture-rancher-api-server.svg | 2 +- 13 files changed, 192 insertions(+), 140 deletions(-) delete mode 100644 content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md diff --git a/content/rancher/v2.x/en/cluster-admin/kubeconfig/_index.md b/content/rancher/v2.x/en/cluster-admin/kubeconfig/_index.md index 36531877490..94e7b5746c6 100644 --- a/content/rancher/v2.x/en/cluster-admin/kubeconfig/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/kubeconfig/_index.md @@ -24,11 +24,13 @@ kubectl --kubeconfig /custom/path/kube.config get pods ## Accessing Rancher Launched Kubernetes clusters without Rancher server running +By default, all Rancher Launched Kubernetes clusters have [Authorized Cluster Endpoint]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#authorized-cluster-endpoint) enabled. + +> The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{}}/rancher/v2.x/en/overview/architecture/#tools-for-provisioning-kubernetes-clusters) to provision the cluster. It is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS. + By default, Rancher generates a kubeconfig file that will proxy through the Rancher server to connect to the Kubernetes API server on a cluster. -For [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters) clusters, which have [Authorized Cluster Endpoint]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#authorized-cluster-endpoint) enabled, Rancher generates extra context(s) in the kubeconfig file in order to connect directly to the cluster. - -> **Note:** By default, all Rancher Launched Kubernetes clusters have [Authorized Cluster Endpoint]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#authorized-cluster-endpoint) enabled. +For [Rancher Launched Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters) clusters that have the authorized cluster endpoint enabled, Rancher generates extra context(s) in the kubeconfig file in order to connect directly to the cluster. To find the name of the context(s), run: @@ -38,6 +40,9 @@ CURRENT NAME CLUSTER AUTHINFO N * my-cluster my-cluster user-46tmn my-cluster-controlplane-1 my-cluster-controlplane-1 user-46tmn ``` +For more information on how the authorized cluster endpoint works, refer to the [architecture section.]({{}}/rancher/v2.x/en/overview/architecture/4-authorized-cluster-endpoint) + +We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the [recommended architecture section.]({{}}/rancher/v2.x/en/overview/architecture-recommendations/#architecture-for-an-authorized-cluster-endpoint) ### Clusters with FQDN defined as an Authorized Cluster Endpoint @@ -65,7 +70,9 @@ kubectl --kubeconfig /custom/path/kube.config --context -}}/rancher/v2.x/en/overview/architecture/4-authorized-cluster-endpoint) + +The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint. When you access the user cluster using `kubectl`, the cluster's Kubernetes API server authenticates you by using the `kube-api-auth` service as a webhook. During cluster provisioning, the file `/etc/kubernetes/kube-api-authn-webhook.yaml` is deployed and `kube-apiserver` is configured with `--authentication-token-webhook-config-file=/etc/kubernetes/kube-api-authn-webhook.yaml`. This configures the `kube-apiserver` to query `http://127.0.0.1:6440/v1/authenticate` to determine authentication for bearer tokens. diff --git a/content/rancher/v2.x/en/cluster-provisioning/_index.md b/content/rancher/v2.x/en/cluster-provisioning/_index.md index 1e7fd61f1db..9f70062844b 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/_index.md @@ -12,7 +12,7 @@ Rancher simplifies the creation of clusters by allowing you to create them throu This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{}}/rancher/v2.x/en/overview/concepts) page. -For a conceptual overview of how the Rancher server provisions clusters, refer to the [architecture]({{}}/rancher/v2.x/en/overview/rancher-and-downstream) section. +For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the [architecture]({{}}/rancher/v2.x/en/overview/architecture/) ## Cluster Creation Options diff --git a/content/rancher/v2.x/en/cluster-provisioning/rancher-agents/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rancher-agents/_index.md index c33c0e85b48..dfbe6716ebd 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rancher-agents/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rancher-agents/_index.md @@ -8,6 +8,8 @@ There are two different agent resources deployed on Rancher managed clusters: - [cattle-cluster-agent](#cattle-cluster-agent) - [cattle-node-agent](#cattle-node-agent) +For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the [architecture]({{}}/rancher/v2.x/en/overview/architecture/) + ### cattle-cluster-agent The `cattle-cluster-agent` is used to connect to the Kubernetes API of [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) clusters. The `cattle-cluster-agent` is deployed using a Deployment resource. diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md index 2b97cb7f728..1313a317b15 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md @@ -71,7 +71,15 @@ See the [RKE documentation on private registries]({{< baseurl >}}/rke/latest/en/ _Available as of v2.2.0_ -Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher. This is enabled by default, using the IP of the node with the `controlplane` role and the default Kubernetes self signed certificates. It is recommended to create an FQDN pointing to a load balancer which load balances across your nodes with the `controlplane` role. If you are using private CA signed certificates on the load balancer, you have to supply the CA certificate which will be included in the generated kubeconfig to validate the certificate chain. See the [Kubeconfig Files]({{}}/rancher/v2.x/en/k8s-in-rancher/kubeconfig/) and [API Keys]({{}}/rancher/v2.x/en/user-settings/api-keys/#creating-an-api-key) documentation for more information. +Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher. + +> The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{}}/rancher/v2.x/en/overview/architecture/#tools-for-provisioning-kubernetes-clusters) to provision the cluster. It is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS. + +This is enabled by default in Rancher-launched Kubernetes clusters, using the IP of the node with the `controlplane` role and the default Kubernetes self signed certificates. + +For more detail on how an authorized cluster endpoint works and why it is used, refer to the [architecture section.]({{}}/rancher/v2.x/en/overview/architecture/4-authorized-cluster-endpoint) + +We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the [recommended architecture section.]({{}}/rancher/v2.x/en/overview/architecture-recommendations/#architecture-for-an-authorized-cluster-endpoint) ### Advanced Cluster Options diff --git a/content/rancher/v2.x/en/overview/_index.md b/content/rancher/v2.x/en/overview/_index.md index 11c5d0b07c8..ed21062618f 100644 --- a/content/rancher/v2.x/en/overview/_index.md +++ b/content/rancher/v2.x/en/overview/_index.md @@ -22,4 +22,5 @@ Rancher provides an intuitive user interface for DevOps engineers to manage thei The following figure illustrates the role Rancher plays in IT and DevOps organizations. Each team deploys their applications on the public or private clouds they choose. IT administrators gain visibility and enforce policies across all users, clusters, and clouds. -![Platform]({{< baseurl >}}/img/rancher/platform.png) \ No newline at end of file +![Platform]({{< baseurl >}}/img/rancher/platform.png) + diff --git a/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md b/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md index 3dd8476a703..1ae162a6ddf 100644 --- a/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md +++ b/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md @@ -14,6 +14,7 @@ This section covers the following topics: - [Recommended Load Balancer Configuration for HA Installations](#recommended-load-balancer-configuration-for-ha-installations) - [Environment for HA Installations](#environment-for-ha-installations) - [Recommended Node Roles for HA Installations](#recommended-node-roles-for-ha-installations) +- [Architecture for an Authorized Cluster Endpoint](#architecture-for-an-authorized-cluster-endpoint) # Separation of Rancher and User Clusters @@ -82,4 +83,10 @@ With that said, it is safe to use all three roles on three nodes when setting up Because no additional workloads will be deployed on the Rancher server cluster, in most cases it is not necessary to use the same architecture that we recommend for the scalability and reliability of user clusters. -For details on the recommended best practices for user clusters, refer to the [production checklist]({{}}/rancher/v2.x/en/cluster-provisioning/production) or our [best practices guide.]({{}}/rancher/v2.x/en/best-practices/management/#tips-for-scaling-and-reliability) \ No newline at end of file +For more best practices for user clusters, refer to the [production checklist]({{}}/rancher/v2.x/en/cluster-provisioning/production) or our [best practices guide.]({{}}/rancher/v2.x/en/best-practices/management/#tips-for-scaling-and-reliability) + +# Architecture for an Authorized Cluster Endpoint + +If you are using an [authorized cluster endpoint,]({{}}/rancher/v2.x/en/overview/architecture/#4-authorized-cluster-endpoint) we recommend creating an FQDN pointing to a load balancer which balances traffic across your nodes with the `controlplane` role. + +If you are using private CA signed certificates on the load balancer, you have to supply the CA certificate, which will be included in the generated kubeconfig file to validate the certificate chain. See the documentation on [kubeconfig files]({{}}/rancher/v2.x/en/k8s-in-rancher/kubeconfig/) and [API keys]({{}}/rancher/v2.x/en/user-settings/api-keys/#creating-an-api-key) for more information. \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/architecture/_index.md b/content/rancher/v2.x/en/overview/architecture/_index.md index eb0f915a12c..6378cba8efd 100644 --- a/content/rancher/v2.x/en/overview/architecture/_index.md +++ b/content/rancher/v2.x/en/overview/architecture/_index.md @@ -1,26 +1,30 @@ --- -title: Rancher Server Architecture +title: Architecture weight: 1 --- -This section focuses on the Rancher server and its components. The Rancher server includes all the software components used to manage the entire Rancher deployment. +This section focuses on the Rancher server, its components, and how Rancher communicates with downstream Kubernetes clusters. -- For the different ways that Rancher can be installed, refer to the [installation options section.]({{}}/rancher/v2.x/en/overview/architecture/installation-options) -- For guidance about setting up the underlying infrastructure for the Rancher server, refer to the [architecture recommendations.]({{}}/rancher/v2.x/en/overview/architecture/architecture-recommendations) -- For an explanation of how Rancher communicates with downstream Kubernetes clusters, refer to the section on [Rancher and downstream user clusters.]({{}}/rancher/v2.x/en/overview/architecture/rancher-and-downstream) +The Rancher server includes all the software components used to manage the entire Rancher deployment. + +For the different ways that Rancher can be installed, refer to the [installation options section.]({{}}/rancher/v2.x/en/overview/installation-options) + +For guidance about setting up the underlying infrastructure for the Rancher server, refer to the [architecture recommendations.]({{}}/rancher/v2.x/en/overview/architecture-recommendations) > This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{}}/rancher/v2.x/en/overview/concepts) page. -# Features of the Rancher API Server +This section covers the following topics: -The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: - -- **User management:** The Rancher API server manages user identities that correspond to external authentication providers like Active Directory or GitHub. -- **Authorization:** The Rancher API server manages access control and security policies. -- **Managing projects:** A _project_ is a group of multiple namespaces and access control policies within a cluster. -- **Tracking nodes:** The Rancher API server tracks identities of all the nodes in all clusters. -- **Provisioning Kubernetes Clusters:** The Rancher API server can provision Kubernetes clusters. Rancher can also set up Kubernetes on existing nodes, or import existing Kubernetes clusters into Rancher. -- **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision new nodes and persistent storage in the cloud. +- [Rancher server architecture](#rancher-server-architecture) + - [Features of the Rancher API server](#features-of-the-rancher-api-server) + - [Rancher server components and source code](#rancher-server-components-and-source-code) +- [Communicating with downstream user clusters](#communicating-with-downstream-user-clusters) + - [The authentication proxy](#1-the-authentication-proxy) + - [Cluster controllers and cluster agents](#2-cluster-controllers-and-cluster-agents) + - [Node agents](#3-node-agents) + - [Authorized cluster endpoint](#4-authorized-cluster-endpoint) +- [Important files](#important-files) +- [Tools for provisioning Kubernetes clusters](#tools-for-provisioning-kubernetes-clusters) # Rancher Server Architecture @@ -30,13 +34,28 @@ The figure below illustrates the high-level architecture of Rancher 2.x. The fig For the best performance and security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads. -![Architecture]({{< baseurl >}}/img/rancher/rancher-architecture-rancher-api-server.svg) - You can install Rancher on a single node, or on a high-availability Kubernetes cluster. A single-node installation is recommended for development and testing purposes, and a high-availability installation is recommended for production. -### Rancher Server Components +The diagram below shows how users can manipulate both [Rancher-launched Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) clusters and [hosted Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) clusters through Rancher's authentication proxy: + +
Manipulating Clusters through Rancher's Authentication Proxy
+ +![Architecture]({{< baseurl >}}/img/rancher/rancher-architecture-rancher-api-server.svg) + +### Features of the Rancher API Server + +The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: + +- **User management:** The Rancher API server [manages user identities]({{}}/rancher/v2.x/en/admin-settings/authentication/) that correspond to external authentication providers like Active Directory or GitHub. +- **Authorization:** The Rancher API server manages [access control]({{}}/rancher/v2.x/en/admin-settings/rbac/) and [security]({{}}/rancher/v2.x/en/admin-settings/pod-security-policies/) policies. +- **Managing projects:** A [project]({{}}/rancher/v2.x/en/project-admin/) is a group of multiple namespaces and access control policies within a cluster. +- **Tracking nodes:** The Rancher API server tracks identities of all the [nodes]({{}}/rancher/v2.x/en/cluster-admin/nodes/) in all clusters. +- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/) on existing nodes, or [import existing Kubernetes clusters]({{}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) into Rancher. +- **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision [new nodes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) and [persistent storage]({{}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) in the cloud. + +### Rancher Server Components and Source Code This diagram shows each component that the Rancher server is composed of: @@ -50,4 +69,113 @@ The GitHub repositories for each component of Rancher can be found at the follow - [Norman,](https://github.com/rancher/norman) Rancher's API framework - [Types](https://github.com/rancher/types) - [Rancher CLI](https://github.com/rancher/cli) -- [Catalog applications](https://github.com/rancher/helm) \ No newline at end of file +- [Catalog applications](https://github.com/rancher/helm) + +# Communicating with Downstream User Clusters + +This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. + +
Cluster Controller, Cluster Agent, and Node Agents Allow Rancher to Control Downstream Clusters
+ +![Rancher Components]({{}}/img/rancher/rancher-architecture-cluster-controller.svg) + +The following descriptions correspond to the numbers in the diagram above: + +1. [The Authentication Proxy](#1-the-authentication-proxy) +2. [Cluster Controllers and Cluster Agents](#2-cluster-controllers-and-cluster-agents) +3. [Node Agents](#3-node-agents) +4. [Authorized Cluster Endpoint](#4-authorized-cluster-endpoint) + +### 1. The Authentication Proxy + +In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a `kubectl` command to see +the pods. Bob is authenticated through Rancher's authentication proxy. + +The authentication proxy forwards all Kubernetes API calls to downstream clusters. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters. + +Rancher communicates with Kubernetes clusters using a [service account,](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) which provides an identity for processes that run in a pod. + +By default, Rancher generates a [kubeconfig file]({{}}/rancher/v2.x/en/cluster-admin/kubeconfig/) that contains credentials for proxying through the Rancher server to connect to the Kubernetes API server on a downstream user cluster. The kubeconfig file (`kube_config_rancher-cluster.yml`) contains full access to the cluster. + +### 2. Cluster Controllers and Cluster Agents + +Each downstream user cluster has a cluster agent, which opens a tunnel to the corresponding cluster controller within the Rancher server. + +There is one cluster controller and one cluster agent for each downstream cluster. + +By default, to enable Rancher to communicate with a downstream cluster, the cluster controller connects to the cluster agent. If the cluster agent is not available, the cluster controller can connect to a [node agent](#3-node-agents) instead. + +The cluster controller is a component of the Rancher server performs the following tasks: + +- Configures access control policies to clusters and projects +- Provisions clusters by calling the required Docker machine drivers and Kubernetes engines, such as RKE and GKE + +The cluster agent, also called `cattle-cluster-agent`, is a component that runs in a downstream user cluster. It performs the following tasks: + +- Connects to the Kubernetes API of Rancher-launched Kubernetes clusters +- Manages workloads, pod creation and deployment within each cluster +- Applies the roles and bindings defined in each cluster's global policies +- Communicates between the cluster and Rancher server (through a tunnel to the cluster controller) about events, stats, node info, and health + +### 3. Node Agents + +If the cluster agent (also called `cattle-cluster-agent`) is not available, one of the node agents creates a tunnel to the cluster controller to communicate with Rancher. + +The `cattle-node-agent` is deployed using a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) resource to make sure it runs on every node in a Rancher-launched Kubernetes cluster. It is used to interact with the nodes when performing cluster operations. Examples of cluster operations include upgrading the Kubernetes version and creating or restoring etcd snapshots. + +### 4. Authorized Cluster Endpoint + +An authorized cluster endpoint allows users to connect to the Kubernetes API server of a downstream cluster without having to route their requests through the Rancher authentication proxy. + +> The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{}}/rancher/v2.x/en/overview/architecture/#tools-for-provisioning-kubernetes-clusters) to provision the cluster. It is not available for imported clusters, or for clusters in a hosted Kubernetes provider, such as Amazon's EKS. + +There are two main reasons why a user might need the authorized cluster endpoint: + +- To access a downstream user cluster while Rancher is down +- To reduce latency in situations where the Rancher server and downstream cluster are separated by a long distance + +The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint. When you access the user cluster using `kubectl`, the cluster's Kubernetes API server authenticates you by using the `kube-api-auth` service as a webhook. + +Like the authorized cluster endpoint, the `kube-api-auth` authentication service is also only available for Rancher-launched Kubernetes clusters. + +> **Example scenario:** Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in China. A user, Alice, also lives in China. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from China to the Rancher server in the United States, then be proxied back to China, where the downstream user cluster is. The geographical distance may cause significant latency. To reduce the latency, which Alice can reduce by using the authorized cluster endpoint. + +With this endpoint enabled for the downstream cluster, Rancher generates an extra Kubernetes context in the kubeconfig file in order to connect directly to the cluster. This file has the credentials for `kubectl` and `helm`. + +You will need to use a context defined in this kubeconfig file to access the cluster if Rancher goes down. Therefore, we recommend exporting the kubeconfig file so that if Rancher goes down, you can still use the credentials in the file to access your cluster. For more information, refer to the [kubeconfig file]({{}}/rancher/v2.x/en/cluster-admin/kubeconfig) documentation. + +# Important Files + +The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster: + +- `rancher-cluster.yml`: The RKE cluster configuration file. +- `kube_config_rancher-cluster.yml`: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster. You can use this file to authenticate with a Rancher-launched Kubernetes cluster if Rancher goes down. +- `rancher-cluster.rkestate`: The Kubernetes cluster state file. This file contains credentials for full access to the cluster. Note: This state file is only created when using RKE v0.2.0 or higher. + +For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the [kubeconfig file]({{}}/rancher/v2.x/en/cluster-admin/kubeconfig/) documentation. + +# Tools for Provisioning Kubernetes Clusters + +The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned. + +### Rancher Launched Kubernetes for Hodes Hosted in an Infrastructure Provider + +Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them. + +Rancher provisions this type of cluster using [RKE](https://github.com/rancher/rke) and [docker-machine.](https://github.com/rancher/machine) + +### Rancher Launched Kubernetes for Custom Nodes + +When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster. + +Rancher provisions this type of cluster using [RKE.](https://github.com/rancher/rke) + +### Hosted Kubernetes Providers + +When setting up this type of cluster, Kubernetes is installed by providers such as Google Kubernetes Engine, Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service. + +Rancher provisions this type of cluster using [kontainer-engine.](https://github.com/rancher/kontainer-engine) + +### Imported Kubernetes Clusters + +In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster. \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/concepts/_index.md b/content/rancher/v2.x/en/overview/concepts/_index.md index 636c39232e0..c7d848f88da 100644 --- a/content/rancher/v2.x/en/overview/concepts/_index.md +++ b/content/rancher/v2.x/en/overview/concepts/_index.md @@ -3,6 +3,8 @@ title: Kubernetes Concepts weight: 4 --- +This page explains concepts related to Kubernetes that are important for understanding how Rancher works. The descriptions below provide a simplified interview of Kubernetes components. For more details, refer to the [official documentation on Kubernetes components.](https://kubernetes.io/docs/concepts/overview/components/) + This section covers the following topics: - [About Docker](#about-docker) diff --git a/content/rancher/v2.x/en/overview/installation-options/_index.md b/content/rancher/v2.x/en/overview/installation-options/_index.md index e54fb488014..18b2f30f426 100644 --- a/content/rancher/v2.x/en/overview/installation-options/_index.md +++ b/content/rancher/v2.x/en/overview/installation-options/_index.md @@ -21,10 +21,10 @@ Basic options for installing Rancher include the following: Level of Internet Access | Single Node Instructions | HA Instructions ---------------------------|-----------------------------|------------------ With direct access to the Internet | [Docs]({{}}/rancher/v2.x/en/installation/single-node/) | [Docs]({{}}/rancher/v2.x/en/installation/ha/) -Behind an HTTP proxy | [Docs]({{}}/rancher/v2.x/en/installation/single-node/proxy/) | [Docs]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#http-proxy) +Behind an HTTP proxy | These [docs,]({{}}/rancher/v2.x/en/installation/single-node/) plus this [configuration]({{}}/rancher/v2.x/en/installation/single-node/proxy/) | These [docs,]({{}}/rancher/v2.x/en/installation/ha/) plus this [configuration]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#http-proxy) In an air gap environment | [Docs]({{}}/rancher/v2.x/en/installation/air-gap/) | [Docs]({{}}/rancher/v2.x/en/installation/air-gap/) -# More Options +# More Options for HA Installations Refer to the [Helm chart options]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/) for details on installing HA Rancher with other configurations, including: @@ -32,10 +32,14 @@ Refer to the [Helm chart options]({{}}/rancher/v2.x/en/installation/ha/ - With [TLS termination on a load balancer]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#external-tls-termination) - With a [custom Ingress]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#customizing-your-ingress) -RKE also has many configuration options for customizing the Kubernetes cluster to suit your specific environment. Please see the [RKE Documentation]({{}}/rke/latest/en/config-options/) for the full list of options and capabilities. +# More Options for Single Node Installations Refer to the [single node installation docs]({{}}/rancher/v2.x/en/installation/single-node/) for details other configurations including: - With [API auditing to record all transactions]({{}}/rancher/v2.x/en/installation/single-node/#api-audit-log) - With an [external load balancer]({{}}/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/) -- With a [persistent data store]({{}}/rancher/v2.x/en/installation/single-node/#persistent-data) \ No newline at end of file +- With a [persistent data store]({{}}/rancher/v2.x/en/installation/single-node/#persistent-data) + +# More Kubernetes Options + +RKE also has many configuration options for customizing the Kubernetes cluster to suit your specific environment. Please see the [RKE Documentation]({{}}/rke/latest/en/config-options/) for the full list of options and capabilities. \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md b/content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md deleted file mode 100644 index 36a9868dfa4..00000000000 --- a/content/rancher/v2.x/en/overview/rancher-and-downstream/_index.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Rancher and Downstream User Clusters -weight: 5 ---- - -This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. - -- [How Rancher Communicates with Downstream User Clusters](#how-rancher-communicates-with-downstream-user-clusters) -- [Authentication Proxy](#authentication-proxy) - - [Connecting to a Cluster without the Rancher UI](#connecting-to-a-cluster-without-the-rancher-ui) -- [How Rancher Provisions Kubernetes Clusters](#how-rancher-provisions-kubernetes-clusters) - -# How Rancher Communicates with Downstream User Clusters - -Rancher communicates with downstream user clusters by using three types of components: the cluster controller, the cluster agent, and the node agent. These components are used for provisioning and managing Kubernetes clusters. - -The cluster controller and cluster agents implement the business logic required to manage Kubernetes clusters. - -Rancher installs the `cattle-node-agent` on each node in downstream user clusters in order to manage them. - -
Cluster Controller, Cluster Agent, and Node Agents Allow Rancher to Control Downstream Clusters
- -![Rancher Components]({{}}/img/rancher/rancher-architecture-cluster-controller.svg) - -The following descriptions correspond to the numbers in the diagram above: - -1. Let's say a user, Bob, wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a `kubectl` command to see -the pods. Bob is authenticated through Rancher's authentication proxy. - -2. Each downstream user cluster has a cluster agent, which opens a tunnel connecting the user cluster with Rancher's corresponding cluster controller. - -3. By default, the cluster controller connects to the cluster agent. If the cluster agent is not available, one of the node agents creates a tunnel to the cluster controller to communicate with Rancher. - -4. Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in China. A user, Alice, lives in China. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but she may experience latency due to the distance between US and China. To reduce latency, she can use Rancher's authorized cluster endpoint feature. By default, an authorized cluster endpoint is enabled, which allows Alice to be authenticated by calling the Kubernetes API server of the user cluster, without going through Rancher's authentication proxy. When Alice uses kubectl to access the user cluster, the cluster's Kubernetes API server authenticates Alice by using the `kube-api-auth` service as a webhook. The `kube-api-auth` authentication service and authorized cluster endpoint are only available for Rancher-launched Kubernetes clusters. - -### The Cluster Controller - -The _cluster controller_ implements the logic required for the global Rancher install. It performs the following actions: - -- Configures access control policies to clusters and projects -- Provisions clusters by calling the required Docker machine drivers and Kubernetes engines, such as RKE and GKE - -### The Cluster Agent - -The `cattle-cluster-agent` is used to connect to the Kubernetes API of Rancher Launched Kubernetes clusters. The `cattle-cluster-agent` is deployed on the Rancher server using a deployment resource. - -The cluster agent implements the logic required for the corresponding downstream user cluster. It performs the following activities: - -- Manages workloads, pod creation and deployment within each cluster -- Applies the roles and bindings defined in each cluster's global policies -- Communicates between clusters and Rancher server about events, stats, node info, and health - -### The Node Agent - -The `cattle-node-agent` is deployed using a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) resource to make sure it runs on every node in a Rancher-launched Kubernetes cluster. It is used to interact with the nodes when performing cluster operations. Examples of cluster operations include upgrading the Kubernetes version and creating or restoring etcd snapshots. - -The `cattle-node-agent` is also used as fallback option to connect to the Kubernetes API of Rancher Launched Kubernetes clusters when `cattle-cluster-agent` is unavailable. - -# Authentication Proxy - -The _authentication proxy_ forwards all Kubernetes API calls. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters. - -Rancher communicates with Kubernetes clusters using a [service account,](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), which provides an identity for processes that run in a pod. - -### Connecting to a Cluster without the Rancher UI - -By default, Rancher generates a kubeconfig file that will proxy through the Rancher server to connect to the Kubernetes API server on a cluster. - -For [Rancher launched Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters) clusters, which have an [authorized cluster endpoint]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#authorized-cluster-endpoint) enabled, Rancher generates extra context(s) in the kubeconfig file in order to connect directly to the cluster. The authorized cluster endpoint is enabled by default. - -When you want to use kubectl to access this cluster without Rancher, you will need to use a context defined in this kubeconfig file. This file has the credentials for `kubectl` and `helm`. - -The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint. - -The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster: - -- `rancher-cluster.yml`: The RKE cluster configuration file. -- `kube_config_rancher-cluster.yml`: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster. -- `rancher-cluster.rkestate`: The Kubernetes Cluster State file. This file contains credentials for full access to the cluster. Note: This state file is only created when using RKE v0.2.0 or higher. - -For more information on connecting to a cluster without the Rancher UI, refer to the [kubeconfig file]({{}}/rancher/v2.x/en/cluster-admin/kubeconfig/) documentation. - -# How Rancher Provisions Kubernetes Clusters - -The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned. - -### Rancher Launched Kubernetes for Hodes Hosted in an Infrastructure Provider - -Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them. - -Rancher provisions this type of cluster using [RKE](https://github.com/rancher/rke) and [docker-machine.](https://github.com/rancher/machine) - -### Rancher Launched Kubernetes for Custom Nodes - -When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster. - -Rancher provisions this type of cluster using [RKE.](https://github.com/rancher/rke) - -### Hosted Kubernetes Providers - -When setting up this type of cluster, Kubernetes is installed by providers such as Google Kubernetes Engine, Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service. - -Rancher provisions this type of cluster using [kontainer-engine.](https://github.com/rancher/kontainer-engine) - -### Imported Kubernetes Clusters - -In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster. \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-cluster-controller.svg b/static/img/rancher/rancher-architecture-cluster-controller.svg index 629e256d947..5513b083a82 100644 --- a/static/img/rancher/rancher-architecture-cluster-controller.svg +++ b/static/img/rancher/rancher-architecture-cluster-controller.svg @@ -1,3 +1,3 @@ -
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
kubectl get pods
[Not supported by viewer]
kube-api-auth
[Not supported by viewer]
Bob
[Not supported by viewer]
Alice
Alice
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
4
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
kubectl get pods
[Not supported by viewer]
Cluster Agent
[Not supported by viewer]
1
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
Cluster Controller 1
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Cluster Controller 3
[Not supported by viewer]
Authentication
Proxy
[Not supported by viewer]
2
[Not supported by viewer]
3
[Not supported by viewer]
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
User Cluster 2
[Not supported by viewer]
User Cluster 2
[Not supported by viewer] \ No newline at end of file +
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
kubectl get pods
[Not supported by viewer]
kube-api-auth
[Not supported by viewer]
Bob
[Not supported by viewer]
Alice
Alice
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
4
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
kubectl get pods
[Not supported by viewer]
Cluster Agent
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
Cluster Controller 1
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Cluster Controller 3
[Not supported by viewer]
2
[Not supported by viewer]
3
[Not supported by viewer]
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
User Cluster 2
[Not supported by viewer]
User Cluster 2
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer]
1
[Not supported by viewer]
Authorized Cluster Endpoint
Authorized Cluster Endpoint \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-node-roles.svg b/static/img/rancher/rancher-architecture-node-roles.svg index 5819125b275..a4ecef73357 100644 --- a/static/img/rancher/rancher-architecture-node-roles.svg +++ b/static/img/rancher/rancher-architecture-node-roles.svg @@ -1,3 +1,3 @@ -
Roles for Nodes in a High-Availability Rancher Server Cluster
<font style="font-size: 16px">Roles for Nodes in a High-Availability Rancher Server Cluster<br></font>
Roles for Nodes in a Downstream User Cluster
<font style="font-size: 16px">Roles for Nodes in a Downstream User Cluster<br></font>
Kubernetes Master
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Kubernetes Master
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Node with etcd role
Node with etcd role
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Node with controlplane role
Node with controlplane role
Kubelet
[Not supported by viewer]
Note: A kubelet is an agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
Note: A kubelet is an agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer] \ No newline at end of file +
Roles for Nodes in a High-Availability Rancher Server Cluster
<font style="font-size: 16px">Roles for Nodes in a High-Availability Rancher Server Cluster<br></font>
Roles for Nodes in a Downstream User Cluster
<font style="font-size: 16px">Roles for Nodes in a Downstream User Cluster<br></font>
Kubernetes Master
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Note: A kubelet is an agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
Note: A kubelet is an agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
Kubernetes Master
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Node with etcd role
Node with etcd role
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Node with controlplane role
Node with controlplane role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer] \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-rancher-api-server.svg b/static/img/rancher/rancher-architecture-rancher-api-server.svg index 1fe663f730a..4b37175686b 100644 --- a/static/img/rancher/rancher-architecture-rancher-api-server.svg +++ b/static/img/rancher/rancher-architecture-rancher-api-server.svg @@ -1,3 +1,3 @@ -
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Rancher UI
CLI
API
[Not supported by viewer]
kubectl
K8s API
[Not supported by viewer]
RKE Nodes
[Not supported by viewer]
AWS EKS Nodes
[Not supported by viewer]
RKE
K8s Master
[Not supported by viewer]
EKS
K8s Master
[Not supported by viewer]
Downstream User Cluster 1,
controlled by Cluster Agent 1
[Not supported by viewer]
Downstream User Cluster 2,
controlled by Cluster Agent 2
[Not supported by viewer]
Cluster Agent 1
[Not supported by viewer]
Cluster Agent 2
[Not supported by viewer]
Cluster Controller
[Not supported by viewer]
Rancher API
Server
[Not supported by viewer]
Auth Proxy
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
etcd
[Not supported by viewer]
Rancher Server Data Store
<font style="font-size: 16px">Rancher Server Data Store<br></font> \ No newline at end of file +
Rancher UI,
CLI, or API
[Not supported by viewer]
kubectl,
Kubernetes
API
[Not supported by viewer]
RKE Nodes
[Not supported by viewer]
AWS
EKS Nodes
[Not supported by viewer]
RKE
Kubernetes API Server
[Not supported by viewer]
Cluster Agent 1
[Not supported by viewer]
Cluster Agent 2
[Not supported by viewer]
Cluster Controller 1
[Not supported by viewer]
Rancher API
Server
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
etcd
[Not supported by viewer]
Rancher Server
Data Store
[Not supported by viewer]
EKS
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Downstream User
Cluster 1
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Downstream User
Cluster 2
[Not supported by viewer]
Rancher User
Rancher User \ No newline at end of file From afbff987c8488c5c20daa2c36f78a524c8dafd99 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 21 Nov 2019 15:07:45 -0700 Subject: [PATCH 06/18] Respond to feedback on architecture page --- content/rancher/v2.x/en/catalog/_index.md | 68 +++++++++--------- .../rancher/v2.x/en/contributing/_index.md | 2 +- .../v2.x/en/overview/architecture/_index.md | 72 +++++++++++-------- .../overview/installation-options/_index.md | 6 +- ...ancher-architecture-cluster-controller.svg | 2 +- ...ancher-architecture-rancher-api-server.svg | 2 +- 6 files changed, 82 insertions(+), 70 deletions(-) diff --git a/content/rancher/v2.x/en/catalog/_index.md b/content/rancher/v2.x/en/catalog/_index.md index 6a954a02a01..7f0070a1ebb 100644 --- a/content/rancher/v2.x/en/catalog/_index.md +++ b/content/rancher/v2.x/en/catalog/_index.md @@ -7,29 +7,38 @@ aliases: - /rancher/v2.x/en/tasks/global-configuration/catalog/ --- -## Catalogs - Rancher provides the ability to use a catalog of Helm charts that make it easy to repeatedly deploy applications. -_Catalogs_ are GitHub repositories or Helm Chart repositories filled with applications that are ready-made for deployment. Applications are bundled in objects called _Helm charts_. - ->A collection of files that describe a related set of Kubernetes resources. A single chart might be used to deploy something simple, like a memcached pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on. +- **Catalogs** are GitHub repositories or Helm Chart repositories filled with applications that are ready-made for deployment. Applications are bundled in objects called _Helm charts_. +- **Helm charts** are a collection of files that describe a related set of Kubernetes resources. A single chart might be used to deploy something simple, like a memcached pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on. Rancher improves on Helm catalogs and charts. All native Helm charts can work within Rancher, but Rancher adds several enhancements to improve their user experience. -## Catalog Scopes +This section covers the following topics: -Catalogs can be added at different scopes of Rancher. +- [Catalog scopes](#catalog-scopes) +- [Enabling built-in global catalogs](#enabling-built-in-global-catalogs) +- [Adding custom global catalogs](#adding-custom-global-catalogs) + - [Add custom Git repositories](#add-custom-git-repositories) + - [Add custom Helm chart repositories](#add-custom-helm-chart-repositories) + - [Add private Git/Helm chart repositories](#add-private-git-helm-chart-repositories) +- [Launching catalog applications](#launching-catalog-applications) +- [Working with catalogs](#working-with-catalogs) + - [Apps](#apps) + - [Global DNS](#global-dns) + - [Chart compatibility with Rancher](#chart-compatibility-with-rancher) -Scope | Description ---- | --- -Global | Catalogs added at this scope are available for all clusters and all projects in Rancher. -Cluster | Catalogs added within a cluster are available for all projects in that cluster. -Project | Catalogs added within a project are only available for that project. +# Catalog Scopes -## Global catalogs +Within Rancher, you can manage catalogs at three different scopes. Global catalogs are shared across all clusters and project. There are some use cases where you might not want to share catalogs across between different clusters or even projects in the same cluster. By leveraging cluster and project scoped catalogs, you will be able to provide applications for specific teams without needing to share them with all clusters and/or projects. -## Enabling Built-in Catalogs +Scope | Description | Available As of | +--- | --- | --- | +Global | All clusters and all projects can access the Helm charts in this catalog | v2.0.0 | +Cluster | All projects in the specific cluster can access the Helm charts in this catalog | v2.2.0 | +Project | This specific cluster can access the Helm charts in this catalog | v2.2.0 | + +# Enabling Built-in Global Catalogs Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator. @@ -53,15 +62,14 @@ Within Rancher, there are default catalogs packaged as part of Rancher. These ca **Result**: The chosen catalogs are enabled. Wait a few minutes for Rancher to replicate the catalog charts. When replication completes, you'll be able to see them in any of your projects by selecting **Apps** from the main navigation bar. In versions prior to v2.2.0, you can select **Catalog Apps** from the main navigation bar. -## Adding Custom Catalogs +# Adding Custom Global Catalogs Adding a catalog is as simple as adding a catalog name, a URL and a branch name. -#### Add Custom Git Repositories +### Add Custom Git Repositories The Git URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will use the `master` branch by default. Whenever you add a catalog to Rancher, it will be available immediately. - -#### Add Custom Helm Chart Repositories +### Add Custom Helm Chart Repositories A Helm chart repository is an HTTP server that houses one or more packaged charts. Any HTTP server that can serve YAML files and tar files and can answer GET requests can be used as a repository server. @@ -69,7 +77,7 @@ Helm comes with built-in package server for developer testing (helm serve). The In Rancher, you can add the custom Helm chart repository with only a catalog name and the URL address of the chart repository. -#### Add Private Git/Helm Chart Repositories +### Add Private Git/Helm Chart Repositories _Available as of v2.2.0_ In Rancher v2.2.0, you can add private catalog repositories using credentials like Username and Password. You may also want to use the @@ -90,7 +98,7 @@ NEEDS TO BE FIXED FOR 2.0: Any [users]({{site.baseurl}}/rancher/{{page.version}} **Result**: Your catalog is added to Rancher. -## Launching Catalog Applications +# Launching Catalog Applications After you've either enabled the built-in catalogs or added your own custom catalog, you can start launching any catalog application.> @@ -121,31 +129,21 @@ After you've either enabled the built-in catalogs or added your own custom catal By creating a customized repository with added files, Rancher improves on Helm repositories and charts. All native Helm charts can work within Rancher, but Rancher adds several enhancements to improve their user experience. -### Catalog Scope - -Within Rancher, you can manage catalogs at three different scopes. Global catalogs is shared across all clusters and project. There are some use cases where you might not want to share catalogs across between different clusters or even projects in the same cluster. By leveraging cluster and project scoped catalogs, you will be able to provide applications for specific teams without needing to share them with all clusters and/or projects. - -Scope | Description | Available As of | ---- | --- | --- | -Global | All clusters and all projects can access the Helm charts in this catalog | v2.0.0 | -Cluster | All projects in the specific cluster can access the Helm charts in this catalog | v2.2.0 | -Project | This specific cluster can access the Helm charts in this catalog | v2.2.0 | - -### Working with catalogs +# Working with Catalogs There are two types of catalogs in Rancher. Learn more about each type: * [Built-in Global Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/built-in/) * [Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/) -## Apps +### Apps In Rancher, applications are deployed from the templates in a catalog. Rancher supports two types of applications: * [Multi-cluster applications]({{< baseurl >}}/rancher/v2.x/en/catalog/multi-cluster-apps/) * [Applications deployed in a specific Project]({{< baseurl >}}/rancher/v2.x/en/catalog/apps) -## Global DNS +### Global DNS _Available as v2.2.0_ @@ -153,6 +151,6 @@ When creating applications that span multiple Kubernetes clusters, a Global DNS For more information on how to use this feature, see [Global DNS]({{< baseurl >}}/rancher/v2.x/en/catalog/globaldns/). -## Chart Compatibility with Rancher +### Chart Compatibility with Rancher -Charts now support a field called `rancher_min_version` and `rancher_max_version` in the [`questions.yml` file](https://github.com/rancher/integration-test-charts/blob/master/charts/chartmuseum/v1.6.0/questions.yml) to specify the versions of Rancher that the chart is compatible with. When using the UI, only app versions that are valid for the version of Rancher running will be shown. API validation is done to ensure apps that don't meet the Rancher requirements cannot be launched. An app that is already running will not be affected on a Rancher upgrade if the newer Rancher version does not meet the app's requirements. +Charts now support the fields `rancher_min_version` and `rancher_max_version` in the [`questions.yml` file](https://github.com/rancher/integration-test-charts/blob/master/charts/chartmuseum/v1.6.0/questions.yml) to specify the versions of Rancher that the chart is compatible with. When using the UI, only app versions that are valid for the version of Rancher running will be shown. API validation is done to ensure apps that don't meet the Rancher requirements cannot be launched. An app that is already running will not be affected on a Rancher upgrade if the newer Rancher version does not meet the app's requirements. diff --git a/content/rancher/v2.x/en/contributing/_index.md b/content/rancher/v2.x/en/contributing/_index.md index 375a42b995e..857f81ef92c 100644 --- a/content/rancher/v2.x/en/contributing/_index.md +++ b/content/rancher/v2.x/en/contributing/_index.md @@ -36,7 +36,7 @@ CLI | https://github.com/rancher/cli | This repository is the source code for th Telemetry repository | https://github.com/rancher/telemetry | This repository is the source for the Telemetry binary. loglevel repository | https://github.com/rancher/loglevel | This repository is the source of the loglevel binary, used to dynamically change log levels. -To see all libraries/projects used in Rancher, see the `vendor.conf` in the `rancher/rancher` repository. +To see all libraries/projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository. ![Rancher diagram]({{< baseurl >}}/img/rancher/ranchercomponentsdiagram.svg)
Rancher components used for provisioning/managing Kubernetes clusters. diff --git a/content/rancher/v2.x/en/overview/architecture/_index.md b/content/rancher/v2.x/en/overview/architecture/_index.md index 6378cba8efd..29ba8dd699d 100644 --- a/content/rancher/v2.x/en/overview/architecture/_index.md +++ b/content/rancher/v2.x/en/overview/architecture/_index.md @@ -5,9 +5,7 @@ weight: 1 This section focuses on the Rancher server, its components, and how Rancher communicates with downstream Kubernetes clusters. -The Rancher server includes all the software components used to manage the entire Rancher deployment. - -For the different ways that Rancher can be installed, refer to the [installation options section.]({{}}/rancher/v2.x/en/overview/installation-options) +For information on the different ways that Rancher can be installed, refer to the [installation options section.]({{}}/rancher/v2.x/en/overview/installation-options) For guidance about setting up the underlying infrastructure for the Rancher server, refer to the [architecture recommendations.]({{}}/rancher/v2.x/en/overview/architecture-recommendations) @@ -17,7 +15,6 @@ This section covers the following topics: - [Rancher server architecture](#rancher-server-architecture) - [Features of the Rancher API server](#features-of-the-rancher-api-server) - - [Rancher server components and source code](#rancher-server-components-and-source-code) - [Communicating with downstream user clusters](#communicating-with-downstream-user-clusters) - [The authentication proxy](#1-the-authentication-proxy) - [Cluster controllers and cluster agents](#2-cluster-controllers-and-cluster-agents) @@ -25,6 +22,7 @@ This section covers the following topics: - [Authorized cluster endpoint](#4-authorized-cluster-endpoint) - [Important files](#important-files) - [Tools for provisioning Kubernetes clusters](#tools-for-provisioning-kubernetes-clusters) +- [Rancher server components and source code](#rancher-server-components-and-source-code) # Rancher Server Architecture @@ -34,48 +32,42 @@ The figure below illustrates the high-level architecture of Rancher 2.x. The fig For the best performance and security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads. -You can install Rancher on a single node, or on a high-availability Kubernetes cluster. - -A single-node installation is recommended for development and testing purposes, and a high-availability installation is recommended for production. - The diagram below shows how users can manipulate both [Rancher-launched Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) clusters and [hosted Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) clusters through Rancher's authentication proxy: -
Manipulating Clusters through Rancher's Authentication Proxy
+
Managing Kubernetes Clusters through Rancher's Authentication Proxy
![Architecture]({{< baseurl >}}/img/rancher/rancher-architecture-rancher-api-server.svg) +You can install Rancher on a single node, or on a high-availability Kubernetes cluster. + +A high-availability installation is recommended for production. A single-node installation may be used for development and testing purposes, but there is no migration path from a single-node to a high-availability installation. Therefore, you may want to use a high-availability installation from the start. + +The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. + ### Features of the Rancher API Server The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: -- **User management:** The Rancher API server [manages user identities]({{}}/rancher/v2.x/en/admin-settings/authentication/) that correspond to external authentication providers like Active Directory or GitHub. +- **User management:** The Rancher API server [manages user identities]({{}}/rancher/v2.x/en/admin-settings/authentication/) that correspond to external authentication providers like Active Directory or GitHub, in addition to local users. - **Authorization:** The Rancher API server manages [access control]({{}}/rancher/v2.x/en/admin-settings/rbac/) and [security]({{}}/rancher/v2.x/en/admin-settings/pod-security-policies/) policies. -- **Managing projects:** A [project]({{}}/rancher/v2.x/en/project-admin/) is a group of multiple namespaces and access control policies within a cluster. +- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, and it allows you manage multiple namespaces as a group. The Rancher UI provides features for [project administration]({{}}/rancher/v2.x/en/project-admin/) and for [managing applications within projects.]({{}}/rancher/v2.x/en/k8s-in-rancher/) - **Tracking nodes:** The Rancher API server tracks identities of all the [nodes]({{}}/rancher/v2.x/en/cluster-admin/nodes/) in all clusters. -- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/) on existing nodes, or [import existing Kubernetes clusters]({{}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) into Rancher. +- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/) on existing nodes, [import existing Kubernetes clusters]({{}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) into Rancher, or perform [Kubernetes upgrades.]({{}}/rancher/v2.x/en/cluster-admin/editing-clusters/#upgrading-kubernetes) - **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision [new nodes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) and [persistent storage]({{}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) in the cloud. - -### Rancher Server Components and Source Code - -This diagram shows each component that the Rancher server is composed of: - -![Rancher Components]({{}}/img/rancher/rancher-architecture-rancher-components.svg) - -The GitHub repositories for each component of Rancher can be found at the following links: - -- [Main Rancher server repository](https://github.com/rancher/rancher) -- [Rancher UI](https://github.com/rancher/ui) -- [Rancher API UI](https://github.com/rancher/api-ui) -- [Norman,](https://github.com/rancher/norman) Rancher's API framework -- [Types](https://github.com/rancher/types) -- [Rancher CLI](https://github.com/rancher/cli) -- [Catalog applications](https://github.com/rancher/helm) +- **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts]({{}}/rancher/v2.x/en/catalog/) that make it easy to repeatedly deploy applications. +- **Logging:** Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters. Logging can be set up [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/logging/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/logging/) +- **Monitoring:** Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. Monitoring can be configured [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/monitoring/) +- **Alerting:** To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. To help you stay informed of these events, you can configure alerts [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/alerts/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/alerts/) +- **Pipelines:** Setting up a [pipeline]({{}}/rancher/v2.x/en/project-admin/tools/pipelines/) can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects. +- **Istio:** Our [integration with Istio]({{}}/rancher/v2.x/en/cluster-admin/tools/istio/) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing. # Communicating with Downstream User Clusters This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. -
Cluster Controller, Cluster Agent, and Node Agents Allow Rancher to Control Downstream Clusters
+The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters. + +
Communicating with Downstream Clusters
![Rancher Components]({{}}/img/rancher/rancher-architecture-cluster-controller.svg) @@ -158,7 +150,7 @@ For more information on connecting to a cluster without the Rancher authenticati The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned. -### Rancher Launched Kubernetes for Hodes Hosted in an Infrastructure Provider +### Rancher Launched Kubernetes for Nodes Hosted in an Infrastructure Provider Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them. @@ -178,4 +170,22 @@ Rancher provisions this type of cluster using [kontainer-engine.](https://github ### Imported Kubernetes Clusters -In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster. \ No newline at end of file +In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster. + +# Rancher Server Components and Source Code + +This diagram shows each component that the Rancher server is composed of: + +![Rancher Components]({{}}/img/rancher/rancher-architecture-rancher-components.svg) + +The GitHub repositories for Rancher can be found at the following links: + +- [Main Rancher server repository](https://github.com/rancher/rancher) +- [Rancher UI](https://github.com/rancher/ui) +- [Rancher API UI](https://github.com/rancher/api-ui) +- [Norman,](https://github.com/rancher/norman) Rancher's API framework +- [Types](https://github.com/rancher/types) +- [Rancher CLI](https://github.com/rancher/cli) +- [Catalog applications](https://github.com/rancher/helm) + +This is a partial list of the most important Rancher repositories. For more details about Rancher source code, refer to the section on [contributing to Rancher.]({{}}/rancher/v2.x/en/contributing/#repositories) To see all libraries and projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository. \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/installation-options/_index.md b/content/rancher/v2.x/en/overview/installation-options/_index.md index 18b2f30f426..55bf24e267f 100644 --- a/content/rancher/v2.x/en/overview/installation-options/_index.md +++ b/content/rancher/v2.x/en/overview/installation-options/_index.md @@ -5,6 +5,10 @@ weight: 2 Rancher can be installed on a single node or a high-availability cluster. +A high-availability installation is recommended for production. A single-node installation may be used for development and testing purposes, but there is no migration path from a single-node to a high-availability installation. Therefore, you may want to use a high-availability installation from the start. + +The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. + On a single node, Rancher is installed with Docker and many options are configured with Docker commands. On a Kubernetes cluster, Rancher is installed with Helm, and Helm commands are used to pass in configuration options. [Helm]({{}}/rancher/v2.x/en/overview/architecture/concepts/#about-helm) is a Kubernetes package manager. @@ -42,4 +46,4 @@ Refer to the [single node installation docs]({{}}/rancher/v2.x/en/insta # More Kubernetes Options -RKE also has many configuration options for customizing the Kubernetes cluster to suit your specific environment. Please see the [RKE Documentation]({{}}/rke/latest/en/config-options/) for the full list of options and capabilities. \ No newline at end of file +In the Rancher installation instructions, we recommend using RKE (Rancher Kubernetes Engine) to set up a Kubernetes cluster before installing Rancher on the cluster. RKE has many configuration options for customizing the Kubernetes cluster to suit your specific environment. Please see the [RKE Documentation]({{}}/rke/latest/en/config-options/) for the full list of options and capabilities. \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-cluster-controller.svg b/static/img/rancher/rancher-architecture-cluster-controller.svg index 5513b083a82..517cb8d903d 100644 --- a/static/img/rancher/rancher-architecture-cluster-controller.svg +++ b/static/img/rancher/rancher-architecture-cluster-controller.svg @@ -1,3 +1,3 @@ -
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
kubectl get pods
[Not supported by viewer]
kube-api-auth
[Not supported by viewer]
Bob
[Not supported by viewer]
Alice
Alice
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
4
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
kubectl get pods
[Not supported by viewer]
Cluster Agent
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
Cluster Controller 1
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Cluster Controller 3
[Not supported by viewer]
2
[Not supported by viewer]
3
[Not supported by viewer]
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
User Cluster 2
[Not supported by viewer]
User Cluster 2
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer]
1
[Not supported by viewer]
Authorized Cluster Endpoint
Authorized Cluster Endpoint \ No newline at end of file +
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
kubectl get pods
[Not supported by viewer]
kube-api-auth
[Not supported by viewer]
Bob
[Not supported by viewer]
Alice
Alice
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
4
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
kubectl get pods
[Not supported by viewer]
Cluster Agent
[Not supported by viewer]
1
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
Cluster Controller 1
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Cluster Controller 3
[Not supported by viewer]
2
[Not supported by viewer]
3
[Not supported by viewer]
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
User Cluster 2
[Not supported by viewer]
User Cluster 3
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer] \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-rancher-api-server.svg b/static/img/rancher/rancher-architecture-rancher-api-server.svg index 4b37175686b..1b89e28d84a 100644 --- a/static/img/rancher/rancher-architecture-rancher-api-server.svg +++ b/static/img/rancher/rancher-architecture-rancher-api-server.svg @@ -1,3 +1,3 @@ -
Rancher UI,
CLI, or API
[Not supported by viewer]
kubectl,
Kubernetes
API
[Not supported by viewer]
RKE Nodes
[Not supported by viewer]
AWS
EKS Nodes
[Not supported by viewer]
RKE
Kubernetes API Server
[Not supported by viewer]
Cluster Agent 1
[Not supported by viewer]
Cluster Agent 2
[Not supported by viewer]
Cluster Controller 1
[Not supported by viewer]
Rancher API
Server
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
etcd
[Not supported by viewer]
Rancher Server
Data Store
[Not supported by viewer]
EKS
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Downstream User
Cluster 1
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Downstream User
Cluster 2
[Not supported by viewer]
Rancher User
Rancher User \ No newline at end of file +
Rancher UI,
CLI, or API
[Not supported by viewer]
kubectl,
Kubernetes
API
[Not supported by viewer]
RKE Nodes
[Not supported by viewer]
Amazon
EKS Nodes
[Not supported by viewer]
RKE
Kubernetes API Server
[Not supported by viewer]
Cluster Agent 1
[Not supported by viewer]
Cluster Agent 2
[Not supported by viewer]
Cluster Controller 1
[Not supported by viewer]
Rancher API
Server
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
etcd
[Not supported by viewer]
Rancher Server
Data Store
[Not supported by viewer]
EKS
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Downstream User
Cluster 1
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Downstream User
Cluster 2
[Not supported by viewer]
Rancher User
Rancher User
Kubernetes provisioned
by Rancher Kubernetes
Engine
[Not supported by viewer]
Kubernetes provisioned
by Amazon Elastic
Kubernetes Service
[Not supported by viewer] \ No newline at end of file From 3c917c84f1460f5f1f105b6c6877fbced135abe7 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 21 Nov 2019 15:21:55 -0700 Subject: [PATCH 07/18] Move list of Rancher features to overview page --- content/rancher/v2.x/en/overview/_index.md | 16 +++++++++++++++ .../v2.x/en/overview/architecture/_index.md | 20 ++----------------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/content/rancher/v2.x/en/overview/_index.md b/content/rancher/v2.x/en/overview/_index.md index ed21062618f..8b0bb3e0bb9 100644 --- a/content/rancher/v2.x/en/overview/_index.md +++ b/content/rancher/v2.x/en/overview/_index.md @@ -24,3 +24,19 @@ The following figure illustrates the role Rancher plays in IT and DevOps organiz ![Platform]({{< baseurl >}}/img/rancher/platform.png) +## Features of the Rancher API Server + +The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: + +- **User management:** The Rancher API server [manages user identities]({{}}/rancher/v2.x/en/admin-settings/authentication/) that correspond to external authentication providers like Active Directory or GitHub, in addition to local users. +- **Authorization:** The Rancher API server manages [access control]({{}}/rancher/v2.x/en/admin-settings/rbac/) and [security]({{}}/rancher/v2.x/en/admin-settings/pod-security-policies/) policies. +- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, and it allows you manage multiple namespaces as a group. The Rancher UI provides features for [project administration]({{}}/rancher/v2.x/en/project-admin/) and for [managing applications within projects.]({{}}/rancher/v2.x/en/k8s-in-rancher/) +- **Tracking nodes:** The Rancher API server tracks identities of all the [nodes]({{}}/rancher/v2.x/en/cluster-admin/nodes/) in all clusters. +- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/) on existing nodes, [import existing Kubernetes clusters]({{}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) into Rancher, or perform [Kubernetes upgrades.]({{}}/rancher/v2.x/en/cluster-admin/editing-clusters/#upgrading-kubernetes) +- **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision [new nodes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) and [persistent storage]({{}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) in the cloud. +- **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts]({{}}/rancher/v2.x/en/catalog/) that make it easy to repeatedly deploy applications. +- **Logging:** Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters. Logging can be set up [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/logging/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/logging/) +- **Monitoring:** Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. Monitoring can be configured [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/monitoring/) +- **Alerting:** To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. To help you stay informed of these events, you can configure alerts [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/alerts/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/alerts/) +- **Pipelines:** Setting up a [pipeline]({{}}/rancher/v2.x/en/project-admin/tools/pipelines/) can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects. +- **Istio:** Our [integration with Istio]({{}}/rancher/v2.x/en/cluster-admin/tools/istio/) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing. \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/architecture/_index.md b/content/rancher/v2.x/en/overview/architecture/_index.md index 29ba8dd699d..dbbca932569 100644 --- a/content/rancher/v2.x/en/overview/architecture/_index.md +++ b/content/rancher/v2.x/en/overview/architecture/_index.md @@ -7,6 +7,8 @@ This section focuses on the Rancher server, its components, and how Rancher comm For information on the different ways that Rancher can be installed, refer to the [installation options section.]({{}}/rancher/v2.x/en/overview/installation-options) +For a list of main eatures of the Rancher API server, refer to the [overview section.]({{}}/rancher/v2.x/en/overview/#features-of-the-rancher-api-server) + For guidance about setting up the underlying infrastructure for the Rancher server, refer to the [architecture recommendations.]({{}}/rancher/v2.x/en/overview/architecture-recommendations) > This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{}}/rancher/v2.x/en/overview/concepts) page. @@ -14,7 +16,6 @@ For guidance about setting up the underlying infrastructure for the Rancher serv This section covers the following topics: - [Rancher server architecture](#rancher-server-architecture) - - [Features of the Rancher API server](#features-of-the-rancher-api-server) - [Communicating with downstream user clusters](#communicating-with-downstream-user-clusters) - [The authentication proxy](#1-the-authentication-proxy) - [Cluster controllers and cluster agents](#2-cluster-controllers-and-cluster-agents) @@ -44,23 +45,6 @@ A high-availability installation is recommended for production. A single-node in The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. -### Features of the Rancher API Server - -The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: - -- **User management:** The Rancher API server [manages user identities]({{}}/rancher/v2.x/en/admin-settings/authentication/) that correspond to external authentication providers like Active Directory or GitHub, in addition to local users. -- **Authorization:** The Rancher API server manages [access control]({{}}/rancher/v2.x/en/admin-settings/rbac/) and [security]({{}}/rancher/v2.x/en/admin-settings/pod-security-policies/) policies. -- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, and it allows you manage multiple namespaces as a group. The Rancher UI provides features for [project administration]({{}}/rancher/v2.x/en/project-admin/) and for [managing applications within projects.]({{}}/rancher/v2.x/en/k8s-in-rancher/) -- **Tracking nodes:** The Rancher API server tracks identities of all the [nodes]({{}}/rancher/v2.x/en/cluster-admin/nodes/) in all clusters. -- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/) on existing nodes, [import existing Kubernetes clusters]({{}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) into Rancher, or perform [Kubernetes upgrades.]({{}}/rancher/v2.x/en/cluster-admin/editing-clusters/#upgrading-kubernetes) -- **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision [new nodes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) and [persistent storage]({{}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) in the cloud. -- **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts]({{}}/rancher/v2.x/en/catalog/) that make it easy to repeatedly deploy applications. -- **Logging:** Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters. Logging can be set up [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/logging/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/logging/) -- **Monitoring:** Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. Monitoring can be configured [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/monitoring/) -- **Alerting:** To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. To help you stay informed of these events, you can configure alerts [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/alerts/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/alerts/) -- **Pipelines:** Setting up a [pipeline]({{}}/rancher/v2.x/en/project-admin/tools/pipelines/) can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects. -- **Istio:** Our [integration with Istio]({{}}/rancher/v2.x/en/cluster-admin/tools/istio/) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing. - # Communicating with Downstream User Clusters This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. From 7b40b8251731b4b8d551e9fbc2be750e0b4b2b64 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 21 Nov 2019 15:44:50 -0700 Subject: [PATCH 08/18] Fix broken link on catalog page --- content/rancher/v2.x/en/catalog/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/rancher/v2.x/en/catalog/_index.md b/content/rancher/v2.x/en/catalog/_index.md index 7f0070a1ebb..0481cacca6f 100644 --- a/content/rancher/v2.x/en/catalog/_index.md +++ b/content/rancher/v2.x/en/catalog/_index.md @@ -119,7 +119,7 @@ After you've either enabled the built-in catalogs or added your own custom catal * For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs), answers are provided as key value pairs in the **Answers** section. * Keys and values are available within **Detailed Descriptions**. - * When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of --set](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm. + * When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of --set](https://helm.sh/docs/intro/using_helm/#the-format-and-limitations-of-set), as Rancher passes them as `--set` flags to Helm. For example, when entering an answer that includes two values separated by a comma (i.e., `abc, bcd`), wrap the values with double quotes (i.e., `"abc, bcd"`). From 969f541c29291873e26a1371b848897d15387b0f Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 21 Nov 2019 16:38:31 -0700 Subject: [PATCH 09/18] Expand section about cluster controllers --- .../rancher/v2.x/en/overview/architecture/_index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/rancher/v2.x/en/overview/architecture/_index.md b/content/rancher/v2.x/en/overview/architecture/_index.md index dbbca932569..3414abec0db 100644 --- a/content/rancher/v2.x/en/overview/architecture/_index.md +++ b/content/rancher/v2.x/en/overview/architecture/_index.md @@ -77,15 +77,15 @@ By default, Rancher generates a [kubeconfig file]({{}}/rancher/v2.x/en/ Each downstream user cluster has a cluster agent, which opens a tunnel to the corresponding cluster controller within the Rancher server. -There is one cluster controller and one cluster agent for each downstream cluster. - -By default, to enable Rancher to communicate with a downstream cluster, the cluster controller connects to the cluster agent. If the cluster agent is not available, the cluster controller can connect to a [node agent](#3-node-agents) instead. - -The cluster controller is a component of the Rancher server performs the following tasks: +There is one cluster controller and one cluster agent for each downstream cluster. Each cluster controller: +- Watches for resource changes in the downstream cluster +- Brings the current state of the downstream cluster to the desired state - Configures access control policies to clusters and projects - Provisions clusters by calling the required Docker machine drivers and Kubernetes engines, such as RKE and GKE +By default, to enable Rancher to communicate with a downstream cluster, the cluster controller connects to the cluster agent. If the cluster agent is not available, the cluster controller can connect to a [node agent](#3-node-agents) instead. + The cluster agent, also called `cattle-cluster-agent`, is a component that runs in a downstream user cluster. It performs the following tasks: - Connects to the Kubernetes API of Rancher-launched Kubernetes clusters From c84d79223ae6d53f3cacaec55ecf18a4d76ca4f5 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 21 Nov 2019 16:51:49 -0700 Subject: [PATCH 10/18] Update RKE logo to new logo --- static/img/rancher/rancher-architecture-cluster-controller.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/img/rancher/rancher-architecture-cluster-controller.svg b/static/img/rancher/rancher-architecture-cluster-controller.svg index 517cb8d903d..ce9fb2958f6 100644 --- a/static/img/rancher/rancher-architecture-cluster-controller.svg +++ b/static/img/rancher/rancher-architecture-cluster-controller.svg @@ -1,3 +1,3 @@ -
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
kubectl get pods
[Not supported by viewer]
kube-api-auth
[Not supported by viewer]
Bob
[Not supported by viewer]
Alice
Alice
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
4
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
kubectl get pods
[Not supported by viewer]
Cluster Agent
[Not supported by viewer]
1
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
Cluster Controller 1
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Cluster Controller 3
[Not supported by viewer]
2
[Not supported by viewer]
3
[Not supported by viewer]
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
User Cluster 2
[Not supported by viewer]
User Cluster 3
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer] \ No newline at end of file +
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
kubectl get pods
[Not supported by viewer]
kube-api-auth
[Not supported by viewer]
Bob
[Not supported by viewer]
Alice
Alice
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
4
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
kubectl get pods
[Not supported by viewer]
Cluster Agent
[Not supported by viewer]
1
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
Cluster Controller 1
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Cluster Controller 3
[Not supported by viewer]
2
[Not supported by viewer]
3
[Not supported by viewer]
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
User Cluster 2
[Not supported by viewer]
User Cluster 3
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer]
Kubernetes provisioned
by Rancher Kubernetes
Engine
[Not supported by viewer] \ No newline at end of file From c55dea4dd371d7a17178fcdd0d6a00a2984af6a3 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Tue, 26 Nov 2019 10:31:09 -0700 Subject: [PATCH 11/18] Say how to choose an installation method in installation section --- .../choosing-installation}/_index.md | 7 ++----- content/rancher/v2.x/en/overview/architecture/_index.md | 2 +- 2 files changed, 3 insertions(+), 6 deletions(-) rename content/rancher/v2.x/en/{overview/installation-options => installation/choosing-installation}/_index.md (89%) diff --git a/content/rancher/v2.x/en/overview/installation-options/_index.md b/content/rancher/v2.x/en/installation/choosing-installation/_index.md similarity index 89% rename from content/rancher/v2.x/en/overview/installation-options/_index.md rename to content/rancher/v2.x/en/installation/choosing-installation/_index.md index 55bf24e267f..a4d1cd4a3a5 100644 --- a/content/rancher/v2.x/en/overview/installation-options/_index.md +++ b/content/rancher/v2.x/en/installation/choosing-installation/_index.md @@ -1,5 +1,5 @@ --- -title: Installation Options +title: Choosing an Installation Method weight: 2 --- @@ -13,10 +13,7 @@ On a single node, Rancher is installed with Docker and many options are configur On a Kubernetes cluster, Rancher is installed with Helm, and Helm commands are used to pass in configuration options. [Helm]({{}}/rancher/v2.x/en/overview/architecture/concepts/#about-helm) is a Kubernetes package manager. -The simplest way to install Rancher is on a single node with direct access to the Internet. Other options require more steps: - -- For a high-availability installation, you need to first set up a Kubernetes cluster using the Rancher Kubernetes Engine, then install Rancher on the cluster. -- If the installation environment is behind an HTTP proxy or in an air gap environment, additional steps are required to work around the lack of direct access to DockerHub and GitHub. +The simplest way to install Rancher is on a single node with direct access to the Internet. Other options require more steps. For a high-availability installation, you need to first set up a Kubernetes cluster using the Rancher Kubernetes Engine, then install Rancher on the cluster. If the installation environment is behind an HTTP proxy or in an air gap environment, additional steps are required to work around the lack of direct access to DockerHub and GitHub. Depending on your environment, the result of of the extra steps is the increased security and reliability of Rancher. diff --git a/content/rancher/v2.x/en/overview/architecture/_index.md b/content/rancher/v2.x/en/overview/architecture/_index.md index 3414abec0db..87f8de08b43 100644 --- a/content/rancher/v2.x/en/overview/architecture/_index.md +++ b/content/rancher/v2.x/en/overview/architecture/_index.md @@ -5,7 +5,7 @@ weight: 1 This section focuses on the Rancher server, its components, and how Rancher communicates with downstream Kubernetes clusters. -For information on the different ways that Rancher can be installed, refer to the [installation options section.]({{}}/rancher/v2.x/en/overview/installation-options) +For information on the different ways that Rancher can be installed, refer to the [section on choosing an installation method.]({{}}/rancher/v2.x/en/installation/choosing-installation) For a list of main eatures of the Rancher API server, refer to the [overview section.]({{}}/rancher/v2.x/en/overview/#features-of-the-rancher-api-server) From cd34a4eee5ef467df919bee9a14b9877b81f012d Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Tue, 3 Dec 2019 15:25:21 -0700 Subject: [PATCH 12/18] Update 'Choosing an installation method' page --- .../installation/choosing-installation/_index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/content/rancher/v2.x/en/installation/choosing-installation/_index.md b/content/rancher/v2.x/en/installation/choosing-installation/_index.md index a4d1cd4a3a5..c391c3157d1 100644 --- a/content/rancher/v2.x/en/installation/choosing-installation/_index.md +++ b/content/rancher/v2.x/en/installation/choosing-installation/_index.md @@ -7,24 +7,24 @@ Rancher can be installed on a single node or a high-availability cluster. A high-availability installation is recommended for production. A single-node installation may be used for development and testing purposes, but there is no migration path from a single-node to a high-availability installation. Therefore, you may want to use a high-availability installation from the start. -The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. - -On a single node, Rancher is installed with Docker and many options are configured with Docker commands. - -On a Kubernetes cluster, Rancher is installed with Helm, and Helm commands are used to pass in configuration options. [Helm]({{}}/rancher/v2.x/en/overview/architecture/concepts/#about-helm) is a Kubernetes package manager. - The simplest way to install Rancher is on a single node with direct access to the Internet. Other options require more steps. For a high-availability installation, you need to first set up a Kubernetes cluster using the Rancher Kubernetes Engine, then install Rancher on the cluster. If the installation environment is behind an HTTP proxy or in an air gap environment, additional steps are required to work around the lack of direct access to DockerHub and GitHub. Depending on your environment, the result of of the extra steps is the increased security and reliability of Rancher. Basic options for installing Rancher include the following: -Level of Internet Access | Single Node Instructions | HA Instructions +Level of Internet Access | Single Node Instructions | High-Availability Instructions ---------------------------|-----------------------------|------------------ With direct access to the Internet | [Docs]({{}}/rancher/v2.x/en/installation/single-node/) | [Docs]({{}}/rancher/v2.x/en/installation/ha/) Behind an HTTP proxy | These [docs,]({{}}/rancher/v2.x/en/installation/single-node/) plus this [configuration]({{}}/rancher/v2.x/en/installation/single-node/proxy/) | These [docs,]({{}}/rancher/v2.x/en/installation/ha/) plus this [configuration]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#http-proxy) In an air gap environment | [Docs]({{}}/rancher/v2.x/en/installation/air-gap/) | [Docs]({{}}/rancher/v2.x/en/installation/air-gap/) +The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. + +On a single node, Rancher is installed with Docker and many options are configured with Docker commands. + +On a Kubernetes cluster, Rancher is installed with Helm, and Helm commands are used to pass in configuration options. [Helm]({{}}/rancher/v2.x/en/overview/architecture/concepts/#about-helm) is a Kubernetes package manager. + # More Options for HA Installations Refer to the [Helm chart options]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/) for details on installing HA Rancher with other configurations, including: From 8a87da7a8e87154d9c761dc856b81d2335617765 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Tue, 3 Dec 2019 15:28:48 -0700 Subject: [PATCH 13/18] Remove outdated Helm information --- content/rancher/v2.x/en/overview/concepts/_index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/content/rancher/v2.x/en/overview/concepts/_index.md b/content/rancher/v2.x/en/overview/concepts/_index.md index c7d848f88da..f4fe9fc26f0 100644 --- a/content/rancher/v2.x/en/overview/concepts/_index.md +++ b/content/rancher/v2.x/en/overview/concepts/_index.md @@ -69,8 +69,4 @@ For high-availability installations of Rancher, Helm is the tool used to install Helm is the package management tool of choice for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. With Helm we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at [https://helm.sh/](https://helm.sh). -To be able to use Helm, the server-side component `tiller` needs to be installed on your cluster. Helm installs the `tiller` service on your cluster to manage charts because Helm cannot manipulate Kubernetes resources directly. - -Because Rancher Kubernetes Engine enables role-based access control by default, the `tiller` service needs to be given permission to manipulate Kubernetes resources. Therefore, the high-availability Rancher installation instructions show you how to use `kubectl` to create a `serviceaccount` and `clusterrolebinding` so that `tiller` has permission to deploy Rancher on the cluster. - For more information on service accounts and cluster role binding, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) \ No newline at end of file From a0357f4d28868eb34ab03dc0208613a44ede9138 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Tue, 3 Dec 2019 15:30:00 -0700 Subject: [PATCH 14/18] Add missing word --- content/rancher/v2.x/en/cluster-provisioning/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/rancher/v2.x/en/cluster-provisioning/_index.md b/content/rancher/v2.x/en/cluster-provisioning/_index.md index 9f70062844b..79cf83e18be 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/_index.md @@ -12,7 +12,7 @@ Rancher simplifies the creation of clusters by allowing you to create them throu This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{}}/rancher/v2.x/en/overview/concepts) page. -For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the [architecture]({{}}/rancher/v2.x/en/overview/architecture/) +For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the [architecture]({{}}/rancher/v2.x/en/overview/architecture/) page. ## Cluster Creation Options From ae957b883def7976487f830b710764a6b73023d5 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Fri, 6 Dec 2019 13:27:25 -0700 Subject: [PATCH 15/18] Edit Overview section and revise diagrams --- .../v2.x/en/installation/air-gap/_index.md | 2 +- content/rancher/v2.x/en/overview/_index.md | 44 +++++++++++++++---- .../architecture-recommendations/_index.md | 5 +-- ...ancher-architecture-cluster-controller.svg | 2 +- .../rancher-architecture-node-roles.svg | 2 +- ...ancher-architecture-rancher-api-server.svg | 2 +- 6 files changed, 42 insertions(+), 15 deletions(-) diff --git a/content/rancher/v2.x/en/installation/air-gap/_index.md b/content/rancher/v2.x/en/installation/air-gap/_index.md index e4b72412447..49042ba5460 100644 --- a/content/rancher/v2.x/en/installation/air-gap/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap/_index.md @@ -18,7 +18,7 @@ This section is about installations of Rancher server in an air gapped environme Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing Docker images to your machines. If you need help with creating a private registry, please refer to the [Docker documentation](https://docs.docker.com/registry/). {{% tabs %}} -{{% tab "HA Install" %}} +{{% tab "For HA Install Only" %}} The following CLI tools are required for the HA install. Make sure these tools are installed on your workstation and available in your `$PATH`. diff --git a/content/rancher/v2.x/en/overview/_index.md b/content/rancher/v2.x/en/overview/_index.md index 8b0bb3e0bb9..5faff7de3f2 100644 --- a/content/rancher/v2.x/en/overview/_index.md +++ b/content/rancher/v2.x/en/overview/_index.md @@ -4,11 +4,11 @@ weight: 1 --- Rancher is a container management platform built for organizations that deploy containers in production. Rancher makes it easy to run Kubernetes everywhere, meet IT requirements, and empower DevOps teams. -## Run Kubernetes Everywhere +# Run Kubernetes Everywhere Kubernetes has become the container orchestration standard. Most cloud and virtualization vendors now offer it as standard infrastructure. Rancher users have the choice of creating Kubernetes clusters with Rancher Kubernetes Engine (RKE) or cloud Kubernetes services, such as GKE, AKS, and EKS. Rancher users can also import and manage their existing Kubernetes clusters created using any Kubernetes distribution or installer. -## Meet IT requirements +# Meet IT requirements Rancher supports centralized authentication, access control, and monitoring for all Kubernetes clusters under its control. For example, you can: @@ -16,7 +16,7 @@ Rancher supports centralized authentication, access control, and monitoring for - Setup and enforce access control and security policies across all users, groups, projects, clusters, and clouds. - View the health and capacity of your Kubernetes clusters from a single-pane-of-glass. -## Empower DevOps Teams +# Empower DevOps Teams Rancher provides an intuitive user interface for DevOps engineers to manage their application workload. The user does not need to have in-depth knowledge of Kubernetes concepts to start using Rancher. Rancher catalog contains a set of useful DevOps tools. Rancher is certified with a wide selection of cloud native ecosystem products, including, for example, security tools, monitoring systems, container registries, and storage and networking drivers. @@ -24,19 +24,47 @@ The following figure illustrates the role Rancher plays in IT and DevOps organiz ![Platform]({{< baseurl >}}/img/rancher/platform.png) -## Features of the Rancher API Server +# Features of the Rancher API Server The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: +### Authorization and Role-Based Access Control + - **User management:** The Rancher API server [manages user identities]({{}}/rancher/v2.x/en/admin-settings/authentication/) that correspond to external authentication providers like Active Directory or GitHub, in addition to local users. - **Authorization:** The Rancher API server manages [access control]({{}}/rancher/v2.x/en/admin-settings/rbac/) and [security]({{}}/rancher/v2.x/en/admin-settings/pod-security-policies/) policies. -- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, and it allows you manage multiple namespaces as a group. The Rancher UI provides features for [project administration]({{}}/rancher/v2.x/en/project-admin/) and for [managing applications within projects.]({{}}/rancher/v2.x/en/k8s-in-rancher/) + +### Working with Kubernetes Applications + +- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/) on existing nodes, or perform [Kubernetes upgrades.]({{}}/rancher/v2.x/en/cluster-admin/editing-clusters/#upgrading-kubernetes) +- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, which allows you manage multiple namespaces as a group and perform Kubernetes operations in them. The Rancher UI provides features for [project administration]({{}}/rancher/v2.x/en/project-admin/) and for [managing applications within projects.]({{}}/rancher/v2.x/en/k8s-in-rancher/) +- **Pipelines:** Setting up a [pipeline]({{}}/rancher/v2.x/en/project-admin/tools/pipelines/) can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects. + +### Working with Cloud Infrastructure + - **Tracking nodes:** The Rancher API server tracks identities of all the [nodes]({{}}/rancher/v2.x/en/cluster-admin/nodes/) in all clusters. -- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/) on existing nodes, [import existing Kubernetes clusters]({{}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) into Rancher, or perform [Kubernetes upgrades.]({{}}/rancher/v2.x/en/cluster-admin/editing-clusters/#upgrading-kubernetes) - **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision [new nodes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) and [persistent storage]({{}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) in the cloud. + +### Catalogs + - **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts]({{}}/rancher/v2.x/en/catalog/) that make it easy to repeatedly deploy applications. + +### Cluster Visibility + - **Logging:** Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters. Logging can be set up [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/logging/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/logging/) - **Monitoring:** Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. Monitoring can be configured [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/monitoring/) - **Alerting:** To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. To help you stay informed of these events, you can configure alerts [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/alerts/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/alerts/) -- **Pipelines:** Setting up a [pipeline]({{}}/rancher/v2.x/en/project-admin/tools/pipelines/) can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects. -- **Istio:** Our [integration with Istio]({{}}/rancher/v2.x/en/cluster-admin/tools/istio/) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing. \ No newline at end of file +- **Istio:** Our [integration with Istio]({{}}/rancher/v2.x/en/cluster-admin/tools/istio/) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing. + +# Editing Downstream Clusters with Rancher + +The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) have **Cluster Options** available for editing. + +After a cluster is created with Rancher, a cluster administrator can manage cluster membership, enable pod security policies, and manage node pools, among [other options.]({{}}/rancher/v2.x/en/cluster-admin/editing-clusters/) + +The following table shows an overview of the options and settings available for each cluster type: + + Cluster Type | Member Roles | Cluster Options | Node Pools +---------|----------|---------|---------| + [RKE-Launched]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#rancher-launched-kubernetes) | ✓ | ✓ | ✓ | + [Hosted Kubernetes Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#hosted-kubernetes-cluster) | ✓ | | | + [Imported]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#import-existing-cluster) | ✓ | | | \ No newline at end of file diff --git a/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md b/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md index 1ae162a6ddf..11a1494bb7c 100644 --- a/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md +++ b/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md @@ -30,13 +30,12 @@ In HA installations of Rancher, the Rancher server cluster should also be separa We recommend installing the Rancher server on a three-node Kubernetes cluster for production, primarily because it protects the data stored on etcd. The Rancher server stores its data in etcd in both single-node and HA installations. -When Rancher is installed on a single node, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server. +When Rancher is installed on a single node, if the node goes down, there is no copy of the etcd data available on other nodes and you could lose the data on your Rancher server. By contrast, in the high-availability installation, - The etcd data is replicated on three nodes in the cluster, providing redundancy and data duplication in case one of the nodes fails. -- A load balancer serves as the single point of contact for clients, distributing network traffic across multiple servers in the cluster and helping to prevent any one server from becoming a point of failure. -- When one application server fails or becomes unavailable, the load balancer directs traffic to available servers using an algorithm. For example, the least connection method directs traffic to the service with the fewest active connections. The least connection method is indicated with the `least_conn` option in this [example]({{}}/rancher/v2.x/en/installation/ha/create-nodes-lb/nginx/) of how to configure an NGINX server as a basic layer 4 load balancer (TCP). The load balancer handles traffic so that each server can receive a manageable load. +- A load balancer serves as the single point of contact for clients, distributing network traffic across multiple servers in the cluster and helping to prevent any one server from becoming a point of failure. Note: This [example]({{}}/rancher/v2.x/en/installation/ha/create-nodes-lb/nginx/) of how to configure an NGINX server as a basic layer 4 load balancer (TCP). # Recommended Load Balancer Configuration for HA Installations diff --git a/static/img/rancher/rancher-architecture-cluster-controller.svg b/static/img/rancher/rancher-architecture-cluster-controller.svg index ce9fb2958f6..922cc572ef9 100644 --- a/static/img/rancher/rancher-architecture-cluster-controller.svg +++ b/static/img/rancher/rancher-architecture-cluster-controller.svg @@ -1,3 +1,3 @@ -
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
kubectl get pods
[Not supported by viewer]
kube-api-auth
[Not supported by viewer]
Bob
[Not supported by viewer]
Alice
Alice
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
4
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
kubectl get pods
[Not supported by viewer]
Cluster Agent
[Not supported by viewer]
1
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
Cluster Controller 1
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Cluster Controller 3
[Not supported by viewer]
2
[Not supported by viewer]
3
[Not supported by viewer]
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
User Cluster 2
[Not supported by viewer]
User Cluster 3
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer]
Kubernetes provisioned
by Rancher Kubernetes
Engine
[Not supported by viewer] \ No newline at end of file +
User Cluster 1
<font style="font-size: 20px">User Cluster 1</font>
kubectl get pods
[Not supported by viewer]
kube-api-auth
[Not supported by viewer]
Bob
[Not supported by viewer]
Alice
Alice
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
etcd Node
[Not supported by viewer]
4
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Controlplane
Node
[Not supported by viewer]
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node Agent
[Not supported by viewer]
Worker Node
[Not supported by viewer]
kubectl get pods
[Not supported by viewer]
Cluster Agent
[Not supported by viewer]
1
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
Cluster Controller 1
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Cluster Controller 3
[Not supported by viewer]
2
[Not supported by viewer]
3
[Not supported by viewer]
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
Tunnel
User Cluster 2
[Not supported by viewer]
User Cluster 2
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer]
Kubernetes provisioned
by Rancher Kubernetes
Engine
[Not supported by viewer] \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-node-roles.svg b/static/img/rancher/rancher-architecture-node-roles.svg index a4ecef73357..b96c56d1d2c 100644 --- a/static/img/rancher/rancher-architecture-node-roles.svg +++ b/static/img/rancher/rancher-architecture-node-roles.svg @@ -1,3 +1,3 @@ -
Roles for Nodes in a High-Availability Rancher Server Cluster
<font style="font-size: 16px">Roles for Nodes in a High-Availability Rancher Server Cluster<br></font>
Roles for Nodes in a Downstream User Cluster
<font style="font-size: 16px">Roles for Nodes in a Downstream User Cluster<br></font>
Kubernetes Master
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Note: A kubelet is an agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
Note: A kubelet is an agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
Kubernetes Master
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Node with etcd role
Node with etcd role
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Node with controlplane role
Node with controlplane role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer] \ No newline at end of file +
Roles for Nodes in a High-Availability Rancher Server Cluster
<font style="font-size: 16px">Roles for Nodes in a High-Availability Rancher Server Cluster<br></font>
Roles for Nodes in a Downstream User Cluster
<font style="font-size: 16px">Roles for Nodes in a Downstream User Cluster<br></font>
Kubernetes Master
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node with etcd, worker, and controlplane roles
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Node with etcd role
Node with etcd role
Kubelet
[Not supported by viewer]
etcd Nodes
etcd Nodes
Kubelet
[Not supported by viewer]
Node with controlplane role
Node with controlplane role
Kubelet
[Not supported by viewer]
Note: A kubelet is an agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
Note: A kubelet is an agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Node with worker role
Node with worker role
Kubelet
[Not supported by viewer]
Kubernetes Master
[Not supported by viewer] \ No newline at end of file diff --git a/static/img/rancher/rancher-architecture-rancher-api-server.svg b/static/img/rancher/rancher-architecture-rancher-api-server.svg index 1b89e28d84a..0433bbcd803 100644 --- a/static/img/rancher/rancher-architecture-rancher-api-server.svg +++ b/static/img/rancher/rancher-architecture-rancher-api-server.svg @@ -1,3 +1,3 @@ -
Rancher UI,
CLI, or API
[Not supported by viewer]
kubectl,
Kubernetes
API
[Not supported by viewer]
RKE Nodes
[Not supported by viewer]
Amazon
EKS Nodes
[Not supported by viewer]
RKE
Kubernetes API Server
[Not supported by viewer]
Cluster Agent 1
[Not supported by viewer]
Cluster Agent 2
[Not supported by viewer]
Cluster Controller 1
[Not supported by viewer]
Rancher API
Server
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
etcd
[Not supported by viewer]
Rancher Server
Data Store
[Not supported by viewer]
EKS
Kubernetes API Server
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Downstream User
Cluster 1
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Downstream User
Cluster 2
[Not supported by viewer]
Rancher User
Rancher User
Kubernetes provisioned
by Rancher Kubernetes
Engine
[Not supported by viewer]
Kubernetes provisioned
by Amazon Elastic
Kubernetes Service
[Not supported by viewer] \ No newline at end of file +
Rancher UI,
CLI, or API
[Not supported by viewer]
kubectl,
Kubernetes
API
[Not supported by viewer]
RKE Nodes
[Not supported by viewer]
Amazon
EKS Nodes
[Not supported by viewer]
RKE
Kubernetes API Server
[Not supported by viewer]
Cluster Agent 1
[Not supported by viewer]
Cluster Agent 2
[Not supported by viewer]
Cluster Controller 1
[Not supported by viewer]
Rancher API
Server
[Not supported by viewer]
Authentication Proxy
[Not supported by viewer]
Rancher Server
<font style="font-size: 20px">Rancher Server<br></font>
etcd
[Not supported by viewer]
Rancher Server
Data Store
[Not supported by viewer]
EKS
Control Plane
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Cluster Controller 2
[Not supported by viewer]
Downstream User
Cluster 1
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Kubelet
[Not supported by viewer]
Node
[Not supported by viewer]
Downstream User
Cluster 2
[Not supported by viewer]
Rancher User
Rancher User
Kubernetes provisioned
by Rancher Kubernetes
Engine
[Not supported by viewer]
Kubernetes provisioned
by Amazon Elastic
Kubernetes Service
[Not supported by viewer] \ No newline at end of file From d4b0793a2dd636a0c2649ce71eaf1263cb5c5a4b Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Fri, 6 Dec 2019 14:44:15 -0700 Subject: [PATCH 16/18] Change tabs to note where there is only one tab --- .../v2.x/en/installation/air-gap/_index.md | 17 +++++++---------- .../rancher/v2.x/en/installation/ha/_index.md | 2 +- 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/content/rancher/v2.x/en/installation/air-gap/_index.md b/content/rancher/v2.x/en/installation/air-gap/_index.md index 49042ba5460..210fb8c645c 100644 --- a/content/rancher/v2.x/en/installation/air-gap/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap/_index.md @@ -17,17 +17,14 @@ This section is about installations of Rancher server in an air gapped environme Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing Docker images to your machines. If you need help with creating a private registry, please refer to the [Docker documentation](https://docs.docker.com/registry/). -{{% tabs %}} -{{% tab "For HA Install Only" %}} -The following CLI tools are required for the HA install. Make sure these tools are installed on your workstation and available in your `$PATH`. - -* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool. -* [rke]({{< baseurl >}}/rke/latest/en/installation/) - Rancher Kubernetes Engine, cli for building Kubernetes clusters. -* [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements]({{}}/rancher/v2.x/en/installation/helm-version) to choose a version of Helm to install Rancher. - -{{% /tab %}} -{{% /tabs %}} +> **Prerequisites For HA Install Only:** +> +> The following CLI tools are required for the HA install. Make sure these tools are installed on your workstation and available in your `$PATH`. +> +> * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool. +> * [rke]({{< baseurl >}}/rke/latest/en/installation/) - Rancher Kubernetes Engine, cli for building Kubernetes clusters. +> * [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements]({{}}/rancher/v2.x/en/installation/helm-version) to choose a version of Helm to install Rancher. ## Installation Outline diff --git a/content/rancher/v2.x/en/installation/ha/_index.md b/content/rancher/v2.x/en/installation/ha/_index.md index 60375e4b806..636e7f8b77f 100644 --- a/content/rancher/v2.x/en/installation/ha/_index.md +++ b/content/rancher/v2.x/en/installation/ha/_index.md @@ -11,7 +11,7 @@ This procedure walks you through setting up a 3-node cluster with Rancher Kubern > **Important:** For the best performance and security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads. -We recommend the following configurations for the load balancer and Ingress controllers: +We recommend the following architecture and configurations for the load balancer and Ingress controllers: * DNS for Rancher should resolve to a Layer 4 load balancer (TCP) * The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster. From 082d92c209157646e353aa5f3158257c07a43555 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Wed, 11 Dec 2019 14:06:38 -0700 Subject: [PATCH 17/18] Revise installation docs according to feedback --- .../choosing-installation/_index.md | 32 ++++++++++++------- .../en/installation/server-tags/_index.md | 12 ++++--- .../architecture-recommendations/_index.md | 4 ++- .../v2.x/en/overview/architecture/_index.md | 2 +- 4 files changed, 32 insertions(+), 18 deletions(-) diff --git a/content/rancher/v2.x/en/installation/choosing-installation/_index.md b/content/rancher/v2.x/en/installation/choosing-installation/_index.md index c391c3157d1..267e507d3f0 100644 --- a/content/rancher/v2.x/en/installation/choosing-installation/_index.md +++ b/content/rancher/v2.x/en/installation/choosing-installation/_index.md @@ -3,27 +3,35 @@ title: Choosing an Installation Method weight: 2 --- -Rancher can be installed on a single node or a high-availability cluster. +We recommend using [Helm,]({{}}/rancher/v2.x/en/overview/architecture/concepts/#about-helm) a Kubernetes package manager, to install Rancher on a dedicated Kubernetes cluster. This is called a high-availability (HA) installation because increased avaialability is achieved by running Rancher on multiple nodes. -A high-availability installation is recommended for production. A single-node installation may be used for development and testing purposes, but there is no migration path from a single-node to a high-availability installation. Therefore, you may want to use a high-availability installation from the start. +For testing and demonstration purposes, Rancher can be installed with Docker on a single node. -The simplest way to install Rancher is on a single node with direct access to the Internet. Other options require more steps. For a high-availability installation, you need to first set up a Kubernetes cluster using the Rancher Kubernetes Engine, then install Rancher on the cluster. If the installation environment is behind an HTTP proxy or in an air gap environment, additional steps are required to work around the lack of direct access to DockerHub and GitHub. +There are also separate instructions for installing Rancher in an air gap environment or behind an HTTP proxy: -Depending on your environment, the result of of the extra steps is the increased security and reliability of Rancher. - -Basic options for installing Rancher include the following: - -Level of Internet Access | Single Node Instructions | High-Availability Instructions +Level of Internet Access | Installing on a Kubernetes Cluster - Strongly Recommended | Installing in a Single Docker Container ---------------------------|-----------------------------|------------------ -With direct access to the Internet | [Docs]({{}}/rancher/v2.x/en/installation/single-node/) | [Docs]({{}}/rancher/v2.x/en/installation/ha/) +With direct access to the Internet | [Docs]({{}}/rancher/v2.x/en/installation/ha/) | [Docs]({{}}/rancher/v2.x/en/installation/single-node/) Behind an HTTP proxy | These [docs,]({{}}/rancher/v2.x/en/installation/single-node/) plus this [configuration]({{}}/rancher/v2.x/en/installation/single-node/proxy/) | These [docs,]({{}}/rancher/v2.x/en/installation/ha/) plus this [configuration]({{}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#http-proxy) In an air gap environment | [Docs]({{}}/rancher/v2.x/en/installation/air-gap/) | [Docs]({{}}/rancher/v2.x/en/installation/air-gap/) -The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. +### Why We Recommend an HA Installation -On a single node, Rancher is installed with Docker and many options are configured with Docker commands. +An HA installation of Rancher is recommended for production because it protects the Rancher management server's data from being lost. A single-node installation may be used for development and testing purposes, but there is no migration path from a single-node to an HA installation. Therefore, you may want to use an HA installation from the start. -On a Kubernetes cluster, Rancher is installed with Helm, and Helm commands are used to pass in configuration options. [Helm]({{}}/rancher/v2.x/en/overview/architecture/concepts/#about-helm) is a Kubernetes package manager. +> For the best performance and greater security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters]({{}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads. + +For more architecture recommendations, refer to [this page.]({{}}/rancher/v2.x/en/overview/architecture-recommendations) + +### How an HA Rancher Installation Works + +In a typical HA Rancher installation, Kubernetes is first installed on three nodes that are hosted in an infrastructure provider such as Amazon's EC2 or Google Compute Engine. + +Then Helm is used to install Rancher on top of the Kubernetes cluster. Helm uses Rancher's Helm chart to install a replica of Rancher on each of the three nodes in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster, in order to increase Rancher's availability. + +The Rancher server data is stored on etcd. This etcd database also runs on all three nodes, and requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can fail, requiring the cluster to be restored from backup. + +For information on how Rancher works, regardless of the installation method, refer to the [overview section.]({{}}/rancher/v2.x/en/overview/architecture) # More Options for HA Installations diff --git a/content/rancher/v2.x/en/installation/server-tags/_index.md b/content/rancher/v2.x/en/installation/server-tags/_index.md index 0bce71fe02f..31e8cfe61a2 100644 --- a/content/rancher/v2.x/en/installation/server-tags/_index.md +++ b/content/rancher/v2.x/en/installation/server-tags/_index.md @@ -9,8 +9,8 @@ For a high-availability installation of Rancher, which is recommended for produc For single node installations of Rancher, which is used for development and testing, you will install Rancher as a Docker image. -# Single Node Installs - +{{% tabs %}} +{{% tab "Docker Images for Single Node/Docker Installs" %}} When performing [single-node installs]({{< baseurl >}}/rancher/v2.x/en/installation/single-node), upgrades, or rollbacks, you can use _tags_ to install a specific version of Rancher. ### Server Tags @@ -29,8 +29,8 @@ Tag | Description >- Want to install an alpha review for preview? Install using one of the alpha tags listed on our [announcements page](https://forums.rancher.com/c/announcements) (e.g., `v2.2.0-alpha1`). > > _Caveat:_ Alpha releases cannot be upgraded to or from any other release. - -# High Availability Installs +{{% /tab %}} +{{% tab "Helm Charts for HA/Kubernetes Installs" %}} When installing, upgrading, or rolling back Rancher Server in a [high availability configuration]({{< baseurl >}}/rancher/v2.x/en/installation/ha/), Rancher server is installed using a Helm chart on a Kubernetes cluster. Therefore, as you prepare to install or upgrade a high availability Rancher configuration, you must add a Helm chart repository that contains the charts for installing Rancher. @@ -88,3 +88,7 @@ After installing Rancher, if you want to change which Helm chart repository to i ``` 4. Continue to follow the steps to [upgrade Rancher]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade-helm/) from the new Helm chart repository. +{{% /tab %}} +{{% /tabs %}} + + diff --git a/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md b/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md index 11a1494bb7c..ec016dfaba2 100644 --- a/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md +++ b/content/rancher/v2.x/en/overview/architecture-recommendations/_index.md @@ -52,7 +52,9 @@ We recommend the following configurations for the load balancer and Ingress cont # Environment for HA Installations -It is strongly recommended to install Rancher on a Kubernetes cluster on hosted infrastructure such as Amazon's EC2 or Google Compute Engine, and the cluster should be dedicated only to run Rancher. +It is strongly recommended to install Rancher on a Kubernetes cluster on hosted infrastructure such as Amazon's EC2 or Google Compute Engine. + +For the best performance and greater security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads. It is not recommended to install Rancher on top of a managed Kubernetes service such as Amazon’s EKS or Google Kubernetes Engine. These hosted Kubernetes solutions do not expose etcd to a degree that is manageable for Rancher, and their customizations can interfere with Rancher operations. diff --git a/content/rancher/v2.x/en/overview/architecture/_index.md b/content/rancher/v2.x/en/overview/architecture/_index.md index 87f8de08b43..2e4559f50b2 100644 --- a/content/rancher/v2.x/en/overview/architecture/_index.md +++ b/content/rancher/v2.x/en/overview/architecture/_index.md @@ -114,7 +114,7 @@ The `kube-api-auth` microservice is deployed to provide the user authentication Like the authorized cluster endpoint, the `kube-api-auth` authentication service is also only available for Rancher-launched Kubernetes clusters. -> **Example scenario:** Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in China. A user, Alice, also lives in China. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from China to the Rancher server in the United States, then be proxied back to China, where the downstream user cluster is. The geographical distance may cause significant latency. To reduce the latency, which Alice can reduce by using the authorized cluster endpoint. +> **Example scenario:** Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant latency. To reduce the latency, which Alice can reduce by using the authorized cluster endpoint. With this endpoint enabled for the downstream cluster, Rancher generates an extra Kubernetes context in the kubeconfig file in order to connect directly to the cluster. This file has the credentials for `kubectl` and `helm`. From d27669800eab5ef82a4c95fcc8adada2fb1f455e Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Wed, 11 Dec 2019 14:15:10 -0700 Subject: [PATCH 18/18] Edit overview section --- content/rancher/v2.x/en/overview/_index.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/content/rancher/v2.x/en/overview/_index.md b/content/rancher/v2.x/en/overview/_index.md index 5faff7de3f2..f8709e5483e 100644 --- a/content/rancher/v2.x/en/overview/_index.md +++ b/content/rancher/v2.x/en/overview/_index.md @@ -33,27 +33,24 @@ The Rancher API server is built on top of an embedded Kubernetes API server and - **User management:** The Rancher API server [manages user identities]({{}}/rancher/v2.x/en/admin-settings/authentication/) that correspond to external authentication providers like Active Directory or GitHub, in addition to local users. - **Authorization:** The Rancher API server manages [access control]({{}}/rancher/v2.x/en/admin-settings/rbac/) and [security]({{}}/rancher/v2.x/en/admin-settings/pod-security-policies/) policies. -### Working with Kubernetes Applications +### Working with Kubernetes - **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes]({{}}/rancher/v2.x/en/cluster-provisioning/) on existing nodes, or perform [Kubernetes upgrades.]({{}}/rancher/v2.x/en/cluster-admin/editing-clusters/#upgrading-kubernetes) -- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, which allows you manage multiple namespaces as a group and perform Kubernetes operations in them. The Rancher UI provides features for [project administration]({{}}/rancher/v2.x/en/project-admin/) and for [managing applications within projects.]({{}}/rancher/v2.x/en/k8s-in-rancher/) +- **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts]({{}}/rancher/v2.x/en/catalog/) that make it easy to repeatedly deploy applications. +- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, which allows you manage multiple namespaces as a group and perform Kubernetes operations in them. The Rancher UI provides features for [project administration]({{}}/rancher/v2.x/en/project-admin/) and for [managing applications within projects.]({{}}/rancher/v2.x/en/k8s-in-rancher/) - **Pipelines:** Setting up a [pipeline]({{}}/rancher/v2.x/en/project-admin/tools/pipelines/) can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects. +- **Istio:** Our [integration with Istio]({{}}/rancher/v2.x/en/cluster-admin/tools/istio/) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing. ### Working with Cloud Infrastructure - **Tracking nodes:** The Rancher API server tracks identities of all the [nodes]({{}}/rancher/v2.x/en/cluster-admin/nodes/) in all clusters. - **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision [new nodes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) and [persistent storage]({{}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) in the cloud. -### Catalogs - -- **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts]({{}}/rancher/v2.x/en/catalog/) that make it easy to repeatedly deploy applications. - ### Cluster Visibility - **Logging:** Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters. Logging can be set up [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/logging/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/logging/) - **Monitoring:** Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. Monitoring can be configured [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/monitoring/) - **Alerting:** To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. To help you stay informed of these events, you can configure alerts [at the cluster level]({{}}/rancher/v2.x/en/cluster-admin/tools/alerts/) or [at the project level.]({{}}/rancher/v2.x/en/project-admin/tools/alerts/) -- **Istio:** Our [integration with Istio]({{}}/rancher/v2.x/en/cluster-admin/tools/istio/) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing. # Editing Downstream Clusters with Rancher @@ -63,7 +60,7 @@ After a cluster is created with Rancher, a cluster administrator can manage clus The following table shows an overview of the options and settings available for each cluster type: - Cluster Type | Member Roles | Cluster Options | Node Pools + Cluster Type | Manage Member Roles | Edit Cluster Options | Manage Node Pools ---------|----------|---------|---------| [RKE-Launched]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#rancher-launched-kubernetes) | ✓ | ✓ | ✓ | [Hosted Kubernetes Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#hosted-kubernetes-cluster) | ✓ | | |