From d34a9861cd832306415866c11e4ebfa3ec87298f Mon Sep 17 00:00:00 2001 From: Sebastiaan van Steenis Date: Thu, 17 May 2018 01:53:05 +0200 Subject: [PATCH] Add HA L7 LB + ALB --- .../ha-server-install-external-lb/_index.md | 300 ++++++++++++++++++ .../alb/_index.md | 94 ++++++ src/img/rancher/ha/rancher2ha-l7.svg | 2 + 3 files changed, 396 insertions(+) create mode 100644 content/rancher/v2.x/en/installation/ha-server-install-external-lb/_index.md create mode 100644 content/rancher/v2.x/en/installation/ha-server-install-external-lb/alb/_index.md create mode 100644 src/img/rancher/ha/rancher2ha-l7.svg diff --git a/content/rancher/v2.x/en/installation/ha-server-install-external-lb/_index.md b/content/rancher/v2.x/en/installation/ha-server-install-external-lb/_index.md new file mode 100644 index 00000000000..e607d3b2848 --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha-server-install-external-lb/_index.md @@ -0,0 +1,300 @@ +--- +title: High Availability Installation with External Load Balancer +weight: 276 +--- +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 7 Loadbalancer with SSL termination (HTTPS) +- NGINX Ingress controller (HTTP) + +![Rancher HA]({{< baseurl >}}/img/rancher/ha/rancher2ha-l7.svg) + +## Overview + +1. [Provision Linux Hosts](#part-1-provision-linux-hosts) + + Provision three Linux hosts to serve as your Kubernetes cluster. + +2. [Configure Load Balancer](#part-2-configure-load-balancer) + + Configure your load balancer to have a highly available single point of entry to your Rancher cluster. + +3. [Configure DNS](#part-3-configure-dns) + + Make your setup accessible using a DNS name by configuring the DNS to point to your loadbalancer. + +4. [Download RKE](#part-4-download-rke) + + Rancher Kubernetes Engine (RKE) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. + +5. [Download Config File Template](#part-5-download-config-file-template) + + RKE uses a `.yml` config file to install and configure your Kubernetes cluster. Download one of our config file templates to get started. + +6. [Configure Nodes](#part-6-configure-nodes) + + Configure the **Nodes** section of the template. + +7. [Configure Certificates](#part-7-configure-certificates) + + Configure the **Certificates** part of the template too. + +8. [Configure FQDN](#part-8-configure-fqdn) + + You guessed it. Configure the **FQDN** part of the template. + +9. [Backup Your YAML File](#part-9-backup-your-yaml-file) + + After you've completed configuration of the config file template, back the config file up in a safe place. You can reuse this file for upgrades later. + +10. [Run RKE](#part-10-run-rke) + + Run RKE to deploy Rancher to your cluster. + +11. **For those using a certificate signed by a recognized CA:** + + [Remove Default Certificates](#part-11-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. + + +## Part 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 + +{{< requirements_os >}} + +{{< requirements_hardware >}} + +{{< requirements_software >}} + +{{< requirements_ports >}} + +## Part 2-Configure Load Balancer + +When using a load balancer in front of Rancher, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header `X-Forwarded-Proto: https`, this redirect is disabled. This is the expected configuration when terminating SSL externally. + +The load balancer has to be configured to support the following: + +* **WebSocket** connections +* **SPDY** / **HTTP/2** protocols +* Passing / setting the following headers: + +| Header | Value | Description | +|---------------------|----------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Host` | FQDN used to reach Rancher. | To identify the server requested by the client. | +| `X-Forwarded-Proto` | `https` | To identify the protocol that a client used to connect to the load balancer.

**Note:** If this header is present, `rancher/rancher` does not redirect HTTP to HTTPS. | +| `X-Forwarded-Port` | Port used to reach Rancher. | To identify the protocol that client used to connect to the load balancer. | +| `X-Forwarded-For` | IP of the client connection. | To identify the originating IP address of a client. | + +Health checks can be executed on the `/healthz` endpoint of the node, this will return HTTP 200. + +We have example configurations for the following load balancers: + +* [Amazon ALB]({{< baseurl >}}/rancher/v2.x/en/installation/ha-server-install-external-lb/alb) + +## Part 3-Configure DNS + +Choose a fully qualified domain name (FQDN) you want to use to access Rancher (something like `rancher.yourdomain.com`).

