mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-29 14:38:50 +00:00
Link to K3s and RKE resources in installation docs
This commit is contained in:
Catherine Luse
@@ -1,5 +0,0 @@
|
||||
---
|
||||
title: Tutorials
|
||||
weight: 10000
|
||||
---
|
||||
|
||||
@@ -1,114 +0,0 @@
|
||||
---
|
||||
title: Setting up a High-availability K3s Kubernetes Cluster for Rancher
|
||||
shortTitle: Set up K3s for Rancher
|
||||
weight: 2
|
||||
---
|
||||
|
||||
This section describes how to install a Kubernetes cluster according to the [best practices for the Rancher server environment.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture-recommendations/#environment-for-kubernetes-installations)
|
||||
|
||||
For systems without direct internet access, refer to the air gap installation instructions.
|
||||
|
||||
> **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 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.
|
||||
|
||||
# Prerequisites
|
||||
|
||||
These instructions assume you have set up two nodes, a load balancer, a DNS record, and an external MySQL database as described in [this section.](../infra-for-ha-with-external-db)
|
||||
|
||||
# Installing Kubernetes
|
||||
|
||||
### 1. Install Kubernetes and Set up the K3s Server
|
||||
|
||||
When running the command to start the K3s Kubernetes API server, you will pass in an option to use the external datastore that you set up earlier.
|
||||
|
||||
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"
|
||||
```
|
||||
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. In the kubeconfig file, the `server` directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example `k3s.yaml`:
|
||||
|
||||
```yml
|
||||
apiVersion: v1
|
||||
clusters:
|
||||
- cluster:
|
||||
certificate-authority-data: [CERTIFICATE-DATA]
|
||||
server: [LOAD-BALANCER-DNS]:6443 # Edit this line
|
||||
name: default
|
||||
contexts:
|
||||
- context:
|
||||
cluster: default
|
||||
user: default
|
||||
name: default
|
||||
current-context: default
|
||||
kind: Config
|
||||
preferences: {}
|
||||
users:
|
||||
- name: default
|
||||
user:
|
||||
password: [PASSWORD]
|
||||
username: admin
|
||||
```
|
||||
|
||||
**Result:** You can now use `kubectl` to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using `kubectl`:
|
||||
|
||||
```
|
||||
kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces
|
||||
```
|
||||
|
||||
For more information about the `kubeconfig` file, refer to the [K3s documentation]({{<baseurl>}}/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
|
||||
```
|
||||
|
||||
**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.
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
title: 'Set up Infrastructure for a High Availability K3s Kubernetes Cluster'
|
||||
weight: 1
|
||||
---
|
||||
|
||||
This tutorial is intended to help you provision the underlying infrastructure for a Rancher management server.
|
||||
|
||||
The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether Rancher will be installed on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container.
|
||||
|
||||
For more information about each installation option, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/installation)
|
||||
|
||||
> **Note:** These nodes must be in the same region. You may place these servers in separate availability zones (datacenter).
|
||||
|
||||
To install the Rancher management server on 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.
|
||||
- **An external database** to store the cluster data. We recommend MySQL.
|
||||
- **A load balancer** to direct traffic to the two nodes.
|
||||
- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.
|
||||
|
||||
### 1. Set up Linux Nodes
|
||||
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial]({{<baseurl>}}/rancher/v2.x/en/installation/options/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 options allow you to select a datastore that best fits your use case.
|
||||
|
||||
For a high-availability K3s installation, you will need to set a [MySQL](https://www.mysql.com/) external database. Rancher has been tested on K3s Kubernetes clusters using MySQL version 5.7 as the datastore.
|
||||
|
||||
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 MySQL database, refer to this [tutorial]({{<baseurl>}}/rancher/v2.x/en/installation/options/rds/) for setting up MySQL 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.]({{<baseurl>}}/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. That will prevent an outage of any single node from taking down communications to the Rancher management server.
|
||||
|
||||
When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.
|
||||
|
||||
When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.
|
||||
|
||||
For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:
|
||||
|
||||
- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
|
||||
- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.]({{<baseurl>}}/rancher/v2.x/en/installation/options/chart-options/#external-tls-termination)
|
||||
|
||||
For an example showing how to set up an NGINX load balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/installation/options/nginx/)
|
||||
|
||||
For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/installation/options/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.
|
||||
|
||||
### 4. Set up the DNS Record
|
||||
|
||||
Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.
|
||||
|
||||
Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.
|
||||
|
||||
You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.
|
||||
|
||||
For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)
|
||||
Reference in New Issue
Block a user