From 206e74d32c084e11e3d16ddeab879fcbbed74716 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Mon, 7 Mar 2022 19:22:33 -0700 Subject: [PATCH] Discourage Docker install, encourage Helm CLI install --- .../install-rancher-on-k8s/_index.md | 2 + .../single-node-docker/_index.md | 6 +- .../single-node-upgrades/_index.md | 4 +- .../deployment/equinix-metal-qs/_index.md | 2 +- .../quickstart-manual-setup/_index.md | 132 +++++++----------- 5 files changed, 60 insertions(+), 86 deletions(-) diff --git a/content/rancher/v2.6/en/installation/install-rancher-on-k8s/_index.md b/content/rancher/v2.6/en/installation/install-rancher-on-k8s/_index.md index 5d27916781c..a969bd01663 100644 --- a/content/rancher/v2.6/en/installation/install-rancher-on-k8s/_index.md +++ b/content/rancher/v2.6/en/installation/install-rancher-on-k8s/_index.md @@ -148,6 +148,8 @@ cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m The exact command to install Rancher differs depending on the certificate configuration. +> **Tip for testing and development:** This final command to install Rancher requires a domain name that forwards traffic to Rancher. If you are using the Helm CLI to set up a proof of concept, you can use a fake domain name when passing the `hostname` option. An example of a fake domain name would be `.sslip.io`, which would expose Rancher on an IP where Rancher would be running. Production installs would require a real domain name. + {{% tabs %}} {{% tab "Rancher-generated Certificates" %}} diff --git a/content/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/_index.md b/content/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/_index.md index 26ba9770630..e6521e26db2 100644 --- a/content/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/_index.md +++ b/content/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/_index.md @@ -91,7 +91,9 @@ docker run -d --restart=unless-stopped \ ### 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. +In production environments where you're exposing an app publicly, you would use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings. + +The Docker install is not recommended for production. these instructions are provided for testing and development purposes. > **Prerequisites:** > @@ -127,6 +129,8 @@ docker run -d --restart=unless-stopped \ 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. +The Docker install is not recommended for production. These instructions are provided for testing and development purposes. + > **Prerequisites:** > > - Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network. diff --git a/content/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/_index.md b/content/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/_index.md index 42a5504789d..31a47c5f896 100644 --- a/content/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/_index.md +++ b/content/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/_index.md @@ -5,9 +5,11 @@ weight: 1010 The following instructions will guide you through upgrading a Rancher server that was installed with Docker. +> **Docker installs are not supported in production.** We don't support upgrading Docker installs in production environments, and these instructions are provided for testing and development purposes only. If you have already deployed a Docker install in production and need to upgrade to a new Rancher version, we recommend [migrating to the Helm chart install]({{}}/rancher/v2.6/en/backups/migrating-rancher/) before upgrading. + # Prerequisites -- **Review the [known upgrade issues]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/upgrades/#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]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#helm-chart-repositories/) aren’t supported. +- **Review the [known upgrade issues]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/upgrades/#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]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#helm-chart-repositories/) aren’t supported. - **For [air gap installs only,]({{}}/rancher/v2.6/en/installation/other-installation-methods/air-gap) collect and populate images for the new Rancher server version**. Follow the guide to [populate your private registry]({{}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/populate-private-registry/) with the images for the Rancher version that you want to upgrade to. # Placeholder Review diff --git a/content/rancher/v2.6/en/quick-start-guide/deployment/equinix-metal-qs/_index.md b/content/rancher/v2.6/en/quick-start-guide/deployment/equinix-metal-qs/_index.md index 4fce68ecc7d..ad208bd3bf8 100644 --- a/content/rancher/v2.6/en/quick-start-guide/deployment/equinix-metal-qs/_index.md +++ b/content/rancher/v2.6/en/quick-start-guide/deployment/equinix-metal-qs/_index.md @@ -10,7 +10,7 @@ weight: 250 - 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]({{}}/rancher/v2.6/en/installation/). +>**Note:** The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. The Docker install is not recommended for production environments. For comprehensive setup instructions, see [Installation]({{}}/rancher/v2.6/en/installation/). ## Quick Start Outline diff --git a/content/rancher/v2.6/en/quick-start-guide/deployment/quickstart-manual-setup/_index.md b/content/rancher/v2.6/en/quick-start-guide/deployment/quickstart-manual-setup/_index.md index a5c970e3281..57c6d4a37cb 100644 --- a/content/rancher/v2.6/en/quick-start-guide/deployment/quickstart-manual-setup/_index.md +++ b/content/rancher/v2.6/en/quick-start-guide/deployment/quickstart-manual-setup/_index.md @@ -1,118 +1,84 @@ --- -title: Manual Quick Start +title: Helm CLI Quick Start weight: 300 --- -Howdy Partner! This tutorial walks you through: -- Installation of Rancher 2.x -- Creation of your first cluster -- Deployment of an application, Nginx +These instructions capture a quick way to set up a proof-of-concept Rancher installation. ->**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]({{}}/rancher/v2.6/en/installation/). +These instructions assume you have a Linux virtual machine that you will communicate with from your local workstation. Rancher will be installed on the Linux machine. You will need to retrieve the IP address of that machine to make it so that you can access Rancher from your local workstation. Rancher is designed to manage Kubernetes clusters remotely, so any Kubernetes cluster that Rancher manages in the future will also need to be able to reach this IP address. -## Quick Start Outline +We don't recommend installing Rancher locally because it creates a networking problem. Installing Rancher on localhost does not allow Rancher to communicate with downstream Kubernetes clusters, so on localhost you wouldn't be able to test Rancher's cluster provisioning or cluster management functionality. -This Quick Start Guide is divided into different tasks for easier consumption. +Your Linux machine can be anywhere. It could be an Amazon EC2 instance, a Digital Ocean droplet, or an Azure virtual machine, to name a few examples. (Other Rancher docs often use 'node' as a generic term for all of these.) One possible way to deploy a Linux machine is by setting up an Amazon EC2 instance as shown in [this tutorial.]({{}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/) - +The full installation requirements are [here.]({{}}/rancher/v2.6/en/installation/requirements/) -1. [Provision a Linux Host](#1-provision-a-linux-host) +## Install K3s on Linux -1. [Install Rancher](#2-install-rancher) +Install a K3s Kubernetes cluster by running this command on the Linux machine: -1. [Log In](#3-log-in) +``` +curl -sfL https://get.k3s.io | sh -s - server +``` -1. [Create the Cluster](#4-create-the-cluster) +Save the IP of the Linux machine. - -
-### 1. Provision a Linux Host +## Save the kubeconfig to your workstation - Begin creation of a custom cluster by provisioning a Linux host. Your host can be: +The kubeconfig file is important for accessing the Kubernetes cluster. Copy the file at `/etc/rancher/k3s/k3s.yaml` from the Linux machine and save it to your local workstation in the directory `~/.kube/config`. One way to do this is by using the `scp` tool and run this command on your local machine: -- A cloud-host virtual machine (VM) -- An on-prem VM -- A bare-metal server +``` +scp root@:/etc/rancher/k3s/k3s.yaml ~/.kube/config +``` - >**Note:** - > When using a cloud-hosted virtual machine you need to allow inbound TCP communication to ports 80 and 443. Please see your cloud-host's documentation for information regarding port configuration. - > - > For a full list of port requirements, refer to [Docker Installation]({{}}/rancher/v2.6/en/cluster-provisioning/node-requirements/). +## Edit the Rancher server URL in the kubeconfig - Provision the host according to our [Requirements]({{}}/rancher/v2.6/en/installation/requirements/). +In the kubeconfig file, the server directive is defined as `localhost`. You will need to change the server directive from `localhost` to `:6443`. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) This edit is needed so that when you run Helm or kubectl commands from your local workstation, you will be able to communicate with the Kubernetes cluster that Rancher will be installed on. -### 2. Install Rancher +One way to open the kubeconfig file for editing is to use Vim: -To install Rancher on your host, connect to it and then use a shell to install. +``` +vi ~/.kube/config +``` -1. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. +Press `i` to put Vim in insert mode. To save your work, press `Esc`. Then press `:wq` and press `enter`. -2. From your shell, enter the following command: +## Install Rancher with Helm - ``` - sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher - ``` +Then from your local workstation, run the following commands. You will need to have installed [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) and [helm.](https://helm.sh/docs/intro/install/) -**Result:** Rancher is installed. +``` +helm repo add rancher-latest https://releases.rancher.com/server-charts/latest -### 3. Log In +kubectl create namespace cattle-system -Log in to Rancher to begin using the application. After you log in, you'll make some one-time configurations. +kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml -1. Open a web browser and enter the IP address of your host: `https://`. +helm repo add jetstack https://charts.jetstack.io - Replace `` with your host IP address. +helm repo update -2. When prompted, create a password for the default `admin` account there cowpoke! +helm install cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --version v1.5.1 +``` -3. Set the **Rancher Server URL**. The URL can either be an IP address or a host name. However, each node added to your cluster must be able to connect to this URL.

