mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-25 12:38:05 +00:00
[2.0-2.4] Move files out of pages-for-subheaders
This commit is contained in:
Billy Tat
+9
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: Advanced
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/advanced-user-guides"/>
|
||||
</head>
|
||||
|
||||
The documents in this section contain resources for less common use cases.
|
||||
+38
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Installing Rancher in an Air Gapped Environment with Helm 2
|
||||
---
|
||||
|
||||
> After Helm 3 was released, the Rancher installation instructions were updated to use Helm 3.
|
||||
>
|
||||
> If you are using Helm 2, we recommend [migrating to Helm 3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) because it is simpler to use and more secure than Helm 2.
|
||||
>
|
||||
> This section provides a copy of the older instructions for installing Rancher on a Kubernetes cluster using Helm 2 in an air air gap environment, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
This section is about installations of Rancher server in an air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
|
||||
|
||||
Throughout the installations instructions, there will be _tabs_ for either a high availability Kubernetes installation or a single-node Docker installation.
|
||||
|
||||
### Air Gapped Kubernetes Installations
|
||||
|
||||
This section covers how to install Rancher on a Kubernetes cluster in an air gapped environment.
|
||||
|
||||
A Kubernetes installation is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.
|
||||
|
||||
### Air Gapped Docker Installations
|
||||
|
||||
These instructions also cover how to install Rancher on a single node in an air gapped environment.
|
||||
|
||||
The Docker installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a `docker run` command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.
|
||||
|
||||
> **Important:** If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation.
|
||||
|
||||
Instead of running the Docker installation, you have the option to follow the Kubernetes Install guide, but only use one node to install Rancher. Afterwards, you can scale up the etcd nodes in your Kubernetes cluster to make it a Kubernetes Installation.
|
||||
|
||||
## Installation Outline
|
||||
|
||||
- [1. Prepare your Node(s)](../../../other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md)
|
||||
- [2. Collect and Publish Images to your Private Registry](../../../other-installation-methods/air-gapped-helm-cli-install/publish-images.md)
|
||||
- [3. Launch a Kubernetes Cluster with RKE](../../../other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md)
|
||||
- [4. Install Rancher](../../../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)
|
||||
|
||||
### [Next: Prepare your Node(s)](../../../other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md)
|
||||
+2
-2
@@ -10,11 +10,11 @@ title: '2. Collect and Publish Images to your Private Registry'
|
||||
>
|
||||
> **Note:** Populating the private registry with images is the same process for HA and Docker installations, the differences in this section is based on whether or not you are planning to provision a Windows cluster or not.
|
||||
|
||||
By default, all images used to [provision Kubernetes clusters](../../../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md) or launch any [tools](../../../../../reference-guides/rancher-cluster-tools.md) in Rancher, e.g. monitoring, pipelines, alerts, are pulled from Docker Hub. In an air gap installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.
|
||||
By default, all images used to [provision Kubernetes clusters](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) or launch any [tools](../../../../../reference-guides/rancher-cluster-tools.md) in Rancher, e.g. monitoring, pipelines, alerts, are pulled from Docker Hub. In an air gap installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.
|
||||
|
||||
This section describes how to set up your private registry so that when you install Rancher, Rancher will pull all the required images from this registry.
|
||||
|
||||
By default, we provide the steps of how to populate your private registry assuming you are provisioning Linux only clusters, but if you plan on provisioning any [Windows clusters](../../../../../pages-for-subheaders/use-windows-clusters.md), there are separate instructions to support the images needed for a Windows cluster.
|
||||
By default, we provide the steps of how to populate your private registry assuming you are provisioning Linux only clusters, but if you plan on provisioning any [Windows clusters](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/use-windows-clusters.md), there are separate instructions to support the images needed for a Windows cluster.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Linux Only Clusters">
|
||||
|
||||
+4
-4
@@ -15,7 +15,7 @@ This section is about how to prepare your node(s) to install Rancher for your ai
|
||||
|
||||
### OS, Docker, Hardware, and Networking
|
||||
|
||||
Make sure that your node(s) fulfill the general [installation requirements.](../../../../../pages-for-subheaders/installation-requirements.md)
|
||||
Make sure that your node(s) fulfill the general [installation requirements.](../../../installation-requirements/installation-requirements.md)
|
||||
|
||||
### Private Registry
|
||||
|
||||
@@ -37,7 +37,7 @@ The following CLI tools are required for the Kubernetes Install. Make sure these
|
||||
|
||||
### OS, Docker, Hardware, and Networking
|
||||
|
||||
Make sure that your node(s) fulfill the general [installation requirements.](../../../../../pages-for-subheaders/installation-requirements.md)
|
||||
Make sure that your node(s) fulfill the general [installation requirements.](../../../installation-requirements/installation-requirements.md)
|
||||
|
||||
### Private Registry
|
||||
|
||||
@@ -70,7 +70,7 @@ Rancher recommends installing Rancher on a Kubernetes cluster. A highly availabl
|
||||
|
||||
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
|
||||
|
||||
View hardware and software requirements for each of your cluster nodes in [Requirements](../../../../../pages-for-subheaders/installation-requirements.md).
|
||||
View hardware and software requirements for each of your cluster nodes in [Requirements](../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
### B. Set up your Load Balancer
|
||||
|
||||
@@ -99,7 +99,7 @@ Instead of running the Docker installation, you have the option to follow the Ku
|
||||
|
||||
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
|
||||
|
||||
View hardware and software requirements for each of your cluster nodes in [Requirements](../../../../../pages-for-subheaders/installation-requirements.md).
|
||||
View hardware and software requirements for each of your cluster nodes in [Requirements](../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
+5
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: cluster.yml Templates for RKE add-on installs
|
||||
---
|
||||
|
||||
These templates are intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.
|
||||
+5
-5
@@ -9,18 +9,18 @@ A layer-7 load balancer can be beneficial if you want to centralize your TLS ter
|
||||
This install procedure walks you through deployment of Rancher using a single container, and then provides a sample configuration for a layer-7 NGINX load balancer.
|
||||
|
||||
> **Want to skip the external load balancer?**
|
||||
> See [Docker Installation](../../../../pages-for-subheaders/rancher-on-a-single-node-with-docker.md) instead.
|
||||
> See [Docker Installation](../../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) instead.
|
||||
|
||||
## Requirements for OS, Docker, Hardware, and Networking
|
||||
|
||||
Make sure that your node fulfills the general [installation requirements.](../../../../pages-for-subheaders/installation-requirements.md)
|
||||
Make sure that your node fulfills the general [installation requirements.](../../installation-requirements/installation-requirements.md)
|
||||
|
||||
## Installation Outline
|
||||
|
||||
|
||||
## 1. Provision Linux Host
|
||||
|
||||
Provision a single Linux host according to our [Requirements](../../../../pages-for-subheaders/installation-requirements.md) to launch your Rancher Server.
|
||||
Provision a single Linux host according to our [Requirements](../../installation-requirements/installation-requirements.md) to launch your Rancher Server.
|
||||
|
||||
## 2. Choose an SSL Option and Install Rancher
|
||||
|
||||
@@ -157,7 +157,7 @@ http {
|
||||
## What's Next?
|
||||
|
||||
- **Recommended:** Review [Single Node Backup and Restore](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md). Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use.
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md).
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
@@ -179,7 +179,7 @@ If you want to record all transactions with the Rancher API, enable the [API Aud
|
||||
|
||||
### Air Gap
|
||||
|
||||
If you are visiting this page to complete an [Air Gap Installation](../../../../pages-for-subheaders/air-gap-helm2.md), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `<REGISTRY.DOMAIN.COM:PORT>` with your private registry URL in front of `rancher/rancher:latest`.
|
||||
If you are visiting this page to complete an [Air Gap Installation](air-gap-helm2/air-gap-helm2.md), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `<REGISTRY.DOMAIN.COM:PORT>` with your private registry URL in front of `rancher/rancher:latest`.
|
||||
|
||||
**Example:**
|
||||
|
||||
|
||||
+1
-1
@@ -66,7 +66,7 @@ kubectl -n cattle-system logs -f rancher-84d886bdbb-s4s69 rancher-audit-log
|
||||
|
||||
#### Shipping the Audit Log
|
||||
|
||||
You can enable Rancher's built in log collection and shipping for the cluster to ship the audit and other services logs to a supported collection endpoint. See [Rancher Tools - Logging](../../../../pages-for-subheaders/cluster-logging.md) for details.
|
||||
You can enable Rancher's built in log collection and shipping for the cluster to ship the audit and other services logs to a supported collection endpoint. See [Rancher Tools - Logging](../../../../explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) for details.
|
||||
|
||||
## Audit Log Samples
|
||||
|
||||
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "1. Create Nodes and Load Balancer"
|
||||
---
|
||||
|
||||
Use your provider of choice to provision 3 nodes and a Load Balancer endpoint for your RKE install.
|
||||
|
||||
> **Note:** These nodes must be in the same region/datacenter. You may place these servers in separate availability zones.
|
||||
|
||||
### Node Requirements
|
||||
|
||||
View the supported operating systems and hardware/software/networking requirements for nodes running Rancher at [Node Requirements](../../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
View the OS requirements for RKE at [RKE Requirements](https://rancher.com/docs/rke/latest/en/os/)
|
||||
|
||||
### Load Balancer
|
||||
|
||||
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.
|
||||
|
||||
Configure a load balancer as a basic Layer 4 TCP forwarder. The exact configuration will vary depending on your environment.
|
||||
|
||||
>**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.
|
||||
|
||||
#### Examples
|
||||
|
||||
* [Nginx](nginx.md)
|
||||
* [Amazon NLB](nlb.md)
|
||||
|
||||
### [Next: Install Kubernetes with RKE](../kubernetes-rke/kubernetes-rke.md)
|
||||
+1
-1
@@ -21,7 +21,7 @@ After installing NGINX, you need to update the NGINX configuration file, `nginx.
|
||||
|
||||
1. Copy and paste the code sample below into your favorite text editor. Save it as `nginx.conf`.
|
||||
|
||||
2. From `nginx.conf`, replace both occurrences (port 80 and port 443) of `<IP_NODE_1>`, `<IP_NODE_2>`, and `<IP_NODE_3>` with the IPs of your [nodes](../../../../../../pages-for-subheaders/helm2-create-nodes-lb.md).
|
||||
2. From `nginx.conf`, replace both occurrences (port 80 and port 443) of `<IP_NODE_1>`, `<IP_NODE_2>`, and `<IP_NODE_3>` with the IPs of your [nodes](create-nodes-lb.md).
|
||||
|
||||
>**Note:** See [NGINX Documentation: TCP and UDP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/) for all configuration options.
|
||||
|
||||
|
||||
+65
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: "Initialize Helm: Install the Tiller Service"
|
||||
description: "With Helm, you can create configurable deployments instead of using static files. In order to use Helm, the Tiller service needs to be installed on your cluster."
|
||||
---
|
||||
|
||||
Helm is the package management tool of choice for Kubernetes. Helm "charts" provide templating syntax for Kubernetes YAML manifest documents. With Helm we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at [https://helm.sh/](https://helm.sh/). To be able to use Helm, the server-side component `tiller` needs to be installed on your cluster.
|
||||
|
||||
For systems without direct internet access, see [Helm - Air Gap](../../../../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) for install details.
|
||||
|
||||
Refer to the [Helm version requirements](../../../../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
> **Note:** The installation instructions assume you are using Helm 2. The instructions will be updated for Helm 3 soon. In the meantime, if you want to use Helm 3, refer to [these instructions.](https://github.com/ibrokethecloud/rancher-helm3)
|
||||
|
||||
### Install Tiller on the Cluster
|
||||
|
||||
> **Important:** Due to an issue with Helm v2.12.0 and cert-manager, please use Helm v2.12.1 or higher.
|
||||
|
||||
Helm installs the `tiller` service on your cluster to manage charts. Since RKE enables RBAC by default we will need to use `kubectl` to create a `serviceaccount` and `clusterrolebinding` so `tiller` has permission to deploy to the cluster.
|
||||
|
||||
* Create the `ServiceAccount` in the `kube-system` namespace.
|
||||
* Create the `ClusterRoleBinding` to give the `tiller` account access to the cluster.
|
||||
* Finally use `helm` to install the `tiller` service
|
||||
|
||||
```plain
|
||||
kubectl -n kube-system create serviceaccount tiller
|
||||
|
||||
kubectl create clusterrolebinding tiller \
|
||||
--clusterrole=cluster-admin \
|
||||
--serviceaccount=kube-system:tiller
|
||||
|
||||
helm init --service-account tiller
|
||||
|
||||
# Users in China: You will need to specify a specific tiller-image in order to initialize tiller.
|
||||
# The list of tiller image tags are available here: https://dev.aliyun.com/detail.html?spm=5176.1972343.2.18.ErFNgC&repoId=62085.
|
||||
# When initializing tiller, you'll need to pass in --tiller-image
|
||||
|
||||
helm init --service-account tiller \
|
||||
--tiller-image registry.cn-hangzhou.aliyuncs.com/google_containers/tiller:<tag>
|
||||
```
|
||||
|
||||
> **Note:** This`tiller`install has full cluster access, which should be acceptable if the cluster is dedicated to Rancher server. See the [Helm docs](https://docs.helm.sh/using_helm/#role-based-access-control) for instructions on restricting `tiller` access to suit your security requirements.
|
||||
|
||||
### Test your Tiller installation
|
||||
|
||||
Run the following command to verify the installation of `tiller` on your cluster:
|
||||
|
||||
```
|
||||
kubectl -n kube-system rollout status deploy/tiller-deploy
|
||||
Waiting for deployment "tiller-deploy" rollout to finish: 0 of 1 updated replicas are available...
|
||||
deployment "tiller-deploy" successfully rolled out
|
||||
```
|
||||
|
||||
And run the following command to validate Helm can talk to the `tiller` service:
|
||||
|
||||
```
|
||||
helm version
|
||||
Client: &version.Version{SemVer:"v2.12.1", GitCommit:"02a47c7249b1fc6d8fd3b94e6b4babf9d818144e", GitTreeState:"clean"}
|
||||
Server: &version.Version{SemVer:"v2.12.1", GitCommit:"02a47c7249b1fc6d8fd3b94e6b4babf9d818144e", GitTreeState:"clean"}
|
||||
```
|
||||
|
||||
### Issues or errors?
|
||||
|
||||
See the [Troubleshooting](troubleshooting.md) page.
|
||||
|
||||
### [Next: Install Rancher](../helm-rancher/helm-rancher.md)
|
||||
+1
-1
@@ -19,4 +19,4 @@ helm version --server
|
||||
Error: could not find tiller
|
||||
```
|
||||
|
||||
When you have confirmed that `tiller` has been removed, please follow the steps provided in [Initialize Helm (Install tiller)](../../../../../../pages-for-subheaders/helm2-helm-init.md) to install `tiller` with the correct `ServiceAccount`.
|
||||
When you have confirmed that `tiller` has been removed, please follow the steps provided in [Initialize Helm (Install tiller)](helm-init.md) to install `tiller` with the correct `ServiceAccount`.
|
||||
|
||||
+3
-3
@@ -48,13 +48,13 @@ title: Chart Options
|
||||
|
||||
Enabling the [API Audit Log](../../enable-api-audit-log.md).
|
||||
|
||||
You can collect this log as you would any container log. Enable the [Logging service under Rancher Tools](../../../../../../pages-for-subheaders/cluster-logging.md) for the `System` Project on the Rancher server cluster.
|
||||
You can collect this log as you would any container log. Enable the [Logging service under Rancher Tools](../../../../../../explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) for the `System` Project on the Rancher server cluster.
|
||||
|
||||
```plain
|
||||
--set auditLog.level=1
|
||||
```
|
||||
|
||||
By default enabling Audit Logging will create a sidecar container in the Rancher pod. This container (`rancher-audit-log`) will stream the log to `stdout`. You can collect this log as you would any container log. When using the sidecar as the audit log destination, the `hostPath`, `maxAge`, `maxBackups`, and `maxSize` options do not apply. It's advised to use your OS or Docker daemon's log rotation features to control disk space use. Enable the [Logging service under Rancher Tools](../../../../../../pages-for-subheaders/cluster-logging.md/) for the Rancher server cluster or System Project.
|
||||
By default enabling Audit Logging will create a sidecar container in the Rancher pod. This container (`rancher-audit-log`) will stream the log to `stdout`. You can collect this log as you would any container log. When using the sidecar as the audit log destination, the `hostPath`, `maxAge`, `maxBackups`, and `maxSize` options do not apply. It's advised to use your OS or Docker daemon's log rotation features to control disk space use. Enable the [Logging service under Rancher Tools](../../../../../../explanations/integrations-in-rancher/cluster-logging/cluster-logging.md/) for the Rancher server cluster or System Project.
|
||||
|
||||
Set the `auditLog.destination` to `hostPath` to forward logs to volume shared with the host system instead of streaming to a sidecar container. When setting the destination to `hostPath` you may want to adjust the other auditLog parameters for log rotation.
|
||||
|
||||
@@ -142,7 +142,7 @@ kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-
|
||||
For details on installing Rancher with a private registry, see:
|
||||
|
||||
- [Air Gap: Docker Install](../../../../../../reference-guides/installation-references/tls-settings.md)
|
||||
- [Air Gap: Kubernetes Install](../../../../../../pages-for-subheaders/air-gap-helm2.md)
|
||||
- [Air Gap: Kubernetes Install](../../air-gap-helm2/air-gap-helm2.md)
|
||||
|
||||
|
||||
### External TLS Termination
|
||||
|
||||
+231
@@ -0,0 +1,231 @@
|
||||
---
|
||||
title: "4. Install Rancher"
|
||||
---
|
||||
|
||||
Rancher installation is managed using the Helm package manager for Kubernetes. Use `helm` to install the prerequisite and charts to install Rancher.
|
||||
|
||||
For systems without direct internet access, see [Air Gap: Kubernetes install](../../air-gap-helm2/install-rancher.md).
|
||||
|
||||
Refer to the [Helm version requirements](../../../../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
> **Note:** The installation instructions assume you are using Helm 2. The instructions will be updated for Helm 3 soon. In the meantime, if you want to use Helm 3, refer to [these instructions.](https://github.com/ibrokethecloud/rancher-helm3)
|
||||
|
||||
### Add the Helm Chart Repository
|
||||
|
||||
Use `helm repo add` command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see [Choosing a Version of Rancher](../../../../resources/choose-a-rancher-version.md).
|
||||
|
||||
- Latest: Recommended for trying out the newest features
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
```
|
||||
- Stable: Recommended for production environments
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
- Alpha: Experimental preview of upcoming releases.
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
Note: Upgrades are not supported to, from, or between Alphas.
|
||||
|
||||
### Choose your SSL Configuration
|
||||
|
||||
Rancher Server is designed to be secure by default and requires SSL/TLS configuration.
|
||||
|
||||
There are three recommended options for the source of the certificate.
|
||||
|
||||
> **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer](chart-options.md#external-tls-termination).
|
||||
|
||||
| Configuration | Chart option | Description | Requires cert-manager |
|
||||
|-----|-----|-----|-----|
|
||||
| [Rancher Generated Certificates](#rancher-generated-certificates) | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)<br/>This is the **default** | [yes](#optional-install-cert-manager) |
|
||||
| [Let’s Encrypt](#let-s-encrypt) | `ingress.tls.source=letsEncrypt` | Use [Let's Encrypt](https://letsencrypt.org/) to issue a certificate | [yes](#optional-install-cert-manager) |
|
||||
| [Certificates from Files](#certificates-from-files) | `ingress.tls.source=secret` | Use your own certificate files by creating Kubernetes Secret(s) | no |
|
||||
|
||||
### Optional: Install cert-manager
|
||||
|
||||
**Note:** cert-manager is only required for certificates issued by Rancher's generated CA (`ingress.tls.source=rancher`) and Let's Encrypt issued certificates (`ingress.tls.source=letsEncrypt`). You should skip this step if you are using your own certificate files (option `ingress.tls.source=secret`) or if you use [TLS termination on an External Load Balancer](chart-options.md#external-tls-termination).
|
||||
|
||||
> **Important:**
|
||||
> Due to an issue with Helm v2.12.0 and cert-manager, please use Helm v2.12.1 or higher.
|
||||
|
||||
> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation](../../../../resources/upgrade-cert-manager.md).
|
||||
|
||||
Rancher relies on [cert-manager](https://github.com/jetstack/cert-manager) to issue certificates from Rancher's own generated CA or to request Let's Encrypt certificates.
|
||||
|
||||
These instructions are adapted from the [official cert-manager documentation](https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html#installing-with-helm).
|
||||
|
||||
|
||||
1. Install the CustomResourceDefinition resources separately
|
||||
```plain
|
||||
kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml
|
||||
```
|
||||
|
||||
1. Create the namespace for cert-manager
|
||||
```plain
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
1. Label the cert-manager namespace to disable resource validation
|
||||
```plain
|
||||
kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true
|
||||
```
|
||||
|
||||
1. Add the Jetstack Helm repository
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
```
|
||||
|
||||
1. Update your local Helm chart repository cache
|
||||
```plain
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Install the cert-manager Helm chart
|
||||
```plain
|
||||
helm install \
|
||||
--name cert-manager \
|
||||
--namespace cert-manager \
|
||||
--version v0.14.2 \
|
||||
jetstack/cert-manager
|
||||
```
|
||||
|
||||
Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:
|
||||
|
||||
```
|
||||
kubectl get pods --namespace cert-manager
|
||||
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
cert-manager-7cbdc48784-rpgnt 1/1 Running 0 3m
|
||||
cert-manager-webhook-5b5dd6999-kst4x 1/1 Running 0 3m
|
||||
cert-manager-cainjector-3ba5cd2bcd-de332x 1/1 Running 0 3m
|
||||
```
|
||||
|
||||
If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check the [troubleshooting](https://docs.cert-manager.io/en/latest/getting-started/troubleshooting.html) guide.
|
||||
|
||||
<br/>
|
||||
|
||||
#### Rancher Generated Certificates
|
||||
|
||||
> **Note:** You need to have [cert-manager](#optional-install-cert-manager) installed before proceeding.
|
||||
|
||||
The default is for Rancher to generate a CA and uses `cert-manager` to issue the certificate for access to the Rancher server interface. Because `rancher` is the default option for `ingress.tls.source`, we are not specifying `ingress.tls.source` when running the `helm install` command.
|
||||
|
||||
- Set the `hostname` to the DNS name you pointed at your load balancer.
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
```
|
||||
helm install rancher-<CHART_REPO>/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
Wait for Rancher to be rolled out:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
#### Let's Encrypt
|
||||
|
||||
> **Note:** You need to have [cert-manager](#optional-install-cert-manager) installed before proceeding.
|
||||
|
||||
This option uses `cert-manager` to automatically request and renew [Let's Encrypt](https://letsencrypt.org/) certificates. This is a free service that provides you with a valid certificate as Let's Encrypt is a trusted CA. This configuration uses HTTP validation (`HTTP-01`) so the load balancer must have a public DNS record and be accessible from the internet.
|
||||
|
||||
In the following command,
|
||||
|
||||
- Set `hostname` to the public DNS record that resolves to your load balancer.
|
||||
- Set `ingress.tls.source` to `letsEncrypt`.
|
||||
- Set `letsEncrypt.email` to the email address used for communication about your certificate (for example, expiry notices).
|
||||
- Set `letsEncrypt.ingress.class` to whatever your ingress controller is, e.g., `traefik`, `nginx`, `haproxy`, etc.
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
```
|
||||
helm install rancher-<CHART_REPO>/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=letsEncrypt \
|
||||
--set letsEncrypt.email=me@example.org \
|
||||
--set letsEncrypt.ingress.class=nginx
|
||||
```
|
||||
|
||||
Wait for Rancher to be rolled out:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
#### Certificates from Files
|
||||
|
||||
Create Kubernetes secrets from your own certificates for Rancher to use.
|
||||
|
||||
|
||||
> **Note:** The `Common Name` or a `Subject Alternative Names` entry in the server certificate must match the `hostname` option, or the ingress controller will fail to configure correctly. Although an entry in the `Subject Alternative Names` is technically required, having a matching `Common Name` maximizes compatibility with older browsers/applications. If you want to check if your certificates are correct, see [How do I check Common Name and Subject Alternative Names in my server certificate?](../../../../../../faq/technical-items.md#how-do-i-check-common-name-and-subject-alternative-names-in-my-server-certificate)
|
||||
|
||||
- Set `hostname` and set `ingress.tls.source` to `secret`.
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
```
|
||||
helm install rancher-<CHART_REPO>/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=secret
|
||||
```
|
||||
|
||||
If you are using a Private CA signed certificate , add `--set privateCA=true` to the command:
|
||||
|
||||
```
|
||||
helm install rancher-<CHART_REPO>/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=secret
|
||||
--set privateCA=true
|
||||
```
|
||||
|
||||
Now that Rancher is deployed, see [Adding TLS Secrets](tls-secrets.md) to publish the certificate files so Rancher and the ingress controller can use them.
|
||||
|
||||
After adding the secrets, check if Rancher was rolled out successfully:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
If you see the following error: `error: deployment "rancher" exceeded its progress deadline`, you can check the status of the deployment by running the following command:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system get deploy rancher
|
||||
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
|
||||
rancher 3 3 3 3 3m
|
||||
```
|
||||
|
||||
It should show the same count for `DESIRED` and `AVAILABLE`.
|
||||
|
||||
### Advanced Configurations
|
||||
|
||||
The Rancher chart configuration has many options for customizing the install to suit your specific environment. Here are some common advanced scenarios.
|
||||
|
||||
* [HTTP Proxy](../../../../../../reference-guides/installation-references/helm-chart-options.md)
|
||||
* [Private Docker Image Registry](../../../../../../reference-guides/installation-references/helm-chart-options.md#private-registry-and-air-gap-installs)
|
||||
* [TLS Termination on an External Load Balancer](chart-options.md#external-tls-termination)
|
||||
|
||||
See the [Chart Options](chart-options.md) for the full list of options.
|
||||
|
||||
### Save your options
|
||||
|
||||
Make sure you save the `--set` options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm.
|
||||
|
||||
### Finishing Up
|
||||
|
||||
That's it you should have a functional Rancher server. Point a browser at the hostname you picked and you should be greeted by the colorful login page.
|
||||
|
||||
Doesn't work? Take a look at the [Troubleshooting](troubleshooting.md) Page
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Kubernetes Installation Using Helm 2
|
||||
---
|
||||
|
||||
> After Helm 3 was released, the Rancher installation instructions were updated to use Helm 3.
|
||||
>
|
||||
> If you are using Helm 2, we recommend [migrating to Helm 3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) because it is simpler to use and more secure than Helm 2.
|
||||
>
|
||||
> This section provides a copy of the older high-availability Kubernetes Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
For production environments, we recommend installing Rancher in a high-availability configuration so that your user base can always access Rancher Server. When installed in a Kubernetes cluster, Rancher will integrate with the cluster's etcd database and take advantage of Kubernetes scheduling for high-availability.
|
||||
|
||||
This procedure walks you through setting up a 3-node cluster with Rancher Kubernetes Engine (RKE) and installing the Rancher chart with the Helm package manager.
|
||||
|
||||
> **Important:** 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.
|
||||
|
||||
> **Important:** For the best performance, 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](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) for running your workloads.
|
||||
|
||||
## Recommended Architecture
|
||||
|
||||
- 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.
|
||||
|
||||
<figcaption>Kubernetes Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers</figcaption>
|
||||
|
||||
|
||||
<sup>Kubernetes Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers</sup>
|
||||
|
||||
## Required 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](https://rancher.com/docs/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](../../../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
## Installation Outline
|
||||
|
||||
- [Create Nodes and Load Balancer](create-nodes-lb/create-nodes-lb.md)
|
||||
- [Install Kubernetes with RKE](kubernetes-rke/kubernetes-rke.md)
|
||||
- [Initialize Helm (tiller)](helm-init/helm-init.md)
|
||||
- [Install Rancher](helm-rancher/helm-rancher.md)
|
||||
|
||||
## Additional Install Options
|
||||
|
||||
- [Migrating from a Kubernetes Install with an RKE Add-on](../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md)
|
||||
|
||||
## Previous Methods
|
||||
|
||||
[RKE add-on install](rke-add-on/rke-add-on.md)
|
||||
|
||||
> **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
> Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
> If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to move to using the Helm chart.
|
||||
+131
@@ -0,0 +1,131 @@
|
||||
---
|
||||
title: "2. Install Kubernetes with RKE"
|
||||
---
|
||||
|
||||
Use RKE to install Kubernetes with a high availability etcd configuration.
|
||||
|
||||
>**Note:** For systems without direct internet access see [Air Gap: Kubernetes install](../../air-gap-helm2/air-gap-helm2.md) for install details.
|
||||
|
||||
### Create the `rancher-cluster.yml` File
|
||||
|
||||
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.
|
||||
|
||||
> **Note:** 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.
|
||||
|
||||
|
||||
```yaml
|
||||
nodes:
|
||||
- address: 165.227.114.63
|
||||
internal_address: 172.16.22.12
|
||||
user: ubuntu
|
||||
role: [controlplane,worker,etcd]
|
||||
- address: 165.227.116.167
|
||||
internal_address: 172.16.32.37
|
||||
user: ubuntu
|
||||
role: [controlplane,worker,etcd]
|
||||
- address: 165.227.127.226
|
||||
internal_address: 172.16.42.73
|
||||
user: ubuntu
|
||||
role: [controlplane,worker,etcd]
|
||||
|
||||
services:
|
||||
etcd:
|
||||
snapshot: true
|
||||
creation: 6h
|
||||
retention: 24h
|
||||
```
|
||||
|
||||
#### Common RKE Nodes Options
|
||||
|
||||
| Option | Required | Description |
|
||||
| --- | --- | --- |
|
||||
| `address` | yes | The public DNS or IP address |
|
||||
| `user` | yes | A user that can run docker commands |
|
||||
| `role` | yes | List of Kubernetes roles assigned to the node |
|
||||
| `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
|
||||
|
||||
RKE has many configuration options for customizing the install to suit your specific environment.
|
||||
|
||||
Please see the [RKE Documentation](https://rancher.com/docs/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](../../tune-etcd-for-large-installs.md).
|
||||
|
||||
### Run RKE
|
||||
|
||||
```
|
||||
rke up --config ./rancher-cluster.yml
|
||||
```
|
||||
|
||||
When finished, it should end with the line: `Finished building Kubernetes cluster successfully`.
|
||||
|
||||
### Testing Your Cluster
|
||||
|
||||
RKE should have created a file `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_<FILE_NAME>.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`.
|
||||
|
||||
```
|
||||
export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml
|
||||
```
|
||||
|
||||
Test your connectivity with `kubectl` and see if all your nodes are in `Ready` state.
|
||||
|
||||
```
|
||||
kubectl get nodes
|
||||
|
||||
NAME STATUS ROLES AGE VERSION
|
||||
165.227.114.63 Ready controlplane,etcd,worker 11m v1.13.5
|
||||
165.227.116.167 Ready controlplane,etcd,worker 11m v1.13.5
|
||||
165.227.127.226 Ready controlplane,etcd,worker 11m v1.13.5
|
||||
```
|
||||
|
||||
### Check the Health of Your Cluster Pods
|
||||
|
||||
Check that all the required pods and containers are healthy are ready to continue.
|
||||
|
||||
* Pods are in `Running` or `Completed` state.
|
||||
* `READY` column shows all the containers are running (i.e. `3/3`) for pods with `STATUS` `Running`
|
||||
* Pods with `STATUS` `Completed` are run-once Jobs. For these pods `READY` should be `0/1`.
|
||||
|
||||
```
|
||||
kubectl get pods --all-namespaces
|
||||
|
||||
NAMESPACE NAME READY STATUS RESTARTS AGE
|
||||
ingress-nginx nginx-ingress-controller-tnsn4 1/1 Running 0 30s
|
||||
ingress-nginx nginx-ingress-controller-tw2ht 1/1 Running 0 30s
|
||||
ingress-nginx nginx-ingress-controller-v874b 1/1 Running 0 30s
|
||||
kube-system canal-jp4hz 3/3 Running 0 30s
|
||||
kube-system canal-z2hg8 3/3 Running 0 30s
|
||||
kube-system canal-z6kpw 3/3 Running 0 30s
|
||||
kube-system kube-dns-7588d5b5f5-sf4vh 3/3 Running 0 30s
|
||||
kube-system kube-dns-autoscaler-5db9bbb766-jz2k6 1/1 Running 0 30s
|
||||
kube-system metrics-server-97bc649d5-4rl2q 1/1 Running 0 30s
|
||||
kube-system rke-ingress-controller-deploy-job-bhzgm 0/1 Completed 0 30s
|
||||
kube-system rke-kubedns-addon-deploy-job-gl7t4 0/1 Completed 0 30s
|
||||
kube-system rke-metrics-addon-deploy-job-7ljkc 0/1 Completed 0 30s
|
||||
kube-system rke-network-plugin-deploy-job-6pbgj 0/1 Completed 0 30s
|
||||
```
|
||||
|
||||
### 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](https://rancher.com/docs/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](https://rancher.com/docs/rke/latest/en/installation/#kubernetes-cluster-state), this file contains credentials for full access to the cluster.<br/><br/>_The Kubernetes Cluster State file is only created when using RKE v0.2.0 or higher._
|
||||
|
||||
> **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](troubleshooting.md) page.
|
||||
|
||||
### [Next: Initialize Helm (Install tiller)](../helm-init/helm-init.md)
|
||||
+380
@@ -0,0 +1,380 @@
|
||||
---
|
||||
title: Kubernetes Install with External Load Balancer (TCP/Layer 4)
|
||||
---
|
||||
import SslFaqHa from '@site/src/components/SslFaqHa'
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a High-availability Kubernetes install with an RKE add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to move to using the Helm chart.
|
||||
|
||||
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 4 load balancer (TCP)
|
||||
- [NGINX ingress controller with SSL termination (HTTPS)](https://kubernetes.github.io/ingress-nginx/)
|
||||
|
||||
In a Kubernetes setup that uses a layer 4 load balancer, the load balancer accepts Rancher client connections over the TCP/UDP protocols (i.e., the transport level). The load balancer then forwards these connections to individual cluster nodes without reading the request itself. Because the load balancer cannot read the packets it's forwarding, the routing decisions it can make are limited.
|
||||
|
||||
<sup>Kubernetes Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers</sup>
|
||||
|
||||
|
||||
|
||||
<br/>
|
||||
|
||||
## 1. Provision Linux Hosts
|
||||
|
||||
Provision three Linux hosts according to our [Requirements](../../../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
## 2. Configure Load Balancer
|
||||
|
||||
We will be using NGINX as our Layer 4 Load Balancer (TCP). NGINX will forward all connections to one of your Rancher nodes. If you want to use Amazon NLB, you can skip this step and use [Amazon NLB configuration](nlb.md)
|
||||
|
||||
>**Note:**
|
||||
> In this configuration, the load balancer is positioned in front of your Linux hosts. The load balancer can be any host that you have available that's capable of running NGINX.
|
||||
>
|
||||
>One caveat: do not use one of your Rancher nodes as the load balancer.
|
||||
|
||||
### A. Install NGINX
|
||||
|
||||
Start by installing NGINX on your load balancer host. NGINX has packages available for all known operating systems. For help installing NGINX, refer to their [install documentation](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/).
|
||||
|
||||
The `stream` module is required, which is present when using the official NGINX packages. Please refer to your OS documentation how to install and enable the NGINX `stream` module on your operating system.
|
||||
|
||||
### B. Create NGINX Configuration
|
||||
|
||||
After installing NGINX, you need to update the NGINX config file, `nginx.conf`, with the IP addresses for your nodes.
|
||||
|
||||
1. Copy and paste the code sample below into your favorite text editor. Save it as `nginx.conf`.
|
||||
|
||||
2. From `nginx.conf`, replace `IP_NODE_1`, `IP_NODE_2`, and `IP_NODE_3` with the IPs of your [Linux hosts](#1-provision-linux-hosts).
|
||||
|
||||
>**Note:** This Nginx configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - TCP and UDP Load Balancer](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/).
|
||||
|
||||
**Example NGINX config:**
|
||||
```
|
||||
worker_processes 4;
|
||||
worker_rlimit_nofile 40000;
|
||||
|
||||
events {
|
||||
worker_connections 8192;
|
||||
}
|
||||
|
||||
http {
|
||||
server {
|
||||
listen 80;
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
}
|
||||
|
||||
stream {
|
||||
upstream rancher_servers {
|
||||
least_conn;
|
||||
server IP_NODE_1:443 max_fails=3 fail_timeout=5s;
|
||||
server IP_NODE_2:443 max_fails=3 fail_timeout=5s;
|
||||
server IP_NODE_3:443 max_fails=3 fail_timeout=5s;
|
||||
}
|
||||
server {
|
||||
listen 443;
|
||||
proxy_pass rancher_servers;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Save `nginx.conf` to your load balancer at the following path: `/etc/nginx/nginx.conf`.
|
||||
|
||||
4. Load the updates to your NGINX configuration by running the following command:
|
||||
|
||||
```
|
||||
# nginx -s reload
|
||||
```
|
||||
|
||||
### Option - Run NGINX as Docker container
|
||||
|
||||
Instead of installing NGINX as a package on the operating system, you can rather run it as a Docker container. Save the edited **Example NGINX config** as `/etc/nginx.conf` and run the following command to launch the NGINX container:
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /etc/nginx.conf:/etc/nginx/nginx.conf \
|
||||
nginx:1.14
|
||||
```
|
||||
|
||||
## 3. Configure DNS
|
||||
|
||||
Choose a fully qualified domain name (FQDN) that you want to use to access Rancher (e.g., `rancher.yourdomain.com`).<br/><br/>
|
||||
|
||||
1. Log into your DNS server a create a `DNS A` record that points to the IP address of your [load balancer](#2-configure-load-balancer).
|
||||
|
||||
2. Validate that the `DNS A` is working correctly. Run the following command from any terminal, replacing `HOSTNAME.DOMAIN.COM` with your chosen FQDN:
|
||||
|
||||
`nslookup HOSTNAME.DOMAIN.COM`
|
||||
|
||||
**Step Result:** Terminal displays output similar to the following:
|
||||
|
||||
```
|
||||
$ nslookup rancher.yourdomain.com
|
||||
Server: YOUR_HOSTNAME_IP_ADDRESS
|
||||
Address: YOUR_HOSTNAME_IP_ADDRESS#53
|
||||
|
||||
Non-authoritative answer:
|
||||
Name: rancher.yourdomain.com
|
||||
Address: HOSTNAME.DOMAIN.COM
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
## 4. Install RKE
|
||||
|
||||
RKE (Rancher Kubernetes Engine) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. We will use RKE to setup our cluster and run Rancher.
|
||||
|
||||
1. Follow the [RKE Install](https://rancher.com/docs/rke/latest/en/installation) instructions.
|
||||
|
||||
2. Confirm that RKE is now executable by running the following command:
|
||||
|
||||
```
|
||||
rke --version
|
||||
```
|
||||
|
||||
## 5. Download RKE 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 self-signed certificate<br/> `3-node-certificate.yml`](../../../cluster-yml-templates/node-certificate.md)
|
||||
- [Template for certificate signed by recognized CA<br/> `3-node-certificate-recognizedca.yml`](../../../cluster-yml-templates/node-certificate-recognizedca.md)
|
||||
|
||||
>**Advanced Config Options:**
|
||||
>
|
||||
>- Want records of all transactions with the Rancher API? Enable the [API Auditing](../../../enable-api-audit-log.md) feature by editing your RKE config file. For more information, see how to enable it in [your RKE config file](../api-auditing.md).
|
||||
>- Want to know the other config options available for your RKE template? See the [RKE Documentation: Config Options](https://rancher.com/docs/rke/latest/en/config-options/).
|
||||
|
||||
|
||||
2. Rename the file to `rancher-cluster.yml`.
|
||||
|
||||
## 6. Configure Nodes
|
||||
|
||||
Once you have the `rancher-cluster.yml` config file template, edit the nodes section to point toward your Linux hosts.
|
||||
|
||||
1. Open `rancher-cluster.yml` in your favorite text editor.
|
||||
|
||||
1. Update the `nodes` section with the information of your [Linux hosts](#1-provision-linux-hosts).
|
||||
|
||||
For each node in your cluster, update the following placeholders: `IP_ADDRESS_X` and `USER`. The specified user should be able to access the Docker socket, you can test this by logging in with the specified user and run `docker ps`.
|
||||
|
||||
>**Note:**
|
||||
> When using RHEL/CentOS, the SSH user can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565. See [Operating System Requirements](https://rancher.com/docs/rke/latest/en/installation/os#redhat-enterprise-linux-rhel-centos) >for RHEL/CentOS specific requirements.
|
||||
|
||||
nodes:
|
||||
# The IP address or hostname of the node
|
||||
- address: IP_ADDRESS_1
|
||||
# User that can login to the node and has access to the Docker socket (i.e. can execute `docker ps` on the node)
|
||||
# When using RHEL/CentOS, this can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
# Path the SSH key that can be used to access to node with the specified user
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_2
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_3
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
|
||||
1. **Optional:** By default, `rancher-cluster.yml` is configured to take backup snapshots of your data. To disable these snapshots, change the `backup` directive setting to `false`, as depicted below.
|
||||
|
||||
services:
|
||||
etcd:
|
||||
backup: false
|
||||
|
||||
|
||||
## 7. Configure Certificates
|
||||
|
||||
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Option A—Bring Your Own Certificate: Self-Signed</summary>
|
||||
|
||||
>**Prerequisites:**
|
||||
>Create a self-signed certificate.
|
||||
>
|
||||
>- The certificate files must be in PEM format.
|
||||
>- The certificate files must be encoded in [base64](#base64).
|
||||
>- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates.
|
||||
|
||||
1. In `kind: Secret` with `name: cattle-keys-ingress`:
|
||||
|
||||
* Replace `<BASE64_CRT>` with the base64 encoded string of the Certificate file (usually called `cert.pem` or `domain.crt`)
|
||||
* Replace `<BASE64_KEY>` with the base64 encoded string of the Certificate Key file (usually called `key.pem` or `domain.key`)
|
||||
|
||||
>**Note:**
|
||||
> The base64 encoded string should be on the same line as `tls.crt` or `tls.key`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
**Step Result:** After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-ingress
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
|
||||
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
|
||||
```
|
||||
|
||||
2. In `kind: Secret` with `name: cattle-keys-server`, replace `<BASE64_CA>` with the base64 encoded string of the CA Certificate file (usually called `ca.pem` or `ca.crt`).
|
||||
|
||||
>**Note:**
|
||||
> The base64 encoded string should be on the same line as `cacerts.pem`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
|
||||
**Step Result:** The file should look like the example below (the base64 encoded string should be different):
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-server
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details id="option-b">
|
||||
<summary>Option B—Bring Your Own Certificate: Signed by Recognized CA</summary>
|
||||
|
||||
If you are using a Certificate Signed By A Recognized Certificate Authority, you will need to generate a base64 encoded string for the Certificate file and the Certificate Key file. Make sure that your certificate file includes all the intermediate certificates in the chain, the order of certificates in this case is first your own certificate, followed by the intermediates. Please refer to the documentation of your CSP (Certificate Service Provider) to see what intermediate certificate(s) need to be included.
|
||||
|
||||
In the `kind: Secret` with `name: cattle-keys-ingress`:
|
||||
|
||||
* Replace `<BASE64_CRT>` with the base64 encoded string of the Certificate file (usually called `cert.pem` or `domain.crt`)
|
||||
* Replace `<BASE64_KEY>` with the base64 encoded string of the Certificate Key file (usually called `key.pem` or `domain.key`)
|
||||
|
||||
After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
>**Note:**
|
||||
> The base64 encoded string should be on the same line as `tls.crt` or `tls.key`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-ingress
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
|
||||
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
|
||||
## 8. Configure FQDN
|
||||
|
||||
There are two references to `<FQDN>` in the config file (one in this step and one in the next). Both need to be replaced with the FQDN chosen in [Configure DNS](#3-configure-dns).
|
||||
|
||||
In the `kind: Ingress` with `name: cattle-ingress-http`:
|
||||
|
||||
* Replace `<FQDN>` with the FQDN chosen in [Configure DNS](#3-configure-dns).
|
||||
|
||||
After replacing `<FQDN>` with the FQDN chosen in [Configure DNS](#3-configure-dns), the file should look like the example below (`rancher.yourdomain.com` is the FQDN used in this example):
|
||||
|
||||
```yaml
|
||||
---
|
||||
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
|
||||
tls:
|
||||
- secretName: cattle-keys-ingress
|
||||
hosts:
|
||||
- rancher.yourdomain.com
|
||||
```
|
||||
|
||||
Save the `.yml` file and close it.
|
||||
|
||||
## 9. Configure Rancher version
|
||||
|
||||
The last reference that needs to be replaced is `<RANCHER_VERSION>`. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the [GitHub README](https://github.com/rancher/rancher/blob/master/README.md). Make sure the version is an actual version number, and not a named tag like `stable` or `latest`. The example below shows the version configured to `v2.0.6`.
|
||||
|
||||
```
|
||||
spec:
|
||||
serviceAccountName: cattle-admin
|
||||
containers:
|
||||
- image: rancher/rancher:v2.0.6
|
||||
imagePullPolicy: Always
|
||||
```
|
||||
|
||||
## 10. Back Up Your RKE Config 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.
|
||||
|
||||
## 11. Run RKE
|
||||
|
||||
With all configuration in place, use RKE to launch Rancher. You can complete this action by running the `rke up` command and using the `--config` parameter to point toward your config file.
|
||||
|
||||
1. From your workstation, make sure `rancher-cluster.yml` and the downloaded `rke` binary are in the same directory.
|
||||
|
||||
2. Open a Terminal instance. Change to the directory that contains your config file and `rke`.
|
||||
|
||||
3. Enter one of the `rke up` commands listen below.
|
||||
|
||||
```
|
||||
rke up --config rancher-cluster.yml
|
||||
```
|
||||
|
||||
**Step Result:** 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
|
||||
```
|
||||
|
||||
## 12. Back Up Auto-Generated Config File
|
||||
|
||||
During installation, RKE automatically generates a config file named `kube_config_rancher-cluster.yml` in the same directory as the RKE binary. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server.
|
||||
|
||||
## What's Next?
|
||||
|
||||
You have a couple of options:
|
||||
|
||||
- Create a backup of your Rancher Server in case of a disaster scenario: [High Availability Back Up and Restore](../../../../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md).
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../../../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
## FAQ and Troubleshooting
|
||||
|
||||
<SslFaqHa/>
|
||||
+270
@@ -0,0 +1,270 @@
|
||||
---
|
||||
title: Kubernetes Install with External Load Balancer (HTTPS/Layer 7)
|
||||
---
|
||||
import SslFaqHa from '@site/src/components/SslFaqHa'
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to move to using the Helm chart.
|
||||
|
||||
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)](https://kubernetes.github.io/ingress-nginx/)
|
||||
|
||||
In an Kubernetes setup that uses a layer 7 load balancer, the load balancer accepts Rancher client connections over the HTTP protocol (i.e., the application level). This application-level access allows the load balancer to read client requests and then redirect to them to cluster nodes using logic that optimally distributes load.
|
||||
|
||||
<sup>Kubernetes Rancher install with layer 7 load balancer, depicting SSL termination at load balancer</sup>
|
||||
|
||||
|
||||
|
||||
## 1. Provision Linux Hosts
|
||||
|
||||
Provision three Linux hosts according to our [Requirements](../../../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
## 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.<br /><br/>**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 configuration](alb.md)
|
||||
* [NGINX configuration](nginx.md)
|
||||
|
||||
## 3. Configure DNS
|
||||
|
||||
Choose a fully qualified domain name (FQDN) that you want to use to access Rancher (e.g., `rancher.yourdomain.com`).<br/><br/>
|
||||
|
||||
1. Log into your DNS server a create a `DNS A` record that points to the IP address of your [load balancer](#2-configure-load-balancer).
|
||||
|
||||
2. Validate that the `DNS A` is working correctly. Run the following command from any terminal, replacing `HOSTNAME.DOMAIN.COM` with your chosen FQDN:
|
||||
|
||||
`nslookup HOSTNAME.DOMAIN.COM`
|
||||
|
||||
**Step Result:** Terminal displays output similar to the following:
|
||||
|
||||
```
|
||||
$ nslookup rancher.yourdomain.com
|
||||
Server: YOUR_HOSTNAME_IP_ADDRESS
|
||||
Address: YOUR_HOSTNAME_IP_ADDRESS#53
|
||||
|
||||
Non-authoritative answer:
|
||||
Name: rancher.yourdomain.com
|
||||
Address: HOSTNAME.DOMAIN.COM
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
## 4. Install RKE
|
||||
|
||||
RKE (Rancher Kubernetes Engine) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. We will use RKE to setup our cluster and run Rancher.
|
||||
|
||||
1. Follow the [RKE Install](https://rancher.com/docs/rke/latest/en/installation) instructions.
|
||||
|
||||
2. Confirm that RKE is now executable by running the following command:
|
||||
|
||||
```
|
||||
rke --version
|
||||
```
|
||||
|
||||
## 5. Download RKE Config File Template
|
||||
|
||||
RKE uses a YAML 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 self-signed certificate<br/> `3-node-externalssl-certificate.yml`](../../../cluster-yml-templates/node-externalssl-certificate.md)
|
||||
- [Template for certificate signed by recognized CA<br/> `3-node-externalssl-recognizedca.yml`](../../../cluster-yml-templates/node-externalssl-recognizedca.md)
|
||||
|
||||
>**Advanced Config Options:**
|
||||
>
|
||||
>- Want records of all transactions with the Rancher API? Enable the [API Auditing](../../../enable-api-audit-log.md) feature by editing your RKE config file. For more information, see how to enable it in [your RKE config file](../api-auditing.md).
|
||||
>- Want to know the other config options available for your RKE template? See the [RKE Documentation: Config Options](https://rancher.com/docs/rke/latest/en/config-options/).
|
||||
|
||||
|
||||
2. Rename the file to `rancher-cluster.yml`.
|
||||
|
||||
## 6. Configure Nodes
|
||||
|
||||
Once you have the `rancher-cluster.yml` config file template, edit the nodes section to point toward your Linux hosts.
|
||||
|
||||
1. Open `rancher-cluster.yml` in your favorite text editor.
|
||||
|
||||
1. Update the `nodes` section with the information of your [Linux hosts](#1-provision-linux-hosts).
|
||||
|
||||
For each node in your cluster, update the following placeholders: `IP_ADDRESS_X` and `USER`. The specified user should be able to access the Docker socket, you can test this by logging in with the specified user and run `docker ps`.
|
||||
|
||||
>**Note:**
|
||||
>
|
||||
>When using RHEL/CentOS, the SSH user can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565. See [Operating System Requirements](https://rancher.com/docs/rke/latest/en/installation/os#redhat-enterprise-linux-rhel-centos) for RHEL/CentOS specific requirements.
|
||||
|
||||
nodes:
|
||||
# The IP address or hostname of the node
|
||||
- address: IP_ADDRESS_1
|
||||
# User that can login to the node and has access to the Docker socket (i.e. can execute `docker ps` on the node)
|
||||
# When using RHEL/CentOS, this can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
# Path the SSH key that can be used to access to node with the specified user
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_2
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_3
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
|
||||
1. **Optional:** By default, `rancher-cluster.yml` is configured to take backup snapshots of your data. To disable these snapshots, change the `backup` directive setting to `false`, as depicted below.
|
||||
|
||||
services:
|
||||
etcd:
|
||||
backup: false
|
||||
|
||||
## 7. Configure Certificates
|
||||
|
||||
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Option A—Bring Your Own Certificate: Self-Signed</summary>
|
||||
|
||||
>**Prerequisites:**
|
||||
>Create a self-signed certificate.
|
||||
>
|
||||
>- The certificate files must be in PEM format.
|
||||
>- The certificate files must be encoded in base64.
|
||||
>- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](../../../../../other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)
|
||||
|
||||
In `kind: Secret` with `name: cattle-keys-ingress`, replace `<BASE64_CA>` with the base64 encoded string of the CA Certificate file (usually called `ca.pem` or `ca.crt`)
|
||||
|
||||
>**Note:** The base64 encoded string should be on the same line as `cacerts.pem`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-server
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
|
||||
|
||||
</details>
|
||||
<details id="option-b">
|
||||
<summary>Option B—Bring Your Own Certificate: Signed by Recognized CA</summary>
|
||||
|
||||
If you are using a Certificate Signed By A Recognized Certificate Authority, you don't need to perform any step in this part.
|
||||
</details>
|
||||
|
||||
## 8. Configure FQDN
|
||||
|
||||
There is one reference to `<FQDN>` in the RKE config file. Replace this reference with the FQDN you chose in [3. Configure DNS](#3-configure-dns).
|
||||
|
||||
1. Open `rancher-cluster.yml`.
|
||||
|
||||
2. In the `kind: Ingress` with `name: cattle-ingress-http:`
|
||||
|
||||
Replace `<FQDN>` with the FQDN chosen in [3. Configure DNS](#3-configure-dns).
|
||||
|
||||
**Step Result:** After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
3. Save the file and close it.
|
||||
|
||||
## 9. Configure Rancher version
|
||||
|
||||
The last reference that needs to be replaced is `<RANCHER_VERSION>`. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the [GitHub README](https://github.com/rancher/rancher/blob/master/README.md). Make sure the version is an actual version number, and not a named tag like `stable` or `latest`. The example below shows the version configured to `v2.0.6`.
|
||||
|
||||
```
|
||||
spec:
|
||||
serviceAccountName: cattle-admin
|
||||
containers:
|
||||
- image: rancher/rancher:v2.0.6
|
||||
imagePullPolicy: Always
|
||||
```
|
||||
|
||||
## 10. Back Up Your RKE Config File
|
||||
|
||||
After you close your RKE config file, `rancher-cluster.yml`, back it up to a secure location. You can use this file again when it's time to upgrade Rancher.
|
||||
|
||||
## 11. Run RKE
|
||||
|
||||
With all configuration in place, use RKE to launch Rancher. You can complete this action by running the `rke up` command and using the `--config` parameter to point toward your config file.
|
||||
|
||||
1. From your workstation, make sure `rancher-cluster.yml` and the downloaded `rke` binary are in the same directory.
|
||||
|
||||
2. Open a Terminal instance. Change to the directory that contains your config file and `rke`.
|
||||
|
||||
3. Enter one of the `rke up` commands listen below.
|
||||
|
||||
```
|
||||
rke up --config rancher-cluster.yml
|
||||
```
|
||||
|
||||
**Step Result:** 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
|
||||
```
|
||||
|
||||
## 12. Back Up Auto-Generated Config File
|
||||
|
||||
During installation, RKE automatically generates a config file named `kube_config_rancher-cluster.yml` in the same directory as the `rancher-cluster.yml` file. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server.
|
||||
|
||||
## What's Next?
|
||||
|
||||
- **Recommended:** Review [Creating Backups—High Availability Back Up and Restore](../../../../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md) to learn how to backup your Rancher Server in case of a disaster scenario.
|
||||
- Create a Kubernetes cluster: [Creating a Cluster](../../../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
## FAQ and Troubleshooting
|
||||
|
||||
<SslFaqHa/>
|
||||
+2
-2
@@ -24,8 +24,8 @@ NO_PROXY | Network address(es), network address range(s) and do
|
||||
|
||||
When using Kubernetes installation, the environment variables need to be added to the RKE Config File template.
|
||||
|
||||
* [Kubernetes Installation with External Load Balancer (TCP/Layer 4) RKE Config File Template](../../../../../../pages-for-subheaders/helm2-rke-add-on-layer-4-lb.md#5-download-rke-config-file-template)
|
||||
* [Kubernetes Installation with External Load Balancer (HTTPS/Layer 7) RKE Config File Template](../../../../../../pages-for-subheaders/helm2-rke-add-on-layer-7-lb.md#5-download-rke-config-file-template)
|
||||
* [Kubernetes Installation with External Load Balancer (TCP/Layer 4) RKE Config File Template](layer-4-lb/layer-4-lb.md#5-download-rke-config-file-template)
|
||||
* [Kubernetes Installation with External Load Balancer (HTTPS/Layer 7) RKE Config File Template](layer-7-lb/layer-7-lb.md#5-download-rke-config-file-template)
|
||||
|
||||
The environment variables should be defined in the `Deployment` inside the RKE Config File Template. You only have to add the part starting with `env:` to (but not including) `ports:`. Make sure the indentation is identical to the preceding `name:`. Required values for `NO_PROXY` are:
|
||||
|
||||
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: RKE Add-On Install
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
|
||||
* [Kubernetes installation with External Load Balancer (TCP/Layer 4)](../../rke-add-on/layer-4-lb.md)
|
||||
* [Kubernetes installation with External Load Balancer (HTTPS/Layer 7)](../../rke-add-on/layer-7-lb.md)
|
||||
* [HTTP Proxy Configuration for a Kubernetes installation](proxy.md)
|
||||
* [Troubleshooting RKE Add-on Installs](troubleshooting/troubleshooting.md)
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Troubleshooting HA RKE Add-On Install
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
This section contains common errors seen when setting up a Kubernetes installation.
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
- [Generic troubleshooting](generic-troubleshooting.md)
|
||||
|
||||
In this section, you can find generic ways to debug your Kubernetes cluster.
|
||||
|
||||
- [Failed to set up SSH tunneling for host](https://rancher.com/docs/rke/latest/en/troubleshooting/ssh-connectivity-errors/)
|
||||
|
||||
In this section, you can find errors related to SSH tunneling when you run the `rke` command to setup your nodes.
|
||||
|
||||
- [Failed to get job complete status](job-complete-status.md)
|
||||
|
||||
In this section, you can find errors related to deploying addons.
|
||||
|
||||
- [404 - default backend](404-default-backend.md)
|
||||
|
||||
In this section, you can find errors related to the `404 - default backend` page that is shown when trying to access Rancher.
|
||||
+3
-3
@@ -5,7 +5,7 @@ import SSlFaqHa from '@site/src/components/SslFaqHa'
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install](../../../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md).
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install](../../../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
@@ -29,7 +29,7 @@ Installation of Rancher in a high-availability configuration involves multiple p
|
||||
|
||||
## 1. Provision Linux Hosts
|
||||
|
||||
Provision three Linux hosts according to our [Requirements](../../../../../pages-for-subheaders/installation-requirements.md).
|
||||
Provision three Linux hosts according to our [Requirements](../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
## 2. Configure Load Balancer
|
||||
|
||||
@@ -372,7 +372,7 @@ During installation, RKE automatically generates a config file named `kube_confi
|
||||
You have a couple of options:
|
||||
|
||||
- Create a backup of your Rancher Server in case of a disaster scenario: [High Availability Back Up and Restore](../../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md).
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../../../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md).
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
|
||||
+3
-3
@@ -5,7 +5,7 @@ import SslFaqHa from '@site/src/components/SslFaqHa'
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install](../../../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md).
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install](../../../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
@@ -26,7 +26,7 @@ Installation of Rancher in a high-availability configuration involves multiple p
|
||||
|
||||
## 1. Provision Linux Hosts
|
||||
|
||||
Provision three Linux hosts according to our [Requirements](../../../../../pages-for-subheaders/installation-requirements.md).
|
||||
Provision three Linux hosts according to our [Requirements](../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
## 2. Configure Load Balancer
|
||||
|
||||
@@ -262,7 +262,7 @@ During installation, RKE automatically generates a config file named `kube_confi
|
||||
## What's Next?
|
||||
|
||||
- **Recommended:** Review [Creating Backups—High Availability Back Up and Restoration](../../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md) to learn how to backup your Rancher Server in case of a disaster scenario.
|
||||
- Create a Kubernetes cluster: [Creating a Cluster](../../../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md).
|
||||
- Create a Kubernetes cluster: [Creating a Cluster](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: RKE Add-On Install
|
||||
---
|
||||
|
||||
- [Kubernetes Install with External Load Balancer (TCP/Layer 4)](layer-4-lb.md)
|
||||
- [Kubernetes Install with External Load Balancer (HTTPS/Layer 7)](layer-7-lb.md)
|
||||
+139
@@ -0,0 +1,139 @@
|
||||
---
|
||||
title: Enabling Experimental Features
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/enable-experimental-features"/>
|
||||
</head>
|
||||
|
||||
Rancher includes some features that are experimental and disabled by default. You might want to enable these features, for example, if you decide that the benefits of using an [unsupported storage type](unsupported-storage-drivers.md) outweighs the risk of using an untested feature. Feature flags were introduced to allow you to try these features that are not enabled by default.
|
||||
|
||||
The features can be enabled in three ways:
|
||||
|
||||
- [Enable features when starting Rancher.](#enabling-features-when-starting-rancher) When installing Rancher with a CLI, you can use a feature flag to enable a feature by default.
|
||||
- [Enable features from the Rancher UI](#enabling-features-with-the-rancher-ui) in Rancher v2.3.3+ by going to the **Settings** page.
|
||||
- [Enable features with the Rancher API](#enabling-features-with-the-rancher-api) after installing Rancher.
|
||||
|
||||
Each feature has two values:
|
||||
|
||||
- A default value, which can be configured with a flag or environment variable from the command line
|
||||
- A set value, which can be configured with the Rancher API or UI
|
||||
|
||||
If no value has been set, Rancher uses the default value.
|
||||
|
||||
Because the API sets the actual value and the command line sets the default value, that means that if you enable or disable a feature with the API or UI, it will override any value set with the command line.
|
||||
|
||||
For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. See the [feature flags page](../../../../reference-guides/installation-references/feature-flags.md) for more information.
|
||||
|
||||
## Enabling Features when Starting Rancher
|
||||
|
||||
When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing a Kubernetes Installation of Rancher.
|
||||
|
||||
> **Note:** Values set from the Rancher API will override the value passed in through the command line.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Kubernetes Install">
|
||||
|
||||
When installing Rancher with a Helm chart, use the `--features` option. In the below example, two features are enabled by passing the feature flag names names in a comma separated list:
|
||||
|
||||
```
|
||||
helm install rancher-latest/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
|
||||
```
|
||||
|
||||
Note: If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
### Rendering the Helm Chart for Air Gap Installations
|
||||
|
||||
For an air gap installation of Rancher, you need to add a Helm chart repository and render a Helm template before installing Rancher with Helm. For details, refer to the [air gap installation documentation.](../../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)
|
||||
|
||||
Here is an example of a command for passing in the feature flag names when rendering the Helm template. In the below example, two features are enabled by passing the feature flag names in a comma separated list.
|
||||
|
||||
The Helm 3 command is as follows:
|
||||
|
||||
```
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
|
||||
```
|
||||
|
||||
The Helm 2 command is as follows:
|
||||
|
||||
```
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
|
||||
```
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker Install">
|
||||
|
||||
When installing Rancher with Docker, use the `--features` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:
|
||||
|
||||
```
|
||||
docker run -d -p 80:80 -p 443:443 \
|
||||
--restart=unless-stopped \
|
||||
rancher/rancher:rancher-latest \
|
||||
--features=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true # Available as of v2.3.0
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Enabling Features with the Rancher UI
|
||||
|
||||
1. Go to the **Global** view and click **Settings.**
|
||||
1. Click the **Feature Flags** tab. You will see a list of experimental features.
|
||||
1. To enable a feature, go to the disabled feature you want to enable and click **⋮ > Activate.**
|
||||
|
||||
**Result:** The feature is enabled.
|
||||
|
||||
### Disabling Features with the Rancher UI
|
||||
|
||||
1. Go to the **Global** view and click **Settings.**
|
||||
1. Click the **Feature Flags** tab. You will see a list of experimental features.
|
||||
1. To disable a feature, go to the enabled feature you want to disable and click **⋮ > Deactivate.**
|
||||
|
||||
**Result:** The feature is disabled.
|
||||
|
||||
## Enabling Features with the Rancher API
|
||||
|
||||
1. Go to `<RANCHER-SERVER-URL>/v3/features`.
|
||||
1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable.
|
||||
1. In the upper left corner of the screen, under **Operations,** click **Edit.**
|
||||
1. In the **Value** drop-down menu, click **True.**
|
||||
1. Click **Show Request.**
|
||||
1. Click **Send Request.**
|
||||
1. Click **Close.**
|
||||
|
||||
**Result:** The feature is enabled.
|
||||
|
||||
### Disabling Features with the Rancher API
|
||||
|
||||
1. Go to `<RANCHER-SERVER-URL>/v3/features`.
|
||||
1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable.
|
||||
1. In the upper left corner of the screen, under **Operations,** click **Edit.**
|
||||
1. In the **Value** drop-down menu, click **False.**
|
||||
1. Click **Show Request.**
|
||||
1. Click **Send Request.**
|
||||
1. Click **Close.**
|
||||
|
||||
**Result:** The feature is disabled.
|
||||
+1
-1
@@ -4,7 +4,7 @@ title: UI for Istio Virtual Services and Destination Rules
|
||||
|
||||
This feature enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio.
|
||||
|
||||
> **Prerequisite:** Turning on this feature does not enable Istio. A cluster administrator needs to [enable Istio for the cluster](../../../../pages-for-subheaders/istio-setup-guide.md) in order to use the feature.
|
||||
> **Prerequisite:** Turning on this feature does not enable Istio. A cluster administrator needs to [enable Istio for the cluster](../../../../how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md) in order to use the feature.
|
||||
|
||||
To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.](../../../../reference-guides/installation-references/feature-flags.md)
|
||||
|
||||
|
||||
+1
-1
@@ -9,7 +9,7 @@ title: "Running on ARM64 (Experimental)"
|
||||
The following options are available when using an ARM64 platform:
|
||||
|
||||
- Running Rancher on ARM64 based node(s)
|
||||
- Only for Docker Install. Please note that the following installation command replaces the examples found in the [Docker Install](../../../../pages-for-subheaders/rancher-on-a-single-node-with-docker.md) link:
|
||||
- Only for Docker Install. Please note that the following installation command replaces the examples found in the [Docker Install](../../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) link:
|
||||
|
||||
```
|
||||
# In the last line `rancher/rancher:vX.Y.Z`, be certain to replace "X.Y.Z" with a released version in which ARM64 builds exist. For example, if your matching version is v2.5.8, you would fill in this line with `rancher/rancher:v2.5.8`.
|
||||
|
||||
+296
@@ -0,0 +1,296 @@
|
||||
---
|
||||
title: Install Rancher on a Kubernetes Cluster
|
||||
description: Learn how to install Rancher in development and production environments. Read about single node and high availability installation
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster"/>
|
||||
</head>
|
||||
|
||||
## Prerequisite
|
||||
|
||||
Set up the Rancher server's local Kubernetes cluster.
|
||||
|
||||
The cluster requirements depend on the Rancher version:
|
||||
|
||||
- **In Rancher v2.4.x,** Rancher needs to be installed on a K3s Kubernetes cluster or an RKE Kubernetes cluster.
|
||||
- **In Rancher before v2.4,** Rancher needs to be installed on an RKE Kubernetes cluster.
|
||||
|
||||
For the tutorial to install an RKE Kubernetes cluster, refer to [this page.](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md) For help setting up the infrastructure for a high-availability RKE cluster, refer to [this page.](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.md)
|
||||
|
||||
For the tutorial to install a K3s Kubernetes cluster, refer to [this page.](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md) For help setting up the infrastructure for a high-availability K3s cluster, refer to [this page.](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md)
|
||||
|
||||
## Install the Rancher Helm Chart
|
||||
|
||||
Rancher is installed using the Helm package manager for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents.
|
||||
|
||||
With Helm, we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at https://helm.sh/.
|
||||
|
||||
For systems without direct internet access, see [Air Gap: Kubernetes install](../advanced-options/advanced-use-cases/air-gap-helm2/install-rancher.md).
|
||||
|
||||
To choose a Rancher version to install, refer to [Choosing a Rancher Version.](../resources/choose-a-rancher-version.md)
|
||||
|
||||
To choose a version of Helm to install Rancher with, refer to the [Helm version requirements](../resources/helm-version-requirements.md)
|
||||
|
||||
> **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](../resources/helm-version-requirements.md) 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.
|
||||
|
||||
To set up Rancher,
|
||||
|
||||
1. [Install the required CLI tools](#1-install-the-required-cli-tools)
|
||||
2. [Add the Helm chart repository](#2-add-the-helm-chart-repository)
|
||||
3. [Create a namespace for Rancher](#3-create-a-namespace-for-rancher)
|
||||
4. [Choose your SSL configuration](#4-choose-your-ssl-configuration)
|
||||
5. [Install cert-manager](#5-install-cert-manager) (unless you are bringing your own certificates, or TLS will be terminated on a load balancer)
|
||||
6. [Install Rancher with Helm and your chosen certificate option](#6-install-rancher-with-helm-and-your-chosen-certificate-option)
|
||||
7. [Verify that the Rancher server is successfully deployed](#7-verify-that-the-rancher-server-is-successfully-deployed)
|
||||
8. [Save your options](#8-save-your-options)
|
||||
|
||||
### 1. Install the Required CLI Tools
|
||||
|
||||
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](../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
### 2. Add the Helm Chart Repository
|
||||
|
||||
Use `helm repo add` command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see [Choosing a Rancher Version](../resources/choose-a-rancher-version.md).
|
||||
|
||||
- Latest: Recommended for trying out the newest features
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
```
|
||||
- Stable: Recommended for production environments
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
- Alpha: Experimental preview of upcoming releases.
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
Note: Upgrades are not supported to, from, or between Alphas.
|
||||
|
||||
### 3. Create a Namespace for Rancher
|
||||
|
||||
We'll need to define a Kubernetes namespace where the resources created by the Chart should be installed. This should always be `cattle-system`:
|
||||
|
||||
```
|
||||
kubectl create namespace cattle-system
|
||||
```
|
||||
|
||||
### 4. Choose your SSL Configuration
|
||||
|
||||
The Rancher management server is designed to be secure by default and requires SSL/TLS configuration.
|
||||
|
||||
> **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer](../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination).
|
||||
|
||||
There are three recommended options for the source of the certificate used for TLS termination at the Rancher server:
|
||||
|
||||
- **Rancher-generated TLS certificate:** In this case, you will need to install `cert-manager` into the cluster. Rancher utilizes `cert-manager` to issue and maintain its certificates. Rancher will generate a CA certificate of its own, and sign a cert using that CA. `cert-manager` is then responsible for managing that certificate.
|
||||
- **Let's Encrypt:** The Let's Encrypt option also uses `cert-manager`. However, in this case, cert-manager is combined with a special Issuer for Let's Encrypt that performs all actions (including request and validation) necessary for getting a Let's Encrypt issued cert. This configuration uses HTTP validation (`HTTP-01`), so the load balancer must have a public DNS record and be accessible from the internet.
|
||||
- **Bring your own certificate:** This option allows you to bring your own public- or private-CA signed certificate. Rancher will use that certificate to secure websocket and HTTPS traffic. In this case, you must upload this certificate (and associated key) as PEM-encoded files with the name `tls.crt` and `tls.key`. If you are using a private CA, you must also upload that certificate. This is due to the fact that this private CA may not be trusted by your nodes. Rancher will take that CA certificate, and generate a checksum from it, which the various Rancher components will use to validate their connection to Rancher.
|
||||
|
||||
|
||||
| Configuration | Helm Chart Option | Requires cert-manager |
|
||||
| ------------------------------ | ----------------------- | ------------------------------------- |
|
||||
| Rancher Generated Certificates (Default) | `ingress.tls.source=rancher` | [yes](#5-install-cert-manager) |
|
||||
| Let’s Encrypt | `ingress.tls.source=letsEncrypt` | [yes](#5-install-cert-manager) |
|
||||
| Certificates from Files | `ingress.tls.source=secret` | no |
|
||||
|
||||
### 5. Install cert-manager
|
||||
|
||||
> You should skip this step if you are bringing your own certificate files (option `ingress.tls.source=secret`), or if you use [TLS termination on an external load balancer](../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination).
|
||||
|
||||
This step is only required to use certificates issued by Rancher's generated CA (`ingress.tls.source=rancher`) or to request Let's Encrypt issued certificates (`ingress.tls.source=letsEncrypt`).
|
||||
|
||||
<details id="cert-manager">
|
||||
<summary>Click to Expand</summary>
|
||||
|
||||
> **Important:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade documentation](../resources/upgrade-cert-manager.md).
|
||||
|
||||
These instructions are adapted from the [official cert-manager documentation](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm).
|
||||
|
||||
```
|
||||
# Install the CustomResourceDefinition resources separately
|
||||
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml
|
||||
|
||||
# **Important:**
|
||||
# If you are running Kubernetes v1.15 or below, you
|
||||
# will need to add the `--validate=false` flag to your
|
||||
# kubectl apply command, or else you will receive a
|
||||
# validation error relating to the
|
||||
# x-kubernetes-preserve-unknown-fields field in
|
||||
# cert-manager’s CustomResourceDefinition resources.
|
||||
# This is a benign error and occurs due to the way kubectl
|
||||
# performs resource validation.
|
||||
|
||||
# Create the namespace for cert-manager
|
||||
kubectl create namespace cert-manager
|
||||
|
||||
# Add the Jetstack Helm repository
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
|
||||
# Update your local Helm chart repository cache
|
||||
helm repo update
|
||||
|
||||
# Install the cert-manager Helm chart
|
||||
helm install \
|
||||
cert-manager jetstack/cert-manager \
|
||||
--namespace cert-manager \
|
||||
--version v1.0.4
|
||||
```
|
||||
|
||||
Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:
|
||||
|
||||
```
|
||||
kubectl get pods --namespace cert-manager
|
||||
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
cert-manager-5c6866597-zw7kh 1/1 Running 0 2m
|
||||
cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m
|
||||
cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 6. Install Rancher with Helm and Your Chosen Certificate Option
|
||||
|
||||
The exact command to install Rancher differs depending on the certificate configuration.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher-generated Certificates">
|
||||
|
||||
The default is for Rancher to generate a CA and uses `cert-manager` to issue the certificate for access to the Rancher server interface.
|
||||
|
||||
Because `rancher` is the default option for `ingress.tls.source`, we are not specifying `ingress.tls.source` when running the `helm install` command.
|
||||
|
||||
- Set the `hostname` to the DNS name you pointed at your load balancer.
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
- To install a specific Rancher version, use the `--version` flag, example: `--version 2.3.6`
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
Wait for Rancher to be rolled out:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Let's Encrypt">
|
||||
|
||||
This option uses `cert-manager` to automatically request and renew [Let's Encrypt](https://letsencrypt.org/) certificates. This is a free service that provides you with a valid certificate as Let's Encrypt is a trusted CA.
|
||||
|
||||
In the following command,
|
||||
|
||||
- `hostname` is set to the public DNS record,
|
||||
- `ingress.tls.source` is set to `letsEncrypt`
|
||||
- `letsEncrypt.email` is set to the email address used for communication about your certificate (for example, expiry notices)
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=letsEncrypt \
|
||||
--set letsEncrypt.email=me@example.org \
|
||||
```
|
||||
|
||||
Wait for Rancher to be rolled out:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Certificates from Files">
|
||||
|
||||
In this option, Kubernetes secrets are created from your own certificates for Rancher to use.
|
||||
|
||||
When you run this command, the `hostname` option must match the `Common Name` or a `Subject Alternative Names` entry in the server certificate or the Ingress controller will fail to configure correctly.
|
||||
|
||||
Although an entry in the `Subject Alternative Names` is technically required, having a matching `Common Name` maximizes compatibility with older browsers and applications.
|
||||
|
||||
> If you want to check if your certificates are correct, see [How do I check Common Name and Subject Alternative Names in my server certificate?](../../../faq/technical-items.md#how-do-i-check-common-name-and-subject-alternative-names-in-my-server-certificate)
|
||||
|
||||
- Set the `hostname`.
|
||||
- Set `ingress.tls.source` to `secret`.
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=secret
|
||||
```
|
||||
|
||||
If you are using a Private CA signed certificate , add `--set privateCA=true` to the command:
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=secret \
|
||||
--set privateCA=true
|
||||
```
|
||||
|
||||
Now that Rancher is deployed, see [Adding TLS Secrets](../resources/add-tls-secrets.md) to publish the certificate files so Rancher and the Ingress controller can use them.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
The Rancher chart configuration has many options for customizing the installation to suit your specific environment. Here are some common advanced scenarios.
|
||||
|
||||
- [HTTP Proxy](../../../reference-guides/installation-references/helm-chart-options.md#http-proxy)
|
||||
- [Private Docker Image Registry](../../../reference-guides/installation-references/helm-chart-options.md#private-registry-and-air-gap-installs)
|
||||
- [TLS Termination on an External Load Balancer](../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination)
|
||||
|
||||
See the [Chart Options](../../../reference-guides/installation-references/helm-chart-options.md) for the full list of options.
|
||||
|
||||
|
||||
### 7. Verify that the Rancher Server is Successfully Deployed
|
||||
|
||||
After adding the secrets, check if Rancher was rolled out successfully:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
If you see the following error: `error: deployment "rancher" exceeded its progress deadline`, you can check the status of the deployment by running the following command:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system get deploy rancher
|
||||
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
|
||||
rancher 3 3 3 3 3m
|
||||
```
|
||||
|
||||
It should show the same count for `DESIRED` and `AVAILABLE`.
|
||||
|
||||
### 8. Save Your Options
|
||||
|
||||
Make sure you save the `--set` options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm.
|
||||
|
||||
### Finishing Up
|
||||
|
||||
That's it. You should have a functional Rancher server.
|
||||
|
||||
In a web browser, go to the DNS name that forwards traffic to your load balancer. Then you should be greeted by the colorful login page.
|
||||
|
||||
Doesn't work? Take a look at the [Troubleshooting](troubleshooting.md) Page
|
||||
|
||||
|
||||
### Optional Next Steps
|
||||
|
||||
Enable the Enterprise Cluster Manager.
|
||||
+3
-3
@@ -8,7 +8,7 @@ title: Upgrading Rancher Installed on Kubernetes with Helm 2
|
||||
|
||||
> Helm 3 has been released. If you are using Helm 2, we recommend [migrating to Helm 3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) because it is simpler to use and more secure than Helm 2.
|
||||
>
|
||||
> The [current instructions for Upgrading Rancher Installed on Kubernetes](../../../../pages-for-subheaders/upgrades.md) use Helm 3.
|
||||
> The [current instructions for Upgrading Rancher Installed on Kubernetes](upgrades.md) use Helm 3.
|
||||
>
|
||||
> This section provides a copy of the older instructions for upgrading Rancher with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
@@ -26,8 +26,8 @@ If you installed Rancher using the RKE Add-on yaml, follow the directions to [mi
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Review the [known upgrade issues](../../../../pages-for-subheaders/upgrades.md)** in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
- **For [air gap installs only,](../../../../pages-for-subheaders/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version.** Follow the guide to [populate your private registry](../../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
|
||||
- **Review the [known upgrade issues](upgrades.md)** in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
- **For [air gap installs only,](../../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version.** Follow the guide to [populate your private registry](../../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
|
||||
|
||||
## Upgrade Outline
|
||||
|
||||
|
||||
+2
-2
@@ -101,5 +101,5 @@ addons: |-
|
||||
|
||||
From here follow the standard install steps.
|
||||
|
||||
* [3 - Initialize Helm](../../../../pages-for-subheaders/helm2-helm-init.md)
|
||||
* [4 - Install Rancher](../../../../pages-for-subheaders/helm-rancher.md)
|
||||
* [3 - Initialize Helm](../../advanced-options/advanced-use-cases/helm2/helm-init/helm-init.md)
|
||||
* [4 - Install Rancher](../../advanced-options/advanced-use-cases/helm2/helm-rancher/helm-rancher.md)
|
||||
|
||||
+1
-1
@@ -56,7 +56,7 @@ You can prevent cluster networking issues from occurring during your upgrade to
|
||||
|
||||
1. Repeat these steps for each cluster where you've assigned system namespaces to projects.
|
||||
|
||||
**Result:** All system namespaces are moved out of Rancher projects. You can now safely begin the [upgrade](../../../../pages-for-subheaders/upgrades.md).
|
||||
**Result:** All system namespaces are moved out of Rancher projects. You can now safely begin the [upgrade](upgrades.md).
|
||||
|
||||
## Restoring Cluster Networking
|
||||
|
||||
|
||||
+286
@@ -0,0 +1,286 @@
|
||||
---
|
||||
title: Upgrades
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades"/>
|
||||
</head>
|
||||
|
||||
The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air gap installs with Helm.
|
||||
|
||||
For the instructions to upgrade Rancher installed with Docker, refer to [this page.](../../other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md)
|
||||
|
||||
To upgrade the components in your Kubernetes cluster, or the definition of the [Kubernetes services](https://rancher.com/docs/rke/latest/en/config-options/services/) or [add-ons](https://rancher.com/docs/rke/latest/en/config-options/add-ons/), refer to the [upgrade documentation for RKE](https://rancher.com/docs/rke/latest/en/upgrades/), the Rancher Kubernetes Engine.
|
||||
|
||||
If you installed Rancher using the RKE Add-on yaml, follow the directions to [migrate or upgrade](migrating-from-rke-add-on.md).
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Upgrade Outline](#upgrade-outline)
|
||||
- [Known Upgrade Issues](#known-upgrade-issues)
|
||||
- [RKE Add-on Installs](#rke-add-on-installs)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Access to kubeconfig
|
||||
|
||||
Helm should be run from the same location as your kubeconfig file, or the same location where you run your kubectl commands from.
|
||||
|
||||
If you installed Kubernetes with RKE, the config will have been created in the directory you ran `rke up` in.
|
||||
|
||||
The kubeconfig can also be manually targeted for the intended cluster with the `--kubeconfig` tag (see: https://helm.sh/docs/helm/helm/)
|
||||
|
||||
### Review Known Issues
|
||||
|
||||
Review the [known upgrade issues](#known-upgrade-issues) in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher.
|
||||
|
||||
A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
|
||||
Note that upgrades _to_ or _from_ any chart in the [rancher-alpha repository](../../resources/choose-a-rancher-version.md#helm-chart-repositories) aren't supported.
|
||||
|
||||
### Helm Version
|
||||
|
||||
The upgrade 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/) The [Helm 2 upgrade page here](helm2.md)provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
### For air gap installs: Populate private registry
|
||||
|
||||
-For [air gap installs only,](../../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version. Follow the guide to [populate your private registry](../../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
|
||||
|
||||
### For upgrades from v2.0-v2.2 with external TLS termination
|
||||
|
||||
If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS termination, you will need to edit the cluster.yml to [enable using forwarded host headers.](../../../../reference-guides/installation-references/helm-chart-options.md#configuring-ingress-for-external-tls-when-using-nginx-v025)
|
||||
|
||||
### For upgrades with cert-manager older than 0.8.0
|
||||
|
||||
[Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) Upgrade cert-manager to the latest version by following [these instructions.](../../resources/upgrade-cert-manager.md)
|
||||
|
||||
## Upgrade Outline
|
||||
|
||||
Follow the steps to upgrade Rancher server:
|
||||
|
||||
- [1. Back up your Kubernetes cluster that is running Rancher server](#1-back-up-your-kubernetes-cluster-that-is-running-rancher-server)
|
||||
- [2. Update the Helm chart repository](#2-update-the-helm-chart-repository)
|
||||
- [3. Upgrade Rancher](#3-upgrade-rancher)
|
||||
- [4. Verify the Upgrade](#4-verify-the-upgrade)
|
||||
|
||||
## 1. Back up Your Kubernetes Cluster that is Running Rancher Server
|
||||
|
||||
|
||||
[Take a one-time snapshot](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md#option-b-one-time-snapshots)
|
||||
of your Kubernetes cluster running Rancher server.
|
||||
|
||||
You'll use the backup as a restoration point if something goes wrong during upgrade.
|
||||
|
||||
## 2. Update the Helm chart repository
|
||||
|
||||
1. Update your local Helm repo cache:
|
||||
|
||||
```
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Get the repository name that you used to install Rancher.
|
||||
|
||||
For information about the repos and their differences, see [Helm Chart Repositories](../../resources/choose-a-rancher-version.md#helm-chart-repositories).
|
||||
|
||||
- Latest: Recommended for trying out the newest features
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
```
|
||||
- Stable: Recommended for production environments
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
- Alpha: Experimental preview of upcoming releases.
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
Note: Upgrades are not supported to, from, or between Alphas.
|
||||
|
||||
```
|
||||
helm repo list
|
||||
|
||||
NAME URL
|
||||
stable https://charts.helm.sh/stable
|
||||
rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
|
||||
```
|
||||
|
||||
> **Note:** If you want to switch to a different Helm chart repository, please follow the [steps on how to switch repositories](../../resources/choose-a-rancher-version.md#switching-to-a-different-helm-chart-repository). If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.
|
||||
|
||||
|
||||
1. Fetch the latest chart to install Rancher from the Helm chart repository.
|
||||
|
||||
This command will pull down the latest charts and save it in the current directory as a `.tgz` file.
|
||||
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher
|
||||
```
|
||||
You can fetch the chart for the specific version you are upgrading to by adding in the `--version=` tag. For example:
|
||||
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher --version=v2.4.11
|
||||
```
|
||||
|
||||
## 3. Upgrade Rancher
|
||||
|
||||
This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Kubernetes Upgrade">
|
||||
|
||||
Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed.
|
||||
|
||||
```
|
||||
helm get values rancher -n cattle-system
|
||||
|
||||
hostname: rancher.my.org
|
||||
```
|
||||
|
||||
> **Note:** There will be more values that are listed with this command. This is just an example of one of the values.
|
||||
|
||||
If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow [Option B: Reinstalling Rancher and cert-manager.](#option-b-reinstalling-rancher-and-cert-manager)
|
||||
|
||||
Otherwise, follow [Option A: Upgrading Rancher.](#option-a-upgrading-rancher)
|
||||
|
||||
### Option A: Upgrading Rancher
|
||||
|
||||
Upgrade Rancher to the latest version with all your settings.
|
||||
|
||||
Take all the values from the previous step and append them to the command using `--set key=value`:
|
||||
|
||||
```
|
||||
helm upgrade rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
> **Note:** The above is an example, there may be more values from the previous step that need to be appended.
|
||||
|
||||
Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:
|
||||
|
||||
```
|
||||
helm get values rancher -n cattle-system -o yaml > values.yaml
|
||||
|
||||
helm upgrade rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
-f values.yaml \
|
||||
--version=2.4.5
|
||||
```
|
||||
|
||||
### Option B: Reinstalling Rancher and cert-manager
|
||||
|
||||
If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manager due to the API change in cert-manager v0.11.
|
||||
|
||||
1. Uninstall Rancher
|
||||
|
||||
```
|
||||
helm delete rancher -n cattle-system
|
||||
```
|
||||
|
||||
2. Uninstall and reinstall `cert-manager` according to the instructions on the [Upgrading Cert-Manager](../../resources/upgrade-cert-manager-helm-2.md) page.
|
||||
|
||||
3. Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using `--set key=value`. Note: There will be many more options from the step 1 that need to be appended.
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Kubernetes Air Gap Upgrade">
|
||||
|
||||
Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
Based on the choice you made during installation, complete one of the procedures below.
|
||||
|
||||
Placeholder | Description
|
||||
------------|-------------
|
||||
`<VERSION>` | The version number of the output tarball.
|
||||
`<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
|
||||
`<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
|
||||
`<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.
|
||||
|
||||
|
||||
### Option A: Default Self-signed Certificate
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set certmanager.version=<CERTMANAGER_VERSION> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
### Option B: Certificates from Files using Kubernetes Secrets
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`:
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set privateCA=true \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
### Apply the Rendered Templates
|
||||
|
||||
Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.
|
||||
|
||||
Use `kubectl` to apply the rendered manifests.
|
||||
|
||||
```plain
|
||||
kubectl -n cattle-system apply -R -f ./rancher
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 4. Verify the Upgrade
|
||||
|
||||
Log into Rancher to confirm that the upgrade succeeded.
|
||||
|
||||
>**Having network issues following upgrade?**
|
||||
>
|
||||
> See [Restoring Cluster Networking](namespace-migration.md#restoring-cluster-networking).
|
||||
|
||||
## Known Upgrade Issues
|
||||
|
||||
The following table lists some of the most noteworthy issues to be considered when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
|
||||
Upgrade Scenario | Issue
|
||||
---|---
|
||||
Upgrading to v2.4.6 or v2.4.7 | These Rancher versions had an issue where the `kms:ListKeys` permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8.
|
||||
Upgrading to v2.3.0+ | Any user provisioned cluster will be automatically updated upon any edit as tolerations were added to the images used for Kubernetes provisioning.
|
||||
Upgrading to v2.2.0-v2.2.x | Rancher introduced the [system charts](https://github.com/rancher/system-charts) repository which contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. To be able to use these features in an air gap install, you will need to mirror the `system-charts` repository locally and configure Rancher to use that repository. Please follow the instructions to [configure Rancher system charts](../../resources/local-system-charts.md).
|
||||
Upgrading from v2.0.13 or earlier | If your cluster's certificates have expired, you will need to perform [additional steps](../../../../how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.md#rotating-expired-certificates-after-upgrading-older-rancher-versions) to rotate the certificates.
|
||||
Upgrading from v2.0.7 or earlier | Rancher introduced the `system` project, which is a project that's automatically created to store important namespaces that Kubernetes needs to operate. During upgrade to v2.0.7+, Rancher expects these namespaces to be unassigned from all projects. Before beginning upgrade, check your system namespaces to make sure that they're unassigned to [prevent cluster networking issues.](namespace-migration.md)
|
||||
|
||||
## RKE Add-on Installs
|
||||
|
||||
**Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
|
||||
Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install](../install-upgrade-on-a-kubernetes-cluster.md).
|
||||
|
||||
If you are currently using the RKE add-on install method, see [Migrating from a RKE add-on install](migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
+96
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: Installing/Upgrading Rancher
|
||||
description: Learn how to install Rancher in development and production environments. Read about single node and high availability installation
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-and-upgrade"/>
|
||||
</head>
|
||||
|
||||
This section provides an overview of the architecture options of installing Rancher, describing advantages of each option.
|
||||
|
||||
## Terminology
|
||||
|
||||
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.
|
||||
- **K3s (Lightweight Kubernetes)** 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 100 MB. As of Rancher v2.4, Rancher can be installed on a K3s cluster.
|
||||
|
||||
## Overview of Installation Options
|
||||
|
||||
Rancher can be installed on these main architectures:
|
||||
|
||||
### High-availability Kubernetes Install with the Helm CLI
|
||||
|
||||
We recommend using Helm, a Kubernetes package manager, to install Rancher on multiple nodes on a dedicated Kubernetes cluster. For RKE clusters, three nodes are required to achieve a high-availability cluster. For K3s clusters, only two nodes are required.
|
||||
|
||||
### Single-node Kubernetes Install
|
||||
|
||||
Rancher can be installed on a single-node Kubernetes cluster. In this case, the Rancher server doesn't 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.
|
||||
|
||||
### Docker Install
|
||||
|
||||
For test and demonstration purposes, Rancher can be installed with Docker on a single node.
|
||||
|
||||
For Rancher v2.0-v2.4, there is no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start.
|
||||
|
||||
### Other Options
|
||||
|
||||
There are also separate instructions for installing Rancher in an air gap environment or behind an HTTP proxy:
|
||||
|
||||
| Level of Internet Access | Kubernetes Installation - Strongly Recommended | Docker Installation |
|
||||
| ---------------------------------- | ------------------------------ | ---------- |
|
||||
| With direct access to the Internet | [Docs](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) | [Docs](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) |
|
||||
| Behind an HTTP proxy | These [docs,](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) plus this [configuration](../../reference-guides/installation-references/helm-chart-options.md#http-proxy) | These [docs,](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) plus this [configuration](../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md) |
|
||||
| In an air gap environment | [Docs](other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) | [Docs](other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) |
|
||||
|
||||
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 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.
|
||||
|
||||
> The type of cluster that Rancher needs to be installed on depends on the Rancher version.
|
||||
>
|
||||
> For Rancher v2.4.x, either an RKE Kubernetes cluster or K3s Kubernetes cluster can be used.
|
||||
> For Rancher before v2.4, an RKE cluster must be used.
|
||||
|
||||
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. The Docker install allows you to explore the Rancher server functionality, but it is intended to be used for development and testing purposes only.
|
||||
|
||||
Our [instructions for installing Rancher on Kubernetes](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) describe how to first use K3s or RKE to create and manage a Kubernetes cluster, then install Rancher onto that cluster.
|
||||
|
||||
When the nodes in your Kubernetes cluster are running and fulfill the [node requirements,](installation-requirements/installation-requirements.md) 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,](../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md) [recommendations for production-grade architecture,](../../reference-guides/rancher-manager-architecture/architecture-recommendations.md) or our [best practices guide.](../../reference-guides/best-practices/deployment-types.md)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before installing Rancher, make sure that your nodes fulfill all of the [installation requirements.](installation-requirements/installation-requirements.md)
|
||||
|
||||
## Architecture Tip
|
||||
|
||||
For the best performance and greater security, we recommend a separate, 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](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) for running your workloads.
|
||||
|
||||
For more architecture recommendations, refer to [this page.](../../reference-guides/rancher-manager-architecture/architecture-recommendations.md)
|
||||
|
||||
### More Options for Installations on a Kubernetes Cluster
|
||||
|
||||
Refer to the [Helm chart options](../../reference-guides/installation-references/helm-chart-options.md) for details on installing Rancher on a Kubernetes cluster with other configurations, including:
|
||||
|
||||
- With [API auditing to record all transactions](../../reference-guides/installation-references/helm-chart-options.md#api-audit-log)
|
||||
- With [TLS termination on a load balancer](../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination)
|
||||
- With a [custom Ingress](../../reference-guides/installation-references/helm-chart-options.md#customizing-your-ingress)
|
||||
|
||||
In the Rancher installation instructions, we recommend using K3s or RKE to set up a Kubernetes cluster before installing Rancher on the cluster. Both K3s and RKE have many configuration options for customizing the Kubernetes cluster to suit your specific environment. For the full list of their capabilities, refer to their documentation:
|
||||
|
||||
- [RKE configuration options](https://rancher.com/docs/rke/latest/en/config-options/)
|
||||
- [K3s configuration options](https://rancher.com/docs/k3s/latest/en/installation/install-options/)
|
||||
|
||||
### More Options for Installations with Docker
|
||||
|
||||
Refer to the [docs about options for Docker installs](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) for details about other configurations including:
|
||||
|
||||
- With [API auditing to record all transactions](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log)
|
||||
- With an [external load balancer](advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.md)
|
||||
- With a [persistent data store](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#persistent-data)
|
||||
+147
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: Installation Requirements
|
||||
description: Learn the node requirements for each node running Rancher server when you’re configuring Rancher to run either in a Docker or Kubernetes setup
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-requirements"/>
|
||||
</head>
|
||||
|
||||
This page describes the software, hardware, and networking requirements for the nodes where the Rancher server will be installed. The Rancher server can be installed on a single node or a high-availability Kubernetes cluster.
|
||||
|
||||
> It is important to note that if you install Rancher on a Kubernetes cluster, requirements are different from the [node requirements for downstream user clusters,](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md) which will run your apps and services.
|
||||
|
||||
Make sure the node(s) for the Rancher server fulfill the following requirements:
|
||||
|
||||
- [Operating Systems and Container Runtime Requirements](#operating-systems-and-container-runtime-requirements)
|
||||
- [Hardware Requirements](#hardware-requirements)
|
||||
- [CPU and Memory](#cpu-and-memory)
|
||||
- [CPU and Memory for Rancher before v2.4.0](#cpu-and-memory-for-rancher-before-v240)
|
||||
- [Disks](#disks)
|
||||
- [Networking Requirements](#networking-requirements)
|
||||
- [Node IP Addresses](#node-ip-addresses)
|
||||
- [Port Requirements](#port-requirements)
|
||||
|
||||
For a list of best practices that we recommend for running the Rancher server in production, refer to the [best practices section.](../../../reference-guides/best-practices/deployment-types.md)
|
||||
|
||||
The Rancher UI works best in Firefox or Chrome.
|
||||
|
||||
## Operating Systems and Container Runtime Requirements
|
||||
|
||||
Rancher should work with any modern Linux distribution.
|
||||
|
||||
For details on which OS, Docker, and Kubernetes versions were tested with each Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/)
|
||||
|
||||
All supported operating systems are 64-bit x86.
|
||||
|
||||
The `ntp` (Network Time Protocol) package should be installed. This prevents errors with certificate validation that can occur when the time is not synchronized between the client and server.
|
||||
|
||||
Some distributions of Linux may have default firewall rules that block communication with Helm. We recommend disabling firewalld. For Kubernetes 1.19, firewalld must be turned off.
|
||||
|
||||
If you plan to run Rancher on ARM64, see [Running on ARM64 (Experimental).](../advanced-options/enable-experimental-features/rancher-on-arm64.md)
|
||||
|
||||
### RKE Specific Requirements
|
||||
|
||||
For the container runtime, RKE should work with any modern Docker version.
|
||||
|
||||
### K3s Specific Requirements
|
||||
|
||||
For the container runtime, K3s should work with any modern version of Docker or containerd.
|
||||
|
||||
Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script.
|
||||
|
||||
If you are installing Rancher on a K3s cluster with **Raspbian Buster**, follow [these steps](https://rancher.com/docs/k3s/latest/en/advanced/#enabling-legacy-iptables-on-raspbian-buster) to switch to legacy iptables.
|
||||
|
||||
If you are installing Rancher on a K3s cluster with Alpine Linux, follow [these steps](https://rancher.com/docs/k3s/latest/en/advanced/#additional-preparation-for-alpine-linux-setup) for additional setup.
|
||||
|
||||
### Installing Docker
|
||||
|
||||
Docker is required for Helm chart installs, and it can be installed by following the steps in the official [Docker documentation.](https://docs.docker.com/) Rancher also provides [scripts](install-docker.md) to install Docker with one command.
|
||||
|
||||
## Hardware Requirements
|
||||
|
||||
This section describes the CPU, memory, and disk requirements for the nodes where the Rancher server is installed.
|
||||
|
||||
### 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 in a single container with Docker, or if you are installing Rancher on a Kubernetes cluster.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="RKE">
|
||||
|
||||
These requirements apply to each host in an [RKE Kubernetes cluster where the Rancher server is installed.](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)
|
||||
|
||||
Performance increased in Rancher v2.4.0. For the requirements of Rancher before v2.4.0, refer to [this section.](#cpu-and-memory-for-rancher-before-v240)
|
||||
|
||||
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
|
||||
| --------------- | ---------- | ------------ | -------| ------- |
|
||||
| Small | Up to 150 | Up to 1500 | 2 | 8 GB |
|
||||
| Medium | Up to 300 | Up to 3000 | 4 | 16 GB |
|
||||
| Large | Up to 500 | Up to 5000 | 8 | 32 GB |
|
||||
| X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB |
|
||||
| XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB |
|
||||
|
||||
Every use case and environment is different. Please [contact Rancher](https://rancher.com/contact/) to review yours.
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="K3s">
|
||||
|
||||
These requirements apply to each host in a [K3s Kubernetes cluster where the Rancher server is installed.](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)
|
||||
|
||||
| Deployment Size | Clusters | Nodes | vCPUs | RAM | Database Size |
|
||||
| --------------- | ---------- | ------------ | -------| ---------| ------------------------- |
|
||||
| Small | Up to 150 | Up to 1500 | 2 | 8 GB | 2 cores, 4 GB + 1000 IOPS |
|
||||
| Medium | Up to 300 | Up to 3000 | 4 | 16 GB | 2 cores, 4 GB + 1000 IOPS |
|
||||
| Large | Up to 500 | Up to 5000 | 8 | 32 GB | 2 cores, 4 GB + 1000 IOPS |
|
||||
| X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB | 2 cores, 4 GB + 1000 IOPS |
|
||||
| XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB | 2 cores, 4 GB + 1000 IOPS |
|
||||
|
||||
Every use case and environment is different. Please [contact Rancher](https://rancher.com/contact/) to review yours.
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker">
|
||||
|
||||
These requirements apply to a host with a [single-node](../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) installation of Rancher.
|
||||
|
||||
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
|
||||
| --------------- | -------- | --------- | ----- | ---- |
|
||||
| Small | Up to 5 | Up to 50 | 1 | 4 GB |
|
||||
| Medium | Up to 15 | Up to 200 | 2 | 8 GB |
|
||||
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### CPU and Memory for Rancher before v2.4.0
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
These requirements apply to installing Rancher on an RKE Kubernetes cluster before Rancher v2.4.0:
|
||||
|
||||
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
|
||||
| --------------- | --------- | ---------- | ----------------------------------------------- | ----------------------------------------------- |
|
||||
| Small | Up to 5 | Up to 50 | 2 | 8 GB |
|
||||
| Medium | Up to 15 | Up to 200 | 4 | 16 GB |
|
||||
| Large | Up to 50 | Up to 500 | 8 | 32 GB |
|
||||
| X-Large | Up to 100 | Up to 1000 | 32 | 128 GB |
|
||||
| XX-Large | 100+ | 1000+ | [Contact Rancher](https://rancher.com/contact/) | [Contact Rancher](https://rancher.com/contact/) |
|
||||
</details>
|
||||
|
||||
### Disks
|
||||
|
||||
Rancher performance depends on etcd in the cluster performance. To ensure optimal speed, we recommend always using SSD disks to back your Rancher management Kubernetes cluster. On cloud providers, you will also want to use the minimum size that allows the maximum IOPS. In larger clusters, consider using dedicated storage devices for etcd data and wal directories.
|
||||
|
||||
## Networking Requirements
|
||||
|
||||
This section describes the networking requirements for the node(s) where the Rancher server is installed.
|
||||
|
||||
### Node IP Addresses
|
||||
|
||||
Each node used should have a static IP configured, regardless of whether you are installing Rancher on a single node or on an HA cluster. In case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.
|
||||
|
||||
### Port Requirements
|
||||
|
||||
To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. [Port Requirements](port-requirements.md) lists all the necessary ports for Rancher and Downstream Clusters for the different cluster types.
|
||||
+5
-5
@@ -135,9 +135,9 @@ The following tables break down the port requirements for Rancher nodes, for inb
|
||||
|
||||
Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them.
|
||||
|
||||
The port requirements differ depending on how the downstream cluster was launched. Each of the tabs below list the ports that need to be opened for different [cluster types](../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md).
|
||||
The port requirements differ depending on how the downstream cluster was launched. Each of the tabs below list the ports that need to be opened for different [cluster types](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
The following diagram depicts the ports that are opened for each [cluster type](../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md).
|
||||
The following diagram depicts the ports that are opened for each [cluster type](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<figcaption>Port Requirements for the Rancher Management Plane</figcaption>
|
||||
|
||||
@@ -152,7 +152,7 @@ The following diagram depicts the ports that are opened for each [cluster type](
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
The following table depicts the port requirements for [Rancher Launched Kubernetes](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) with nodes created in an [Infrastructure Provider](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md).
|
||||
The following table depicts the port requirements for [Rancher Launched Kubernetes](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) with nodes created in an [Infrastructure Provider](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md).
|
||||
|
||||
>**Note:**
|
||||
>The required ports are automatically opened by Rancher during creation of clusters in cloud providers like Amazon EC2 or DigitalOcean.
|
||||
@@ -166,7 +166,7 @@ The following table depicts the port requirements for [Rancher Launched Kubernet
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
The following table depicts the port requirements for [Rancher Launched Kubernetes](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) with [Custom Nodes](../../../pages-for-subheaders/use-existing-nodes.md).
|
||||
The following table depicts the port requirements for [Rancher Launched Kubernetes](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) with [Custom Nodes](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md).
|
||||
|
||||
<PortsCustomNodes/>
|
||||
|
||||
@@ -177,7 +177,7 @@ The following table depicts the port requirements for [Rancher Launched Kubernet
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
The following table depicts the port requirements for [hosted clusters](../../../pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.md).
|
||||
The following table depicts the port requirements for [hosted clusters](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md).
|
||||
|
||||
<PortsImportedHosted/>
|
||||
|
||||
|
||||
+30
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Air Gapped Helm CLI Install
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/air-gapped-helm-cli-install"/>
|
||||
</head>
|
||||
|
||||
This section is about using the Helm CLI to install the Rancher server in an air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
|
||||
|
||||
The installation steps differ depending on whether Rancher is installed on an RKE Kubernetes cluster, a K3s Kubernetes cluster, or a single Docker container.
|
||||
|
||||
For more information on each installation option, refer to [this page.](../../installation-and-upgrade.md)
|
||||
|
||||
Throughout the installation instructions, there will be _tabs_ for each installation option.
|
||||
|
||||
> **Important:** If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation.
|
||||
|
||||
## Installation Outline
|
||||
|
||||
1. [Set up infrastructure and private registry](infrastructure-private-registry.md)
|
||||
2. [Collect and publish images to your private registry](publish-images.md)
|
||||
3. [Set up a Kubernetes cluster (Skip this step for Docker installations)](install-kubernetes.md)
|
||||
4. [Install Rancher](install-rancher-ha.md)
|
||||
|
||||
## Upgrades
|
||||
|
||||
To upgrade Rancher with Helm CLI in an air gap environment, follow [this procedure.](../../install-upgrade-on-a-kubernetes-cluster/upgrades/upgrades.md)
|
||||
|
||||
### [Next: Prepare your Node(s)](infrastructure-private-registry.md)
|
||||
+4
-4
@@ -10,7 +10,7 @@ In this section, you will provision the underlying infrastructure for your Ranch
|
||||
|
||||
An air gapped environment is an environment where the Rancher server is installed offline or behind a firewall.
|
||||
|
||||
The infrastructure depends on whether you are installing Rancher on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. For more information on each installation option, refer to [this page.](../../../../pages-for-subheaders/installation-and-upgrade.md)
|
||||
The infrastructure depends on whether you are installing Rancher on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. For more information on each installation option, refer to [this page.](../../installation-and-upgrade.md)
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="K3s">
|
||||
@@ -27,7 +27,7 @@ We recommend setting up the following infrastructure for a high-availability ins
|
||||
|
||||
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
|
||||
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../../../pages-for-subheaders/installation-requirements.md)
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../installation-requirements/installation-requirements.md)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
@@ -107,7 +107,7 @@ The etcd database requires an odd number of nodes so that it can always elect a
|
||||
|
||||
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
|
||||
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../../../pages-for-subheaders/installation-requirements.md)
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../installation-requirements/installation-requirements.md)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
@@ -161,7 +161,7 @@ If you need help with creating a private registry, please refer to the [official
|
||||
|
||||
This host will be disconnected from the Internet, but needs to be able to connect to your private registry.
|
||||
|
||||
Make sure that your node fulfills the general installation requirements for [OS, Docker, hardware, and networking.](../../../../pages-for-subheaders/installation-requirements.md)
|
||||
Make sure that your node fulfills the general installation requirements for [OS, Docker, hardware, and networking.](../../installation-requirements/installation-requirements.md)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Other Installation Methods
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/other-installation-methods"/>
|
||||
</head>
|
||||
|
||||
### Air Gapped Installations
|
||||
|
||||
Follow [these steps](air-gapped-helm-cli-install.md) to install the Rancher server in an air gapped environment.
|
||||
|
||||
An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
|
||||
|
||||
### Docker Installations
|
||||
|
||||
The [single-node Docker installation](../rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a `docker run` command.
|
||||
|
||||
The Docker installation is for development and testing environments only.
|
||||
|
||||
Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.
|
||||
|
||||
There is no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start.
|
||||
+2
-2
@@ -8,11 +8,11 @@ title: '2. Collect and Publish Images to your Private Registry'
|
||||
|
||||
This section describes how to set up your private registry so that when you install Rancher, Rancher will pull all the required images from this registry.
|
||||
|
||||
By default, all images used to [provision Kubernetes clusters](../../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md) or launch any [tools](../../../../reference-guides/rancher-cluster-tools.md) in Rancher, e.g. monitoring, pipelines, alerts, are pulled from Docker Hub. In an air gapped installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.
|
||||
By default, all images used to [provision Kubernetes clusters](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) or launch any [tools](../../../../reference-guides/rancher-cluster-tools.md) in Rancher, e.g. monitoring, pipelines, alerts, are pulled from Docker Hub. In an air gapped installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.
|
||||
|
||||
Populating the private registry with images is the same process for installing Rancher with Docker and for installing Rancher on a Kubernetes cluster.
|
||||
|
||||
The steps in this section differ depending on whether or not you are planning to use Rancher to provision a downstream cluster with Windows nodes or not. By default, we provide the steps of how to populate your private registry assuming that Rancher will provision downstream Kubernetes clusters with only Linux nodes. But if you plan on provisioning any [downstream Kubernetes clusters using Windows nodes](../../../../pages-for-subheaders/use-windows-clusters.md), there are separate instructions to support the images needed.
|
||||
The steps in this section differ depending on whether or not you are planning to use Rancher to provision a downstream cluster with Windows nodes or not. By default, we provide the steps of how to populate your private registry assuming that Rancher will provision downstream Kubernetes clusters with only Linux nodes. But if you plan on provisioning any [downstream Kubernetes clusters using Windows nodes](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/use-windows-clusters.md), there are separate instructions to support the images needed.
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Installing Rancher behind an HTTP Proxy
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/rancher-behind-an-http-proxy"/>
|
||||
</head>
|
||||
|
||||
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 set 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](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md).
|
||||
|
||||
## Installation Outline
|
||||
|
||||
1. [Set up infrastructure](set-up-infrastructure.md)
|
||||
2. [Set up a Kubernetes cluster](install-kubernetes.md)
|
||||
3. [Install Rancher](install-rancher.md)
|
||||
+1
-1
@@ -26,7 +26,7 @@ The etcd database requires an odd number of nodes so that it can always elect a
|
||||
|
||||
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.](../../../../pages-for-subheaders/installation-requirements.md)
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../installation-requirements/installation-requirements.md)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
|
||||
+162
@@ -0,0 +1,162 @@
|
||||
---
|
||||
title: Installing Rancher on a Single Node Using Docker
|
||||
description: For development and testing environments only, use a Docker install. Install Docker on a single Linux host, and deploy Rancher with a single Docker container.
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/rancher-on-a-single-node-with-docker"/>
|
||||
</head>
|
||||
|
||||
Rancher can be installed by running a single Docker container.
|
||||
|
||||
In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container.
|
||||
|
||||
> **Want to use an external load balancer?**
|
||||
> See [Docker Install with an External Load Balancer](../../advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.md) instead.
|
||||
|
||||
A Docker installation of Rancher is recommended only for development and testing purposes.
|
||||
|
||||
For Rancher v2.0-v2.4, there is no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start.
|
||||
|
||||
## Requirements for OS, Docker, Hardware, and Networking
|
||||
|
||||
Make sure that your node fulfills the general [installation requirements.](../../installation-requirements/installation-requirements.md)
|
||||
|
||||
## 1. Provision Linux Host
|
||||
|
||||
Provision a single Linux host according to our [Requirements](../../installation-requirements/installation-requirements.md) to launch your Rancher server.
|
||||
|
||||
## 2. Choose an SSL Option and Install Rancher
|
||||
|
||||
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
|
||||
|
||||
> **Do you want to...**
|
||||
>
|
||||
> - Use a proxy? See [HTTP Proxy Configuration](../../../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md)
|
||||
> - Configure custom CA root certificate to access your services? See [Custom CA root certificate](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#custom-ca-certificate)
|
||||
> - Complete an Air Gap Installation? See [Air Gap: Docker Install](../../advanced-options/advanced-use-cases/air-gap-helm2/air-gap-helm2.md)
|
||||
> - Record all transactions with the Rancher API? See [API Auditing](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log)
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
- [Option A: Default Rancher-generated Self-signed Certificate](#option-a-default-rancher-generated-self-signed-certificate)
|
||||
- [Option B: Bring Your Own Certificate, Self-signed](#option-b-bring-your-own-certificate-self-signed)
|
||||
- [Option C: Bring Your Own Certificate, Signed by a Recognized CA](#option-c-bring-your-own-certificate-signed-by-a-recognized-ca)
|
||||
- [Option D: Let's Encrypt Certificate](#option-d-lets-encrypt-certificate)
|
||||
|
||||
### Option A: Default Rancher-generated Self-signed Certificate
|
||||
|
||||
If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.
|
||||
|
||||
Log into your Linux host, and then run the minimum installation command below.
|
||||
|
||||
|
||||
```bash
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
rancher/rancher:latest
|
||||
```
|
||||
|
||||
### Option B: Bring Your Own Certificate, Self-signed
|
||||
In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher.
|
||||
|
||||
> **Prerequisites:**
|
||||
> Create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice.
|
||||
>
|
||||
> - The certificate files must be in PEM format.
|
||||
> - In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](certificate-troubleshooting.md)
|
||||
|
||||
After creating your certificate, run the Docker command below to install Rancher. Use the `-v` flag and provide the path to your certificates to mount them in your container.
|
||||
|
||||
| Placeholder | Description |
|
||||
| ------------------- | --------------------- |
|
||||
| `<CERT_DIRECTORY>` | The path to the directory containing your certificate files. |
|
||||
| `<FULL_CHAIN.pem>` | The path to your full certificate chain. |
|
||||
| `<PRIVATE_KEY.pem>` | The path to the private key for your certificate. |
|
||||
| `<CA_CERTS.pem>` | The path to the certificate authority's certificate. |
|
||||
|
||||
```bash
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
|
||||
-v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
|
||||
-v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
|
||||
rancher/rancher:latest
|
||||
```
|
||||
|
||||
### Option C: Bring Your Own Certificate, Signed by a Recognized CA
|
||||
|
||||
In production environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings.
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> - The certificate files must be in PEM format.
|
||||
> - In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](certificate-troubleshooting.md)
|
||||
|
||||
After obtaining your certificate, run the Docker command below.
|
||||
|
||||
- Use the `-v` flag and provide the path to your certificates to mount them in your container. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
|
||||
- Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher.
|
||||
|
||||
| Placeholder | Description |
|
||||
| ------------------- | ----------------------------- |
|
||||
| `<CERT_DIRECTORY>` | The path to the directory containing your certificate files. |
|
||||
| `<FULL_CHAIN.pem>` | The path to your full certificate chain. |
|
||||
| `<PRIVATE_KEY.pem>` | The path to the private key for your certificate. |
|
||||
|
||||
|
||||
```bash
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
|
||||
-v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
|
||||
rancher/rancher:latest \
|
||||
--no-cacerts
|
||||
```
|
||||
|
||||
### Option D: Let's Encrypt Certificate
|
||||
|
||||
> **Remember:** Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/).
|
||||
|
||||
For production environments, you also have the option of using [Let's Encrypt](https://letsencrypt.org/) certificates. Let's Encrypt uses an http-01 challenge to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, `rancher.mydomain.com`) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS.
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> - Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network.
|
||||
> - Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (`rancher.mydomain.com` for example).
|
||||
> - Open port `TCP/80` on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port `TCP/80` must be open to all IP addresses.
|
||||
|
||||
After you fulfill the prerequisites, you can install Rancher using a Let's Encrypt certificate by running the following command.
|
||||
|
||||
| Placeholder | Description |
|
||||
| ----------------- | ------------------- |
|
||||
| `<YOUR.DNS.NAME>` | Your domain address |
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
rancher/rancher:latest \
|
||||
--acme-domain <YOUR.DNS.NAME>
|
||||
```
|
||||
|
||||
## Advanced Options
|
||||
|
||||
When installing Rancher on a single node with Docker, there are several advanced options that can be enabled:
|
||||
|
||||
- Custom CA Certificate
|
||||
- API Audit Log
|
||||
- TLS Settings
|
||||
- Air Gap
|
||||
- Persistent Data
|
||||
- Running `rancher/rancher` and `rancher/rancher-agent` on the Same Node
|
||||
|
||||
Refer to [this page](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md) for details.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Refer to [this page](certificate-troubleshooting.md) for frequently asked questions and troubleshooting tips.
|
||||
|
||||
## What's Next?
|
||||
|
||||
- **Recommended:** Review Single Node [Backup](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md) and [Restore](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md). Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use.
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
+2
-2
@@ -10,8 +10,8 @@ The following instructions will guide you through upgrading a Rancher server tha
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Review the [known upgrade issues](../../../../pages-for-subheaders/upgrades.md#known-upgrade-issues) in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12) Note that upgrades to or from any chart in the [rancher-alpha repository](../../resources/choose-a-rancher-version.md#helm-chart-repositories) aren’t supported.
|
||||
- **For [air gap installs only,](../../../../pages-for-subheaders/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version.** Follow the guide to [populate your private registry](../air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
|
||||
- **Review the [known upgrade issues](../../install-upgrade-on-a-kubernetes-cluster/upgrades/upgrades.md#known-upgrade-issues) in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12) Note that upgrades to or from any chart in the [rancher-alpha repository](../../resources/choose-a-rancher-version.md#helm-chart-repositories) aren’t supported.
|
||||
- **For [air gap installs only,](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version.** Follow the guide to [populate your private registry](../air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
|
||||
|
||||
## Placeholder Review
|
||||
|
||||
|
||||
+1
-1
@@ -38,4 +38,4 @@ kubectl -n cattle-system create secret generic tls-ca \
|
||||
|
||||
## Updating a Private CA Certificate
|
||||
|
||||
Follow the steps on [this page](update-rancher-certificate.md) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate.
|
||||
Follow the steps on [this page](update-rancher-certificate.md) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate.
|
||||
+3
-3
@@ -15,7 +15,7 @@ For Docker installations of Rancher, which is used for development and testing,
|
||||
<Tabs>
|
||||
<TabItem value="Helm Charts">
|
||||
|
||||
When installing, upgrading, or rolling back Rancher Server when it is [installed on a Kubernetes cluster](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md), Rancher server is installed using a Helm chart on a Kubernetes cluster. Therefore, as you prepare to install or upgrade a high availability Rancher configuration, you must add a Helm chart repository that contains the charts for installing Rancher.
|
||||
When installing, upgrading, or rolling back Rancher Server when it is [installed on a Kubernetes cluster](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md), Rancher server is installed using a Helm chart on a Kubernetes cluster. Therefore, as you prepare to install or upgrade a high availability Rancher configuration, you must add a Helm chart repository that contains the charts for installing Rancher.
|
||||
|
||||
Refer to the [Helm version requirements](./helm-version-requirements.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
@@ -88,12 +88,12 @@ After installing Rancher, if you want to change which Helm chart repository to i
|
||||
helm repo add rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
|
||||
```
|
||||
|
||||
4. Continue to follow the steps to [upgrade Rancher](../../../pages-for-subheaders/upgrades.md) from the new Helm chart repository.
|
||||
4. Continue to follow the steps to [upgrade Rancher](../install-upgrade-on-a-kubernetes-cluster/upgrades/upgrades.md) from the new Helm chart repository.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker Images">
|
||||
|
||||
When performing [Docker installs](../../../pages-for-subheaders/rancher-on-a-single-node-with-docker.md), upgrades, or rollbacks, you can use _tags_ to install a specific version of Rancher.
|
||||
When performing [Docker installs](../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md), upgrades, or rollbacks, you can use _tags_ to install a specific version of Rancher.
|
||||
|
||||
### Server Tags
|
||||
|
||||
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Resources
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/resources"/>
|
||||
</head>
|
||||
|
||||
### Docker Installations
|
||||
|
||||
The [single-node Docker installation](../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a `docker run` command.
|
||||
|
||||
Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.
|
||||
|
||||
### Air Gapped Installations
|
||||
|
||||
Follow [these steps](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) to install the Rancher server in an air gapped environment.
|
||||
|
||||
An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
|
||||
|
||||
### Advanced Options
|
||||
|
||||
When installing Rancher, there are several advanced options that can be enabled during installation. Within each install guide, these options are presented. Learn more about these options:
|
||||
|
||||
| Advanced Option | Available as of |
|
||||
| ----------------------------------------------------------------------------------------------------------------------- | --------------- |
|
||||
| [Custom CA Certificate](custom-ca-root-certificates.md) | v2.0.0 |
|
||||
| [API Audit Log](../advanced-options/advanced-use-cases/enable-api-audit-log.md) | v2.0.0 |
|
||||
| [TLS Settings](../../../reference-guides/installation-references/tls-settings.md) | v2.1.7 |
|
||||
| [etcd configuration](../advanced-options/advanced-use-cases/tune-etcd-for-large-installs.md) | v2.2.0 |
|
||||
| [Local System Charts for Air Gap Installations](local-system-charts.md) | v2.3.0 |
|
||||
+1
-1
@@ -8,7 +8,7 @@ title: Updating the Rancher Certificate
|
||||
|
||||
## Updating a Private CA Certificate
|
||||
|
||||
Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate.
|
||||
Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate.
|
||||
|
||||
A summary of the steps is as follows:
|
||||
|
||||
|
||||
+1
-1
@@ -26,7 +26,7 @@ To address these changes, this guide will do two things:
|
||||
|
||||
> The reason is that when Helm upgrades Rancher, it will reject the upgrade and show error messages if the running Rancher app does not match the chart template used to install it. Because cert-manager changed its API group and we cannot modify released charts for Rancher, there will always be a mismatch on the cert-manager's API version, therefore the upgrade will be rejected.
|
||||
|
||||
> For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart](../../../pages-for-subheaders/upgrades.md) under the upgrade Rancher section.
|
||||
> For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart](../install-upgrade-on-a-kubernetes-cluster/upgrades/upgrades.md) under the upgrade Rancher section.
|
||||
|
||||
## Upgrade Cert-Manager Only
|
||||
|
||||
|
||||
+1
-1
@@ -26,7 +26,7 @@ To address these changes, this guide will do two things:
|
||||
|
||||
> The reason is that when Helm upgrades Rancher, it will reject the upgrade and show error messages if the running Rancher app does not match the chart template used to install it. Because cert-manager changed its API group and we cannot modify released charts for Rancher, there will always be a mismatch on the cert-manager's API version, therefore the upgrade will be rejected.
|
||||
|
||||
> For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart](../../../pages-for-subheaders/upgrades.md) under the upgrade Rancher section.
|
||||
> For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart](../install-upgrade-on-a-kubernetes-cluster/upgrades/upgrades.md) under the upgrade Rancher section.
|
||||
|
||||
## Upgrade Cert-Manager
|
||||
|
||||
|
||||
+2
-2
@@ -61,8 +61,8 @@ The cluster cannot be downgraded to a previous Kubernetes version.
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> - The options below are available only for [Rancher-launched RKE Kubernetes clusters](../../pages-for-subheaders/launch-kubernetes-with-rancher.md) and imported/registered K3s Kubernetes clusters.
|
||||
> - Before upgrading Kubernetes, [back up your cluster.](../../pages-for-subheaders/backup-restore-and-disaster-recovery.md)
|
||||
> - The options below are available only for [Rancher-launched RKE Kubernetes clusters](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) and imported/registered K3s Kubernetes clusters.
|
||||
> - Before upgrading Kubernetes, [back up your cluster.](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md)
|
||||
|
||||
1. From the **Global** view, find the cluster for which you want to upgrade Kubernetes. Select **⋮ > Edit**.
|
||||
|
||||
|
||||
+1
-1
@@ -12,7 +12,7 @@ The RKE metadata feature allows you to provision clusters with new versions of K
|
||||
|
||||
> **Note:** The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions.
|
||||
|
||||
Rancher's Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision [RKE clusters](../../pages-for-subheaders/launch-kubernetes-with-rancher.md). Rancher syncs the data periodically and creates custom resource definitions (CRDs) for **system images,** **service options** and **addon templates.** Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/) (RKE) uses for deploying various Kubernetes versions.
|
||||
Rancher's Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision [RKE clusters](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md). Rancher syncs the data periodically and creates custom resource definitions (CRDs) for **system images,** **service options** and **addon templates.** Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/) (RKE) uses for deploying various Kubernetes versions.
|
||||
|
||||
This table below describes the CRDs that are affected by the periodic data sync.
|
||||
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/overview"/>
|
||||
</head>
|
||||
|
||||
The [overview](overview.md) will discuss Rancher's features, capabilities, and how it makes running Kubernetes easy. The guide to the [new Rancher docs structure, Divio,](what-are-divio-docs.md) will explain more about the updated look and function of our docs.
|
||||
@@ -34,21 +34,21 @@ The Rancher API server is built on top of an embedded Kubernetes API server and
|
||||
|
||||
### Authorization and Role-Based Access Control
|
||||
|
||||
- **User management:** The Rancher API server [manages user identities](../../pages-for-subheaders/about-authentication.md) that correspond to external authentication providers like Active Directory or GitHub, in addition to local users.
|
||||
- **Authorization:** The Rancher API server manages [access control](../../pages-for-subheaders/manage-role-based-access-control-rbac.md) and [security](../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.md) policies.
|
||||
- **User management:** The Rancher API server [manages user identities](../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/about-authentication.md) that correspond to external authentication providers like Active Directory or GitHub, in addition to local users.
|
||||
- **Authorization:** The Rancher API server manages [access control](../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md) and [security](../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.md) policies.
|
||||
|
||||
### Working with Kubernetes
|
||||
|
||||
- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes](../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md) on existing nodes, or perform [Kubernetes upgrades.](../installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)
|
||||
- **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts](../../pages-for-subheaders/helm-charts-in-rancher.md) that make it easy to repeatedly deploy applications.
|
||||
- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, which allows you to manage multiple namespaces as a group and perform Kubernetes operations in them. The Rancher UI provides features for [project administration](../../pages-for-subheaders/manage-projects.md) and for [managing applications within projects.](../../pages-for-subheaders/kubernetes-resources-setup.md)
|
||||
- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) on existing nodes, or perform [Kubernetes upgrades.](../installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)
|
||||
- **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts](../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md) that make it easy to repeatedly deploy applications.
|
||||
- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, which allows you to manage multiple namespaces as a group and perform Kubernetes operations in them. The Rancher UI provides features for [project administration](../../how-to-guides/advanced-user-guides/manage-projects/manage-projects.md) and for [managing applications within projects.](../../how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-resources-setup.md)
|
||||
- **Pipelines:** Setting up a [pipeline](../../how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.md) can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects.
|
||||
- **Istio:** Our [integration with Istio](../../pages-for-subheaders/istio.md) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.
|
||||
- **Istio:** Our [integration with Istio](../../explanations/integrations-in-rancher/istio/istio.md) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.
|
||||
|
||||
### Working with Cloud Infrastructure
|
||||
|
||||
- **Tracking nodes:** The Rancher API server tracks identities of all the [nodes](../../how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.md) in all clusters.
|
||||
- **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision [new nodes](../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md) and [persistent storage](../../pages-for-subheaders/create-kubernetes-persistent-storage.md) in the cloud.
|
||||
- **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision [new nodes](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md) and [persistent storage](../../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md) in the cloud.
|
||||
|
||||
### Cluster Visibility
|
||||
|
||||
@@ -58,9 +58,9 @@ The Rancher API server is built on top of an embedded Kubernetes API server and
|
||||
|
||||
## Editing Downstream Clusters with Rancher
|
||||
|
||||
The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE](../../pages-for-subheaders/launch-kubernetes-with-rancher.md) have **Cluster Options** available for editing.
|
||||
The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) have **Cluster Options** available for editing.
|
||||
|
||||
After a cluster is created with Rancher, a cluster administrator can manage cluster membership, enable pod security policies, and manage node pools, among [other options.](../../pages-for-subheaders/cluster-configuration.md)
|
||||
After a cluster is created with Rancher, a cluster administrator can manage cluster membership, enable pod security policies, and manage node pools, among [other options.](../../reference-guides/cluster-configuration/cluster-configuration.md)
|
||||
|
||||
The following table summarizes the options and settings available for each cluster type:
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ title: What Are Divio Docs?
|
||||
|
||||
The [Divio documentation system](https://documentation.divio.com/) is a software documentation paradigm that is based on functionality and the premise that the best documentation is specific, concise, and purposeful. Divio traditionally consists of four main categories: tutorials, how-to guides, reference guides, and explanations.
|
||||
|
||||
In our docs, we have used this guideline to craft a unique set of docs which include [getting started](../../getting-started.md), [how-to guides](../../how-to-guides.md) (including [new](../../pages-for-subheaders/new-user-guides.md) and [advanced user guides](../../pages-for-subheaders/advanced-user-guides.md)), [reference guides](../../reference-guides.md), [explanations](../../explanations.md), an [FAQ section](../../faq.md), [troubleshooting tips](../../troubleshooting.md), and the ability to [contribute to Rancher](../../contribute-to-rancher.md).
|
||||
In our docs, we have used this guideline to craft a unique set of docs which include [getting started](../../getting-started.md), [how-to guides](../../how-to-guides.md) (including [new](../../how-to-guides/new-user-guides/new-user-guides.md) and [advanced user guides](../../how-to-guides/advanced-user-guides/advanced-user-guides.md)), [reference guides](../../reference-guides.md), [explanations](../../explanations.md), an [FAQ section](../../faq.md), [troubleshooting tips](../../troubleshooting.md), and the ability to [contribute to Rancher](../../contribute-to-rancher.md).
|
||||
|
||||
- [Getting Started](#getting-started)
|
||||
- [How-to Guides](#how-to-guides)
|
||||
@@ -27,7 +27,7 @@ To get up and running with Rancher quickly, we have included a **Getting Started
|
||||
|
||||
The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.
|
||||
|
||||
Please see the [introduction](../../pages-for-subheaders/introduction.md), [quick start guides](../../pages-for-subheaders/quick-start-guides.md), and the [installation and upgrade](../../pages-for-subheaders/installation-and-upgrade.md) sections for more.
|
||||
Please see the [introduction](introduction.md), [quick start guides](../quick-start-guides/quick-start-guides.md), and the [installation and upgrade](../installation-and-upgrade/installation-and-upgrade.md) sections for more.
|
||||
|
||||
## How-to Guides
|
||||
|
||||
@@ -59,7 +59,7 @@ These docs may also include some usage steps in the course of description; howev
|
||||
|
||||
The users who utilize reference guides are knowledgeable with the Rancher product as well as how to use it. They will benefit from detailed descriptions of something to be used when needing to refer to specifics of usage.
|
||||
|
||||
Good examples of Rancher reference guides would be the [Rancher architecture](../../pages-for-subheaders/rancher-manager-architecture.md) and [cluster configuration guides](../../pages-for-subheaders/cluster-configuration.md).
|
||||
Good examples of Rancher reference guides would be the [Rancher architecture](../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md) and [cluster configuration guides](../../reference-guides/cluster-configuration/cluster-configuration.md).
|
||||
|
||||
## Explanations
|
||||
|
||||
@@ -67,13 +67,13 @@ Explanation docs are concerned primarily with providing theoretical knowledge fo
|
||||
|
||||
Explanatory docs do not instruct the user how to do something, as in tutorials and how-to guides, nor do they give detailed descriptions as references do. Explanations serve to give substance and background on both simple and complex topics.
|
||||
|
||||
For our new docs, we are working to build up this section as most of our previous documentation was process-oriented rather than discussion-oriented. Currently, we feature [Integrations in Rancher](../../pages-for-subheaders/integrations-in-rancher.md) to discuss our integrated products.
|
||||
For our new docs, we are working to build up this section as most of our previous documentation was process-oriented rather than discussion-oriented. Currently, we feature [Integrations in Rancher](../../explanations/integrations-in-rancher/integrations-in-rancher.md) to discuss our integrated products.
|
||||
|
||||
### Integrations in Rancher
|
||||
|
||||
Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI. To assist users in learning more about these integrations, this subsection has been added under **Explanations**.
|
||||
|
||||
Examples of some of these integrations are [Istio](../../pages-for-subheaders/istio.md) and [CIS Scans](../../pages-for-subheaders/cis-scans.md).
|
||||
Examples of some of these integrations are [Istio](../../explanations/integrations-in-rancher/istio/istio.md) and [CIS Scans](../../explanations/integrations-in-rancher/cis-scans/cis-scans.md).
|
||||
|
||||
## Other Docs Categories
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ Interact with Rancher using command line interface (CLI) tools from your worksta
|
||||
|
||||
## Rancher CLI
|
||||
|
||||
Follow the steps in [rancher cli](../../pages-for-subheaders/cli-with-rancher.md).
|
||||
Follow the steps in [rancher cli](../../reference-guides/cli-with-rancher/cli-with-rancher.md).
|
||||
|
||||
Ensure you can run `rancher kubectl get pods` successfully.
|
||||
|
||||
|
||||
+2
-2
@@ -9,7 +9,7 @@ description: Read this step by step Rancher AWS guide to quickly deploy a Ranche
|
||||
|
||||
The following steps will quickly deploy a Rancher Server on AWS with a single node cluster attached.
|
||||
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../../pages-for-subheaders/installation-and-upgrade.md).
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -63,7 +63,7 @@ Two Kubernetes clusters are deployed into your AWS account, one running Rancher
|
||||
|
||||
### What's Next?
|
||||
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../../../pages-for-subheaders/deploy-rancher-workloads.md).
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-rancher-workloads.md).
|
||||
|
||||
## Destroying the Environment
|
||||
|
||||
|
||||
+2
-2
@@ -9,7 +9,7 @@ description: Read this step by step Rancher Azure guide to quickly deploy a Ranc
|
||||
|
||||
The following steps will quickly deploy a Rancher server on Azure in a single-node RKE Kubernetes cluster, with a single-node downstream Kubernetes cluster attached.
|
||||
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../../pages-for-subheaders/installation-and-upgrade.md).
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -68,7 +68,7 @@ Two Kubernetes clusters are deployed into your Azure account, one running Ranche
|
||||
|
||||
### What's Next?
|
||||
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../../../pages-for-subheaders/deploy-rancher-workloads.md).
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-rancher-workloads.md).
|
||||
|
||||
## Destroying the Environment
|
||||
|
||||
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: Deploying Rancher Server
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/deploy-rancher-manager"/>
|
||||
</head>
|
||||
|
||||
Use one of the following guides to deploy and provision Rancher and a Kubernetes cluster in the provider of your choice.
|
||||
|
||||
- [DigitalOcean](digitalocean.md) (uses Terraform)
|
||||
- [AWS](aws.md) (uses Terraform)
|
||||
- [Azure](azure.md) (uses Terraform)
|
||||
- [GCP](gcp.md) (uses Terraform)
|
||||
- [Vagrant](vagrant.md)
|
||||
|
||||
If you prefer, the following guide will take you through the same process in individual steps. Use this if you want to run Rancher in a different provider, on prem, or if you would just like to see how easy it is.
|
||||
|
||||
- [Manual Install](helm-cli.md)
|
||||
+2
-2
@@ -9,7 +9,7 @@ description: Read this step by step Rancher DigitalOcean guide to quickly deploy
|
||||
|
||||
The following steps will quickly deploy a Rancher Server on DigitalOcean with a single node cluster attached.
|
||||
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../../pages-for-subheaders/installation-and-upgrade.md).
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -63,7 +63,7 @@ Two Kubernetes clusters are deployed into your DigitalOcean account, one running
|
||||
|
||||
### What's Next?
|
||||
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../../../pages-for-subheaders/deploy-rancher-workloads.md).
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-rancher-workloads.md).
|
||||
|
||||
## Destroying the Environment
|
||||
|
||||
|
||||
+2
-2
@@ -9,7 +9,7 @@ description: Read this step by step Rancher GCP guide to quickly deploy a Ranche
|
||||
|
||||
The following steps will quickly deploy a Rancher server on GCP in a single-node RKE Kubernetes cluster, with a single-node downstream Kubernetes cluster attached.
|
||||
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../../pages-for-subheaders/installation-and-upgrade.md).
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -64,7 +64,7 @@ Two Kubernetes clusters are deployed into your GCP account, one running Rancher
|
||||
|
||||
### What's Next?
|
||||
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../../../pages-for-subheaders/deploy-rancher-workloads.md).
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-rancher-workloads.md).
|
||||
|
||||
## Destroying the Environment
|
||||
|
||||
|
||||
+3
-3
@@ -8,7 +8,7 @@ Howdy Partner! This tutorial walks you through:
|
||||
- Creation of your first cluster
|
||||
- Deployment of an application, Nginx
|
||||
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../../pages-for-subheaders/installation-and-upgrade.md).
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md).
|
||||
|
||||
## Quick Start Outline
|
||||
|
||||
@@ -28,7 +28,7 @@ This Quick Start Guide is divided into different tasks for easier consumption.
|
||||
>
|
||||
> For a full list of port requirements, refer to [Docker Installation](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md).
|
||||
|
||||
Provision the host according to our [Requirements](../../../pages-for-subheaders/installation-requirements.md).
|
||||
Provision the host according to our [Requirements](../../installation-and-upgrade/installation-requirements/installation-requirements.md).
|
||||
|
||||
### 2. Install Rancher
|
||||
|
||||
@@ -103,4 +103,4 @@ Congratulations! You have created your first cluster.
|
||||
|
||||
#### What's Next?
|
||||
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../../../pages-for-subheaders/deploy-rancher-workloads.md).
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-rancher-workloads.md).
|
||||
|
||||
+2
-2
@@ -8,7 +8,7 @@ title: Vagrant Quick Start
|
||||
|
||||
The following steps quickly deploy a Rancher Server with a single node cluster attached.
|
||||
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../../pages-for-subheaders/installation-and-upgrade.md).
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -42,7 +42,7 @@ The following steps quickly deploy a Rancher Server with a single node cluster a
|
||||
|
||||
### What's Next?
|
||||
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../../../pages-for-subheaders/deploy-rancher-workloads.md).
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-rancher-workloads.md).
|
||||
|
||||
## Destroying the Environment
|
||||
|
||||
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Deploying Workloads
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/deploy-rancher-workloads"/>
|
||||
</head>
|
||||
|
||||
These guides walk you through the deployment of an application, including how to expose the application for use outside of the cluster.
|
||||
|
||||
- [Workload with Ingress](workload-ingress.md)
|
||||
- [Workload with NodePort](nodeports.md)
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: Rancher Deployment Quick Start Guides
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/quick-start-guides"/>
|
||||
</head>
|
||||
|
||||
>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../installation-and-upgrade/installation-and-upgrade.md).
|
||||
|
||||
Howdy buckaroos! Use this section of the docs to jump start your deployment and testing of Rancher 2.x! It contains instructions for a simple Rancher setup and some common use cases. We plan on adding more content to this section in the future.
|
||||
|
||||
We have Quick Start Guides for:
|
||||
|
||||
- [Deploying Rancher Server](deploy-rancher-manager/deploy-rancher-manager.md): Get started running Rancher using the method most convenient for you.
|
||||
|
||||
- [Deploying Workloads](deploy-workloads/deploy-rancher-workloads.md): Deploy a simple [workload](https://kubernetes.io/docs/concepts/workloads/) and expose it, letting you access it from outside the cluster.
|
||||
|
||||
- [Using the CLI](cli.md): Use `kubectl` or Rancher command line interface (CLI) to interact with your Rancher instance.
|
||||
Reference in New Issue
Block a user