You need to create a DNS A record, pointing to the IP address of your [Load Balancer](#part-2-configure-load-balancer). If the DNS A record is created, you can validate if it's setup correctly by running `nslookup rancher.yourdomain.com`. It should return the IP address of your [Load Balancer](#part-2-configure-load-balancer) like in the example below. + +``` +$ nslookup rancher.yourdomain.com +Server: your_nameserver_ip +Address: your_nameserver_ip#53 + +Non-authoritative answer: +Name: rancher.yourdomain.com +Address: ip_of_loadbalancer +``` + +## Part 4-Download RKE + +Rancher Kubernetes Engine (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. + +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` + +Make the RKE binary that you just downloaded executable. Open Terminal, change directory to the location of the RKE binary, and then run the following command: + +``` +# MacOS +$ chmod +x rke_darwin-amd64 +# Linux +$ chmod +x rke_linux-amd64 +``` + +Confirm that RKE is now executable by running the following command: + +``` +# MacOS +$ ./rke_darwin-amd64 -version +# Linux +$ ./rke_linux-amd64 -version +``` + +**Result:** You receive output similar to what follows: +``` +rke version v +``` + +## Part 5-Download 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 using Self Signed Certificate (3-node-externalssl-certificate.yml)](https://raw.githubusercontent.com/rancher/rancher/e9d29b3f3b9673421961c68adf0516807d1317eb/rke-templates/3-node-certificate.yml) + - [Template for using Certificate Signed By A Recognized Certificate Authority (3-node-externalssl-recognizedca.yml)](https://raw.githubusercontent.com/rancher/rancher/e9d29b3f3b9673421961c68adf0516807d1317eb/rke-templates/3-node-certificate-recognizedca.yml) +2. Rename the file `rancher-cluster.yml`. + +## Part 6-Configure Nodes + +Once you have the `rancher-cluster.yml` config file template, edit the nodes section to point toward your Linux hosts. + +Open `rancher-cluster.yml` in your favorite text editor. + +Update the `nodes` section with the information of your [Linux hosts](#provision-linux-hosts) + +For each node in your cluster, update the following placeholders: + +- ``: The IP address or hostname of the node. +- ``: The username to use to setup a SSH connection to the node. If the user is not the `root` user, make sure the user has access to the Docker socket. This can be tested by logging in on the node as the configured user and run `docker ps`. +- ``: The path of the SSH private key file used to authenticate to the node. + +**Example nodes section YAML** + +``` +nodes: + - address: 1.1.1.1 + user: root + role: [controlplane,etcd,worker] + ssh_key_path: ~/.ssh/id_rsa + - address: 2.2.2.2 + user: root + role: [controlplane,etcd,worker] + ssh_key_path: ~/.ssh/id_rsa + - address: 3.3.3.3 + user: root + role: [controlplane,etcd,worker] + ssh_key_path: ~/.ssh/id_rsa +``` + +## Part 7-Configure certificates + +Certificates can be configured by using base64 encoded strings in the config file. The base64 encoded string can be generated using the following command: + + - **MacOS**: `cat FILENAME| base64` + - **Linux**: `cat FILENAME | base64 -w0` + - **Windows**: `certutil -encode FILENAME FILENAME.base64` + +### Option A-Self Signed Certificate + +>**Note:** +> If you are using Certificate Signed By A Recognized Certificate Authority, [click here](#option-b-certificate-signed-by-a-recognized-certificate-authority) to proceed. + +If you are using a Self Signed Certificate, you will need to generate a base64 encoded string for your CA certificate file. + +In the `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`) + +After replacing the value, the file should look like the example below (the base64 encoded string should be different): + +``` +--- +apiVersion: v1 +kind: Secret +metadata: + name: cattle-keys-server + namespace: cattle-system +type: Opaque +data: + cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg== +``` + +### Option B-Certificate Signed By A Recognized Certificate Authority + +If you are using a Certificate Signed By A Recognized Certificate Authority, you don't need to perform any step in this part. + +## Part 8-Configure FQDN + +There is 1 reference to `` in the config file. This needs to be replaced with the FQDN chosen in [Configure DNS](#configure-dns). + +In the `kind: Ingress` with `name: cattle-ingress-http`: + +* Replace `` with the FQDN chosen in [Configure DNS](#configure-dns). + +After replacing `` with the FQDN chosen in [Configure DNS](#configure-dns), the file should look like the example below (`rancher.yourdomain.com` is the FQDN used in this example): + +``` + --- + 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 +``` + +Save the `.yml` file and close it. + +## Part 9-Backup Your YAML 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. + +## Part 10-Run RKE + +All configuration is in place to run RKE. You can do this by running the `rke up` command and using the `--config` parameter to point to your config file. + +From your workstation, make sure `rancher-cluster.yml` and the downloaded `rke` binary are in the same directory. + +Open a Terminal instance. Change to the directory that contains your config file and `rke`. + +**Example:** + +``` +# MacOS +./rke_darwin-amd64 up --config rancher-cluster.yml +# Linux +./rke_linux-amd64 up --config rancher-cluster.yml +``` + +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 +``` + +## Part 11-Remove Default Certificates + +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? + +Log in to Rancher to make sure it deployed successfully. Open a web browser and navigate to the FQDN chosen in [Configure DNS](#configure-dns). 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-server-install-external-lb/alb/_index.md new file mode 100644 index 00000000000..424d35bdd3f --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha-server-install-external-lb/alb/_index.md @@ -0,0 +1,94 @@ +--- +title: Amazon ALB configuration +weight: 277 +--- +## Objectives + +Configuring an Amazon ALB is a multistage process. We've broken it down into multiple tasks so that it's easy to follow. + +1. [Create Target Group](#create-target-group) + + Begin by creating one target group for the http protocol. You'll add your Linux nodes to this group. + +2. [Register Targets](#register-targets) + + Add your Linux nodes to the target group. + +3. [Create Your ALB](#create-your-alb) + + Use Amazon's Wizard to create an Application Load Balancer. As part of this process, you'll add the target groups you created in **1. Create Target Groups**. + + +## Create Target Group + +Your first ALB configuration step is to create one target group for HTTP. + +Log into the [Amazon AWS Console](https://console.aws.amazon.com/ec2/) to get started. + +The document below will guide you through this process. Use the data in the tables below to complete the procedure. + +[Amazon Documentation: Create a Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-target-group.html) + +### Target Group (HTTP) + +Option | Setting +----------------------------|------------------------------------ +Target Group Name | `rancher-http-80` +Protocol | `HTTP` +Port | `80` +Target type | `instance` +VPC | Choose your VPC +Protocol
(Health Check) | `HTTP` +Path
(Health Check) | `/healthz` + +## Register Targets + +Next, add your Linux nodes to your target group. + +[Amazon Documentation: Register Targets with Your Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/target-group-register-targets.html) + +### Create Your ALB + +Use Amazon's Wizard to create an Application Load Balancer. As part of this process, you'll add the target group you created in [Create Target Group](#create-target-group). + +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 **Application Load Balancer**. + +5. Complete the **Step 1: Configure Load Balancer** form. + - **Basic Configuration** + + - Name: `rancher-http` + - Scheme: `internet-facing` + - IP address type: `ipv4` + - **Listeners** + + Add the **Load Balancer Protocols** and **Load Balancer Ports** below. + - `HTTP`: `80` + - `HTTPS`: `443` + + - **Availability Zones** + + - Select Your **VPC** and **Availability Zones**. + +6. Complete the **Step 2: Configure Security Settings** form. + + Configure the certificate you want to use for SSL termination. + +7. Complete the **Step 3: Configure Security Groups** form. + +8. Complete the **Step 4: Configure Routing** form. + + - From the **Target Group** drop-down, choose **Existing target group**. + + - Add target group `rancher-http-80`. + +9. Complete **Step 5: Register Targets**. Since you registered your targets earlier, all you have to do it click **Next: Review**. + +10. Complete **Step 6: Review**. Look over the load balancer details and click **Create** when you're satisfied. + +11. After AWS creates the ALB, click **Close**. diff --git a/src/img/rancher/ha/rancher2ha-l7.svg b/src/img/rancher/ha/rancher2ha-l7.svg new file mode 100644 index 00000000000..87041de905e --- /dev/null +++ b/src/img/rancher/ha/rancher2ha-l7.svg @@ -0,0 +1,2 @@ + +
Rancher
Rancher
Node 1
Node 1
Node 2
Node 2
Node 3
Node 3
rancher.yourdomain.com
rancher.yourdomain.com<br>
NGINX Ingress controller
(HTTP)
NGINX Ingress controller<br>(HTTP)<br>
NGINX Ingress controller
(HTTP)
NGINX Ingress controller<br>(HTTP)<br>
NGINX Ingress controller
(HTTP)
NGINX Ingress controller<br>(HTTP)<br>
Rancher
Rancher
Layer 7 Load Balancer
(HTTPS)
Layer 7 Load Balancer<br>(HTTPS)<br> \ No newline at end of file