Merge pull request #47 from MBishop17/loadbalance

initial check in of NGINX configuration doc. Also deleted HAProxy placeholder…
2026-09-25 04:28:15 +00:00 · 2018-04-27 21:46:54 -07:00
parent 4887ba4424 6ebcbde3a9
commit 1f2dcb9a65
11 changed files with 96 additions and 53 deletions
@@ -3,3 +3,5 @@ title: Installation
 weight: 50
 ---
 # Installation
+
+This section contains instructions for installing Rancher in development and production environments.
@@ -1,26 +0,0 @@
---
-title: Installation Scenarios
-weight: 100
---
-
-# Installation Scenarios
-
-## Single Node Scenarios
-
-In these scenarios, you'll install {{< product >}} on a single Linux host. These scenarios assume that you're starting fresh: no previously existing Kubernetes clusters.
-
-### Option 1: Single Container Install
-
-An install using one Linux host and a single Docker container. That's it!
-
-### Option 2: Single Container Install with External etcd
-
-### Option 3: Local Cluster Install
-
-## Multi Node Scenarios
-
-### Option 1 (and only): RKE Install
-
-## Special Scenarios
-
-### No Internet Connection Install
@@ -3,6 +3,8 @@ title: Load Balancer Configuration
 weight: 300
 ---

-# External Load Balancer Configuration
+# Load Balancer Configuration

 Following {{< product >}} installation, you have the option of configuring an external load balancer to direct cluster traffic.
+
+Rancher has tested a few load balancer configurations. Choose from the available options below. There is no "best" configuration. Choose the load balancer that best suits your needs.
@@ -4,6 +4,8 @@ weight: 305
 ---
 # Option 1-Amazon ALB

+Amazon Elastic Load Balancing offers a couple of different load balancers that we're tested. This procedure provides step-by-step instruction for configuring Amazon Application Load Balancer (ALB) with your Rancher Server.
+
 ## Objectives

 Configuring an Amazon ALB is a multistage process. We've broken it down into multiple tasks so that it's easy to follow.
@@ -25,7 +27,7 @@ Configuring an Amazon ALB is a multistage process. We've broken it down into mul
 	The Wizard in **3. Create Your ALB** only allows you to add a single target group. Go back into Amazon's console and add the second target group manually.


-## Create Target Groups
+### Create Target Groups

 Your first ALB configuration step is to create two target groups: one for HTTP, the other for HTTPS.

@@ -35,7 +37,7 @@ The document below will guide you through this process. Use the data in the tabl

 [Amazon Documentation: Create a Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-target-group.html)

-### Target Group 1 (HTTP)
+#### Target Group 1 (HTTP)

 Option                      | Setting
 ----------------------------|------------------------------------
@@ -47,7 +49,7 @@ VPC                         | Choose your VPC
 Protocol<br/>(Health Check) | `HTTP`


-### Target Group 2 (HTTPS)
+#### Target Group 2 (HTTPS)

 Option                      | Setting
 ----------------------------|------------------------------------
@@ -58,7 +60,7 @@ Target type                 | `instance`
 VPC                         | Choose your VPC
 Protocol<br/>(Health Check) | `HTTPS`

-## Register Targets
+### Register Targets

 Next, add your Kubernetes nodes assigned either the `controlplane` or `worker` role to _both_ of your target groups.

@@ -4,6 +4,8 @@ weight: 310
 ---
 # Option 2-Amazon NLB

+Amazon Elastic Load Balancing offers a couple of different load balancers that we're tested. This procedure provides step-by-step instruction for configuring Amazon Network Load Balancer (NLB) with your Rancher Server.
+
 ## Objectives

 Configuring an Amazon NLB is a multistage process. We've broken it down into multiple tasks so that it's easy to follow.
@@ -25,7 +27,7 @@ Configuring an Amazon NLB is a multistage process. We've broken it down into mul
 	The Wizard in **3. Create Your NLB** only allows you to add a single target group. Go back into Amazon's console and add the second target group manually.


-## Create Target Groups
+### Create Target Groups

 Your first NLB configuration step is to create two target groups for the TCP protocol: one on port 80, the other on port 443.

@@ -35,7 +37,7 @@ The document below will guide you through this process. Use the data in the tabl

 [Amazon Documentation: Create a Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-target-group.html)

-### Target Group 1 (TCP)
+#### Target Group 1 (TCP)

 Option                      | Setting
 ----------------------------|------------------------------------
@@ -47,7 +49,7 @@ VPC                         | Choose your VPC
 Protocol<br/>(Health Check) | `TCP`


-### Target Group 2 (TCP)
+#### Target Group 2 (TCP)

 Option                      | Setting
 ----------------------------|------------------------------------
