diff --git a/content/rancher/v2.x/en/cluster-provisioning/_index.md b/content/rancher/v2.x/en/cluster-provisioning/_index.md index baca10785ed..1f2977aa002 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/_index.md @@ -18,7 +18,7 @@ A _Kubernetes Cluster_ is a cluster that uses the [Kubernetes container-orchestr 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 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. diff --git a/content/rancher/v2.x/en/installation/removing-rancher/cleaning-cluster-nodes/_index.md b/content/rancher/v2.x/en/faq/cleaning-cluster-nodes/_index.md similarity index 97% rename from content/rancher/v2.x/en/installation/removing-rancher/cleaning-cluster-nodes/_index.md rename to content/rancher/v2.x/en/faq/cleaning-cluster-nodes/_index.md index 29fda3d5053..4d9c627eedd 100644 --- a/content/rancher/v2.x/en/installation/removing-rancher/cleaning-cluster-nodes/_index.md +++ b/content/rancher/v2.x/en/faq/cleaning-cluster-nodes/_index.md @@ -1,6 +1,9 @@ --- title: Cleaning cluster nodes weight: 375 +aliases: + - /rancher/v2.x/en/installation/removing-rancher/cleaning-cluster-nodes/ + - /rancher/v2.x/en/installation/removing-rancher/ --- When adding a node to a cluster, resources (containers/(virtual) network interfaces) and configuration items (certificates/configuration files) are created. When removing a node from a cluster (if it is in `Active` state), those resources will be automatically cleaned and the only action needed is to restart the node. When a node has become unreachable and the automatic cleanup process cannot be used, we describe the steps that need to be executed before the node can be added to a cluster again. @@ -183,4 +186,4 @@ Chains | iptables -L -t nat iptables -L -t mangle iptables -L -``` +``` \ No newline at end of file diff --git a/content/rancher/v2.x/en/faq/networking/_index.md b/content/rancher/v2.x/en/faq/networking/_index.md new file mode 100644 index 00000000000..ef4a030f7a8 --- /dev/null +++ b/content/rancher/v2.x/en/faq/networking/_index.md @@ -0,0 +1,9 @@ +--- +title: Networking +weight: 8005 +--- + +Networking FAQ's + +- [CNI Providers]({{< baseurl >}}/rancher/v2.x/en/faq/networking/cni-providers/) + diff --git a/content/rancher/v2.x/en/faq/networking/cni-providers/_index.md b/content/rancher/v2.x/en/faq/networking/cni-providers/_index.md new file mode 100644 index 00000000000..9d8dcae502b --- /dev/null +++ b/content/rancher/v2.x/en/faq/networking/cni-providers/_index.md @@ -0,0 +1,136 @@ +--- +title: CNI Providers +weight: 2300 +draft: true +--- + +## What is CNI? + +CNI (Container Network Interface), a [Cloud Native Computing Foundation project](https://cncf.io/), consists of a specification and libraries for writing plugins to configure network interfaces in Linux containers, along with a number of supported plugins. CNI concerns itself only with network connectivity of containers and removing allocated resources when the container is deleted. + +Kubernetes uses CNI as an interface between network providers and Kubernetes pod networking. + +![CNI Logo]({{< baseurl >}}/img/rancher/cni-logo.png) + +For more information visit [CNI GitHub project](https://github.com/containernetworking/cni). + +### What Network Models are Used in CNI? + +CNI providers implement their network fabric using either an encapsulated network model such as Virtual Extensible Lan ([VXLAN](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#vxlan)) or an unencapsulated network model such as Border Gateway Protocol ([BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol)). + +#### What is an Encapsulated Network? + +This network model provides a logical Layer 2 (L2) network encapsulated over the existing Layer 3 (L3) network topology that spans the Kubernetes cluster nodes. With this model you have an isolated L2 network for containers without needing routing distribution, all at the cost of minimal overhead in terms of processing and increased IP package size, which comes from an IP header generated by overlay encapsulation. Encapsulation information is distributed by UDP ports between Kubernetes workers, interchanging network control plane information about how MAC addresses can be reached. Common encapsulation used in this kind of network model is VXLAN, Internet Protocol Security (IPSec), and IP-in-IP. + +In simple terms, this network model generates a kind of network bridge extended between Kubernetes workers, where pods are connected. + +This network model is used when an extended L2 bridge is preferred. This network model is sensible for L3 network latencies of the Kubernetes workers. If datacenters are in distinct geolocations, be sure to have low latencies between them to avoid eventual network segmentation. + +CNI providers using this network model include Flannel, Canal, and Weave. + +![Encapsulated Network]({{< baseurl >}}/img/rancher/encapsulated-network.svg) + +#### What is an Unencapsulated Network? + +This network model provides an L3 network to route packets between containers. This model doesn't generate an isolated l2 network, nor generates overhead. These benefits come at the cost of Kubernetes workers having to manage any route distribution that's needed. Instead of using IP headers for encapsulation, this network model uses a network protocol between Kubernetes workers to distribute routing information to reach pods, such as [BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol). + +In simple terms, this network model generates a kind of network router extended between Kubernetes workers, which provides information about how to reach pods. + +This network model is used when a routed L3 network is preferred. This mode dynamically updates routes at the OS level for Kubernetes workers. It's less sensible to latency. + +CNI providers using this network model include Calico and Romana. + +![Unencapsulated Network]({{< baseurl >}}/img/rancher/unencapsulated-network.svg) + +### What CNI Providers are Supported by Rancher? + +Out-of-the-box, Rancher supports three different CNI providers for Kubernetes clusters: Canal, Flannel, and Calico. You can choose your CNI when you create new Kubernetes clusters from Rancher. + +#### Canal + +![Canal Logo]({{< baseurl >}}/img/rancher/canal-logo.png) + +Canal is a CNI provider that gives you the best of Flannel and Calico. It allows users to easily deploy Calico and Flannel networking together as a unified networking solution, combining Calico’s network policy enforcement with the rich superset of Calico (unencapsulated) and/or Flannel (encapsulated) network connectivity options. + +In Rancher, Canal is the default CNI provider combined with Flannel and VXLAN encapsulation. + +Kubernetes workers should open UDP port `8472` (VXLAN) and `9099` (healthcheck). + +![Canal Diagram]({{< baseurl >}}/img/rancher/canal-diagram.png) + +For more information, see the [Canal GitHub Page](https://github.com/projectcalico/canal). + +#### Flannel + +![Flannel Logo]({{< baseurl >}}/img/rancher/flannel-logo.png) + +Flannel is a simple and easy way to configure L3 network fabric designed for Kubernetes. Flannel runs a single binary agent named flanneld on each host, which is responsible for allocating a subnet lease to each host out of a larger, preconfigured address space. Flannel uses either the Kubernetes API or etcd directly to store the network configuration, the allocated subnets, and any auxiliary data (such as the host's public IP). Packets are forwarded using one of several backend mechanisms, with the default encapsulation being [VXLAN](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#vxlan). + +Encapsulated traffic is unencrypted by default. Threfore, flannel provides an experimental backend for encryption, [IPSec](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#ipsec), which makes use of [strongSwan](https://www.strongswan.org/) to establish encrypted IPSec tunnels between Kubernetes workers. + +Kubernetes workers should open UDP port `8472` (VXLAN) and `9099` (healthcheck). + +![Flannel Diagram]({{< baseurl >}}/img/rancher/flannel-diagram.png) + +For more information, see the [Flannel GitHub Page](https://github.com/coreos/flannel). + +#### Calico + +![Calico Logo]({{< baseurl >}}/img/rancher/calico-logo.png) + +Calico enables networking and network policy in Kubernetes clusters across the cloud. Calico uses a pure, unencapsulated IP network fabric and policy engine to provide networking for your Kubernetes workloads. Workloads are able to communicate over both cloud infrastructure and on-premise using BGP. + +Calico also provides a stateless IP-in-IP encapsulation mode that can be used, if necessary. Calico also offers policy isolation, allowing you to secure and govern your Kubernetes workloads using advanced ingress and egress policies. + +Kubernetes workers should open TCP port `179` (BGP). + +![Calico Diagram]({{< baseurl >}}/img/rancher/calico-diagram.svg) + +For more information, see the following pages: + +- [Project Calico Official Site](https://www.projectcalico.org/) +- [Project Calico GitHub Page](https://github.com/projectcalico/calico) + + +### CNI Features by Provider + +The following table summarizes the different features available for each CNI provider supported by Rancher. + +| Provider | Network Model | Route Distribution | Network Policies | Mesh | External Datastore | Encryption | Ingress/Egress Policies | Commercial Support | +| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | +| Canal | Encapsulated (VXLAN) | No | Yes | No | K8S API | No | Yes | No | +| Flannel | Encapsulated (VXLAN) | No | No | No | K8S API | No | No | No | +| Calico | Unencapsulated | Yes | Yes | Yes | Etcd | Yes | Yes | Yes | + + +- Network Model: Encapsulated or unencapsulated. For more information, see [What Network Models are Used in CNI?](#what-network-models-are-used-in-cni) + +- Route Distribution: An exterior gateway protocol designed to exchange routing and reachability information on the Internet. BGP can assist with pod-to-pod networking between clusters. This feature is a must on unencapsulated CNI providers, and it is typically done by BGP. If you plan to build clusters split across network segments, route distribution is a feature that's nice-to-have. + +- Network Policies: Kubernetes offers functionality to enforce rules about which services can communicate with each other using network policies. This feature is stable as of Kubernetes v1.7 and is ready to use with supported networking plugins. + +- Mesh: This feature allows service-to-service networking communication between distinct Kubernetes clusters. + +- External Datastore: CNI providers with this feature need an external datastore for its data. + +- Encyption: This feature allows cyphered and secure network control and data planes. + +- Ingress/Egress Policies: This feature allows you to manage routing control for both Kubernetes and non-Kubernetes communications. + +#### CNI Community Popularity + +The following table summarizes different GitHub metrics to give you an idea of each supported project's popularity and activity. This data was collected in July 2018. + +| Provider | Project | Stars | Forks | Contributors | +| ---- | ---- | ---- | ---- | ---- | +| Canal | https://github.com/projectcalico/canal | 536 | 75 | 19 | +| flannel | https://github.com/coreos/flannel | 3.279 | 774 | 107 | +| Calico | https://github.com/projectcalico/calico | 572 | 225 | 82 | +
+### Which CNI Provider Should I Use? + +It depends on your project needs. There are many different providers, which each have various features and options. There isn't one provider that meets everyone's needs. At the moment, Rancher v2.0 supports the 3 most versatile CNI providers. + +As of Rancher v2.0.7, Canal is the default CNI provider. We recommend it for most use cases. It provides encapsulated networking for containers with Flannel, while adding Calico network policies that can provide project/namespace isolation in terms of networking. + +All of 3 solutions are capable CNI providers and will likely suit your needs. diff --git a/content/rancher/v2.x/en/installation/_index.md b/content/rancher/v2.x/en/installation/_index.md index 3c8753c6312..6493b977fb9 100644 --- a/content/rancher/v2.x/en/installation/_index.md +++ b/content/rancher/v2.x/en/installation/_index.md @@ -4,38 +4,18 @@ weight: 50 --- This section contains instructions for installing Rancher in development and production environments. -Choose from the following installation options: +### Installation Options -- [Single Node Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install) +- [Single Node Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/) - In this simple install scenario, you install Rancher on a single Linux host. + Install Rancher on a single Linux host. -- [Single Node Installation with External Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install-external-lb) +- [High Availability Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/ha/) - In this scenario, you install Rancher on a single Linux host and access it using an external load balancer/proxy. + This install scenario creates a new Kubernetes cluster dedicated to running Rancher Server in a high-availability (HA) configuration. -- [High Availability Installation]({{< baseurl >}}/rancher/v2.x/en/installation/ha-server-install/) +### Reference - This install scenario creates a new Kubernetes cluster dedicated to running Rancher Server in a high-availabilty (HA) configuration. +- [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/references/) -- [High Availability Installation with External Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/ha-server-install-external-lb) - - This install scenario creates a new Kubernetes cluster dedicated to running Rancher Server in a high-availabilty (HA) configuration. A load balancer is placed in front of the HA configuration. - -- [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/) - - We also have instructions for a more specialized use case where you install Rancher Server in an environment without an Internet connection. - -This section also includes help content for Rancher configuration and maintenance. - -- [Backups and Rollbacks]({{< baseurl >}}/rancher/v2.x/en/backups/) - - This section is devoted to protecting your Rancher Server data in a disaster scenario. - -- [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/references/) - - This page lists the ports you must open to operate Rancher. - -- [HTTP Proxy Configuration]({{< baseurl >}}/rancher/v2.x/en/installation/proxy-configuration/) - - If your Rancher installation runs behind a proxy, this page provides information on how to configure Rancher for your proxy. + List of required ports you must open to operate Rancher. diff --git a/content/rancher/v2.x/en/installation/air-gap-installation/_index.md b/content/rancher/v2.x/en/installation/air-gap-installation/_index.md index a65c2d4614e..558b5664dc5 100644 --- a/content/rancher/v2.x/en/installation/air-gap-installation/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-installation/_index.md @@ -1,12 +1,11 @@ --- -title: Air Gap Installation -weight: 345 +title: Preparing for Air Gap Install +weight: 300 --- Rancher supports installing from a private registry. In every [release](https://github.com/rancher/rancher/releases), we provide you with the needed Docker images and scripts to mirror those images to your own registry. The Docker images are used when nodes are added to a cluster, or when you enable features like pipelines or logging. >**Prerequisite:** It is assumed you either have your own private registry or other means of distributing docker images to your machine. If you need help with creating a private registry, please refer to the [Docker documentation for private registries](https://docs.docker.com/registry/). - >**Note:** In Rancher v2.0.0, registries with authentication are not supported for installing from a private registry. The Docker images can only be pulled from a registry without authentication enabled. This limitation only applies to Docker images. ## Release files @@ -15,14 +14,14 @@ Rancher supports installing from a private registry. In every [release](https:// * **rancher-save-images.sh**: This script will pull all needed images from DockerHub, and save all of the images as a compressed file called `rancher-images.tar.gz`. This file can be transferred to your on-premise host that can access your private registry. * **rancher-load-images.sh**: This script will load images from rancher-images.tar.gz and push them to your private registry. You have to supply the hostname of your private registry as first argument to the script.
`rancher-load-images.sh registry.yourdomain.com:5000` -### Making the Rancher images available +## Making the Rancher images available We will cover two scenarios: -* **Scenario 1**: You have one host that can access DockerHub to pull and save the images, and a separate host that access your private registry to push the images. -* **Scenario 2**: You have one host that can access both DockerHub and your private registry. +* **Scenario 1**: You have a node that can access DockerHub to pull and save the images, and a separate node(s) that access your private registry to push the images. +* **Scenario 2**: You have node(s) that can access both DockerHub and your private registry. -#### Scenario 1: One host that can access DockerHub, separate host that can access private registry +### Scenario 1: A node that can access DockerHub, separate node(s) that can access the private registry ![Scenario1]({{< baseurl >}}/img/rancher/airgap/privateregistry.svg) @@ -34,19 +33,7 @@ We will cover two scenarios: 4. Transfer and run `rancher-load-images.sh` on the host that can access the private registry. It should be run in the same directory as `rancher-images.tar.gz`. -5. Complete installation of Rancher using the instructions in [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/). - - >**Note:** - > When completing [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/), prepend your private registry URL to the image when running the `docker run` command. - > - > Example: - > ``` - docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - /rancher/rancher:latest - ``` - -#### Scenario 2: You have one host that can access both DockerHub and your private registry. +### Scenario 2: You have node(s) that can access both DockerHub and your private registry. ![Scenario2]({{< baseurl >}}/img/rancher/airgap/privateregistrypushpull.svg) @@ -66,20 +53,25 @@ for IMAGE in $IMAGES; do done ``` -3. Complete installation of Rancher using the instructions in [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/). +## Completing the Rancher installation - >**Note:** - > When completing [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/), prepend your private registry URL to the image when running the `docker run` command. - > - > Example: - > ``` +After your private registry is setup on all node(s) for your Rancher installation, complete your Rancher installation. + +### Single Node Install + +Complete installation of Rancher using the instructions in [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/). + +>**Note:** +> When completing [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/), prepend your private registry URL to the image when running the `docker run` command. +> +> Example: +> ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ /rancher/rancher:latest - ``` +``` - -### Configuring Rancher to use the private registry +## Configuring Rancher to use the private registry Rancher needs to be configured to use the private registry as source for the needed images. diff --git a/content/rancher/v2.x/en/installation/custom-ca-root-certificate/_index.md b/content/rancher/v2.x/en/installation/custom-ca-root-certificate/_index.md deleted file mode 100644 index 423c087784d..00000000000 --- a/content/rancher/v2.x/en/installation/custom-ca-root-certificate/_index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Adding custom CA root certificates -weight: 365 ---- -Services that Rancher needs to access are sometimes configured with a certificate from an custom/internal Certificate Authority (CA) root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error will appear: `x509: certificate signed by unknown authority`. - -To validate the certificate, the CA root certificates need to be added to Rancher. As Rancher is written in Go, we can use the environment variable `SSL_CERT_DIR` to point to the directory where the CA root certificates are located in the container. The CA root certificates directory can be mounted using the Docker volume option (`-v host-source-directory:container-destination-directory`) when starting the Rancher container. - -Examples of services that Rancher can access: - -* Catalogs -* Authentication providers -* Accessing hosting/cloud API when using Node Drivers - -## Start Rancher Container with custom CA root certificates - -The requirements are: - -* Mount the host directory containing the CA root certificates in the container using the volume option. -* Add the environment variable `SSL_CERT_DIR` with as value the mounted CA root certificates directory location inside the container. - -Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`, mounting a host directory inside the container can be done using `-v host-source-directory:container-destination-directory` or `--volume host-source-directory:container-destination-directory`. - -The example below is based on having the CA root certificates in the `/host/certs` directory on the host and mounting this directory on `/container/certs` inside the Rancher container. - -``` -docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - -v /host/certs:/container/certs \ - -e SSL_CERT_DIR="/container/certs" \ - rancher/rancher:latest -``` diff --git a/content/rancher/v2.x/en/installation/ha-server-install2/_index.md b/content/rancher/v2.x/en/installation/ha-server-install2/_index.md deleted file mode 100644 index c936195f38a..00000000000 --- a/content/rancher/v2.x/en/installation/ha-server-install2/_index.md +++ /dev/null @@ -1,458 +0,0 @@ ---- -title: High Availability Installation 2 -weight: 275 -draft: true ---- -This set of instructions creates a new Kubernetes cluster that's dedicated to running Rancher in a high-availability (HA) configuration. This procedure walks you through setting up a 3-node cluster using the Rancher Kubernetes Engine (RKE). The cluster's sole purpose is running pods for Rancher. The setup is based on: - -- Layer 4 load balancer (TCP) -- NGINX ingress controller with SSL termination (HTTPS) - -![Rancher HA]({{< baseurl >}}/img/rancher/ha/rancher2ha.svg) - -## Installation Outline - -Installation of Rancher in a high-availability configuration involves multiple procedures. Review this outline to learn about each procedure you need to complete. - -1. [Provision Linux Hosts](#1-provision-linux-hosts) - - Provision three Linux hosts to serve as your Kubernetes cluster. - -2. [Configure Load Balancer](#2-configure-load-balancer) - - Configure your load balancer to have a highly available single point of entry to your Rancher cluster. - -3. [Configure DNS](#3-configure-dns) - - Make your setup accessible using a DNS name by configuring the DNS to point to your loadbalancer. - -4. [Download RKE](#4-download-rke) - - [RKE](https://github.com/rancher/rke/releases) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. - -5. [Download RKE Config File Template](#5-download-rke-config-file-template) - - RKE uses a YAML config file to install and configure your Kubernetes cluster. Download one of our RKE config file templates to get started. - -6. [Configure Nodes](#6-configure-nodes) - - Configure the **Nodes** section of the RKE config template. - -7. [Configure Certificates](#7-configure-certificates) - - Configure the **Certificates** part of the template too. - -8. [Configure FQDN](#8-configure-fqdn) - - And the **FQDN** part. - -9. [Back Up Your RKE Config File](#9-back-up-your-rke-config-file) - - After you've completed configuration of the RKE config file: 1. it's no longer a template since you'll be using it, and 2. you should back up the RKE config file to a safe place. You will reuse this file for upgrades later. - -10. [Run RKE](#10-run-rke) - - Run RKE to deploy Rancher to your cluster. - -11. [Back Up Auto-Generated Config File](#11-back-up-auto-generated-config-file) - - During installation, RKE generates a config file that you'll use later for upgrades. Back it up to a safe location. - -12. **For those using a certificate signed by a recognized CA:** - - [Remove Default Certificates](#12-remove-default-certificates) - - If you chose [Option B](#option-b-bring-your-own-certificate-signed-by-recognized-ca) as your SSL option, log into the Rancher UI and remove the certificates that Rancher automatically generates. - -
- -## 1. Provision Linux Hosts - -Before you install Rancher, confirm you meet the host requirements. Provision 3 new Linux hosts using the requirements below. - -### Host Requirements - -#### Operating System - -{{< requirements_os >}} - -#### Hardware - -{{< requirements_hardware >}} - -#### Software - -{{< requirements_software >}} - -{{< note_server-tags >}} - -#### Ports - -The following diagram depicts the basic port requirements for Rancher. For a comprehensive list, see [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/references/). - -![Basic Port Requirements]({{< baseurl >}}/img/rancher/port-communications.png) - -## 2. Configure Load Balancer - -We will be using NGINX as our Layer 4 Load Balancer (TCP). NGINX will forward all connections to one of your Rancher nodes. If you want to use Amazon NLB, you can skip this step and use [Amazon NLB configuration]({{< baseurl >}}/rancher/v2.x/en/installation/ha-server-install/nlb/) - ->**Note:** -> In this configuration, the load balancer is positioned in front of your Linux hosts. The load balancer can be any host that you have available that's capable of running NGINX. -> ->One caveat: do not use one of your Rancher nodes as the load balancer. - -### A. Install NGINX - -Start by installing NGINX on your load balancer host. NGINX has packages available for all known operating systems. - -For help installing NGINX, refer to their [install documentation](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/). - -### B. Create NGINX Configuration - -After installing NGINX, you need to update the NGINX config file, `nginx.conf`, with the IP addresses for your nodes. - -1. Copy and paste the code sample below into your favorite text editor. Save it as `nginx.conf`. - -2. From `nginx.conf`, replace `IP_NODE_1`, `IP_NODE_2`, and `IP_NODE_3` with the IPs of your [Linux hosts](#1-provision-linux-hosts). - - **Example NGINX config:** - ``` - worker_processes 4; - worker_rlimit_nofile 40000; - - events { - worker_connections 8192; - } - - http { - server { - listen 80; - return 301 https://$host$request_uri; - } - } - - stream { - upstream rancher_servers { - least_conn; - server IP_NODE_1:443 max_fails=3 fail_timeout=5s; - server IP_NODE_2:443 max_fails=3 fail_timeout=5s; - server IP_NODE_3:443 max_fails=3 fail_timeout=5s; - } - server { - listen 443; - proxy_pass rancher_servers; - } - } - ``` - -3. Save `nginx.conf` to your load balancer at the following path: `/etc/nginx/nginx.conf`. - -4. Load the updates to your NGINX configuration by running the following command: - - ``` - # nginx -s reload - ``` - -### Option - Run NGINX as Docker container - -Instead of installing NGINX as a package on the operating system, you can rather run it as a Docker container. Save the edited **Example NGINX config** as `/etc/nginx.conf` and run the following command to launch the NGINX container: - -``` -docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - -v /etc/nginx.conf:/etc/nginx/nginx.conf \ - nginx:1.14 -``` - -## 3. Configure DNS - -Choose a fully qualified domain name (FQDN) that you want to use to access Rancher (e.g., `rancher.yourdomain.com`).

- -1. Log into your DNS server a create a `DNS A` record that points to the IP address of your [load balancer](#2-configure-load-balancer). - -2. Validate that the `DNS A` is working correctly. Run the following command from any terminal, replacing `HOSTNAME.DOMAIN.COM` with your chosen FQDN: - - `nslookup HOSTNAME.DOMAIN.COM` - - **Step Result:** Terminal displays output similar to the following: - - ``` - $ nslookup rancher.yourdomain.com - Server: YOUR_HOSTNAME_IP_ADDRESS - Address: YOUR_HOSTNAME_IP_ADDRESS#53 - - Non-authoritative answer: - Name: rancher.yourdomain.com - Address: HOSTNAME.DOMAIN.COM - ``` - -
- -## 4. Download RKE - -RKE is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. We will be using RKE to setup our cluster and run Rancher. - -1. From your workstation, open a web browser and navigate to our [RKE Releases](https://github.com/rancher/rke/releases/latest) page. Download the latest RKE installer applicable to your Operating System: - - - **MacOS**: `rke_darwin-amd64` - - **Linux**: `rke_linux-amd64` - - **Windows**: `rke_windows-amd64.exe` - -2. Make the RKE binary that you just downloaded executable. Open Terminal, change directory to the location of the RKE binary, and then run one of the commands below. - - >**Using Windows?** - >The file is already an executable. Skip to [Download RKE Config File Template](#5-download-rke-config-file-template). - - ``` - # MacOS - $ chmod +x rke_darwin-amd64 - # Linux - $ chmod +x rke_linux-amd64 - ``` - -3. Confirm that RKE is now executable by running the following command: - - ``` - # MacOS - $ ./rke_darwin-amd64 --version - # Linux - $ ./rke_linux-amd64 --version - ``` - - **Step Result:** You receive output similar to what follows: - ``` - rke version v - ``` - -## 5. Download RKE Config File Template - -RKE uses a `.yml` config file to install and configure your Kubernetes cluster. There are 2 templates to choose from, depending on the SSL certificate you want to use. - -1. Download one of following templates, depending on the SSL certificate you're using. - - - [Template for self-signed certificate
`3-node-certificate.yml`](https://raw.githubusercontent.com/rancher/rancher/e9d29b3f3b9673421961c68adf0516807d1317eb/rke-templates/3-node-certificate.yml) - - [Template for certificate signed by recognized CA
`3-node-certificate-recognizedca.yml`](https://raw.githubusercontent.com/rancher/rancher/e9d29b3f3b9673421961c68adf0516807d1317eb/rke-templates/3-node-certificate-recognizedca.yml) - -2. Rename the file to `rancher-cluster.yml`. - -## 6. Configure Nodes - -Once you have the `rancher-cluster.yml` config file template, edit the nodes section to point toward your Linux hosts. - -1. Open `rancher-cluster.yml` in your favorite text editor. - -2. Update the `nodes` section with the information of your [Linux hosts](#1-provision-linux-hosts). - - For each node in your cluster, update the following placeholders: `IP_ADDRESS_X` and `USER`. - -``` -nodes: - - address: IP_ADDRESS_1 - # THE IP ADDRESS OR HOSTNAME OF THE NODE - user: USER - # USER WITH ADMIN ACCESS. USUALLY `root` - role: [controlplane,etcd,worker] - ssh_key_path: ~/.ssh/id_rsa - # PATH TO SSH KEY THAT AUTHENTICATES ON YOUR WORKSTATION - # USUALLY THE VALUE ABOVE - - address: IP_ADDRESS_2 - user: USER - role: [controlplane,etcd,worker] - ssh_key_path: ~/.ssh/id_rsa - - address: IP_ADDRESS_3 - user: USER - role: [controlplane,etcd,worker] - ssh_key_path: ~/.ssh/id_rsa -``` - -## 7. Configure Certificates - -For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. - -Choose from the following options: - -- [Option A—Bring Your Own Certificate: Self-Signed](#option-a-bring-your-own-certificate-self-signed) -- [Option B—Bring Your Own Certificate: Signed by Recognized CA](#option-b-bring-your-own-certificate-signed-by-recognized-ca) - -### Option A—Bring Your Own Certificate: Self-Signed - ->**Prerequisites:** ->Create a self-signed certificate. -> ->- The certificate files must be in [PEM format](#pem). ->- The certificate files must be encoded in [base64](#base64). ->- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Intermediate Certificates](#cert-order). - -1. In `kind: Secret` with `name: cattle-keys-ingress`: - - * Replace `` with the base64 encoded string of the Certificate file (usually called `cert.pem` or `domain.crt`) - * Replace `` with the base64 encoded string of the Certificate Key file (usually called `key.pem` or `domain.key`) - - >**Note:** - > The base64 encoded string should be on the same line as `tls.crt` or `tls.key`, without any newline at the beginning, in between or at the end. - - **Result:** After replacing the values, the file should look like the example below (the base64 encoded strings should be different): - -```yaml ---- - apiVersion: v1 - kind: Secret - metadata: - name: cattle-keys-ingress - namespace: cattle-system - type: Opaque - data: - tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K - tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg== -``` - -2. In `kind: Secret` with `name: cattle-keys-server`, replace `` with the base64 encoded string of the CA Certificate file (usually called `ca.pem` or `ca.crt`). - - >**Note:** - > The base64 encoded string should be on the same line as `cacerts.pem`, without any newline at the beginning, in between or at the end. - - - **Result:** The file should look like the example below (the base64 encoded string should be different): - ```yaml - --- - apiVersion: v1 - kind: Secret - metadata: - name: cattle-keys-server - namespace: cattle-system - type: Opaque - data: - cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg== - ``` - -### Option B—Bring Your Own Certificate: Signed by Recognized CA - ->**Note:** -> If you are using Self Signed Certificate, [click here](#option-a-bring-your-own-certificate-self-signed) to proceed. - -If you are using a Certificate Signed By A Recognized Certificate Authority, you will need to generate a base64 encoded string for the Certificate file and the Certificate Key file. Make sure that your certificate file includes all the [intermediate certificates](#cert-order) in the chain, the order of certificates in this case is first your own certificate, followed by the intermediates. Please refer to the documentation of your CSP (Certificate Service Provider) to see what intermediate certificate(s) need to be included. - -In the `kind: Secret` with `name: cattle-keys-ingress`: - -* Replace `` with the base64 encoded string of the Certificate file (usually called `cert.pem` or `domain.crt`) -* Replace `` with the base64 encoded string of the Certificate Key file (usually called `key.pem` or `domain.key`) - -After replacing the values, the file should look like the example below (the base64 encoded strings should be different): - ->**Note:** -> The base64 encoded string should be on the same line as `tls.crt` or `tls.key`, without any newline at the beginning, in between or at the end. - -```yaml ---- -apiVersion: v1 -kind: Secret -metadata: - name: cattle-keys-ingress - namespace: cattle-system -type: Opaque -data: - tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K - tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg== -``` - -## 8. Configure FQDN - -There are two references to `` in the config file (one in this step and one in the next). Both need to be replaced with the FQDN chosen in [Configure DNS](#3-configure-dns). - -In the `kind: Ingress` with `name: cattle-ingress-http`: - -* Replace `` with the FQDN chosen in [Configure DNS](#3-configure-dns). - -After replacing `` with the FQDN chosen in [Configure DNS](#3-configure-dns), the file should look like the example below (`rancher.yourdomain.com` is the FQDN used in this example): - -```yaml - --- - apiVersion: extensions/v1beta1 - kind: Ingress - metadata: - namespace: cattle-system - name: cattle-ingress-http - annotations: - nginx.ingress.kubernetes.io/proxy-connect-timeout: "30" - nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # Max time in seconds for ws to remain shell window open - nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # Max time in seconds for ws to remain shell window open - spec: - rules: - - host: rancher.yourdomain.com - http: - paths: - - backend: - serviceName: cattle-service - servicePort: 80 - tls: - - secretName: cattle-keys-ingress - hosts: - - rancher.yourdomain.com -``` - -Save the `.yml` file and close it. - -## 9. Back Up Your RKE Config File - -After you close your `.yml` file, back it up to a secure location. You can use this file again when it's time to upgrade Rancher. - -## 10. Run RKE - -With all configuration in place, use RKE to launch Rancher. You can complete this action by running the `rke up` command and using the `--config` parameter to point toward your config file. - -1. From your workstation, make sure `rancher-cluster.yml` and the downloaded `rke` binary are in the same directory. - -2. Open a Terminal instance. Change to the directory that contains your config file and `rke`. - -3. Enter one of the `rke up` commands listen below. - -``` -# MacOS -./rke_darwin-amd64 up --config rancher-cluster.yml -# Linux -./rke_linux-amd64 up --config rancher-cluster.yml -``` - -**Step Result:** The output should be similar to the snippet below: - -``` -INFO[0000] Building Kubernetes cluster -INFO[0000] [dialer] Setup tunnel for host [1.1.1.1] -INFO[0000] [network] Deploying port listener containers -INFO[0000] [network] Pulling image [alpine:latest] on host [1.1.1.1] -... -INFO[0101] Finished building Kubernetes cluster successfully -``` - -## 11. Back Up Auto-Generated Config File - -During installation, RKE automatically generates a config file named `kube_config_rancher-cluster.yml` in the same directory as the RKE binary. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server. - -## 12. Remove Default Certificates - -**For those using a certificate signed by a recognized CA:** - ->**Note:** If you're using a self-signed certificate, you don't have to complete this procedure. Continue to [What's Next?](#what-s-next) - -By default, Rancher automatically generates self-signed certificates for itself after installation. However, since you've provided your own certificates, you must disable the certificates that Rancher generated for itself. - -**To Remove the Default Certificates:** - -1. Log into Rancher. - -2. Select **Settings** > **cacerts**. - -3. Choose `Edit` and remove the contents. Then click `Save`. - -## What's Next? - -You have a couple of options: - -- Create a backup of your Rancher Server in case of a disaster scenario: [High Availablility Back Up and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/ha-backup-and-restoration). -- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/). - -
- -## FAQ and Troubleshooting - -{{< ssl_faq_ha >}} diff --git a/content/rancher/v2.x/en/installation/ha/_index.md b/content/rancher/v2.x/en/installation/ha/_index.md new file mode 100644 index 00000000000..2dee2f962a1 --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/_index.md @@ -0,0 +1,40 @@ +--- +title: High Availability (HA) Install +weight: 275 +draft: true +--- + +When installed in a Kubernetes cluster, Rancher will integrate with the cluster's etcd database and take advantage of Kubernetes scheduling for High-Availability. + +This procedure walks you through setting up a 3-node cluster with RKE and installing the Rancher chart with the Helm package manager. + +> **Note:** For the best performance, we recommend this Kubernetes cluster be dedicated only to the Rancher workload. + +## Recommended Architecture + +* DNS for Rancher should resolve to a Layer 4 Load Balancer +* The Load Balancer should forward ports 80 and 443 TCP to all 3 nodes in the Kubernetes cluster. +* The Ingress controller will redirect http port 80 to https and terminate SSL/TLS on port 443. +* The Ingress controller will forward traffic to port 80 on the Pod in the Rancher Deployment. + +![Rancher HA]({{< baseurl >}}/img/rancher/ha/rancher2ha.svg) + +## Required Tools + +The following CLI tools are required for this install. Please make sure these tools are installed and available in your `$PATH` + +* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool. +* [rke]({{< baseurl >}}/rke/v0.1.x/en/installation/) - Rancher Kubernetes Engine, cli for building Kubernetes clusters. +* [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. + +## Installation Outline + +1. [Create Nodes and Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/ha/create-nodes-lb/) +1. [Install Kubernetes with RKE]({{< baseurl >}}/rancher/v2.x/en/installation/ha/kubernetes-rke/) +1. [Initialize Helm (tiller)]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-init/) +1. [Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/) + +## Additional Install Options + +* [Migrating from RKE add-on install]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on/) +* [RKE add-on install]({{< baseurl >}}/rancher/v2.x/en/installation/ha/rke-add-on/) diff --git a/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md b/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md new file mode 100644 index 00000000000..1a00ac78b24 --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md @@ -0,0 +1,48 @@ +--- +title: 1 - Create Nodes and Load Balancer +weight: 185 +--- + +Use your provider of choice to provision 3 nodes and a Load Balancer endpoint for your RKE install. + +> **Note:** These nodes must be in the same region/datacenter. You may place these servers in separate availability zones. + +**Don't forget to collect the SSH credentials and DNS or IP addresses of your nodes to provide to RKE in the next step.** + +### Host Requirements + +#### Operating System + +{{< requirements_os >}}
+ +#### Nodes + +{{< requirements_hardware >}}
+ +#### Software + +{{< requirements_software >}} + +{{< note_server-tags >}} + +#### Ports + +{{< requirements_ports_rancher_rke >}} + +
+ +If you block ports internally on the nodes see the full [ports list]({{< baseurl >}}/rancher/v2.x/en/installation/references/) for all the communication details. + +### Load Balancer + +RKE will configure an ingress-controller pod, on each of your nodes. The ingress-controller pods are bound to ports 80 and 443 TCP on the host network and are the entry point for HTTPS traffic to the Rancher server. + +Configure a load balancer as a basic Layer 4 TCP forwarder. The exact configuration will vary depending on your environment. + +#### Examples + +* [Amazon NLB]({{< baseurl >}}/rancher/v2.x/en/installation/ha/create-nodes-lb/nlb/) + +
+ +### [Next: Install Kubernetes with RKE]({{< baseurl >}}/rancher/v2.x/en/installation/ha/kubernetes-rke/) \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/ha-server-install/nlb/_index.md b/content/rancher/v2.x/en/installation/ha/create-nodes-lb/nlb/_index.md similarity index 99% rename from content/rancher/v2.x/en/installation/ha-server-install/nlb/_index.md rename to content/rancher/v2.x/en/installation/ha/create-nodes-lb/nlb/_index.md index 1bef7366ae0..ac7a95e5462 100644 --- a/content/rancher/v2.x/en/installation/ha-server-install/nlb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/create-nodes-lb/nlb/_index.md @@ -1,5 +1,5 @@ --- -title: Amazon NLB configuration +title: Amazon NLB weight: 277 --- ## Objectives diff --git a/content/rancher/v2.x/en/installation/ha/helm-init/_index.md b/content/rancher/v2.x/en/installation/ha/helm-init/_index.md new file mode 100644 index 00000000000..bc447a1320d --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/helm-init/_index.md @@ -0,0 +1,31 @@ +--- +title: 3 - Initialize Helm (Install tiller) +weight: 195 +--- + +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/). + +### Initialize Helm on the cluster + +Helm installs the `tiller` service on your cluster to manage charts. Since RKE enables RBAC by default we will need to use `kubectl` to create a `serviceaccount` and `clusterrolebinding` so `tiller` has permission to deploy to the cluster. + +* Create the `ServiceAccount` in the `kube-system` namespace. +* Create the `ClusterRoleBinding` to give the `tiller` account access to the cluster. +* Finally use `helm` to initialize the `tiller` service + +``` +kubectl -n kube-system create serviceaccount tiller +kubectl create clusterrolebinding tiller --clusterrole cluster-admin --serviceaccount=kube-system:tiller +``` + +##### Helm init + +`helm init` installs the `tiller` service in the `kube-system` namespace on your cluster. + +``` +helm init --service-account tiller +``` + +> NOTE: This `tiller` install has full cluster access, which should be acceptable if the cluster is dedicated to Rancher server. Check out the [helm docs](https://docs.helm.sh/using_helm/#role-based-access-control) for restricting `tiller` access to suit your security requirements. + +### [Next: Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/ha//helm-rancher/) \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md new file mode 100644 index 00000000000..f139cc0b560 --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -0,0 +1,102 @@ +--- +title: 4 - Install Rancher +weight: 200 +--- + +Rancher installation is now managed using the Helm package manager for Kubernetes. Use `helm` to install the prerequisite and Rancher charts. + +### Add the Chart Repo + +Use `helm repo add` to add the Rancher chart repository. + +``` +helm repo add rancher-stable https://releases.rancher.com/server-charts/stable +``` + +### Install cert-manager + +> **Note:** cert-manager is only required for Rancher generated and LetsEncrypt issued certificates. You may skip this step if you are bringing your own certificates and using the `ingress.tls.source=secret` option. + +Rancher relies on [cert-manager](https://github.com/kubernetes/charts/tree/master/stable/cert-manager) from the Kubernetes Helm "stable" catalog to issue self-signed or LetsEncrypt certificates. + +Install `cert-manager` from the Helm stable catalog. + +``` +helm install stable/cert-manager --name cert-manager --namespace kube-system +``` + +### Choose your SSL Configuration + +Rancher server is designed to be "secure by default" and requires SSL/TLS configuration. + +There are three options for the source of the certificate. + +* `rancher` - (Default) Use Rancher generated CA/Certificates. +* `letsEncrypt` - Use [LetsEncrypt](https://letsencrypt.org/) to issue a cert. +* `secret` - Configure a Kubernetes Secret with your certificate files. + + + +#### (Default) Rancher Generated Certificates + +The default is for Rancher to generate a CA and use the `cert-manager` to issue the certificate for access to the Rancher server interface. + +The only requirement is to set the `hostname` to the DNS name you pointed at your Load Balancer. + +``` +helm install rancher-stable/rancher --name rancher --namespace cattle-system \ +--set hostname=rancher.my.org +``` + +#### LetsEncrypt + +Use LetsEncrypt's free service to issue trusted SSL certs. This configuration uses http validation so the Load Balancer must have a Public DNS record and be accessible from the internet. + +Set `hostname`, `ingress.tls.source=letEncrypt` and LetsEncrypt options. + +``` +helm install rancher-stable/rancher --name rancher --namespace cattle-system \ +--set hostname=rancher.my.org \ +--set ingress.tls.source=letsEncrypt \ +--set letsEncrypt.email=me@example.org +``` + +> LetsEncrypt ProTip: The default `production` environment only allows you to register a name 5 times in a week. If you're rebuilding a bunch of times, use `--set letsEncrypt.environment=staging` until you have you're confident your config is right. + +#### Certificates from Files (Kubernetes Secret) + +Create Kubernetes Secrets from your own certificates for Rancher to use. + +> NOTE: The common name for the cert will need to match the `hostname` option or the ingress controller will fail to provision the site for Rancher. + +Set `hostname` and `ingress.tls.source=secret` + +> NOTE: If you are using a Private CA signed cert, add `--set privateCA=true` + +``` +helm install rancher-stable/rancher --name rancher --namespace cattle-system \ +--set hostname=rancher.my.org \ +--set ingress.tls.source=secret +``` + +Now that Rancher is running, see [Adding TLS Secrets]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/) to publish the certificate files so Rancher and the Ingress Controller can use them. + +### Advanced Configurations + +The Rancher chart configuration has many options for customizing the install to suit your specific environment. Here are some common advanced scenarios. + +* [HTTP Proxy]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#http-proxy) +* [Private Docker Image Registry]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#private-registry) +* [TLS Termination on an External Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#external-tls-termination) + +See the [Chart Options]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/) for the full list of options. + +### Save your options + +Make sure you save the `--set` options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm. + +### Finishing Up + +That's it you should have a functional Rancher server. Point a browser at the hostname you picked and you should be greeted by the colorful login page. + +Doesn't Work? Take a look at the [Troubleshooting]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/troubleshooting/) Page diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md new file mode 100644 index 00000000000..2b338442f90 --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md @@ -0,0 +1,92 @@ +--- +title: Chart Options +weight: 276 +--- + +### Common Options + +| Option | Default Value | Description | +| --- | --- | --- | +| `hostname` | " " | `string` - the Fully Qualified Domain Name for your Rancher Server | +| `ingress.tls.source` | "rancher" | `string` - Where to get the cert for the ingress. - "rancher, letsEncrypt, secret" | +| `letsEncrypt.email` | " " | `string` - Your email address | +| `letsEncrypt.environment` | "production" | `string` - Valid options: "staging, production" | +| `privateCA` | false | `bool` - Set to true if your cert is signed by a private CA | + +
+ +### Advanced Options + +| Option | Default Value | Description | +| --- | --- | --- | +| `debug` | false | `bool` - set debug flag on rancher server | +| `imagePullSecrets` | [] | `list` - list of names of Secret resource containing private registry credentials | +| `proxy` | "" | `string` - string - HTTP[S] proxy server for Rancher | +| `noProxy` | "localhost,127.0.0.1" | `string` - comma seperated list of hostnames or ip address not to use the proxy | +| `resources` | {} | `map` - rancher pod resource requests & limits | +| `rancherImage` | "rancher/rancher" | `string` - rancher image source | +| `rancherImageTag` | same as chart version | `string` - rancher/rancher image tag | +| `tls` | "ingress" | `string` - Where to terminate SSL. - "ingress, external" + +
+ +### HTTP Proxy + +Rancher requires internet access for some functionality (helm charts). Use `proxy` to set your proxy server. + +Add your IP exceptions to the `noProxy` list. Make sure you add the Service cluster IP range (default: 10.43.0.1/16) and any worker cluster `controlplane` nodes. Rancher supports CIDR notation ranges in this list. + +``` +--set proxy="http://:@:/" +--set noProxy="127.0.0.1,localhost,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16" +``` + +### Private Registry + +You can point to a private registry for the rancher image. + +#### Images + +Populate your private registry with Rancher images. + +You can get the list of images required for rancher and worker cluster installs from the [Releases](https://github.com/rancher/rancher/releases/latest) page. + +#### Create Registry Secret + +Use `kubectl` to create a docker-registry secret in the `cattle-system` namespace. + +``` +kubectl -n cattle-system create secret docker-registry regcred \ +--docker-server="reg.example.com:5000" \ +--docker-email= +``` + +#### Registry Options + +Add the `rancherImage` to point to your private registry image and `imagePullSecrets` to your install command. + +``` +--set rancherImage=reg.example.com:5000/rancher/rancher \ +--set imagePullSecrets[0].name=regcred +``` + +### External TLS Termination + +If you wish to terminate the SSL/TLS on a load-balancer external to the Rancher cluster (ingress), use the `--tls=external` option and point your load balancer at port http 80 on all of the rancher cluster nodes. + +> NOTE: If you are using a Private CA signed cert, add `--set privateCA=true` and see [Adding TLS Secrets - Private CA Signed - Additional Steps]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/#private-ca-signed---additional-steps) to add the CA cert for Rancher. + +Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly. + +> NOTE: The `tls=external` option will expose the Rancher interface on http port 80. Clients that are allowed to connect directly to the Rancher cluster will not be encrypted. We recommend that you restrict direct access at the network level to just your load balancer. + +#### Required headers + +* `Host` +* `X-Forwarded-Proto` +* `X-Forwarded-Port` +* `X-Forwarded-For` + +#### Health checks + +Rancher will respond `200` to health checks on the `/healthz` endpoint. diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/_index.md new file mode 100644 index 00000000000..b77e4e1e9ba --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/_index.md @@ -0,0 +1,26 @@ +--- +title: Adding TLS Secrets +weight: 276 +--- + +Kubernetes will create all the objects and services for Rancher, but it will not become available until we populate the `tls-rancher-ingress` secret in the `cattle-system` namespace with the certificate and key. + +Combine the server certificate followed by the intermediate cert chain your CA provided into a file named `tls.crt`. Copy your key into a file name `tls.key`. + +Use `kubectl` with the `tls` secret type to create the secrets. + +``` +kubectl -n cattle-system create secret tls tls-rancher-ingress \ +--cert=./tls.crt \ +--key=./tls.key +``` + +### Private CA Signed - Additional Steps + +If you are using a private CA, Rancher will need to have a copy of the CA cert to include when generating agent configs. + +Copy the CA cert into a file named `cacerts.pem` and use `kubectl` to create the `tls-ca` secret in the `cattle-system` namespace. + +``` +kubectl -n cattle-system create secret generic tls-ca --from-file=cacerts.pem +``` diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/troubleshooting/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/troubleshooting/_index.md new file mode 100644 index 00000000000..fd12a12e04f --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/troubleshooting/_index.md @@ -0,0 +1,123 @@ +--- +title: Troubleshooting +weight: 276 +--- + +### Where is everything + +Most of the troubleshooting will be done on objects in these 3 namespaces. + +* `cattle-system` - `rancher` deployment and pods. +* `ingress-nginx` - Ingress controller pods and services. +* `kube-system` - `tiller` and `cert-manager` pods. + +### "default backend - 404" + +A number of things can cause the ingress-controller not to forward traffic to your rancher instance. Most of the time its due to a bad ssl configuration. + +Things to check + +* [Is Rancher Running](#is-rancher-running) +* [Cert CN is "Kubernetes Ingress Controller Fake Certificate"](#cert-cn-is-kubernetes-ingress-controller-fake-certificate) + +### Is Rancher Running + +Use `kubectl` to check the `cattle-system` system namespace and see if the Rancher pods are in a Running state. + +``` +kubectl -n cattle-system get pods + +NAME READY STATUS RESTARTS AGE +pod/rancher-784d94f59b-vgqzh 1/1 Running 0 10m +``` + +If the state is not `Running`, run a `describe` on the pod and check the Events. + +``` +kubectl -n cattle-system describe pod + +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Scheduled 11m default-scheduler Successfully assigned rancher-784d94f59b-vgqzh to localhost + Normal SuccessfulMountVolume 11m kubelet, localhost MountVolume.SetUp succeeded for volume "rancher-token-dj4mt" + Normal Pulling 11m kubelet, localhost pulling image "rancher/rancher:v2.0.4" + Normal Pulled 11m kubelet, localhost Successfully pulled image "rancher/rancher:v2.0.4" + Normal Created 11m kubelet, localhost Created container + Normal Started 11m kubelet, localhost Started container +``` + +### Checking the rancher logs + +Use `kubectl` to list the pods. + +``` +kubectl -n cattle-system get pods + +NAME READY STATUS RESTARTS AGE +pod/rancher-784d94f59b-vgqzh 1/1 Running 0 10m +``` + +Use `kubectl` and the pod name to list the logs from the pod. + +``` +kubectl -n cattle-namespace logs -f rancher-784d94f59b-vgqzh +``` + +### Cert CN is "Kubernetes Ingress Controller Fake Certificate" + +Use your browser to check the certificate details. If it says the Common Name is "Kubernetes Ingress Controller Fake Certificate", something may have gone wrong with reading or issuing your SSL cert. + +> Note: if you are using LetsEncrypt to issue certs it can sometimes take a few minuets to issue the cert. + +#### cert-manager issued certs (Rancher Generated or LetsEncrypt) + +`cert-manager` has 3 parts. + +* `cert-manager` pod in the `kube-system` namespace. +* `Issuer` object in the `cattle-system` namespace. +* `Certificate` object in the `cattle-system` namespace. + +Work backwards and do a `kubectl describe` on each object and check the events. You can track down what might be missing. + +For example there is a problem with the Issuer: + +``` +kubectl -n cattle-system describe certificate +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning IssuerNotReady 18s (x23 over 19m) cert-manager Issuer rancher not ready +``` + +``` +kubectl -n cattle-system describe issuer +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning ErrInitIssuer 19m (x12 over 19m) cert-manager Error initializing issuer: secret "tls-rancher" not found + Warning ErrGetKeyPair 9m (x16 over 19m) cert-manager Error getting keypair for CA issuer: secret "tls-rancher" not found +``` + +#### Bring Your Own SSL Certs + +Your certs get applied directly to the Ingress object in the `cattle-system` namespace. + +Check the status of the Ingress object and see if its ready. + +``` +kubectl -n cattle-system describe ingress +``` + +If its ready and the SSL is still not working you may have a malformed cert or secret. + +Check the nginx-ingress-controller logs. Because the nginx-ingress-controller has multiple containers in its pod you will need to specify the name of the container. + +``` +kubectl -n ingress-nginx logs -f nginx-ingress-controller-rfjrq nginx-ingress-controller +... +W0705 23:04:58.240571 7 backend_ssl.go:49] error obtaining PEM from secret cattle-system/tls-rancher-ingress: error retrieving secret cattle-system/tls-rancher-ingress: secret cattle-system/tls-rancher-ingress was not found +``` diff --git a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md new file mode 100644 index 00000000000..ab51ecfc554 --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md @@ -0,0 +1,78 @@ +--- +title: 2 - Install Kubernetes with RKE +weight: 190 +--- + +Use RKE to install Kubernetes with a high-availability etcd configuration. + +### Create the rancher-cluster.yml file + +Using the sample below create the `rancher-cluster.yml` file. Replace the IP Addresses in the `nodes` list with the IP address or DNS names of the 3 Nodes you created. + +```yaml +nodes: +- address: 165.227.114.63 + user: ubuntu + role: [controlplane,worker,etcd] +- address: 165.227.116.167 + user: ubuntu + role: [controlplane,worker,etcd] +- address: 165.227.127.226 + user: ubuntu + role: [controlplane,worker,etcd] +``` + +#### Common RKE nodes: options + +| Option | Description | +| --- | --- | +| `address` | (required) The public DNS or IP address | +| `internal_address` | (optional) The private DNS or IP address for internal cluster traffic | +| `role` | (required) List of Kubernetes roles assigned to the node | +| `ssh_key_path` | (optional) Path to SSH private key used to authenticate to the node | +| `user` | (required) A user that can run docker commands | + +
+ +#### Advanced configurations + +RKE has many configuration options for customizing the install to suit your specific environment. + +Please see the [RKE Documentation]({{< baseurl >}}/rke/v0.1.x/en/) for the full list of options and capabilities. + +### Run RKE + +``` +rke up --config ./rancher-cluster.yml +``` + +### Testing your cluster + +RKE should have created a file `kube_config_rancher-cluster.yml`. This file has the credentials for `kubectl` and `helm`. + +You can copy this file to `$HOME/.kube/config` or if you are working with multiple Kubernetes clusters, set the `KUBECONFIG` environmental variable to the path of `kube_config_rancher-cluster.yml`. + +``` +export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml +``` + +Test you connectivity with `kubectl` and see if you can get the list of nodes back. + +``` +kubectl get nodes + +NAME STATUS ROLES AGE VERSION +165.227.114.63 Ready controlplane,etcd,worker 11m v1.10.1 +165.227.116.167 Ready controlplane,etcd,worker 11m v1.10.1 +165.227.127.226 Ready controlplane,etcd,worker 11m v1.10.1 +``` + +### Save your files + +Save a copy of the `kube_config_rancher-cluster.yml` and `rancher-cluster.yml` files. You will need these files to maintain and upgrade your Rancher instance. + +### Issues or errors? + +See the [Troubleshooting]({{< baseurl >}}/rancher/v2.x/en/installation/ha/kubernetes-rke/troubleshooting/) page. + +### [Next: Initialize Helm]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-init/) \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/troubleshooting/_index.md b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/troubleshooting/_index.md new file mode 100644 index 00000000000..6e677bc0f18 --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/troubleshooting/_index.md @@ -0,0 +1,42 @@ +--- +title: Troubleshooting +weight: 276 +--- + +#### Failed to set up SSH tunneling for host [xxx.xxx.xxx.xxx]: Can't retrieve Docker Info + +##### Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed) + +* User specified to connect with does not have permission to access the Docker socket. This can be checked by logging into the host and running the command `docker ps`: + +``` +$ ssh user@server +user@server$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +``` + +See [Manage Docker as a non-root user](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) how to set this up properly. + +* When using RedHat/CentOS as operating system, you cannot use the user `root` to connect to the nodes because of [Bugzilla #1527565](https://bugzilla.redhat.com/show_bug.cgi?id=1527565). You will need to add a separate user and configure it to access the Docker socket. See [Manage Docker as a non-root user](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) how to set this up properly. + +* SSH server version is not version 6.7 or higher. This is needed for socket forwarding to work, which is used to connect to the Docker socket over SSH. This can be checked using `sshd -V` on the host you are connecting to, or using netcat: +``` +$ nc xxx.xxx.xxx.xxx 22 +SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2.10 +``` + +##### Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: Error configuring SSH: ssh: no key found + +* The key file specified as `ssh_key_path` cannot be accessed. Make sure that you specified the private key file (not the public key, `.pub`), and that the user that is running the `rke` command can access the private key file. + +##### Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain + +* The key file specified as `ssh_key_path` is not correct for accessing the node. Double-check if you specified the correct `ssh_key_path` for the node and if you specified the correct user to connect with. + +##### Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: Error configuring SSH: ssh: cannot decode encrypted private keys + +* If you want to use encrypted private keys, you should use `ssh-agent` to load your keys with your passphrase. If the `SSH_AUTH_SOCK` environment variable is found in the environment where the `rke` command is run, it will be used automatically to connect to the node. + +##### Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? + +* The node is not reachable on the configured `address` and `port`. diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/_index.md new file mode 100644 index 00000000000..eab29cd6494 --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/_index.md @@ -0,0 +1,11 @@ +--- +title: Advanced Install - RKE Add-on +weight: 276 +--- + +Rancher can be installed by providing the appropriate Kubernetes manifest configurations to RKE's `addons` feature. See the following instructions for examples appropriate to your environment. + +* [High Availability Installation with External Load Balancer (TCP/Layer 4)]({{< baseurl >}}/rancher/v2.x/installation/ha/rke-add-on/layer-4-lb/) +* [High Availability Installation with External Load Balancer (HTTPS/Layer 7)]({{< baseurl >}}/rancher/v2.x/installation/ha/rke-add-on/layer-7-lb/) +* [HTTP Proxy Configuration for a High Availability Installation]({{< baseurl >}}/rancher/v2.x/installation/ha/rke-add-on/proxy/) +* [Troubleshooting RKE Add-on Installs]({{< baseurl >}}/rancher/v2.x/installation/ha/rke-add-on/troubleshooting/) diff --git a/content/rancher/v2.x/en/installation/ha-server-install/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md similarity index 99% rename from content/rancher/v2.x/en/installation/ha-server-install/_index.md rename to content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md index dfb67c355d3..581fa1b6f21 100644 --- a/content/rancher/v2.x/en/installation/ha-server-install/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md @@ -1,6 +1,8 @@ --- -title: High Availability Installation with External Load Balancer (TCP/Layer 4) +title: HA Install with External Load Balancer (TCP/Layer 4) weight: 275 +aliases: +- /rancher/v2.x/en/installation/ha-server-install/ --- This set of instructions creates a new Kubernetes cluster that's dedicated to running Rancher in a high-availability (HA) configuration. This procedure walks you through setting up a 3-node cluster using the Rancher Kubernetes Engine (RKE). The cluster's sole purpose is running pods for Rancher. The setup is based on: @@ -109,7 +111,7 @@ After installing NGINX, you need to update the NGINX config file, `nginx.conf`, 2. From `nginx.conf`, replace `IP_NODE_1`, `IP_NODE_2`, and `IP_NODE_3` with the IPs of your [Linux hosts](#1-provision-linux-hosts). >**Note:** This Nginx configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - TCP and UDP Load Balancer](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/). - + **Example NGINX config:** ``` worker_processes 4; diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/nlb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/nlb/_index.md new file mode 100644 index 00000000000..316b0ce50f4 --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/nlb/_index.md @@ -0,0 +1,174 @@ +--- +title: Amazon NLB Configuration +weight: 277 +aliases: +- /rancher/v2.x/en/installation/ha-server-install/nlb/ +--- +## Objectives + +Configuring an Amazon NLB is a multistage process. We've broken it down into multiple tasks so that it's easy to follow. + +1. [Create Target Groups](#create-target-groups) + + Begin by creating two target groups for the **TCP** protocol, one regarding TCP port 443 and one regarding TCP port 80 (providing redirect to TCP port 443). You'll add your Linux nodes to these groups. + +2. [Register Targets](#register-targets) + + Add your Linux nodes to the target groups. + +3. [Create Your NLB](#create-your-nlb) + + Use Amazon's Wizard to create an Network Load Balancer. As part of this process, you'll add the target groups you created in **1. Create Target Groups**. + + +## Create Target Groups + +Your first NLB configuration step is to create two target groups. Technically, only port 443 is needed to access Rancher, but its convenient to add a listener for port 80 which will be redirected to port 443 automatically. The NGINX controller on the nodes will make sure that port 80 gets redirected to port 443. + +Log into the [Amazon AWS Console](https://console.aws.amazon.com/ec2/) to get started, make sure to select the **Region** where your EC2 instances (Linux nodes) are created. + +The Target Groups configuration resides in the **Load Balancing** section of the **EC2** service. Select **Services** and choose **EC2**, find the section **Load Balancing** and open **Target Groups**. + +![EC2 Load Balancing section]({{< baseurl >}}/img/rancher/ha/nlb/ec2-loadbalancing.png) + +Click **Create target group** to create the first target group, regarding TCP port 443. + +### Target Group (TCP port 443) + +Configure the first target group according to the table below. Screenshots of the configuration are shown just below the table. + +Option | Setting +--------------------------------------|------------------------------------ +Target Group Name | `rancher-tcp-443` +Protocol | `TCP` +Port | `443` +Target type | `instance` +VPC | Choose your VPC +Protocol
(Health Check) | `HTTP` +Path
(Health Check) | `/healthz` +Port (Advanced health check) | `override`,`80` +Healthy threshold (Advanced health) | `3` +Unhealthy threshold (Advanced) | `3` +Timeout (Advanced) | `6 seconds` +Interval (Advanced) | `10 second` +Success codes | `200-399` + +
+**Screenshot Target group TCP port 443 settings**
+![Target group 443]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-443.png) + +
+**Screenshot Target group TCP port 443 Advanced settings**
+![Target group 443 Advanced]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-443-advanced.png) + +
+ +Click **Create target group** to create the second target group, regarding TCP port 80. + +### Target Group (TCP port 80) + +Configure the second target group according to the table below. Screenshots of the configuration are shown just below the table. + +Option | Setting +--------------------------------------|------------------------------------ +Target Group Name | `rancher-tcp-80` +Protocol | `TCP` +Port | `80` +Target type | `instance` +VPC | Choose your VPC +Protocol
(Health Check) | `HTTP` +Path
(Health Check) | `/healthz` +Port (Advanced health check) | `traffic port` +Healthy threshold (Advanced health) | `3` +Unhealthy threshold (Advanced) | `3` +Timeout (Advanced) | `6 seconds` +Interval (Advanced) | `10 second` +Success codes | `200-399` + +
+**Screenshot Target group TCP port 80 settings**
+![Target group 80]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-80.png) + +
+**Screenshot Target group TCP port 80 Advanced settings**
+![Target group 80 Advanced]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-80-advanced.png) + +
+ +## Register Targets + +Next, add your Linux nodes to both target groups. + +Select the target group named **rancher-tcp-443**, click the tab **Targets** and choose **Edit**. + +![Edit target group 443]({{< baseurl >}}/img/rancher/ha/nlb/edit-targetgroup-443.png) + +Select the instances (Linux nodes) you want to add, and click **Add to registered**. + +
+**Screenshot Add targets to target group TCP port 443**
+ +![Add targets to target group 443]({{< baseurl >}}/img/rancher/ha/nlb/add-targets-targetgroup-443.png) + +
+**Screenshot Added targets to target group TCP port 443**
+ +![Added targets to target group 443]({{< baseurl >}}/img/rancher/ha/nlb/added-targets-targetgroup-443.png) + +When the instances are added, click **Save** on the bottom right of the screen. + +Repeat those steps, replacing **rancher-tcp-443** with **rancher-tcp-80**. The same instances need to be added as targets to this target group. + +## Create Your NLB + +Use Amazon's Wizard to create an Network Load Balancer. As part of this process, you'll add the target groups you created in [Create Target Groups](#create-target-groups). + +1. From your web browser, navigate to the [Amazon EC2 Console](https://console.aws.amazon.com/ec2/). + +2. From the navigation pane, choose **LOAD BALANCING** > **Load Balancers**. + +3. Click **Create Load Balancer**. + +4. Choose **Network Load Balancer** and click **Create**. + +5. Complete the **Step 1: Configure Load Balancer** form. + - **Basic Configuration** + + - Name: `rancher` + - Scheme: `internet-facing` + - **Listeners** + + Add the **Load Balancer Protocols** and **Load Balancer Ports** below. + - `TCP`: `443` + + - **Availability Zones** + + - Select Your **VPC** and **Availability Zones**. + +6. Complete the **Step 2: Configure Routing** form. + + - From the **Target Group** drop-down, choose **Existing target group**. + + - From the **Name** drop-down, choose `rancher-tcp-443`. + + - Open **Advanced health check settings**, and configure **Interval** to `10 seconds`. + +7. Complete **Step 3: Register Targets**. Since you registered your targets earlier, all you have to do is click **Next: Review**. + +8. Complete **Step 4: Review**. Look over the load balancer details and click **Create** when you're satisfied. + +9. After AWS creates the NLB, click **Close**. + +## Add listener to NLB for TCP port 80 + +1. Select your newly created NLB and select the **Listeners** tab. + +2. Click **Add listener**. + +3. Use `TCP`:`80` as **Protocol** : **Port** + +4. Click **Add action** and choose **Forward to...** + +5. From the **Forward to** drop-down, choose `rancher-tcp-80`. + +6. Click **Save** in the top right of the screen. diff --git a/content/rancher/v2.x/en/installation/ha-server-install-external-lb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md similarity index 97% rename from content/rancher/v2.x/en/installation/ha-server-install-external-lb/_index.md rename to content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md index 3b97214f35b..a000c8089ea 100644 --- a/content/rancher/v2.x/en/installation/ha-server-install-external-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md @@ -1,6 +1,8 @@ --- -title: High Availability Installation with External Load Balancer (HTTPS/Layer 7) +title: HA Install with External Load Balancer (HTTPS/Layer 7) weight: 276 +aliases: +- /rancher/v2.x/en/installation/ha-server-install-external-lb/ --- This set of instructions creates a new Kubernetes cluster that's dedicated to running Rancher in a high-availability (HA) configuration. This procedure walks you through setting up a 3-node cluster using the Rancher Kubernetes Engine (RKE). The cluster's sole purpose is running pods for Rancher. The setup is based on: @@ -105,8 +107,8 @@ Health checks can be executed on the `/healthz` endpoint of the node, this will We have example configurations for the following load balancers: -* [Amazon ALB configuration]({{< baseurl >}}/rancher/v2.x/en/installation/ha-server-install-external-lb/alb) -* [NGINX configuration]({{< baseurl >}}/rancher/v2.x/en/installation/ha-server-install-external-lb/nginx) +* [Amazon ALB configuration](alb/) +* [NGINX configuration](nginx/) ## 3. Configure DNS @@ -331,7 +333,7 @@ During installation, RKE automatically generates a config file named `kube_confi You have a couple of options: -- Create a backup of your Rancher Server in case of a disaster scenario: [High Availablility Back Up and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/ha-backup-and-restoration). +- Create a backup of your Rancher Server in case of a disaster scenario: [High Availablility Back Up and Restoration]({{< baseurl >}}/rancher/v2.x/en/backups/ha-backups/). - Create a Kubernetes cluster: [Creating a Cluster]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/creating-a-cluster/).
diff --git a/content/rancher/v2.x/en/installation/ha-server-install-external-lb/alb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/alb/_index.md similarity index 96% rename from content/rancher/v2.x/en/installation/ha-server-install-external-lb/alb/_index.md rename to content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/alb/_index.md index 424d35bdd3f..abeb64eaded 100644 --- a/content/rancher/v2.x/en/installation/ha-server-install-external-lb/alb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/alb/_index.md @@ -1,6 +1,8 @@ --- -title: Amazon ALB configuration +title: Amazon ALB Configuration weight: 277 +aliases: +- /rancher/v2.x/en/installation/ha-server-install-external-lb/alb/ --- ## Objectives diff --git a/content/rancher/v2.x/en/installation/ha-server-install-external-lb/nginx/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/nginx/_index.md similarity index 96% rename from content/rancher/v2.x/en/installation/ha-server-install-external-lb/nginx/_index.md rename to content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/nginx/_index.md index dbfba4ffe81..d62c2c2c53f 100644 --- a/content/rancher/v2.x/en/installation/ha-server-install-external-lb/nginx/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/nginx/_index.md @@ -1,6 +1,8 @@ --- -title: NGINX configuration +title: NGINX Configuration weight: 277 +aliases: +- /rancher/v2.x/en/installation/ha-server-install-external-lb/nginx/ --- ## Install NGINX diff --git a/content/rancher/v2.x/en/installation/proxy-configuration/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/proxy/_index.md similarity index 78% rename from content/rancher/v2.x/en/installation/proxy-configuration/_index.md rename to content/rancher/v2.x/en/installation/ha/rke-add-on/proxy/_index.md index fe2182510fa..05cb1f6ef2a 100644 --- a/content/rancher/v2.x/en/installation/proxy-configuration/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/proxy/_index.md @@ -1,6 +1,6 @@ --- title: HTTP Proxy Configuration -weight: 360 +weight: 277 --- If you operate Rancher behind a proxy and you want to access services through the proxy (such as retrieving catalogs), you must provide Rancher information about your proxy. As Rancher is written in Go, it uses the common proxy environment variables as shown below. @@ -14,25 +14,6 @@ NO_PROXY | Network address(es), network address range(s) and do > **Note** NO_PROXY must be in uppercase to use network range (CIDR) notation. -## Single Node Installation - -Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`. Required values for `NO_PROXY` in a [Single Node Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/) are: - -* `localhost` -* `127.0.0.1` -* `0.0.0.0` - -The example below is based on a proxy server accessible at `http://192.168.0.1:3128`, and excluding usage the proxy when accessing network range `192.168.10.0/24` and every hostname under the domain `example.com`. - -``` -docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - -e HTTP_PROXY="http://192.168.10.1:3128" \ - -e HTTPS_PROXY="http://192.168.10.1:3128" \ - -e NO_PROXY="localhost,127.0.0.1,0.0.0.0,192.168.10.0/24,example.com" \ - rancher/rancher:latest -``` - ## High Availability Installation When using High Availability Installation, the environment variables need to be added to the RKE Config File template. diff --git a/content/rancher/v2.x/en/installation/troubleshooting-ha/404-default-backend/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/404-default-backend/_index.md similarity index 96% rename from content/rancher/v2.x/en/installation/troubleshooting-ha/404-default-backend/_index.md rename to content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/404-default-backend/_index.md index 81140055fae..78bbfc446b6 100644 --- a/content/rancher/v2.x/en/installation/troubleshooting-ha/404-default-backend/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/404-default-backend/_index.md @@ -1,6 +1,8 @@ --- title: 404 - default backend weight: 30 +aliases: +- /rancher/v2.x/en/installation/troubleshooting-ha/404-default-backend/ --- To debug issues around this error, you will need to download the command-line tool `kubectl`. See [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) how to download `kubectl` for your platform. diff --git a/content/rancher/v2.x/en/installation/troubleshooting-ha/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/_index.md similarity index 50% rename from content/rancher/v2.x/en/installation/troubleshooting-ha/_index.md rename to content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/_index.md index 00ce37f6927..2ab9ccf7147 100644 --- a/content/rancher/v2.x/en/installation/troubleshooting-ha/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/_index.md @@ -1,24 +1,25 @@ --- -title: Troubleshooting High Availability Installation +title: Troubleshooting HA RKE Add-On Install weight: 370 +aliases: +- /rancher/v2.x/en/installation/troubleshooting-ha/ --- This section contains common errors seen when setting up a High Availability Installation. Choose from the following options: -- [Generic troubleshooting]({{< baseurl >}}/rancher/v2.x/en/installation/troubleshooting-ha/generic-troubleshooting) +- [Generic troubleshooting](generic-troubleshooting/) In this section, you can find generic ways to debug your Kubernetes cluster. -- [Failed to set up SSH tunneling for host]({{< baseurl >}}/rancher/v2.x/en/installation/troubleshooting-ha/ssh-tunneling) +- [Failed to set up SSH tunneling for host](ssh-tunneling/) In this section, you can find errors related to SSH tunneling when you run the `rke` command to setup your nodes. -- [Failed to get job complete status]({{< baseurl >}}/rancher/v2.x/en/installation/troubleshooting-ha/job-complete-status) +- [Failed to get job complete status](job-complete-status/) In this section, you can find errors related to deploying addons. -- [404 - default backend]({{< baseurl >}}/rancher/v2.x/en/installation/troubleshooting-ha/404-default-backend) +- [404 - default backend](404-default-backend/) In this section, you can find errors related to the `404 - default backend` page that is shown when trying to access Rancher. - diff --git a/content/rancher/v2.x/en/installation/troubleshooting-ha/generic-troubleshooting/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/generic-troubleshooting/_index.md similarity index 98% rename from content/rancher/v2.x/en/installation/troubleshooting-ha/generic-troubleshooting/_index.md rename to content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/generic-troubleshooting/_index.md index f68ffb9906a..41ead2d7934 100644 --- a/content/rancher/v2.x/en/installation/troubleshooting-ha/generic-troubleshooting/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/generic-troubleshooting/_index.md @@ -1,6 +1,8 @@ --- title: Generic troubleshooting -weight: 5 +weight: 5 +aliases: +- /rancher/v2.x/en/installation/troubleshooting-ha/generic-troubleshooting/ --- Below are steps that you can follow to determine what is wrong in your cluster. diff --git a/content/rancher/v2.x/en/installation/troubleshooting-ha/job-complete-status/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/job-complete-status/_index.md similarity index 96% rename from content/rancher/v2.x/en/installation/troubleshooting-ha/job-complete-status/_index.md rename to content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/job-complete-status/_index.md index 375a6387346..eaec014af2d 100644 --- a/content/rancher/v2.x/en/installation/troubleshooting-ha/job-complete-status/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/job-complete-status/_index.md @@ -1,6 +1,8 @@ --- title: Failed to get job complete status weight: 20 +aliases: +- /rancher/v2.x/en/installation/troubleshooting-ha/job-complete-status/ --- To debug issues around this error, you will need to download the command-line tool `kubectl`. See [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) how to download `kubectl` for your platform. diff --git a/content/rancher/v2.x/en/installation/troubleshooting-ha/ssh-tunneling/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/ssh-tunneling/_index.md similarity index 97% rename from content/rancher/v2.x/en/installation/troubleshooting-ha/ssh-tunneling/_index.md rename to content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/ssh-tunneling/_index.md index ee6573f52ed..d9e2d477628 100644 --- a/content/rancher/v2.x/en/installation/troubleshooting-ha/ssh-tunneling/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/ssh-tunneling/_index.md @@ -1,6 +1,8 @@ --- title: Failed to set up SSH tunneling for host weight: 10 +aliases: +- /rancher/v2.x/en/installation/troubleshooting-ha/ssh-tunneling/ --- ### Failed to set up SSH tunneling for host [xxx.xxx.xxx.xxx]: Can't retrieve Docker Info diff --git a/content/rancher/v2.x/en/installation/references/_index.md b/content/rancher/v2.x/en/installation/references/_index.md index 840bd550840..3f2e7facc22 100644 --- a/content/rancher/v2.x/en/installation/references/_index.md +++ b/content/rancher/v2.x/en/installation/references/_index.md @@ -1,6 +1,6 @@ --- title: Port Requirements -weight: 355 +weight: 280 aliases: - /rancher/v2.x/en/hosts/amazon/#required-ports-for-rancher-to-work/ --- diff --git a/content/rancher/v2.x/en/installation/removing-rancher/_index.md b/content/rancher/v2.x/en/installation/removing-rancher/_index.md deleted file mode 100644 index 3a9f7d56271..00000000000 --- a/content/rancher/v2.x/en/installation/removing-rancher/_index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Removing Rancher -weight: 375 ---- - -This section contains instructions on how to remove Rancher or nodes added to clusters. - -Choose from the following options: - -- [Cleaning cluster nodes]({{< baseurl >}}/rancher/v2.x/en/installation/removing-rancher/cleaning-cluster-nodes) - - In this section, you can find steps to clean nodes that have been added to clusters created in Rancher. 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 2eae26dfe6d..2dde9a9e39b 100644 --- a/content/rancher/v2.x/en/installation/server-tags/_index.md +++ b/content/rancher/v2.x/en/installation/server-tags/_index.md @@ -1,6 +1,6 @@ --- title: Server Tags -weight: 200 +weight: 230 --- {{< product >}} Server is distributed as a Docker image, which have _tags_ attached to them. Tags are used to identify what version is included in the image. Rancher includes additional tags that point to a specific version. Remember that if you use the additional tags, you must explicitly pull a new version of that image tag. Otherwise it will use the cached image on the host. diff --git a/content/rancher/v2.x/en/installation/single-node-install/_index.md b/content/rancher/v2.x/en/installation/single-node/_index.md similarity index 71% rename from content/rancher/v2.x/en/installation/single-node-install/_index.md rename to content/rancher/v2.x/en/installation/single-node/_index.md index 6e16cafbc2f..dbad2d3808e 100644 --- a/content/rancher/v2.x/en/installation/single-node-install/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/_index.md @@ -1,14 +1,14 @@ --- -title: Single Node Installation +title: Single Node Install weight: 250 +aliases: + - /rancher/v2.x/en/installation/single-node-install/ + - /rancher/v2.x/en/installation/custom-ca-root-certificate/ --- For development environments, we recommend installing Rancher by running a single Docker container. In this installation scenario, you'll install Docker on a single Linux host, and then install Rancher on your host using a single Docker container. - >**Want to use an external load balancer?** -> See [Single Node Installation with an External Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install-external-lb) instead. - - +> See [Single Node Install with an External Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/single-node-install-external-lb) instead. ## Installation Outline @@ -28,15 +28,15 @@ Provision a single Linux host to launch your {{< product >}} Server. ### Requirements -#### Operating System +#### Operating System {{< requirements_os >}} -#### Hardware +#### Hardware {{< requirements_hardware >}} -#### Software +#### Software {{< requirements_software >}} @@ -53,7 +53,7 @@ The following diagram depicts the basic port requirements for Rancher. For a com For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. >**Attention Air Gap Users:** -> If you are visiting this page to complete [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Replace `` with your private registry URL. +> If you are visiting this page to complete an [Air Gap]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/) Installation, you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `` with your private registry URL in front of `rancher/rancher:latest`. > > Example: ``` @@ -65,7 +65,8 @@ Choose from the following options: - [Option A—Default Self-Signed Certificate](#option-a-default-self-signed-certificate) - [Option B—Bring Your Own Certificate: Self-Signed](#option-b-bring-your-own-certificate-self-signed) - [Option C—Bring Your Own Certificate: Signed by Recognized CA](#option-c-bring-your-own-certificate-signed-by-recognized-ca) -- [Option D—Let's Encrypt Certificate](#option-d-let-s-encrypt-certificate) +- [Option D—Bring Your Own Certificate: Private CA Root Certificate CA](#option-d-bring-your-own-certificate-private-ca-root-certificate) +- [Option E—Let's Encrypt Certificate](#option-e-let-s-encrypt-certificate) ### Option A—Default Self-Signed Certificate @@ -81,8 +82,6 @@ If you install Rancher without using your own certificate, Rancher generates a s rancher/rancher:latest ``` - - ### Option B—Bring Your Own Certificate: Self-Signed Your Rancher install can use a self-signed certificate that you provide to encrypt communications. @@ -93,7 +92,6 @@ Your Rancher install can use a self-signed certificate that you provide to encry >- The certificate files must be in [PEM format](#pem). >- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [SSL FAQ / Troubleshooting](#cert-order). - **To Install Rancher Using a Self-Signed Cert:** Your Rancher install can use a self-signed certificate that you provide to encrypt communications. @@ -109,7 +107,6 @@ Your Rancher install can use a self-signed certificate that you provide to encry rancher/rancher:latest ``` - ### Option C—Bring Your Own Certificate: Signed by Recognized CA If you're publishing your app publicly, you should ideally be using a certificate signed by a recognized CA. @@ -132,7 +129,38 @@ If you're publishing your app publicly, you should ideally be using a certificat rancher/rancher:latest --no-cacerts ``` -### Option D—Let's Encrypt Certificate +### Option D—Bring Your Own Certificate: Private CA Root Certificate + +Services that Rancher needs to access are sometimes configured with a certificate from an custom/internal Certificate Authority (CA) root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error will appear: `x509: certificate signed by unknown authority`. + +To validate the certificate, the CA root certificates need to be added to Rancher. As Rancher is written in Go, we can use the environment variable `SSL_CERT_DIR` to point to the directory where the CA root certificates are located in the container. The CA root certificates directory can be mounted using the Docker volume option (`-v host-source-directory:container-destination-directory`) when starting the Rancher container. + +Examples of services that Rancher can access: + +* Catalogs +* Authentication providers +* Accessing hosting/cloud API when using Node Drivers + +#### Start Rancher Container with custom CA root certificates + +The requirements are: + +* Mount the host directory containing the CA root certificates in the container using the volume option. +* Add the environment variable `SSL_CERT_DIR` with as value the mounted CA root certificates directory location inside the container. + +Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`, mounting a host directory inside the container can be done using `-v host-source-directory:container-destination-directory` or `--volume host-source-directory:container-destination-directory`. + +The example below is based on having the CA root certificates in the `/host/certs` directory on the host and mounting this directory on `/container/certs` inside the Rancher container. + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /host/certs:/container/certs \ + -e SSL_CERT_DIR="/container/certs" \ + rancher/rancher:latest +``` + +### Option E—Let's Encrypt Certificate Rancher supports Let's Encrypt certificates. Let's Encrypt uses an `http-01 challenge` to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, `rancher.mydomain.com`) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS. @@ -156,7 +184,6 @@ Run the following commands from your Linux host. --acme-domain rancher.mydomain.com ``` - > >**Remember:** Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/). @@ -181,7 +208,7 @@ You have a couple of options: In the situation where you want to use a single node to run Rancher and to be able to add the same node to a cluster, you have to adjust the host ports mapped for the `rancher/rancher` container. -If a node is added to a cluster, it deploys the nginx ingress controller which will use port 80 and 443. This will conflict with the default ports we advice to expose for the `rancher/rancher` container. +If a node is added to a cluster, it deploys the nginx ingress controller which will use port 80 and 443. This will conflict with the default ports we advice to expose for the `rancher/rancher` container. Please note that this setup is not recommended for production use, but can be convenient for development/demo purposes. @@ -192,4 +219,3 @@ docker run -d --restart=unless-stopped \ -p 8080:80 -p 8443:443 \ rancher/rancher:latest ``` - diff --git a/content/rancher/v2.x/en/installation/single-node/proxy/_index.md b/content/rancher/v2.x/en/installation/single-node/proxy/_index.md new file mode 100644 index 00000000000..9a82c8bbdc2 --- /dev/null +++ b/content/rancher/v2.x/en/installation/single-node/proxy/_index.md @@ -0,0 +1,36 @@ +--- +title: HTTP Proxy Configuration +weight: 251 +aliases: +- /rancher/v2.x/en/installation/proxy-configuration/ +--- +If you operate Rancher behind a proxy and you want to access services through the proxy (such as retrieving catalogs), you must provide Rancher information about your proxy. As Rancher is written in Go, it uses the common proxy environment variables as shown below. + +Make sure `NO_PROXY` contains the network addresses, network address ranges and domains that should be excluded from using the proxy. + +Environment variable | Purpose +--------------------------|--------- +HTTP_PROXY | Proxy address to use when initiating HTTP connection(s) +HTTPS_PROXY | Proxy address to use when initiating HTTPS connection(s) +NO_PROXY | Network address(es), network address range(s) and domains to exclude from using the proxy when initiating connection(s) + +> **Note** NO_PROXY must be in uppercase to use network range (CIDR) notation. + +## Single Node Installation + +Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`. Required values for `NO_PROXY` in a [Single Node Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/) are: + +* `localhost` +* `127.0.0.1` +* `0.0.0.0` + +The example below is based on a proxy server accessible at `http://192.168.0.1:3128`, and excluding usage the proxy when accessing network range `192.168.10.0/24` and every hostname under the domain `example.com`. + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e HTTP_PROXY="http://192.168.10.1:3128" \ + -e HTTPS_PROXY="http://192.168.10.1:3128" \ + -e NO_PROXY="localhost,127.0.0.1,0.0.0.0,192.168.10.0/24,example.com" \ + rancher/rancher:latest +``` diff --git a/content/rancher/v2.x/en/installation/single-node-install-external-lb/_index.md b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md similarity index 94% rename from content/rancher/v2.x/en/installation/single-node-install-external-lb/_index.md rename to content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md index 24e05fcf619..0340095d70b 100644 --- a/content/rancher/v2.x/en/installation/single-node-install-external-lb/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md @@ -1,12 +1,14 @@ --- -title: Single Node Installation with External Load Balancer -weight: 260 +title: Single Node Install with External Load Balancer +weight: 252 +aliases: +- /rancher/v2.x/en/installation/single-node-install-external-lb/ --- For development environments, we recommend installing Rancher by running a single Docker container. In this installation scenario, you'll deploy Rancher to a Linux host using a single Docker container. Then you will configure an external load balancer to work with Rancher. >**Want to skip the external load balancer?** -> See [Single Node Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install) instead. +> See [Single Node Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node) instead. @@ -58,7 +60,7 @@ The following diagram depicts the basic port requirements for Rancher. For a com For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. >**Attention Air Gap Users:** -> If you are visiting this page to complete [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must prepend your private registry URL to the server tag when running the installation command in the option that you choose. Replace `` with your private registry URL. +> If you are visiting this page to complete [Air Gap Installation](../air-gap-installation/), you must prepend your private registry URL to the server tag when running the installation command in the option that you choose. Replace `` with your private registry URL. > > Example: ``` @@ -132,7 +134,7 @@ The load balancer or proxy has to be configured to support the following: This Nginx configuration is tested on Nginx version 1.13 (mainline) and 1.14 (stable). >**Note:** This Nginx configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - TCP and UDP Load Balancer](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/). - + ``` upstream rancher { server rancher-server:80; diff --git a/content/rancher/v2.x/en/k8s-in-rancher/editing-clusters/_index.md b/content/rancher/v2.x/en/k8s-in-rancher/editing-clusters/_index.md index 309e665b75c..dc91999fd9b 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/editing-clusters/_index.md +++ b/content/rancher/v2.x/en/k8s-in-rancher/editing-clusters/_index.md @@ -3,9 +3,24 @@ title: Editing Clusters weight: 3015 --- -## Editing the Cluster Membership +After you provision a Kubernetes cluster using Rancher, you can still edit options and settings for the cluster. To edit your cluster, open the **Global** view, make sure the **Clusters** tab is selected, and then select **Ellipsis (...) > Edit** for the cluster that you want to edit. -Following cluster creation, you can add users as cluster members so that they can access its resources. +To Edit an Existing Cluster +![Edit Cluster]({{< baseurl >}}/img/rancher/edit-cluster.png) + +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. + +The following table lists 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) | ✓ | | | + +## Editing Cluster Membership + +Cluster administrators can edit the membership for a cluster, controlling which Rancher users can access the cluster and what features they can use. >**Ping and MS FS Caveats:** > @@ -47,33 +62,99 @@ Following cluster creation, you can add users as cluster members so that they ca ## Cluster Options ->**Note:** These cluster options are only available for [clusters that Rancher has launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). +When editing clusters, clusters that are [launched using RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) feature more options than clusters that are imported or hosted by a Kubernetes provider. The headings that follow document options available only for RKE clusters. -### Adding/Changing a Pod Security Policy +### Upgrading Kubernetes -If you don't apply a PSP as you create your cluster, you can always add one later. +Following an upgrade to the latest version of Rancher, you can update your existing clusters to use the latest supported version of Kubernetes. Before a new version of Rancher is released, it's tested with the latest versions of Kubernetes to ensure compatibility. ->**Prerequisite:** ->Create a Pod Security Policy within Rancher. Before you can assign a default PSP to an existing cluster, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/). +>**Recommended:** Before upgrading Kubernetes, [backup your cluster]({{< baseurl >}}/rancher/v2.x/en/backups). -1. From the **Global** view, find the cluster that you want to apply your PSP to. Select **Vertical Ellipsis (...) > Edit** for the cluster you want to enable PSPs for. +1. From the **Global** view, find the cluster for which you want to upgrade Kubernetes. Select **Vertical Ellipsis (...) > Edit**. -2. Expand the **Cluster Options** accordion. +1. Expand **Cluster Options**. + +1. From the **Kubernetes Version** drop-down, choose the version of Kubernetes that you want to use for the cluster. + +1. Click **Save**. + +**Result:** Kubernetes begins upgrading for the cluster. During the upgrade, your cluster is unavailable. + +### Adding a Pod Security Policy + +When your cluster is running pods with security-sensitive configurations, assign it a [pod security policy]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/), which is a set of rules that monitors the conditions and settings in your pods. If a pod doesn't meet the rules specified in your policy, the policy stops it from running. + +You can assign a pod security policy when you provision a cluster. However, if you need to relax or restrict security for your pods later, you can update the policy while editing your cluster. + +1. From the **Global** view, find the cluster to which you want to apply a pod security policy. Select **Vertical Ellipsis (...) > Edit**. + +2. Expand **Cluster Options**. 3. From **Pod Security Policy Support**, select **Enabled**. - >**Note:** Not all cluster providers support PSPs, so this option may not be available. + >**Note:** This option is only available for clusters [provisioned by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). - **Step Result:** The **Default Pod Security Policy** drop-down activates. +4. From the **Default Pod Security Policy** drop-down, select the policy you want to apply to the cluster. -4. From **Default Pod Security Policy**, select the PSP you want to apply to the cluster. + Rancher ships with [policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/#default-pod-security-policies) of `restricted` and `unrestricted`, although you can [create custom policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/#default-pod-security-policies) as well. 5. Click **Save**. -**Result:** The PSP is applied to the cluster and any projects within the cluster. +**Result:** The pod security policy is applied to the cluster and any projects within the cluster. ->**Note:** Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked if it complies with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP. +>**Note:** Workloads already running before assignment of a pod security policy are grandfathered in. Even if they don't meet your pod security policy, workloads running before assignment of the policy continue to run. +> +>To check if a running workload passes your pod security policy, clone or upgrade it. -### Node pools +### Editing Other Cluster Options + +In [clusters launched by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), you can edit any of the remaining options that follow. + +>**Note:** These options are not available for imported clusters or hosted Kubernetes clusters. + +Options for RKE Clusters +![Cluster Options]({{< baseurl >}}/img/rancher/cluster-options.png) + + +Option | Description | +---------|----------| + Kubernetes Version | The version of Kubernetes installed on each cluster node. For more detail, see [Upgrading Kubernetes](#upgrading-kubernetes). | + Network Provider | The [container networking interface]({{< baseurl >}}/rancher/v2.x/en/faq/networking/cni-providers/) that powers networking for your cluster.