If you use a hostname in the URL, this hostname must be resolvable by DNS on the nodes you want to add to you cluster. +The final command to install Rancher is below. The command requires a domain name that forwards traffic to the Linux machine. For the sake of simplicity in this tutorial, you can use a fake domain name to create your proof of concept. An example of a fake domain name would be `.sslip.io`. -
+``` +helm install rancher rancher-latest/rancher \ + --namespace cattle-system \ + --set hostname=.sslip.io \ + --set replicas=1 \ + --set bootstrapPassword= +``` -### 4. Create the Cluster +Now if you navigate to `.sslip.io` in a web browser, you should see the Rancher UI. -Welcome to Rancher! You are now able to create your first Kubernetes cluster. +To make these instructions simple, we used a fake domain name and self-signed certificates to do this installation. For production installs, you would need a high-availability setup with a load balancer, a real domain name and real certificates. -In this task, you can use the versatile **Custom** option. This option lets you add _any_ Linux host (cloud-hosted VM, on-prem VM, or bare-metal) to be used in a cluster. +These instructions also left out the full installation requirements and other installation options. If you have any issues with these steps, refer to the full [Helm CLI installation docs.]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/) -1. Click **☰ > Cluster Management**. -1. From the **Clusters** page, click **Create**. -2. Choose **Custom**. - -3. Enter a **Cluster Name**. - -4. Skip **Member Roles** and **Cluster Options**. We'll tell you about them later. - -5. Click **Next**. - -6. From **Node Role**, select _all_ the roles: **etcd**, **Control**, and **Worker**. - -7. **Optional**: Rancher auto-detects the IP addresses used for Rancher communication and cluster communication. You can override these using `Public Address` and `Internal Address` in the **Node Address** section. - -8. Skip the **Labels** stuff. It's not important for now. - -9. Copy the command displayed on screen to your clipboard. - -10. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard. - -11. When you finish running the command on your Linux host, click **Done**. - -**Result:** - -Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. - -You can access your cluster after its state is updated to **Active**. - -**Active** clusters are assigned two Projects: - -- `Default`, containing the `default` namespace -- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces - -#### Finished - -Congratulations! You have created your first cluster. - -#### What's Next? - -Use Rancher to create a deployment. For more information, see [Creating Deployments]({{}}/rancher/v2.6/en/quick-start-guide/workload). +To launch new Kubernetes clusters with your new Rancher server, you may need to set up cloud credentials in Rancher. For more information, see [Launching Kubernetes clusters with Rancher.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) \ No newline at end of file