@@ -58,7 +60,7 @@ Target type                 | `instance`
 VPC                         | Choose your VPC
 Protocol<br/>(Health Check) | `TCP`

-## Register Targets
+### Register Targets

 Next, add your Kubernetes nodes assigned either the `controlplane` or `worker` role to _both_ of your target groups.

@@ -1,7 +0,0 @@
---
-title: Option 4—HAProxy
-weight:
---
-# Option 4-HAProxy
-
-Yeah, you can use HAProxy too.
@@ -4,4 +4,65 @@ weight: 315
 ---
 # Option 3-NGINX

-NGINX is a popular application platform that can be used as a load balancer.
+NGINX is a popular application platform that can be used as a load balancer. Rancher supports use of NGINX with ngx_http_v2_module enabled, which isn't enabled by default. Use the following parameter when setting up NGINX to enable the module: `--with-http_v2_module`.
+
+>**Note:**
+>- NGINX is not supported if you are using SSL passthrough.
+>- If you are using self-signed certificates, the certificate and key must be signed by same certificate authority as `cattle-keys-server`.
+
+After the server is running, use the code sample below as a template when setting up your NGINX config file. Replace the variables with host names or IP addresses from your environment.
+
+```
+upstream rancher {
+    server <rancher_server_ip1>;
+    server <rancher_server_ip2>;
+}
+
+map $http_upgrade $connection_upgrade {
+    default Upgrade;
+    ''      close;
+}
+
+server {
+    listen 443 ssl http2 default_server;
+    server_name <FQDN>;
+
+    if ($host != $server_name) {
+        return 301 https://$server_name$request_uri;
+    }
+
+    ssl_certificate <CERT_FILE>;
+    ssl_certificate_key <KEY_FILE>;
+
+    location / {
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Forwarded-Port $server_port;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+
+        # mitigate HTTPoxy Vulnerability
+        # https://www.nginx.com/blog/mitigating-the-httpoxy-vulnerability-with-nginx/
+        proxy_set_header Proxy "";
+
+        proxy_http_version 1.1;
+
+        # This allows the ability for the execute shell window to remain open for up to 30 minutes. Without this parameter, the default is 1 minute and will automatically close.
+        proxy_connect_timeout 30s;
+        proxy_send_timeout 1800s;
+        proxy_read_timeout 1800s;
+
+        proxy_pass http://rancher;
+    }
+}
+
+server {
+    listen 80;
+    server_name <FQDN>;
+    return 301 https://$server_name$request_uri;
+}
+
+```
@@ -1,6 +1,10 @@
 ---
-title: Deploy Rancher
+title: Server Installation
 weight: 225
 ---

-# {{< product >}} Server Installation
+# Rancher Server Installation
+
+This section contains instructions for setting up Rancher Server in development and production environments. The section also contains supplementary documentation for configuring load balancers and SSL certificates to work with Rancher.
+
+Choose from the options below:
@@ -1,13 +1,16 @@
 ---
-title: Single Node Installation
+title: Option 1—Install by Docker Container
 weight: 250
+description: For development environments, we recommend installing Rancher by deploying a single Docker container.
 ---

-# Installing Rancher Using a Docker Container
+# Install by Docker Container
+
+For development environments, we recommend installing Rancher by deploying 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.

 ## Provision Linux Host

-Provision a single Linux host to use as a template to launch your {{< product >}}.
+Provision a single Linux host to use as a template to launch your {{< product >}} Server.

 ### Requirements

@@ -1,11 +1,11 @@
 ---
-title: Installing Rancher in a Kubernetes Cluster
+title: Option 2—Install by K8s Cluster Addon
 weight: 275
 ---

-# Installing Rancher in a Kubernetes Cluster
+# Install by Kubernetes Cluster Addon

-In high-availability installations, Rancher is installed on multiple nodes of a Kubernetes cluster. This multi-node configuration ensures that Rancher server is always available, even if your primary Rancher server goes down.
+For environments already running a Kubernettes cluster, you can deploy Rancher using the Rancher Kubernetes Engine (RKE). RKE is our light-weight, lightening-fast installer. During install, you can point RKE toward a config file that installs Rancher as an Addon.

 ## Provision Linux Hosts

@@ -7,8 +7,8 @@ weight: 200

 {{< product >}} Server has two different tags that you can use during installation.

-	`rancher/server:latest`: Our latest development builds. These builds are validated through our CI automation framework. These releases aren't for production environments.
+-	`rancher/rancher:latest`: Our latest development builds. These builds are validated through our CI automation framework. These releases aren't for production environments.

-	`rancher/server:stable`: Our latest stable release builds. This tag is recommended for production.
+-	`rancher/rancher:stable`: Our latest stable release builds. This tag is recommended for production.

 Please don't use any release with a `rc{n}` suffix. These rc builds are meant for the {{< product >}} team to test out builds.