**Note:** You can only choose this option while provisioning your cluster. It cannot be edited later. | + Project Network Isolation | As of Rancher v2.0.7, if you're using the Canal network provider, you can choose whether to enable or disable inter-project communication. | + Nginx Ingress | If you want to publish your applications in a high-availability configuration, and you're hosting your nodes with a cloud-provider that doesn't have a native load-balancing feature, enable this option to use Nginx ingress within the cluster. | + Metrics Server Monitoring | Each cloud provider capable of launching a cluster using RKE can collect metrics and monitor for your cluster nodes. Enable this option to view your node metrics from your cloud provider's portal. | + Pod Security Policy Support | Enables [pod security policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/) for the cluster. After enabling this option, choose a policy using the **Default Pod Security Policy** drop-down. | + Docker version on nodes | Configures whether nodes are allowed to run versions of Docker that Rancher doesn't officially support. If you choose to require a [supported Docker version]({{< baseurl >}}/rancher/v2.x/en/installation/ha-server-install-external-lb/#software), Rancher will stop pods from running on nodes that don't have a supported Docker version installed. | + Docker Root Directory | The directory on your cluster nodes where you've installed Docker. If you install Docker on your nodes to a non-default directory, update this path. | + Default Pod Security Policy | If you enable **Pod Security Policy Support**, use this drop-down to choose the pod security policy that's applied to the cluster. | + Cloud Provider | If you're using a cloud provider to host cluster nodes launched by RKE, enable [this option]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) so that you can use the cloud provider's native features. If you want to store persistent data for your cloud-hosted cluster, this option is required. | +
+#### Editing Cluster as YAML + +>**Note:** In Rancher v2.0.5 and v2.0.6, the names of services in the Config File (YAML) should contain underscores only: `kube_api` and `kube_controller`. + +Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the [options available]({{< baseurl >}}/rke/v0.1.x/en/config-options/) in an RKE installation. + +- To edit an RKE config file directly from the Rancher UI, click **Edit as YAML**. +- To read from an existing RKE file, click **Read from File**. + +![image]({{< baseurl >}}/img/rancher/cluster-options-yaml.png) + +For an example of RKE config file syntax, see the [RKE documentation]({{< baseurl >}}/rke/v0.1.x/en/example-yamls/). + +## Managing Node Pools + +In clusters [launched by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), you can: + +- Add new [pools of nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to your cluster. The nodes added to the pool are provisioned according to the [node template]({{< baseurl >}}/rancher/v2.x/en/user-settings/node-templates/) that you use. + + - Click **+** and follow the directions on screen to create a new template. + + - You can also reuse existing templates by selecting one from the **Template** drop-down. + +- Redistribute Kubernetes roles amongst your node pools by making different checkbox selections + +- Scale the number of nodes in a pool up or down (although, if you simply want to maintain your node scale, we recommend using the cluster's [Nodes tab]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/nodes/#nodes-provisioned-by-node-pool) instead.) + +>**Note:** The Node Pools section is not available for imported clusters or clusters hosted by a Kubernetes provider. -Changing the nodes in a RKE cluster diff --git a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/_index.md b/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/_index.md index 9e4a90d8fa1..bbce60fb424 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/_index.md +++ b/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/_index.md @@ -11,72 +11,39 @@ There are two ways to create persistent storage in Kubernetes: Persistent Volume ## Persistent Volumes -_Persistent Volumes_ are pre-provisioned storage volumes that you can bind to pods later. For example, in Amazon EC2, you might want to create a number of Elastic Block Store (EBS) volumes before you start running your application. Each pre-provisioned EBS volume corresponds to a Kubernetes persistent volume. When the application starts, it creates Persistent Volume Claims (PVCs) that bind to persistent volumes. A PVC corresponds to a Docker volume. Each PVC binds to one PV that includes the minimum resources that the PVC requires. The following figure illustrates the relationship between pods, PVCs, PVs, and the underlying cloud storage. +_Persistent Volumes_ are pre-provisioned storage volumes that you can bind to pods later. Each pre-provisioned volume corresponds to a Kubernetes persistent volume. When you start your application, it creates Persistent Volume Claims (PVCs) that bind to persistent volumes. A PVC corresponds to a Docker volume. Each PVC binds to one PV that includes the minimum resources that the PVC requires. The following figure illustrates the relationship between pods, PVCs, PVs, and the underlying cloud storage. ![Persistent Volumes]({{< baseurl >}}/img/rancher/persistent-volume.png) Rancher allows you to create PVs at the cluster level and bind them to PVCs later. Volumes are managed on a per-project basis. -### Adding a Persistent Volume - -Your containers can store data on themselves, but if a container fails, that data is lost. To solve this issue, Kubernetes offers _persistent volumes_, which are external storage disks or file systems that your containers can access. If a container crashes, its replacement container can access the data in a persistent volume without any data loss. - -Persistent volumes can either be a disk or file system that you host on premise, or they can be hosted by a vendor, such as Amazon EBS or Azure Disk. - ->**Prerequisites:** -> ->- Working with storage requires the `Manage Volumes` [role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference). ->- You must have a storage medium provisioned. For more information, see [Provisioning Storage]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/). ->- Create a storage volume either on premise or in the cloud, using one of the vendor services listed in [Types of Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes). ->- Gather metadata about your storage volume after you create it. You'll need to enter this information into Rancher. - -1. From the **Global** view, open the cluster running the containers that you want to add persistent volume storage to. - -1. From the main menu, select **Storage > Persistent Volumes**. - -1. Click **Add Volume**. - -1. Enter a **Name** for the persistent volume. - -1. Select the **Volume Plugin** for the disk type or service that you're using. - - >**Note:** If the cluster you are adding storage for is a cloud service that also offers cloud storage, you must enable the `cloud provider` option for the cluster, and you must use the service's plug-in to use cloud storage. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it: - > - > - You must enable the `cloud provider` option for the EC2 cluster. - > - You must use the `Amazon EBS Disk` volume plugin. - -1. Enter the **Capacity** of your volume in gigabytes. - -1. Complete the **Plugin Configuration** form. Each plugin type requires information specific to the vendor of disk type. For help regarding each plugin's form and the information that's required, refer to the plug-in's vendor documentation. - -1. **Optional:** Complete the **Customize** form. This form features: - - - [Access Modes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes): - - This options sets how many nodes can access the volume, along with the node read/write permissions. The [Kubernetes Documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) includes a table that lists which access modes are supported by the plugins available. - - - [Mount Options](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#mount-options): - - Each volume plugin allows you to specify additional command line options during the mounting process. You can enter these options in the **Mount Option** fields. Consult each plugin's vendor documentation for the mount options available. - - - **Assign to Storage Class:** - - If you later want to automatically provision persistent volumes identical to the volume that you've specified here, assign it a storage class. Later, when you create a workload, you can assign it a persistent volume claim that references the storage class, which will provision a persistent volume identical to the volume you've specified here. - - >**Note:** You must [add a storage class](#adding-storage-classes) before you can assign it to a persistent volume. - -1. Click **Save**. - -**Result:** Your new persistent volume is created. - ## Storage Classes Storage Classes allow you to create PVCs dynamically without having to create PVs first. For example, an Amazon EBS Storage Class will dynamically create EBS volumes and bind them to PVCs. A Storage Class is similar to the notion of a _storage driver_. The following figure illustrates how a PVC creation triggers the dynamic provisioning of an underlying EBS volume. ![Storage Classes]({{< baseurl >}}/img/rancher/storage-classes.png) + ### Storage and Cloud Providers +When you provision persistent storage for a cluster [launched by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters), you must host your storage with the same provider that hosts the cluster. For example, if you're hosting your cluster on Amazon EC2, you must host your storage on Amazon EBS. To setup storage for your RKE-launched cluster, you must complete two tasks: enabling the **Cloud Provider** option for your cluster, and adding storage using the same provider. + +Enabling Cloud Provider Option/Choosing Storage Provider +![Cloud Provider]({{< baseurl >}}/img/rancher/cloud-provider.png) + +Before you set up storage for a cluster launched by RKE, make sure that the **Cloud Provider** option for the cluster is enabled. [Cloud providers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) are modules that allow you to use the provider's features in Rancher (like provisioning persistent storage). + +You can turn on the **Cloud Provider** option in one of two contexts: + +- [When provisioning your cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning) +- [When editing your cluster]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/editing-clusters) + +When you begin setting up a [persistent volume](#adding-persistent-volumes) or [storage class](#adding-storage-classes), you can choose the storage plugin or provisioner for your cloud provider. + +#### Storage Classes and Cloud Providers + +Additionally, storage classes feature a few extra settings for cloud providers. + Each storage class contains the fields `provisioner`, `parameters`, and `reclaimPolicy`, which are used when a persistent volume that belongs to the class needs to be dynamically provisioned. The `provisioner` determines which volume plugin is used to provision the persistent volumes. @@ -107,10 +74,78 @@ Finally, you can define custom `MountOptions` for the persistent volume created. `parameters` are specific to each cloud storage provisioner. For full information about the storage classes provisioner parameters, refer to the official [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/storage-classes/#parameters). +### Adding Persistent Volumes + +Your containers can store data on themselves, but if a container fails, that data is lost. To solve this issue, Kubernetes offers _persistent volumes_, which are external storage disks or file systems that your containers can access. If a container crashes, its replacement container can access the data in a persistent volume without any data loss. + +Persistent volumes can either be a disk or file system that you host on premise, or they can be hosted by a vendor, such as Amazon EBS or Azure Disk. + +>**Prerequisites:** +> +>- Permissions: `Manage Volumes` [role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference) +>- You must have [storage provisioned]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/). +>- If provisioning storage for a cluster hosted in the cloud: +> +> - The storage and cluster hosts must be the [same provider](#storage-and-cloud-providers). +> - The [cloud providers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) option must be enabled. + + +1. From the **Global** view, open the cluster running the containers that you want to add persistent volume storage to. + +1. From the main menu, select **Storage > Persistent Volumes**. + +1. Click **Add Volume**. + +1. Enter a **Name** for the persistent volume. + +1. Select the **Volume Plugin** for the disk type or service that you're using. + + >**Note:** When adding storage to a cluster that's hosted by a cloud provider: + > + >- You must enable the [cloud provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) option for the cluster. + >- You must use the cloud provider's plug-in for cloud storage. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it: + > + > - You must enable the `cloud provider` option for the EC2 cluster. + > - You must use the `Amazon EBS Disk` volume plugin. + +1. Enter the **Capacity** of your volume in gigabytes. + +1. Complete the **Plugin Configuration** form. Each plugin type requires information specific to the vendor of disk type. For help regarding each plugin's form and the information that's required, refer to the plug-in's vendor documentation. + +1. **Optional:** Complete the **Customize** form. This form features: + + - [Access Modes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes): + + This options sets how many nodes can access the volume, along with the node read/write permissions. The [Kubernetes Documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) includes a table that lists which access modes are supported by the plugins available. + + - [Mount Options](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#mount-options): + + Each volume plugin allows you to specify additional command line options during the mounting process. You can enter these options in the **Mount Option** fields. Consult each plugin's vendor documentation for the mount options available. + + - **Assign to Storage Class:** + + If you later want to automatically provision persistent volumes identical to the volume that you've specified here, assign it a storage class. Later, when you create a workload, you can assign it a persistent volume claim that references the storage class, which will provision a persistent volume identical to the volume you've specified here. + + >**Note:** You must [add a storage class](#adding-storage-classes) before you can assign it to a persistent volume. + +1. Click **Save**. + +**Result:** Your new persistent volume is created. + + ### Adding Storage Classes _Storage Classes_ allow you to dynamically provision persistent volumes on demand. Think of storage classes as storage profiles that are created automatically upon a request (which is known as a _persistent volume claim_). +>**Prerequisites:** +> +>- Permissions: `Manage Volumes` [role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference) +>- You must have [storage provisioned]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/). +>- If provisioning storage for a cluster hosted in the cloud: +> +> - The storage and cluster hosts must be the [same provider](#storage-and-cloud-providers). +> - The [cloud providers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) option must be enabled. + 1. From the **Global** view, open the cluster for which you want to dynamically provision persistent storage volumes. 1. From the main menu, select `Storage > Storage Classes`. Click `Add Class`. diff --git a/content/rancher/v2.x/en/upgrades/rollbacks/_index.md b/content/rancher/v2.x/en/upgrades/rollbacks/_index.md new file mode 100644 index 00000000000..53b3f8920f9 --- /dev/null +++ b/content/rancher/v2.x/en/upgrades/rollbacks/_index.md @@ -0,0 +1,8 @@ +--- +title: Rollbacks +weight: 1010 +--- +This section contains information about how to rollback your Rancher server to a previous version. + +- [Rolling back a Single Node Install]({{< baseurl >}}/rancher/v2.x/en/upgrades/rollbacks/single-node-rollbacks/) +- [Rolling back a High Availability Install]({{< baseurl >}}/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/) diff --git a/content/rancher/v2.x/en/upgrades/ha-server-rollbacks/_index.md b/content/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/_index.md similarity index 94% rename from content/rancher/v2.x/en/upgrades/ha-server-rollbacks/_index.md rename to content/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/_index.md index 71a3d78fde6..02745f1d2fc 100644 --- a/content/rancher/v2.x/en/upgrades/ha-server-rollbacks/_index.md +++ b/content/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/_index.md @@ -1,8 +1,9 @@ --- -title: High Availability Rollback +title: High Availability (HA) Rollback weight: 1025 aliases: - - /rancher/v2.x/en/backups/rollbacks/ha-server-rollbacks + - /rancher/v2.x/en/backups/rollbacks/ha-server-rollbacks/ + - /rancher/v2.x/en/upgrades/ha-server-rollbacks --- If you upgrade Rancher, but the upgrade does not complete successfully, you may need to roll back your Rancher Server to its last healthy state before upgrade. To restore Rancher: @@ -75,4 +76,4 @@ docker container inspect rke-bundle-cert The important thing to note is the mounts of the container and location of the **pki.bundle.tar.gz**. As of **RKE v0.1.9**, the **rke-bundle-cert** container is removed on both success and -failure of a restore. To debug any issues, you will need to look at the **logs** generated from rke. +failure of a restore. To debug any issues, you will need to look at the **logs** generated from rke. diff --git a/content/rancher/v2.x/en/upgrades/single-node-rollbacks/_index.md b/content/rancher/v2.x/en/upgrades/rollbacks/single-node-rollbacks/_index.md similarity index 96% rename from content/rancher/v2.x/en/upgrades/single-node-rollbacks/_index.md rename to content/rancher/v2.x/en/upgrades/rollbacks/single-node-rollbacks/_index.md index 19526036620..a7f6e85e8ab 100644 --- a/content/rancher/v2.x/en/upgrades/single-node-rollbacks/_index.md +++ b/content/rancher/v2.x/en/upgrades/rollbacks/single-node-rollbacks/_index.md @@ -3,6 +3,7 @@ title: Single Node Rollback weight: 1015 aliases: - /rancher/v2.x/en/backups/rollbacks/single-node-rollbacks + - /rancher/v2.x/en/upgrades/single-node-rollbacks --- Rolling back an unsuccessful Rancher upgrade requires you to diff --git a/content/rancher/v2.x/en/upgrades/upgrades/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/_index.md new file mode 100644 index 00000000000..fd0d80c242b --- /dev/null +++ b/content/rancher/v2.x/en/upgrades/upgrades/_index.md @@ -0,0 +1,10 @@ +--- +title: Upgrades +weight: 1005 +--- +This section contains information about how to upgrade your Rancher server to a newer version. + +- [Upgrading a Single Node Install]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/) +- [Upgrading an Air Gapped Single Node Install]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/single-node-air-gap-upgrade/) +- [Upgrading a High Availability Install]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/) +- [Migrating from a High Availability RKE Add-on Install]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on/) diff --git a/content/rancher/v2.x/en/upgrades/ha-server-upgrade/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md similarity index 95% rename from content/rancher/v2.x/en/upgrades/ha-server-upgrade/_index.md rename to content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md index 0eeb03fd682..0e699a7a9df 100644 --- a/content/rancher/v2.x/en/upgrades/ha-server-upgrade/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md @@ -1,6 +1,8 @@ --- -title: High Availability Upgrade +title: High Availability (HA) Upgrade weight: 1020 +aliases: + - /rancher/v2.x/en/upgrades/ha-server-upgrade/ --- To upgrade Rancher 2.x running in a high availability configuration, run an upgrade command that points to your upgrade config file. diff --git a/content/rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on/_index.md new file mode 100644 index 00000000000..0041f925b23 --- /dev/null +++ b/content/rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on/_index.md @@ -0,0 +1,56 @@ +--- +title: Migrating from a HA RKE Add-on Install +weight: 1030 +--- + +The following instructions will help guide you through migrating from the RKE Add-on install to managing Rancher with the Helm package manager. + +You will need the to have [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) installed and `kube_config_rancher-cluster.yml` credentials file generated by RKE. + +> **Note:** This guide assumes a standard Rancher install. If you have modified any of the object names or namespaces, please adjust accordingly. + +### Point kubectl at your Rancher Cluster + +Make sure `kubectl` is using the correct cluster. Export the `KUBECONFIG` environmental variable pointing at the `kube_config_rancher-cluster.yml` + +``` +export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml +``` + +### Save your certificates + +If you have terminated ssl on the Rancher cluster ingress, recover your certificate and key for use in the Helm install. + +Use `kubectl` to get the secret, decode the value and direct the output to a file. + +``` +kubectl -n cattle-system get secret cattle-keys-ingress -o jsonpath --template='{ .data.tls\.crt }' | base64 -d > tls.crt +kubectl -n cattle-system get secret cattle-keys-ingress -o jsonpath --template='{ .data.tls\.key }' | base64 -d > tls.key +``` + +If you specified a private CA root cert + +``` +kubectl -n cattle-system get secret cattle-keys-server -o jsonpath --template='{ .data.cacerts\.pem }' | base64 -d > cacerts.pem +``` + +### Remove previous Kubernetes objects + +Remove the kubernetes objects created by the RKE install. + +> **Note:** Removing these Kubernetes components will not affect the Rancher configuration or database, but with any maintenance it is a good idea to create a backup of the data before hand. See [Creating Backups-HA Install]({{< baseurl >}}/rancher/v2.x/en/backups/backups/ha-backups) for details. + +``` +kubectl -n cattle-system delete ingress cattle-ingress-http +kubectl -n cattle-system delete service cattle-service +kubectl -n cattle-system delete deployment cattle +kubectl -n cattle-system delete clusterrolebinding cattle-crb +kubectl -n cattle-system delete serviceaccount cattle-admin +``` + +### Follow Helm and Rancher install steps + +From here follow the standard install steps. + +* [3 - Initialize Helm (Install tiller)]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-init/) +* [4 - Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/) diff --git a/content/rancher/v2.x/en/upgrades/air-gap-upgrade/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/single-node-air-gap-upgrade/_index.md similarity index 88% rename from content/rancher/v2.x/en/upgrades/air-gap-upgrade/_index.md rename to content/rancher/v2.x/en/upgrades/upgrades/single-node-air-gap-upgrade/_index.md index 097a644b2bb..62684f0a054 100644 --- a/content/rancher/v2.x/en/upgrades/air-gap-upgrade/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/single-node-air-gap-upgrade/_index.md @@ -1,6 +1,8 @@ --- -title: Air Gap Upgrade -weight: 1500 +title: Single Node Air Gap Upgrade +weight: 1011 +aliases: + - /rancher/v2.x/en/upgrades/air-gap-upgrade/ --- To upgrade an air gapped Rancher Server, update your private registry with the latest Docker images, and then run the upgrade command. diff --git a/content/rancher/v2.x/en/upgrades/single-node-upgrade/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md similarity index 98% rename from content/rancher/v2.x/en/upgrades/single-node-upgrade/_index.md rename to content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md index f2e7dafd952..6247147afa8 100644 --- a/content/rancher/v2.x/en/upgrades/single-node-upgrade/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md @@ -1,6 +1,8 @@ --- title: Single Node Upgrade weight: 1010 +aliases: + - /rancher/v2.x/en/upgrades/single-node-upgrade/ --- To upgrade Rancher Server 2.x after a new version is released, create a backup of your server and then run the upgrade command. diff --git a/layouts/shortcodes/note_server-tags.html b/layouts/shortcodes/note_server-tags.html index 82aa0aaabcf..6a03c80a3ca 100644 --- a/layouts/shortcodes/note_server-tags.html +++ b/layouts/shortcodes/note_server-tags.html @@ -1,7 +1,7 @@

