public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-25 12:38:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revise installation docs according to feedback

Browse Source
This commit is contained in:
Catherine Luse
2019-12-11 14:18:14 -07:00
parent d4b0793a2d
commit 082d92c209
4 changed files with 32 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/rancher/v2.x/en/installation/choosing-installation/_index.md
+20 -12
View File
@@ -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,]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/) | [Docs]({{<baseurl>}}/rancher/v2.x/en/installation/ha/)
With direct access to the Internet | [Docs]({{<baseurl>}}/rancher/v2.x/en/installation/ha/) | [Docs]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/)
Behind an HTTP proxy | These [docs,]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/) plus this [configuration]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/proxy/) | These [docs,]({{<baseurl>}}/rancher/v2.x/en/installation/ha/) plus this [configuration]({{<baseurl>}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#http-proxy)
In an air gap environment | [Docs]({{<baseurl>}}/rancher/v2.x/en/installation/air-gap/) | [Docs]({{<baseurl>}}/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]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads.
For more architecture recommendations, refer to [this page.]({{<baseurl>}}/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.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture)
# More Options for HA Installations
content/rancher/v2.x/en/installation/server-tags/_index.md
+8 -4
View File
@@ -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 %}}
content/rancher/v2.x/en/overview/architecture-recommendations/_index.md
+3 -1
View File
@@ -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.
content/rancher/v2.x/en/overview/architecture/_index.md
+1 -1
View File
@@ -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`.