Add tutorial to show how Rancher can be installed behind a HTTP proxy setup

2026-05-23 21:28:21 +00:00 · 2020-08-24 16:33:26 +02:00
parent 64b01f6944
commit 380e83cacf
4 changed files with 312 additions and 0 deletions
@@ -0,0 +1,14 @@
+---
+title: Installing Rancher behind an HTTP Proxy
+weight: 4
+---
+
+In a lot of enterprise environments servers or VMs running on premise do not have direct Internet access but must connect to external services through a HTTP(S) proxy for security reasons. This tutorial shows step by step how to setup up a highly available Rancher installation in such an environment.
+
+Alternatively, it is also possible to set up Rancher completely air-gapped without any Internet access. This process is described in detail in the [Rancher docs]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/air-gap/).
+
+# Installation Outline
+
+1. [Set up infrastructure]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/behind-proxy/prepare-nodes/)
+2. [Set up a Kubernetes cluster]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/behind-proxy/launch-kubernetes/)
+3. [Install Rancher]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/behind-proxy/install-rancher/)
@@ -0,0 +1,86 @@
+---
+title: 3. Install Rancher
+weight: 300
+---
+
+Now that you have a running RKE cluster, you can install Rancher in it. For security reasons all traffic to Rancher must be encrypted with TLS. For this tutorial you are going to automatically issue a self-signed certificate through [cert-manager](https://cert-manager.io/). In a real-world use-case you will likely use Let's Encrypt or provide your own certificate. For more details see [SSL configuration]({{<baseurl>}}/rancher/v2.x/en/installation/k8s-install/helm-rancher/#4-choose-your-ssl-configuration).
+
+> **Note:** These installation instructions assume you are using Helm 3.
+
+### Install cert-manager
+
+Add the cert-manager helm repository:
+
+```
+helm repo add jetstack https://charts.jetstack.io
+```
+
+Create a namespace for cert-manager:
+
+```
+kubectl create namespace cert-manager
+```
+
+Install the CustomResourceDefinitions of cert-manager:
+
+```
+kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.15.2/cert-manager.crds.yaml
+```
+
+And install it with Helm. Note that cert-manager also needs your proxy configured in case it needs to communicate with Let's Encrypt or other external certificate issuers:
+
+```
+helm upgrade --install cert-manager jetstack/cert-manager \
+  --namespace cert-manager --version v0.15.2 \
+  --set http_proxy=http://${proxy_host} \
+  --set https_proxy=http://${proxy_host} \
+  --set no_proxy=127.0.0.0/8\\,10.0.0.0/8\\,172.16.0.0/12\\,192.168.0.0/16
+```
+
+Now you should wait until cert-manager is finished starting up:
+
+```
+kubectl rollout status deployment -n cert-manager cert-manager
+kubectl rollout status deployment -n cert-manager cert-manager-webhook
+```
+
+### Install Rancher
+
+Next you can install Rancher itself. First add the helm repository:
+
+```
+helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
+```
+
+Create a namespace:
+
+```
+kubectl create namespace cattle-system
+```
+
+And install Rancher with Helm. Rancher also needs a proxy configuration so that it can communicate with external application catalogs or retrieve Kubernetes version update metadata:
+
+```
+helm upgrade --install rancher rancher-latest/rancher \
+   --namespace cattle-system \
+   --set hostname=rancher.example.com \
+   --set proxy=http://${proxy_host}
+```
+
+After waiting for the deployment to finish:
+
+```
+kubectl rollout status deployment -n cattle-system rancher
+```
+
+You can now navigate to `https://rancher.example.com` and start using Rancher.
+
+> **Note:** If you don't intend to send telemetry data, opt out [telemetry]({{<baseurl>}}/rancher/v2.x/en/faq/telemetry/) during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.
+
+### Additional Resources
+
+These resources could be helpful when installing Rancher:
+
+- [Rancher Helm chart options]({{<baseurl>}}/rancher/v2.x/en/installation/options/chart-options/)
+- [Adding TLS secrets]({{<baseurl>}}/rancher/v2.x/en/installation/options/tls-secrets/)
+- [Troubleshooting Rancher Kubernetes Installations]({{<baseurl>}}/rancher/v2.x/en/installation/options/troubleshooting/)
@@ -0,0 +1,151 @@
+---
+title: '2. Install Kubernetes'
+weight: 200
+---
+
+Once the infrastructure is ready, you can continue with setting up an RKE cluster to install Rancher in.
+
+### Installing Docker
+
+First, you have to install Docker and setup the HTTP proxy on all three Linux nodes. For this perform the following steps on all three nodes.
+
+For convenience export the IP address and port of your proxy into an environment variable and set up the HTTP_PROXY variables for your current shell:
+
+```
+export proxy_host="10.0.0.5:8888"
+export HTTP_PROXY=http://${proxy_host}
+export HTTPS_PROXY=http://${proxy_host}
+export NO_PROXY=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
+```
+
+Next configure apt to use this proxy when installing packages. If you are not using Ubuntu, you have to adapt this step accordingly:
+
+```
+cat <<'EOF' | sudo tee /etc/apt/apt.conf.d/proxy.conf > /dev/null
+Acquire::http::Proxy "http://${proxy_host}/";
+Acquire::https::Proxy "http://${proxy_host}/";
+EOF
+```
+
+Now you can install Docker:
+
+```
+curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh
+```
+
+Then ensure that your current user is able to access the Docker daemon without sudo:
+
+```
+sudo usermod -aG docker YOUR_USERNAME
+```
+
+And configure the Docker daemon to use the proxy to pull images:
+
+```
+sudo mkdir -p mkdir /etc/systemd/system/docker.service.d
+cat <<'EOF' | sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null
+[Service]
+Environment="HTTP_PROXY=http://${proxy_host}"
+Environment="HTTPS_PROXY=http://${proxy_host}"
+Environment="NO_PROXY=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
+EOF
+```
+
+To apply the configuration, restart the Docker daemon:
+
+```
+sudo systemctl daemon-reload
+sudo systemctl restart docker
+```
+
+### Creating the RKE Cluster
+
+You need several command line tools on the host where you have SSH access to the Linux nodes to create and interact with the cluster:
+
+*  [RKE CLI binary]({{<baseurl>}}/rke/latest/en/installation/#download-the-rke-binary)
+
+```
+sudo curl -fsSL -o /usr/local/bin/rke https://github.com/rancher/rke/releases/download/v1.1.4/rke_linux-amd64
+sudo chmod +x /usr/local/bin/rke
+```
+
+* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+
+```
+curl -LO "https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl"
+chmod +x ./kubectl
+sudo mv ./kubectl /usr/local/bin/kubectl
+```
+
+* [helm](https://helm.sh/docs/intro/install/)
+
+```
+curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3
+chmod +x get_helm.sh
+sudo ./get_helm.sh
+```
+
+Next, create a YAML file that describes the RKE cluster. Ensure that the IP addresses of the nodes and the SSH username are correct. For more information on the cluster YAML, have a look at the [RKE documentation]({{<baseurl>}}/rke/latest/en/example-yamls/).
+
+```
+nodes:
+  - address: 10.0.1.200
+    user: ubuntu
+    role: [controlplane,worker,etcd]
+  - address: 10.0.1.201
+    user: ubuntu
+    role: [controlplane,worker,etcd]
+  - address: 10.0.1.202
+    user: ubuntu
+    role: [controlplane,worker,etcd]
+
+services:
+  etcd:
+    backup_config:
+      interval_hours: 12
+      retention: 6
+```
+
+After that, you can create the Kubernetes cluster by running:
+
+```
+rke up --config rancher-cluster.yaml
+```
+
+RKE creates a state file called `rancher-cluster.rkestate`, this is needed if you want to perform updates, modify your cluster configuration or restore it from a backup. It also creates a `kube_config_rancher-cluster.yaml` file, that you can use to connect to the remote Kubernetes cluster locally with tools like kubectl or Helm. Make sure to save all of these files in a secure location, for example by putting them into a version control system.
+
+To have a look at your cluster run:
+
+```
+export KUBECONFIG=kube_config_rancher-cluster.yaml
+kubectl cluster-info
+kubectl get pods --all-namespaces
+```
+
+You can also verify that your external load balancer works, and the DNS entry is set up correctly. If you send a request to either, you should receive HTTP 404 response from the ingress controller:
+
+```
+$ curl 10.0.1.100
+default backend - 404
+$ curl rancher.example.com
+default backend - 404
+```
+
+### Save Your Files
+
+> **Important**
+> The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.
+
+Save a copy of the following files in a secure location:
+
+- `rancher-cluster.yml`: The RKE cluster configuration file.
+- `kube_config_rancher-cluster.yml`: The [Kubeconfig file]({{<baseurl>}}/rke/latest/en/kubeconfig/) for the cluster, this file contains credentials for full access to the cluster.
+- `rancher-cluster.rkestate`: The [Kubernetes Cluster State file]({{<baseurl>}}/rke/latest/en/installation/#kubernetes-cluster-state), this file contains the current state of the cluster including the RKE configuration and the certificates.
+
+> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.
+
+### Issues or errors?
+
+See the [Troubleshooting]({{<baseurl>}}/rancher/v2.x/en/installation/options/troubleshooting/) page.
+
+### [Next: Install Rancher](../install-rancher)
@@ -0,0 +1,61 @@
+---
+title: '1. Set up Infrastructure'
+weight: 100
+---
+
+In this section, you will provision the underlying infrastructure for your Rancher management server with internete access through a HTTP proxy.
+
+To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure:
+
+- **Three Linux nodes,** typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere.
+- **A load balancer** to direct front-end traffic to the three 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.
+
+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 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 suffer from [split brain](https://www.quora.com/What-is-split-brain-in-distributed-systems), requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes.
+
+### 1. Set up Linux Nodes
+
+These hosts will connect to the internet through an HTTP proxy.
+
+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 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 RKE tool will deploy an NGINX 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 NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX 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.
+
+### 3. 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 LB 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)
+
+
+### [Next: Set up a Kubernetes cluster]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/behind-proxy/launch-kubernetes/)