Note:

-

The rancher/rancher container is hosted on DockerHub. If you don't have access to DockerHub, or you are installing Rancher without an Internet connection, refer to Air Gap Installation.

+

The rancher/rancher container is hosted on DockerHub. If you don't have access to DockerHub, or you are installing Rancher without an Internet connection, refer to how to prepare for an Air Gap Installation.

Note:

For a list of other Rancher Server tags available, refer to Rancher Server Tags.

diff --git a/layouts/shortcodes/requirements_ports_rancher_rke.html b/layouts/shortcodes/requirements_ports_rancher_rke.html new file mode 100644 index 00000000000..41401055ff8 --- /dev/null +++ b/layouts/shortcodes/requirements_ports_rancher_rke.html @@ -0,0 +1,57 @@ +
+
Cluster External Ports
+

These ports should be open between nodes and the external network for communication and management of Rancher.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProtocolPortDescription
TCP22SSH for RKE
TCP80Ingress controller - redirect to HTTPS
TCP443Ingress controller - HTTPS traffic to Rancher
TCP6443HTTPS to kube-api, used by kubectl and helm
+

+
Additional Ports Required Between Rancher Cluster Nodes
+

In addition to the ports listed above these ports must be open between nodes.

+ + + + + + + + + + + + + + + + + + + + + +
ProtocolPortDescription
TCP2379-2380etcd
udp8472Overlay networking
TCP10250kubelet
+
diff --git a/src/img/rancher/add-persistent-volume.png b/src/img/rancher/add-persistent-volume.png new file mode 100644 index 00000000000..9c47699b292 Binary files /dev/null and b/src/img/rancher/add-persistent-volume.png differ diff --git a/src/img/rancher/calico-diagram.svg b/src/img/rancher/calico-diagram.svg new file mode 100644 index 00000000000..a8a95ec7b50 --- /dev/null +++ b/src/img/rancher/calico-diagram.svg @@ -0,0 +1 @@ +arch-oss-value-prop5-sm \ No newline at end of file diff --git a/src/img/rancher/calico-logo.png b/src/img/rancher/calico-logo.png new file mode 100644 index 00000000000..1babef8df8d Binary files /dev/null and b/src/img/rancher/calico-logo.png differ diff --git a/src/img/rancher/canal-diagram.png b/src/img/rancher/canal-diagram.png new file mode 100644 index 00000000000..51252382eb3 Binary files /dev/null and b/src/img/rancher/canal-diagram.png differ diff --git a/src/img/rancher/canal-logo.png b/src/img/rancher/canal-logo.png new file mode 100644 index 00000000000..22b02f3f8bb Binary files /dev/null and b/src/img/rancher/canal-logo.png differ diff --git a/src/img/rancher/cloud-provider.png b/src/img/rancher/cloud-provider.png new file mode 100644 index 00000000000..fc45d3c3693 Binary files /dev/null and b/src/img/rancher/cloud-provider.png differ diff --git a/src/img/rancher/cluster-options.png b/src/img/rancher/cluster-options.png new file mode 100644 index 00000000000..9a79f5ae97b Binary files /dev/null and b/src/img/rancher/cluster-options.png differ diff --git a/src/img/rancher/cni-logo.png b/src/img/rancher/cni-logo.png new file mode 100644 index 00000000000..50c54d2f524 Binary files /dev/null and b/src/img/rancher/cni-logo.png differ diff --git a/src/img/rancher/edit-cluster.png b/src/img/rancher/edit-cluster.png new file mode 100644 index 00000000000..1f921c7ffe6 Binary files /dev/null and b/src/img/rancher/edit-cluster.png differ diff --git a/src/img/rancher/encapsulated-network.svg b/src/img/rancher/encapsulated-network.svg new file mode 100644 index 00000000000..3f5634e6af2 --- /dev/null +++ b/src/img/rancher/encapsulated-network.svg @@ -0,0 +1,109 @@ + + + + Produced by OmniGraffle 7.4.3 + 2018-07-27 08:48:50 +0000 + + + + + + + + + + Canvas 1 + + + Layer 1 + + + + + k8s worker + + + + + workload 1 + 10.42.0.2 + + + + + fl + anneld + 10.42.0.1 + + + + + workload 2 + 10.42.0.3 + + + + + 192.168.34.10 + + + + + docker0 + + + + + + + + + + k8s worker + + + + + workload 1 + 10.42.1.2 + + + + + fl + anneld + 10.42.1.1 + + + + + workload 2 + 10.42.1.3 + + + + + 192.168.34.11 + + + + + docker0 + + + + + + + + + + encapsulation + + + + Overlay network 10.42.0.0/16 + + + + diff --git a/src/img/rancher/flannel-diagram.png b/src/img/rancher/flannel-diagram.png new file mode 100644 index 00000000000..aba8b2bc42b Binary files /dev/null and b/src/img/rancher/flannel-diagram.png differ diff --git a/src/img/rancher/flannel-logo.png b/src/img/rancher/flannel-logo.png new file mode 100644 index 00000000000..632441620f8 Binary files /dev/null and b/src/img/rancher/flannel-logo.png differ diff --git a/src/img/rancher/unencapsulated-network.svg b/src/img/rancher/unencapsulated-network.svg new file mode 100644 index 00000000000..58bfdbf3760 --- /dev/null +++ b/src/img/rancher/unencapsulated-network.svg @@ -0,0 +1,105 @@ + + + + Produced by OmniGraffle 7.4.3 + 2018-07-27 09:12:19 +0000 + + + + + + + + + + Canvas 1 + + + Layer 1 + + + + + k8s worker + + + + + workload 1 + 10.42.0.2 + + + + + bgp r + outing + + + + + workload 2 + 10.42.0.3 + + + + + 192.168.34.10 + + + + + docker0 + + + + + + + + + + k8s worker + + + + + workload 1 + 10.42.1.2 + + + + + bgp r + outing + + + + + workload 2 + 10.42.1.3 + + + + + 192.168.34.11 + + + + + docker0 + + + + + + + + + + ETCD + + + + + +