diff --git a/content/_index.html b/content/_index.html index fd31063084b..ccad7160a18 100644 --- a/content/_index.html +++ b/content/_index.html @@ -215,7 +215,7 @@
-

Lightweight Kubernetes. Easy to install, half the memory, all in a binary less than 40mb.

+

Lightweight Kubernetes. Easy to install, half the memory, all in a binary less than 50mb.

diff --git a/content/k3s/latest/en/_index.md b/content/k3s/latest/en/_index.md index a1b0508c132..2b47eee622b 100644 --- a/content/k3s/latest/en/_index.md +++ b/content/k3s/latest/en/_index.md @@ -4,7 +4,7 @@ shortTitle: K3s name: "menu" --- -Lightweight Kubernetes. Easy to install, half the memory, all in a binary less than 50mb. +Lightweight Kubernetes. Easy to install, half the memory, all in a binary of less than 50mb. Great for: diff --git a/content/rancher/v2.x/en/installation/_index.md b/content/rancher/v2.x/en/installation/_index.md index 611beca8ccb..205bdd57c56 100644 --- a/content/rancher/v2.x/en/installation/_index.md +++ b/content/rancher/v2.x/en/installation/_index.md @@ -2,6 +2,8 @@ title: Installing Rancher description: Learn how to install Rancher in development and production environments. Read about single node and high availability installation weight: 50 +aliases: + - /rancher/v2.x/en/installation/how-ha-works/ --- This section provides an overview of the architecture options of installing Rancher, describing advantages of each option. @@ -11,29 +13,20 @@ This section provides an overview of the architecture options of installing Ranc In this section, - **The Rancher server** manages and provisions Kubernetes clusters. You can interact with downstream Kubernetes clusters through the Rancher server's user interface. -- **RKE (Rancher Kubernetes Engine)** is a certified Kubernetes distribution and CLI/library which creates and manages a Kubernetes cluster. When you create a cluster in the Rancher UI, it calls RKE as a library to provision Rancher-launched Kubernetes clusters. -- **K3s (5 less than K8s)** is also a fully compliant Kubernetes distribution. It is newer than RKE, easier to use, and more lightweight, with a binary size of less than 40 MB. As of Rancher v2.4, Rancher can be installed on a K3s cluster. +- **RKE (Rancher Kubernetes Engine)** is a certified Kubernetes distribution and CLI/library which creates and manages a Kubernetes cluster. +- **K3s (5 less than K8s)** is also a fully compliant Kubernetes distribution. It is newer than RKE, easier to use, and more lightweight, with a binary size of less than 50 MB. As of Rancher v2.4, Rancher can be installed on a K3s cluster. ### Overview of Installation Options -If you use Rancher to deploy Kubernetes clusters, it is important to ensure that the Rancher server doesn't fail, because if it goes down, you could lose access to the Kubernetes clusters that are managed by Rancher. For that reason, we recommend that for a production-grade architecture, you should set up a high-availability Kubernetes cluster with RKE, then install Rancher on it. After Rancher is installed, you can use Rancher to deploy and manage Kubernetes clusters. +We recommend installing Rancher on a Kubernetes cluster, because in a multi-node cluster, the Rancher management server becomes highly available. This high-availability configuration helps maintain consistent access to the downstream Kubernetes clusters that Rancher will manage. -For testing or demonstration purposes, you can install Rancher in single Docker container. In this installation, you can use Rancher to set up Kubernetes clusters out-of-the-box. +For that reason, we recommend that for a production-grade architecture, you should set up a high-availability Kubernetes cluster, then install Rancher on it. After Rancher is installed, you can use Rancher to deploy and manage Kubernetes clusters. + +For testing or demonstration purposes, you can install Rancher in single Docker container. In this Docker install, you can use Rancher to set up Kubernetes clusters out-of-the-box. Our [instructions for installing Rancher on Kubernetes]({{}}/rancher/v2.x/en/installation/k8s-install) describe how to first use K3s or RKE to create and manage a Kubernetes cluster, then install Rancher onto that cluster. -For a high-availability K3s cluster, we recommend setting up the following infrastructure: - -- **Two Linux nodes,** typically virtual machines, in the infrastructure provider of your choice -- **A load balancer** to direct traffic to the two nodes. -- **An external database** to store the cluster data. PostgreSQL, MySQL, and etcd are supported. - -For a high-availability RKE cluster, we recommend setting up the following infrastructure: - -- **Three Linux nodes,** typically virtual machines, in the infrastructure provider of your choice. -- **A load balancer** to direct front-end traffic to the three nodes. - -When the nodes in your Kubernetes cluster are running and fulfill the [node requirements,]({{}}/rancher/v2.x/en/installation/requirements) you will use RKE or K3s to deploy Kubernetes onto them. Then you will use Helm to deploy Rancher onto Kubernetes. +When the nodes in your Kubernetes cluster are running and fulfill the [node requirements,]({{}}/rancher/v2.x/en/installation/requirements) you will use RKE or K3s to deploy Kubernetes onto them. Then you will use Helm to deploy Rancher onto Kubernetes. Helm uses Rancher's Helm chart to install a replica of Rancher on each node in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster. For a longer discussion of Rancher architecture, refer to the [architecture overview,]({{}}/rancher/v2.x/en/overview/architecture) [recommendations for production-grade architecture,]({{}}/rancher/v2.x/en/overview/architecture-recommendations) or our [best practices guide.]({{}}/rancher/v2.x/en/best-practices/deployment-types) @@ -75,7 +68,7 @@ In the Rancher installation instructions, we recommend using K3s or RKE to set u ### More Options for Installations with Docker -Refer to the [Docker installation docs]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker) for details about other configurations including: +Refer to the [docs about options for Docker installs]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker) for details about other configurations including: - With [API auditing to record all transactions]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/#api-audit-log) - With an [external load balancer]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-install-external-lb/) diff --git a/content/rancher/v2.x/en/installation/k8s-install/_index.md b/content/rancher/v2.x/en/installation/k8s-install/_index.md index 36d6949e90d..cfbb0aa7643 100644 --- a/content/rancher/v2.x/en/installation/k8s-install/_index.md +++ b/content/rancher/v2.x/en/installation/k8s-install/_index.md @@ -16,37 +16,24 @@ If you only have one node, but you want to use the Rancher server in production One option is to install Rancher with Helm on a Kubernetes cluster, but to only use a single node in the cluster. In this case, the Rancher server does not have high availability, which is important for running Rancher in production. However, this option is useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. In the future, you can add nodes to the cluster to get a high-availability Rancher server. -The single-node Kubernetes install can be achieved by describing only one node in the `cluster.yml` when provisioning the Kubernetes cluster with RKE. The single node would have all three roles: `etcd`, `controlplane`, and `worker`. Then Rancher would be installed with Helm on the cluster in the same way that it would be installed on any other cluster. +To set up a single-node RKE cluster, configure only one node in the `cluster.yml` . The single node should have all three roles: `etcd`, `controlplane`, and `worker`. + +To set up a single-node K3s cluster, run the Rancher server installation command on just one node instead of two nodes. + +In both single-node Kubernetes setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. ### Important Notes on Architecture -The Rancher management server can only be run on an RKE-managed Kubernetes cluster. Use of Rancher on hosted Kubernetes or other providers is not supported. +The Rancher management server can only be run on Kubernetes cluster in an infrastructure provider where Kubernetes is installed using K3s or RKE. Use of Rancher on hosted Kubernetes providers, such as EKS, is not supported. For the best performance and security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters]({{}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads. -We recommend the following architecture and configurations for the load balancer and Ingress controllers: - -- DNS for Rancher should resolve to a Layer 4 load balancer (TCP) -- The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster. -- The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443. -- The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment. - -For more information on how a Kubernetes Installation works, refer to [this page.]({{}}/rancher/v2.x/en/installation/how-ha-works) - For information on how Rancher works, regardless of the installation method, refer to the [architecture section.]({{}}/rancher/v2.x/en/overview/architecture) -## Required CLI 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]({{}}/rke/latest/en/installation/) - Rancher Kubernetes Engine, cli for building Kubernetes clusters. -- [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements]({{}}/rancher/v2.x/en/installation/options/helm-version) to choose a version of Helm to install Rancher. - ## Installation Outline -- [Create Nodes and Load Balancer]({{}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/) -- [Install Kubernetes with RKE]({{}}/rancher/v2.x/en/installation/k8s-install/kubernetes-rke/) +- [Set up Infrastructure]({{}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/) +- [Set up a Kubernetes Cluster]({{}}/rancher/v2.x/en/installation/k8s-install/kubernetes-rke/) - [Install Rancher]({{}}/rancher/v2.x/en/installation/k8s-install/helm-rancher/) ## Additional Install Options diff --git a/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/_index.md b/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/_index.md index f414d2ccbf4..573bcee1d5c 100644 --- a/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/_index.md +++ b/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/_index.md @@ -1,32 +1,111 @@ --- -title: '1. Create Nodes and Load Balancer' +title: '1. Set up Infrastructure' weight: 185 aliases: - /rancher/v2.x/en/installation/ha/create-nodes-lb --- -Use your infrastructure provider of choice to provision three nodes and a load balancer endpoint for your RKE install. +In this section, you will provision the underlying infrastructure for your Rancher management server. + +The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether K3s or RKE is used to install Kubernetes. > **Note:** These nodes must be in the same region. You may place these servers in separate availability zones (datacenter). -### Requirements for OS, Docker, Hardware, and Networking +{{% tabs %}} +{{% tab "K3s" %}} +To install the Rancher management server on a high-availability K3s cluster, we recommend setting up the following infrastructure: -Make sure that your nodes fulfill the general [installation requirements.]({{}}/rancher/v2.x/en/installation/requirements/) +- **Two Linux nodes,** typically virtual machines, in the infrastructure provider of your choice. +- **An external database** to store the cluster data. PostgreSQL, MySQL, and etcd are supported. +- **A load balancer** to direct traffic to the two nodes. -View the OS requirements for RKE at [RKE Requirements.]({{}}/rke/latest/en/os/) +### 1. Set up Linux Nodes -### Load Balancer +Make sure that your nodes fulfill the general installation requirements for [OS, Docker, hardware, and networking.]({{}}/rancher/v2.x/en/installation/requirements/) -RKE will configure an Ingress controller pod, on each of your nodes. The Ingress controller pods are bound to ports TCP/80 and TCP/443 on the host network and are the entry point for HTTPS traffic to the Rancher server. +For an example of one way to set up Linux nodes, refer to this [tutorial](./ec2-node) for setting up nodes as instances in Amazon EC2. + +### 2. Set up External Datastore + +The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available datastore options allow you to select a datastore that best fits your use case. + +For a high-availability K3s installation, you will need to set up one of the following external databases: + +* [PostgreSQL](https://www.postgresql.org/) (certified against versions 10.7 and 11.5) +* [MySQL](https://www.mysql.com/) (certified against version 5.7) +* [etcd](https://etcd.io/) (certified against version 3.3.15) + +When you install Kubernetes using the K3s installation script, you will pass in details for K3s to connect to the database. + +For an example of one way to set up the database, refer to this [tutorial](./rds) for setting up a MySQL database on Amazon's RDS service. + +For the complete list of options that are available for configuring a K3s cluster datastore, refer to the [K3s documentation.]({{}}/k3s/latest/en/installation/datastore/) + +### 3. Set up the Load Balancer + +You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. Configure a load balancer as a basic Layer 4 TCP forwarder. The exact configuration will vary depending on your environment. +External traffic will enter the Rancher management server cluster through an Ingress controller pod on each node. The Ingress controller pods are bound to ports TCP/80 and TCP/443 on the host network and are the entry point for HTTPS traffic to the Rancher server. In a later step, you will use the Helm package manager to install Rancher's Helm chart on the Kubernetes cluster. This Helm chart will set up a replica of Rancher on each node in the cluster. Therefore, we recommend using a load balancer to direct traffic to ports 80 and 443 on each replica of Rancher in the cluster. + +- The DNS for Rancher should resolve to a layer 4 load balancer. +- The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster. +- The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443. +- The Ingress controller will forward traffic to port TCP/80 on the Ingress pod in the Rancher deployment. + +For an example showing how to set up an NGINX load balancer, refer to [this page.]({{}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nginx/) + +For a how-to guide for setting up an Amazon NLB load balancer, refer to [this page.]({{}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nlb/) + > **Important:** > Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. -#### How-to Guides +{{% /tab %}} +{{% tab "RKE" %}} +To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure: -- For an example showing how to set up an NGINX load balancer, refer to [this page.]({{}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nginx/) -- For an example showing how to setup an Amazon NLB load balancer, refer to [this page.]({{}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nlb/) +- **Three Linux nodes,** typically virtual machines, in an infrastructure provider such as Amazon's EC2 or Google Compute Engine. +- **A load balancer** to direct front-end traffic to the three nodes. -### [Next: Install Kubernetes with RKE]({{}}/rancher/v2.x/en/installation/k8s-install/kubernetes-rke/) +These nodes must be in the same region/data center. You may place these servers in separate availability zones. + +### Why three nodes? + +In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes. + +The etcd database requires an odd number of nodes is so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can fail, requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can safely elect a leader because they have the majority of the total number of etcd nodes. + +### 1. Set up Linux Nodes + +Make sure that your nodes fulfill the general installation requirements for [OS, Docker, hardware, and networking.]({{}}/rancher/v2.x/en/installation/requirements/) + +For an example of one way to set up Linux nodes, refer to this [tutorial](./ec2-node) for setting up nodes as instances in Amazon EC2. + +### 2. Set up the Load Balancer + +You will also need to set up a load balancer to direct traffic to the Rancher replica on each of the three nodes. + +Configure a load balancer as a basic Layer 4 TCP forwarder. The exact configuration will vary depending on your environment. + +RKE will configure an Ingress controller pod on each node. The Ingress controller pods are bound to ports TCP/80 and TCP/443 on the host network and are the entry point for HTTPS traffic to the Rancher server. In a later step, you will use the Helm package manager to install Rancher's Helm chart on the Kubernetes cluster. This Helm chart will set up a replica of Rancher on each node in the cluster. Therefore, we recommend using a load balancer to direct traffic to ports 80 and 443 on each replica of Rancher in the cluster. + +- The DNS for Rancher should resolve to a layer 4 load balancer +- The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster. +- The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443. +- The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment. + +
Kubernetes Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers
+![High-availability Kubernetes Installation of Rancher]({{}}/img/rancher/ha/rancher2ha.svg) +Kubernetes Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers + +> **Important:** +> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +For an example showing how to set up an NGINX load balancer, refer to [this page.]({{}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nginx/) + +For a how-to guide for setting up an Amazon NLB load balancer, refer to [this page.]({{}}/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nlb/) +{{% /tab %}} +{{% /tabs %}} + +### [Next: Set up a Kubernetes Cluster]({{}}/rancher/v2.x/en/installation/k8s-install/kubernetes-rke/) \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/ec2-node/_index.md b/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/ec2-node/_index.md new file mode 100644 index 00000000000..0321861e458 --- /dev/null +++ b/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/ec2-node/_index.md @@ -0,0 +1,62 @@ +--- +title: Setting up Nodes in Amazon EC2 +weight: 280 +--- + +In this tutorial, you will learn one way to set up Linux nodes for the Rancher management server. These nodes will fulfill the node requirements for [OS, Docker, hardware, and networking.]({{}}/rancher/v2.x/en/installation/requirements/) + +If the Rancher server will be installed on an RKE Kubernetes cluster, you should provision three instances. + +If the Rancher server will be installed on a K3s Kubernetes cluster, you only need to provision two instances. + +### 1. Optional Preparation + +- **Create IAM role:** To allow Rancher to manipulate AWS resources, such as provisioning new storage or new nodes, you will need to configure Amazon as a cloud provider. There are several things you'll need to do to set up the cloud provider on EC2, but part of this process is setting up an IAM role for the Rancher server nodes. For the full details on setting up the cloud provider, refer to this [page.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) +- **Create security group:** We also recommend setting up a security group for the Rancher nodes that complies with the [port requirements for Rancher nodes.]({{}}/rancher/v2.x/en/installation/requirements/#port-requirements) The exact requirements will differ depending on whether Kubernetes is installed with RKE or K3s. + +### 2. Provision Instances + +1. Log into the [Amazon AWS EC2 Console](https://console.aws.amazon.com/ec2/) to get started. Make sure to take note of the **Region** where your EC2 instances (Linux nodes) are created, because all of the infrastructure for the Rancher management server should be in the same region. +1. In the left panel, click **Instances.** +1. Click **Launch Instance.** +1. In the section called **Step 1: Choose an Amazon Machine Image (AMI),** we will use Ubuntu 18.04 as the Linux OS, using `ami-0d1cd67c26f5fca19 (64-bit x86)`. Go to the Ubuntu AMI and click **Select.** +1. In the **Step 2: Choose an Instance Type** section, select the `t2.medium` type. +1. Click **Next: Configure Instance Details.** +1. In the **Number of instances** field, enter the number of instances. A high-availability K3s cluster requires only two instances, while a high-availability RKE cluster requires three instances. +1. Optional: If you created an IAM role for Rancher to manipulate AWS resources, select the new IAM role in the **IAM role** field. +1. Click **Next: Add Storage,** **Next: Add Tags,** and **Next: Configure Security Group.** +1. In **Step 6: Configure Security Group,** select a security group that complies with the [port requirements]({{}}/rancher/v2.x/en/installation/requirements/#port-requirements) for Rancher nodes. +1. Click **Review and Launch.** +1. Click **Launch.** +1. Choose a new or existing key pair that you will use to connect to your instance later. If you are using an existing key pair, make sure you already have access to the private key. +1. Click **Launch Instances.** + +**Result:** You have created Rancher nodes that satisfy the requirements for OS, hardware, and networking. Next, you will install Docker on each node. + +### 3. Install Docker and Create User + +1. From the [AWS EC2 console,](https://console.aws.amazon.com/ec2/) click **Instances** in the left panel. +1. Go to the instance that you want to install Docker on. Select the instance and click **Actions > Connect.** +1. Connect to the instance by following the instructions on the screen that appears. Copy the Public DNS of the instance. An example command to SSH into the instance is as follows: +``` +sudo ssh -i [path-to-private-key] ubuntu@[public-DNS-of-instance] +``` +1. When you are connected to the instance, run the following command on the instance to create a user: +``` +sudo usermod -aG docker ubuntu +``` +1. Run the following command on the instance to install Docker with one of Rancher's installation scripts: +``` +curl https://releases.rancher.com/install-docker/18.09.sh | sh +``` +1. Repeat these steps so that Docker is installed on each node that will eventually run the Rancher management server. + +> To find out whether a script is available for installing a certain Docker version, refer to this [GitHub repository,](https://github.com/rancher/install-docker) which contains all of Rancher’s Docker installation scripts. + +**Result:** You have set up Rancher server nodes that fulfill all the node requirements for OS, Docker, hardware and networking. + +### Next Steps for RKE Kubernetes Cluster Nodes + +If you are going to install an RKE cluster on the new nodes, take note of the **IPv4 Public IP** and **Private IP** of each node. This information can be found on the **Description** tab for each node after it is created. The public and private IP will be used to populate the `address` and `internal_address` of each node in the RKE cluster configuration file, `rancher-cluster.yml`. + +RKE will also need access to the private key to connect to each node. Therefore, you might want to take note of the path to your private keys to connect to the nodes, which can also be included in the `rancher-cluster.yml` under the `ssh_key_path` directive for each node. \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nginx/_index.md b/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nginx/_index.md index f915f340d59..30af71c22c1 100644 --- a/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nginx/_index.md +++ b/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nginx/_index.md @@ -7,10 +7,11 @@ aliases: NGINX will be configured as Layer 4 load balancer (TCP) that forwards connections to one of your Rancher nodes. -> **Note:** -> In this configuration, the load balancer is positioned in front of your nodes. The load balancer can be any host capable of running NGINX. -> -> One caveat: do not use one of your Rancher nodes as the load balancer. +In this configuration, the load balancer is positioned in front of your nodes. The load balancer can be any host capable of running NGINX. + +One caveat: do not use one of your Rancher nodes as the load balancer. + +> These examples show the load balancer being configured to direct traffic to three Rancher server nodes. If Rancher is installed on an RKE Kubernetes cluster, three nodes are required. If Rancher is installed on a K3s Kubernetes cluster, only two nodes are required. ## Install NGINX diff --git a/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nlb/_index.md b/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nlb/_index.md index 29aca8a2e39..36032575e8a 100644 --- a/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nlb/_index.md +++ b/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/nlb/_index.md @@ -7,6 +7,8 @@ aliases: This how-to guide describes how to set up a load balancer in Amazon's EC2 service that will direct traffic to multiple instances on EC2. +These examples show the load balancer being configured to direct traffic to three Rancher server nodes. If Rancher is installed on an RKE Kubernetes cluster, three nodes are required. If Rancher is installed on a K3s Kubernetes cluster, only two nodes are required. + > **Note:** Rancher only supports using the Amazon NLB when terminating traffic in `tcp` mode for port 443 rather than `tls` mode. This is due to the fact that the NLB does not inject the correct headers into requests when terminated at the NLB. This means that if you want to use certificates managed by the Amazon Certificate Manager (ACM), you should use an ELB or ALB. Configuring an Amazon NLB is a multistage process: diff --git a/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/rds/_index.md b/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/rds/_index.md new file mode 100644 index 00000000000..41d7b8eb501 --- /dev/null +++ b/content/rancher/v2.x/en/installation/k8s-install/create-nodes-lb/rds/_index.md @@ -0,0 +1,34 @@ +--- +title: Setting up a MySQL Database in Amazon RDS +weight: 290 +--- +This tutorial describes how to set up a MySQL database in Amazon's RDS. + +This database can later be used as an external datastore for a high-availability K3s Kubernetes cluster. + +1. Log into the [Amazon AWS RDS Console](https://console.aws.amazon.com/rds/) to get started. Make sure to select the **Region** where your EC2 instances (Linux nodes) are created. +1. In the left panel, click **Databases.** +1. Click **Create database.** +1. In the **Engine type** section, click **MySQL.** +1. In the **Version** section, choose **MySQL 5.7.22.** +1. In **Settings** section, under **Credentials Settings,** enter a master password for the **admin** master username. Confirm the password. +1. Expand the **Additional configuration** section. In the **Initial database name** field, enter a name. The name can have only letters, numbers, and underscores. This name will be used to connect to the database. +1. Click **Create database.** + +You'll need to capture the following information about the new database so that the K3s Kubernetes cluster can connect to it. + +To see this information in the Amazon RDS console, click **Databases,** and click the name of the database that you created. + +- **Username:** Use the admin username. +- **Password:** Use the admin password. +- **Hostname:** Use the **Endpoint** as the hostname. The endpoint is available in the **Connectivity & security** section. +- **Port:** The port should be 3306 by default. You can confirm it in the **Connectivity & security** section. +- **Database name:** Confirm the name by going to the **Configuration** tab. The name is listed under **DB name.** + +This information will be used to connect to the database in the following format: + +``` +mysql://username:password@tcp(hostname:3306)/database-name +``` + +For more information on configuring the datastore for K3s, refer to the [K3s documentation.]({{}}/k3s/latest/en/installation/datastore/) \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/k8s-install/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/k8s-install/helm-rancher/_index.md index 5dd4d41cb66..0aeae37ce0c 100644 --- a/content/rancher/v2.x/en/installation/k8s-install/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/k8s-install/helm-rancher/_index.md @@ -16,11 +16,16 @@ To choose a Rancher version to install, refer to [Choosing a Rancher Version.]({ To choose a version of Helm to install Rancher with, refer to the [Helm version requirements]({{}}/rancher/v2.x/en/installation/options/helm-version) -> **Note:** The installation instructions assume you are using Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) This [section]({{}}/rancher/v2.x/en/installation/options/helm2) provides a copy of the older installation instructions for Rancher installed on Kubernetes with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible. +> **Note:** The installation instructions assume you are using Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) This [section]({{}}/rancher/v2.x/en/installation/options/helm2) provides a copy of the older installation instructions for Rancher installed on an RKE Kubernetes cluster with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible. -### Install Helm +# Required CLI Tools -Helm requires a simple CLI tool to be installed. Refer to the [instructions provided by the Helm project](https://helm.sh/docs/intro/install/) for your specific platform. +The following CLI tools are required for setting up the Kubernetes cluster. Please make sure these tools are installed and available in your `$PATH`. + +Refer to the [instructions provided by the Helm project](https://helm.sh/docs/intro/install/) for your specific platform. + +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool. +- [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements]({{}}/rancher/v2.x/en/installation/options/helm-version) to choose a version of Helm to install Rancher. ### Add the Helm Chart Repository @@ -42,9 +47,9 @@ kubectl create namespace cattle-system ### Choose your SSL Configuration -Rancher Server is designed to be secure by default and requires SSL/TLS configuration. +The Rancher management server is designed to be secure by default and requires SSL/TLS configuration. -There are three recommended options for the source of the certificate. +There are three recommended options for the source of the certificate. For discussion of each option and its use case, refer to this [blog post.](https://rancher.com/blog/2020/transport-layer-security-p2) > **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer]({{}}/rancher/v2.x/en/installation/options/chart-options/#external-tls-termination). diff --git a/content/rancher/v2.x/en/installation/k8s-install/kubernetes-rke/_index.md b/content/rancher/v2.x/en/installation/k8s-install/kubernetes-rke/_index.md index 0a7fd9eed28..5a6ef54e701 100644 --- a/content/rancher/v2.x/en/installation/k8s-install/kubernetes-rke/_index.md +++ b/content/rancher/v2.x/en/installation/k8s-install/kubernetes-rke/_index.md @@ -6,21 +6,123 @@ aliases: - /rancher/v2.x/en/installation/ha/kubernetes-rke/ --- -This section describes how to install a Kubernetes cluster on your three nodes according to our [best practices for the Rancher server environment.]({{}}/rancher/v2.x/en/overview/architecture-recommendations/#environment-for-kubernetes-installations) This cluster should be dedicated to run only the Rancher server. We recommend using RKE to install Kubernetes on this cluster. Hosted Kubernetes providers such as EKS should not be used. +This section describes how to install a Kubernetes cluster according to our [best practices for the Rancher server environment.]({{}}/rancher/v2.x/en/overview/architecture-recommendations/#environment-for-kubernetes-installations) This cluster should be dedicated to run only the Rancher server. + +For Rancher prior to v2.4, Rancher should be installed on an RKE Kubernetes cluster. RKE is a CNCF-certified Kubernetes distribution and that runs entirely within Docker containers. + +As of Rancher v2.4, the Rancher management server can be installed on either an RKE cluster or a K3s Kubernetes cluster. K3s is also a fully certified Kubernetes distribution released by Rancher, but is newer than RKE. We recommend installing Rancher on K3s because K3s is easier to use, and more lightweight, with a binary size of less than 50 MB. Note: After Rancher is installed on an RKE cluster, there is no migration path to a K3s setup at this time. + +The Rancher management server can only be run on Kubernetes cluster in an infrastructure provider where Kubernetes is installed using RKE or K3s. Use of Rancher on hosted Kubernetes providers, such as EKS, is not supported. For systems without direct internet access, refer to [Air Gap: Kubernetes install.]({{}}/rancher/v2.x/en/installation/air-gap-high-availability/) > **Single-node Installation Tip:** > In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. > -> To set up a single-node cluster, configure only one node in the `cluster.yml` when provisioning the cluster with RKE. The single node should have all three roles: `etcd`, `controlplane` and `worker`. Then Rancher can be installed with Helm on the cluster in the same way that it would be installed on any other cluster. +> To set up a single-node RKE cluster, configure only one node in the `cluster.yml` . The single node should have all three roles: `etcd`, `controlplane`, and `worker`. +> +> To set up a single-node K3s cluster, run the Rancher server installation command on just one node instead of two nodes. +> +> In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. -### Create the `rancher-cluster.yml` File +# Installing Kubernetes -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. + +The steps to set up the Kubernetes cluster differ depending on whether you are using RKE or K3s. + +{{% tabs %}} +{{% tab "K3s" %}} + +### 1. Install Kubernetes and Set up the K3s Server + +When running the command to start the K3s Kubernetes API server, you will pass in two options: one option to use the external datastore that you set up earlier, and one to prevent K3s from deploying Traefik, which is the default ingress in K3s. You need to disable Traefik because Rancher will use NGINX as the ingress to allow external traffic into the cluster. + +1. Connect to one of the Linux nodes that you have prepared to run the Rancher server. +1. On the Linux node, run this command to start the K3s server and connect it to the external datastore: + ``` + curl -sfL https://get.k3s.io | sh -s - server \ + --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name" \ + --no-deploy=traefik + ``` + Note: The datastore endpoint can also be passed in using the environment variable `$K3S_DATASTORE_ENDPOINT`. + +1. Repeat the same command on your second K3s server node. + +### 2. Confirm that K3s is Running + +To confirm that K3s has been set up successfully, run the following command on either of the K3s server nodes: +``` +sudo k3s kubectl get nodes +``` + +Then you should see two nodes with the master role: +``` +ubuntu@ip-172-31-60-194:~$ sudo k3s kubectl get nodes +NAME STATUS ROLES AGE VERSION +ip-172-31-60-194 Ready master 44m v1.17.2+k3s1 +ip-172-31-63-88 Ready master 6m8s v1.17.2+k3s1 +``` + +Then test the health of the cluster pods: +``` +sudo k3s kubectl get pods --all-namespaces +``` + +**Result:** You have successfully set up a K3s Kubernetes cluster. + +### 3. Save and Start Using the kubeconfig File + +When you installed K3s on each Rancher server node, a `kubeconfig` file was created on the node at `/etc/rancher/k3s/k3s.yaml`. This file contains credentials for full access to the cluster, and you should save this file in a secure location. + +To use this `kubeconfig` file, + +1. Install [kubectl,](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) a Kubernetes command-line tool. +2. Copy the file at `/etc/rancher/k3s/k3s.yaml` and save it to the directory `~/.kube/config` on your local machine. +3. Replace `localhost` in the kubeconfig file with the IP or name of your K3s server. + +**Result:** You can now use `kubectl` to manage your K3s cluster. + +For more information about the `kubeconfig` file, refer to the [K3s documentation]({{}}/k3s/latest/en/cluster-access/) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) about organizing cluster access using `kubeconfig` files. + +### 4. Check the Health of Your Cluster Pods + +Now that you have set up the `kubeconfig` file, you can use `kubectl` to access the cluster from your local machine. + +Check that all the required pods and containers are healthy are ready to continue: +``` +ubuntu@ip-172-31-60-194:~$ sudo kubectl get pods --all-namespaces +NAMESPACE NAME READY STATUS RESTARTS AGE +kube-system metrics-server-6d684c7b5-bw59k 1/1 Running 0 8d +kube-system local-path-provisioner-58fb86bdfd-fmkvd 1/1 Running 0 8d +kube-system coredns-d798c9dd-ljjnf 1/1 Running 0 8d +cert-manager cert-manager-cainjector-85fbdf788-ct5cp 1/1 Running 0 7d22h +cert-manager cert-manager-754d9b75d9-29llx 1/1 Running 0 7d22h +cert-manager cert-manager-webhook-76f9b64b45-lnhdl 1/1 Running 0 7d22h +cattle-system rancher-ddf788bbf-2zdb4 1/1 Running 0 7d22h +cattle-system rancher-ddf788bbf-22dxm 1/1 Running 1 7d22h +cattle-system rancher-ddf788bbf-k6vk4 1/1 Running 1 7d22h +``` + +**Result:** You have confirmed that you can access the cluster with `kubectl` and the K3s cluster is running successfully. Now the Rancher management server can be installed on the cluster. +{{% /tab %}} +{{% tab "RKE" %}} + +### Required CLI Tools + +Install [kubectl,](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) a Kubernetes command-line tool. + +Also install [RKE,]({{}}/rke/latest/en/installation/) the Rancher Kubernetes Engine, a Kubernetes distribution and command-line tool. + +### 1. Create the cluster configuration file + +In this section, you will create a Kubernetes cluster configuration file called `rancher-cluster.yml`. In a later step, when you set up the cluster with an RKE command, it will use this file to install Kubernetes on your nodes. + +Using the sample below as a guide, 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. If your node has public and internal addresses, it is recommended to set the `internal_address:` so Kubernetes will use it for intra-cluster communication. Some services like AWS EC2 require setting the `internal_address:` if you want to use self-referencing security groups or firewalls. +RKE will need to connect to each node over SSH, and it will look for a private key in the default location of `~/.ssh/id_rsa`. If your private key for a certain node is in a different location than the default, you will also need to configure the `ssh_key_path` option for that node. + ```yaml nodes: - address: 165.227.114.63 @@ -50,7 +152,7 @@ ingress: use-forwarded-headers: "true" ``` -#### Common RKE Nodes Options +
Common RKE Nodes Options
| Option | Required | Description | | ------------------ | -------- | -------------------------------------------------------------------------------------- | @@ -60,15 +162,13 @@ ingress: | `internal_address` | no | The private DNS or IP address for internal cluster traffic | | `ssh_key_path` | no | Path to SSH private key used to authenticate to the node (defaults to `~/.ssh/id_rsa`) | -#### Advanced Configurations +> **Advanced Configurations:** RKE has many configuration options for customizing the install to suit your specific environment. +> +> Please see the [RKE Documentation]({{}}/rke/latest/en/config-options/) for the full list of options and capabilities. +> +> For tuning your etcd cluster for larger Rancher installations, see the [etcd settings guide]({{}}/rancher/v2.x/en/installation/options/etcd/). -RKE has many configuration options for customizing the install to suit your specific environment. - -Please see the [RKE Documentation]({{}}/rke/latest/en/config-options/) for the full list of options and capabilities. - -For tuning your etcd cluster for larger Rancher installations see the [etcd settings guide]({{}}/rancher/v2.x/en/installation/options/etcd/). - -### Run RKE +### 2. Run RKE ``` rke up --config ./rancher-cluster.yml @@ -76,19 +176,23 @@ rke up --config ./rancher-cluster.yml When finished, it should end with the line: `Finished building Kubernetes cluster successfully`. -### Testing Your Cluster +### 3. Test Your Cluster -RKE should have created a file `kube_config_rancher-cluster.yml`. This file has the credentials for `kubectl` and `helm`. +This section describes how to set up your workspace so that you can interact with this cluster using the `kubectl` command-line tool. + +Assuming you have installed `kubectl`, you need to place the `kubeconfig` file in a location where `kubectl` can reach it. The `kubeconfig` file contains the credentials necessary to access your cluster with `kubectl`. + +When you ran `rke up`, RKE should have created a `kubeconfig` file named `kube_config_rancher-cluster.yml`. This file has the credentials for `kubectl` and `helm`. > **Note:** If you have used a different file name from `rancher-cluster.yml`, then the kube config file will be named `kube_config_.yml`. -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`. +Move 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 your connectivity with `kubectl` and see if all your nodes are in `Ready` state. +Test your connectivity with `kubectl` and see if all your nodes are in `Ready` state: ``` kubectl get nodes @@ -99,7 +203,7 @@ NAME STATUS ROLES AGE VER 165.227.127.226 Ready controlplane,etcd,worker 11m v1.13.5 ``` -### Check the Health of Your Cluster Pods +### 4. Check the Health of Your Cluster Pods Check that all the required pods and containers are healthy are ready to continue. @@ -126,7 +230,9 @@ kube-system rke-metrics-addon-deploy-job-7ljkc 0/1 Completed kube-system rke-network-plugin-deploy-job-6pbgj 0/1 Completed 0 30s ``` -### Save Your Files +This confirms that you have successfully installed a Kubernetes cluster that the Rancher server will run on. + +### 5. Save Your Files > **Important** > The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster. @@ -142,5 +248,7 @@ Save a copy of the following files in a secure location: ### Issues or errors? See the [Troubleshooting]({{}}/rancher/v2.x/en/installation/options/troubleshooting/) page. +{{% /tab %}} +{{% /tabs %}} ### [Next: Install Rancher]({{}}/rancher/v2.x/en/installation/k8s-install/helm-rancher/) diff --git a/content/rancher/v2.x/en/installation/requirements/_index.md b/content/rancher/v2.x/en/installation/requirements/_index.md index 4afebe9277f..ce3fc738bde 100644 --- a/content/rancher/v2.x/en/installation/requirements/_index.md +++ b/content/rancher/v2.x/en/installation/requirements/_index.md @@ -48,10 +48,10 @@ This section describes the CPU, memory, and disk requirements for the nodes wher ### CPU and Memory -Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements. The requirements are different depending on if you are installing Rancher with Docker or on a Kubernetes cluster. +Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements. The requirements are different depending on if you are installing Rancher in a single container with Docker, or if you are installing Rancher on a Kubernetes cluster. {{% tabs %}} -{{% tab "Nodes in Kubernetes Install" %}} +{{% tab "Kubernetes Install Requirements" %}} These requirements apply to [installing Rancher on a Kubernetes cluster.]({{}}/rancher/v2.x/en/installation/k8s-install/) @@ -64,7 +64,11 @@ These requirements apply to [installing Rancher on a Kubernetes cluster.]({{>>>>>> Explain K3s Rancher install These requirements apply to [single node]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker) installations of Rancher.