mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-26 13:08:11 +00:00
Merge branch 'master' into staging
This commit is contained in:
Jen Travinski
@@ -74,11 +74,15 @@ To add a private CA for Helm Chart repositories:
|
||||
[...]
|
||||
```
|
||||
|
||||
- **Git-based chart repositories**: It is not currently possible to add a private CA. For git-based chart repositories with a certificate signed by a private CA, you must disable TLS verification. Click **Edit YAML** for the chart repo and add the key/value pair as follows:
|
||||
|
||||
- **Git-based chart repositories**: It is not currently possible to add a private CA. For git-based chart repositories with a certificate signed by a private CA, you must disable TLS verification. Click **Edit YAML** for the chart repo and add the key/value pair as follows:
|
||||
```
|
||||
[...]
|
||||
spec:
|
||||
insecureSkipTLSVerify: true
|
||||
caBundle:
|
||||
MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT
|
||||
...
|
||||
nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4=
|
||||
[...]
|
||||
```
|
||||
|
||||
|
||||
@@ -154,6 +154,8 @@ The exact command to install Rancher differs depending on the certificate config
|
||||
|
||||
However, irrespective of the certificate configuration, the name of the Rancher installation in the `cattle-system` namespace should always be `rancher`.
|
||||
|
||||
> **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 `<IP_OF_LINUX_NODE>.sslip.io`, which would expose Rancher on an IP where it is running. Production installs would require a real domain name.
|
||||
|
||||
{{% tabs %}}
|
||||
{{% tab "Rancher-generated Certificates" %}}
|
||||
|
||||
|
||||
+5
-1
@@ -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 only.
|
||||
|
||||
> **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 only.
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> - Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network.
|
||||
|
||||
+3
-1
@@ -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 environments.** 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]({{<baseurl>}}/rancher/v2.6/en/backups/migrating-rancher/) before upgrading.
|
||||
|
||||
# Prerequisites
|
||||
|
||||
- **Review the [known upgrade issues]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#helm-chart-repositories/) aren’t supported.
|
||||
- **Review the [known upgrade issues]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/upgrades/#known-upgrade-issues)** section 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]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#helm-chart-repositories/) aren’t supported.
|
||||
- **For [air gap installs only,]({{<baseurl>}}/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]({{<baseurl>}}/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
|
||||
|
||||
@@ -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]({{<baseurl>}}/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]({{<baseurl>}}/rancher/v2.6/en/installation/).
|
||||
|
||||
## Quick Start Outline
|
||||
|
||||
|
||||
+86
-68
@@ -1,118 +1,136 @@
|
||||
---
|
||||
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]({{<baseurl>}}/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 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]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/).
|
||||
|
||||
<!-- TOC -->
|
||||
The full installation requirements are [here]({{<baseurl>}}/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 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.
|
||||
|
||||
<!-- /TOC -->
|
||||
<br/>
|
||||
### 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
|
||||
{{% tabs %}}
|
||||
{{% tab "Mac and Linux" %}}
|
||||
|
||||
>**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]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/node-requirements/).
|
||||
```
|
||||
scp root@<IP_OF_LINUX_MACHINE>:/etc/rancher/k3s/k3s.yaml ~/.kube/config
|
||||
```
|
||||
|
||||
Provision the host according to our [Requirements]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/).
|
||||
{{% /tab %}}
|
||||
{{% tab "Windows" %}}
|
||||
|
||||
### 2. Install Rancher
|
||||
By default, "scp" is not a recognized command, so we need to install a module first.
|
||||
|
||||
To install Rancher on your host, connect to it and then use a shell to install.
|
||||
In Windows Powershell:
|
||||
|
||||
1. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection.
|
||||
```
|
||||
Find-Module Posh-SSH
|
||||
Install-Module Posh-SSH
|
||||
|
||||
2. From your shell, enter the following command:
|
||||
## Get the remote kubeconfig file
|
||||
scp root@<IP_OF_LINUX_MACHINE>:/etc/rancher/k3s/k3s.yaml $env:USERPROFILE\.kube\config
|
||||
```
|
||||
{{% /tab %}}
|
||||
{{% tabs %}}
|
||||
|
||||
```
|
||||
sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher
|
||||
```
|
||||
## Edit the Rancher server URL in the kubeconfig
|
||||
|
||||
**Result:** Rancher is installed.
|
||||
In the kubeconfig file, the server directive is defined as `localhost`. You will need to change the server directive from `localhost` to `<IP_OF_LINUX_NODE>: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.
|
||||
|
||||
### 3. Log In
|
||||
{{% tabs %}}
|
||||
{{% tab "Mac and Linux" %}}
|
||||
|
||||
Log in to Rancher to begin using the application. After you log in, you'll make some one-time configurations.
|
||||
One way to open the kubeconfig file for editing is to use Vim:
|
||||
|
||||
1. Open a web browser and enter the IP address of your host: `https://<SERVER_IP>`.
|
||||
```
|
||||
vi ~/.kube/config
|
||||
```
|
||||
|
||||
Replace `<SERVER_IP>` with your host IP address.
|
||||
Press `i` to put Vim in insert mode. To save your work, press `Esc`. Then press `:wq` and press `Enter`.
|
||||
|
||||
2. When prompted, create a password for the default `admin` account there cowpoke!
|
||||
{{% /tab %}}
|
||||
{{% tab "Windows" %}}
|
||||
|
||||
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.<br/><br/>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.
|
||||
In Windows Powershell, you can use `notepad.exe` for editing the kubeconfig file:
|
||||
|
||||
<br/>
|
||||
```
|
||||
notepad.exe $env:USERPROFILE\.kube\config
|
||||
```
|
||||
|
||||
### 4. Create the Cluster
|
||||
Once edited, either press `ctrl+s` or go to `File > Save` to save your work.
|
||||
|
||||
Welcome to Rancher! You are now able to create your first Kubernetes cluster.
|
||||
|
||||
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.
|
||||
{{% /tab %}}
|
||||
{{% tabs %}}
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. From the **Clusters** page, click **Create**.
|
||||
2. Choose **Custom**.
|
||||
## Install Rancher with Helm
|
||||
|
||||
3. Enter a **Cluster Name**.
|
||||
Then from your local workstation, run the following commands. You will need to have [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) and [helm.](https://helm.sh/docs/intro/install/) installed.
|
||||
|
||||
4. Skip **Member Roles** and **Cluster Options**. We'll tell you about them later.
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
|
||||
5. Click **Next**.
|
||||
kubectl create namespace cattle-system
|
||||
|
||||
6. From **Node Role**, select _all_ the roles: **etcd**, **Control**, and **Worker**.
|
||||
kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml
|
||||
|
||||
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.
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
|
||||
8. Skip the **Labels** stuff. It's not important for now.
|
||||
helm repo update
|
||||
|
||||
9. Copy the command displayed on screen to your clipboard.
|
||||
helm install cert-manager jetstack/cert-manager \
|
||||
--namespace cert-manager \
|
||||
--create-namespace \
|
||||
--version v1.5.1
|
||||
|
||||
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.
|
||||
# Windows Powershell
|
||||
helm install cert-manager jetstack/cert-manager \`
|
||||
--namespace cert-manager \`
|
||||
--create-namespace \`
|
||||
--version v1.5.1
|
||||
```
|
||||
|
||||
11. When you finish running the command on your Linux host, click **Done**.
|
||||
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 `<IP_OF_LINUX_NODE>.sslip.io`.
|
||||
|
||||
**Result:**
|
||||
```
|
||||
helm install rancher rancher-latest/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<IP_OF_LINUX_NODE>.sslip.io \
|
||||
--set replicas=1 \
|
||||
--set bootstrapPassword=<PASSWORD_FOR_RANCHER_ADMIN>
|
||||
|
||||
Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster.
|
||||
# Windows Powershell
|
||||
helm install rancher rancher-latest/rancher `
|
||||
--namespace cattle-system `
|
||||
--set hostname=<IP_OF_LINUX_NODE>.sslip.io `
|
||||
--set replicas=1 `
|
||||
--set bootstrapPassword=<PASSWORD_FOR_RANCHER_ADMIN>
|
||||
```
|
||||
```
|
||||
|
||||
You can access your cluster after its state is updated to **Active**.
|
||||
Now if you navigate to `<IP_OF_LINUX_NODE>.sslip.io` in a web browser, you should see the Rancher UI.
|
||||
|
||||
**Active** clusters are assigned two Projects:
|
||||
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.
|
||||
|
||||
- `Default`, containing the `default` namespace
|
||||
- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces
|
||||
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.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/)
|
||||
|
||||
#### Finished
|
||||
|
||||
Congratulations! You have created your first cluster.
|
||||
|
||||
#### What's Next?
|
||||
|
||||
Use Rancher to create a deployment. For more information, see [Creating Deployments]({{<baseurl>}}/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.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/)
|
||||
@@ -7,6 +7,9 @@ Rancher is committed to informing the community of security issues in our produc
|
||||
|
||||
| ID | Description | Date | Resolution |
|
||||
|----|-------------|------|------------|
|
||||
| [GHSA-hwm2-4ph6-w6m5](https://github.com/rancher/rancher/security/advisories/GHSA-hwm2-4ph6-w6m5) | A vulnerability was discovered in versions of Rancher starting 2.0 up to and including 2.6.3. The `restricted` pod security policy (PSP) provided in Rancher deviated from the upstream `restricted` policy provided in Kubernetes on account of which Rancher's PSP had `runAsUser` set to `runAsAny`, while upstream had `runAsUser` set to `MustRunAsNonRoot`. This allowed containers to run as any user, including a privileged user (`root`), even when Rancher's `restricted` policy was enforced on a project or at the cluster level. | 31 Mar 2022 | [Rancher v2.6.4](https://github.com/rancher/rancher/releases/tag/v2.6.4) |
|
||||
| [CVE-2021-36775](https://github.com/rancher/rancher/security/advisories/GHSA-28g7-896h-695v) | A vulnerability was discovered in Rancher versions up to and including 2.4.17, 2.5.11 and 2.6.2. After removing a `Project Role` associated with a group from the project, the bindings that granted access to cluster-scoped resources for those subjects were not deleted. This was due to an incomplete authorization logic check. A user who was a member of the affected group with authenticated access to Rancher could exploit this vulnerability to access resources they shouldn't have had access to. The exposure level would depend on the original permission level granted to the affected project role. This vulnerability only affected customers using group based authentication in Rancher. | 31 Mar 2022 | [Rancher v2.6.3](https://github.com/rancher/rancher/releases/tag/v2.6.3), [Rancher v2.5.12](https://github.com/rancher/rancher/releases/tag/v2.5.12) and [Rancher v2.4.18](https://github.com/rancher/rancher/releases/tag/v2.4.18) |
|
||||
| [CVE-2021-36776](https://github.com/rancher/rancher/security/advisories/GHSA-gvh9-xgrq-r8hw) | A vulnerability was discovered in Rancher versions starting 2.5.0 up to and including 2.5.9, that allowed an authenticated user to impersonate any user on a cluster through an API proxy, without requiring knowledge of the impersonated user's credentials. This was due to the API proxy not dropping the impersonation header before sending the request to the Kubernetes API. A malicious user with authenticated access to Rancher could use this to impersonate another user with administrator access in Rancher, thereby gaining administrator level access to the cluster. | 31 Mar 2022 | [Rancher v2.6.0](https://github.com/rancher/rancher/releases/tag/v2.6.0) and [Rancher v2.5.10](https://github.com/rancher/rancher/releases/tag/v2.5.10) |
|
||||
| [CVE-2021-25318](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-25318) | A vulnerability was discovered in Rancher versions 2.0 through the aforementioned fixed versions, where users were granted access to resources regardless of the resource's API group. For example, Rancher should have allowed users access to `apps.catalog.cattle.io`, but instead incorrectly gave access to `apps.*`. Resources affected in the **Downstream clusters** and **Rancher management cluster** can be found [here](https://github.com/rancher/rancher/security/advisories/GHSA-f9xf-jq4j-vqw4). There is not a direct mitigation besides upgrading to the patched Rancher versions. | 14 Jul 2021 | [Rancher v2.5.9](https://github.com/rancher/rancher/releases/tag/v2.5.9) and [Rancher v2.4.16](https://github.com/rancher/rancher/releases/tag/v2.4.16) |
|
||||
| [CVE-2021-31999](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-31999) | A vulnerability was discovered in Rancher 2.0.0 through the aforementioned patched versions, where a malicious Rancher user could craft an API request directed at the proxy for the Kubernetes API of a managed cluster to gain access to information they do not have access to. This is done by passing the "Impersonate-User" or "Impersonate-Group" header in the Connection header, which is then correctly removed by the proxy. At this point, instead of impersonating the user and their permissions, the request will act as if it was from the Rancher management server and incorrectly return the information. The vulnerability is limited to valid Rancher users with some level of permissions on the cluster. There is not a direct mitigation besides upgrading to the patched Rancher versions. | 14 Jul 2021 | [Rancher v2.5.9](https://github.com/rancher/rancher/releases/tag/v2.5.9) and [Rancher v2.4.16](https://github.com/rancher/rancher/releases/tag/v2.4.16) |
|
||||
| [CVE-2021-25320](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-25320) | A vulnerability was discovered in Rancher 2.2.0 through the aforementioned patched versions, where cloud credentials weren't being properly validated through the Rancher API. Specifically through a proxy designed to communicate with cloud providers. Any Rancher user that was logged-in and aware of a cloud-credential ID that was valid for a given cloud provider, could call that cloud provider's API through the proxy API, and the cloud-credential would be attached. The exploit is limited to valid Rancher users. There is not a direct mitigation outside of upgrading to the patched Rancher versions. | 14 Jul 2021 | [Rancher v2.5.9](https://github.com/rancher/rancher/releases/tag/v2.5.9) and [Rancher v2.4.16](https://github.com/rancher/rancher/releases/tag/v2.4.16) |
|
||||
|
||||
Reference in New Issue
Block a user