mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-26 21:18:04 +00:00
Denise
@@ -15,13 +15,24 @@ Use `helm repo add` to add the Rancher chart repository.
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
|
||||
For additional chart details, view the [source of these Rancher server charts](https://github.com/rancher/server-chart).
|
||||
## Chart Versioning Notes
|
||||
|
||||
Up until the initial helm chart release for v2.1.0, the helm chart version matched the Rancher version (i.e `appVersion`).
|
||||
|
||||
Since there are times where the helm chart will require changes without any changes to the Rancher version, we have moved to a `yyyy.mm.<build-number>` helm chart version.
|
||||
|
||||
Run `helm search rancher` to view which Rancher version will be launched for the specific helm chart version.
|
||||
|
||||
```
|
||||
NAME CHART VERSION APP VERSION DESCRIPTION
|
||||
rancher-stable/rancher 2018.10.1 v2.1.0 Install Rancher Server to manage Kubernetes clusters acro...
|
||||
```
|
||||
|
||||
### Install cert-manager
|
||||
|
||||
> **Note:** cert-manager is only required for Rancher generated and LetsEncrypt issued certificates. You may skip this step if you are bringing your own certificates and using the `ingress.tls.source=secret` option.
|
||||
|
||||
Rancher relies on [cert-manager](https://github.com/kubernetes/charts/tree/master/stable/cert-manager) from the Kubernetes Helm "stable" catalog to issue self-signed or LetsEncrypt certificates.
|
||||
Rancher relies on [cert-manager](https://github.com/kubernetes/charts/tree/master/stable/cert-manager) from the Kubernetes Helm stable catalog to issue self-signed or LetsEncrypt certificates.
|
||||
|
||||
Install `cert-manager` from the Helm stable catalog.
|
||||
|
||||
@@ -33,7 +44,7 @@ helm install stable/cert-manager \
|
||||
|
||||
### Choose your SSL Configuration
|
||||
|
||||
Rancher server is designed to be "secure by default" and requires SSL/TLS configuration.
|
||||
Rancher server is designed to be secure by default and requires SSL/TLS configuration.
|
||||
|
||||
There are three options for the source of the certificate.
|
||||
|
||||
@@ -47,7 +58,7 @@ There are three options for the source of the certificate.
|
||||
|
||||
The default is for Rancher to generate a CA and use the `cert-manager` to issue the certificate for access to the Rancher server interface.
|
||||
|
||||
The only requirement is to set the `hostname` to the DNS name you pointed at your Load Balancer.
|
||||
The only requirement is to set the `hostname` to the DNS name you pointed at your load balancer.
|
||||
|
||||
>**Using Air Gap?** [Set the `rancherImage` option]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#install-rancher-using-private-registry) in your command, pointing toward your private registry.
|
||||
|
||||
@@ -77,11 +88,11 @@ helm install rancher-stable/rancher \
|
||||
|
||||
#### Certificates from Files (Kubernetes Secret)
|
||||
|
||||
Create Kubernetes Secrets from your own certificates for Rancher to use.
|
||||
Create Kubernetes secrets from your own certificates for Rancher to use.
|
||||
|
||||
> **Note:** The common name for the cert will need to match the `hostname` option or the ingress controller will fail to provision the site for Rancher.
|
||||
|
||||
Set `hostname` and `ingress.tls.source=secret`
|
||||
Set `hostname` and `ingress.tls.source=secret`.
|
||||
|
||||
> **Note:** If you are using a Private CA signed cert, add `--set privateCA=true`
|
||||
|
||||
@@ -93,7 +104,7 @@ helm install rancher-stable/rancher \
|
||||
--set ingress.tls.source=secret
|
||||
```
|
||||
|
||||
Now that Rancher is running, see [Adding TLS Secrets]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/) to publish the certificate files so Rancher and the Ingress Controller can use them.
|
||||
Now that Rancher is running, see [Adding TLS Secrets]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/) to publish the certificate files so Rancher and the ingress controller can use them.
|
||||
|
||||
### Advanced Configurations
|
||||
|
||||
|
||||
@@ -19,7 +19,13 @@ weight: 276
|
||||
|
||||
| Option | Default Value | Description |
|
||||
| --- | --- | --- |
|
||||
| `additionalTrustedCAs` | false | `bool` - See [Additional Trusted CAs](#additional-trusted-cas) |
|
||||
| `auditLog.destination` | "sidecar" | `string` - Stream to sidecar container console or hostPath volume - "sidecar, hostPath" |
|
||||
| `auditLog.hostPath` | "/var/log/rancher/audit" | `string` - log file destination on host |
|
||||
| `auditLog.level` | 0 | `int` - set the [API Audit Log]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) level. 0 is off. [0-3] |
|
||||
| `auditLog.maxAge` | 1 | `int` - maximum number of days to retain old audit log files |
|
||||
| `auditLog.maxBackups` | 1 | `int` - maximum number of audit log files to retain |
|
||||
| `auditLog.maxSize` | 100 | `int` - maximum size in megabytes of the audit log file before it gets rotated |
|
||||
| `debug` | false | `bool` - set debug flag on rancher server |
|
||||
| `imagePullSecrets` | [] | `list` - list of names of Secret resource containing private registry credentials |
|
||||
| `proxy` | "" | `string` - string - HTTP[S] proxy server for Rancher |
|
||||
@@ -27,52 +33,76 @@ weight: 276
|
||||
| `resources` | {} | `map` - rancher pod resource requests & limits |
|
||||
| `rancherImage` | "rancher/rancher" | `string` - rancher image source |
|
||||
| `rancherImageTag` | same as chart version | `string` - rancher/rancher image tag |
|
||||
| `tls` | "ingress" | `string` - Where to terminate SSL. - "ingress, external" |
|
||||
| `tls` | "ingress" | `string` - See [External TLS Termination](#external-tls-termination) for details. - "ingress, external" |
|
||||
|
||||
<br/>
|
||||
|
||||
### API Audit Log
|
||||
|
||||
Enabling the [API Audit Log](https://rancher.com/docs/rancher/v2.x/en/installation/api-auditing/) will create a sidecar container in the Rancher pod. This container (`rancher-audit-log`) will stream the log to `stdout`.
|
||||
Enabling the [API Audit Log](https://rancher.com/docs/rancher/v2.x/en/installation/api-auditing/).
|
||||
|
||||
You can collect this log as you would any container log. Enable the [Logging service under Rancher Tools](https://rancher.com/docs/rancher/v2.x/en/tools/logging/) 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. Enable the [Logging service under Rancher Tools](https://rancher.com/docs/rancher/v2.x/en/tools/logging/) 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.
|
||||
|
||||
### HTTP Proxy
|
||||
|
||||
Rancher requires internet access for some functionality (helm charts). Use `proxy` to set your proxy server.
|
||||
|
||||
Add your IP exceptions to the `noProxy` list. Make sure you add the Service cluster IP range (default: 10.43.0.1/16) and any worker cluster `controlplane` nodes. Rancher supports CIDR notation ranges in this list.
|
||||
|
||||
```
|
||||
```plain
|
||||
--set proxy="http://<username>:<password>@<proxy_url>:<proxy_port>/"
|
||||
--set noProxy="127.0.0.1,localhost,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
|
||||
```
|
||||
|
||||
### Additional Trusted CAs
|
||||
|
||||
If you have private registries, catalogs or a proxy that intercepts certificates, you may need to add additional trusted CAs to Rancher.
|
||||
|
||||
```plain
|
||||
--set additionalTrustedCAs=true
|
||||
```
|
||||
|
||||
Once the Rancher deployment is created, copy your CA certs in pem format into a file named `ca-additional.pem` and use `kubectl` to create the `tls-ca-additional` secret in the `cattle-system` namespace.
|
||||
|
||||
```plain
|
||||
kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-additional.pem
|
||||
```
|
||||
|
||||
### Private Registry and Air Gap Installs
|
||||
|
||||
See [Installing Rancher - Air Gap]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/) for details on installing Rancher with a private registry.
|
||||
|
||||
### External TLS Termination
|
||||
|
||||
If you wish to terminate the SSL/TLS on a load-balancer external to the Rancher cluster (ingress), use the `--tls=external` option and point your load balancer at port http 80 on all of the rancher cluster nodes.
|
||||
We recommend configuring your load balancer as a Layer 4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher Management cluster nodes. The Ingress Controller on the cluster will redirect http traffic on port 80 to https on port 443.
|
||||
|
||||
You may terminate the SSL/TLS on a L7 load balancer external to the Rancher cluster (ingress). Use the `--tls=external` option and point your load balancer at port http 80 on all of the Rancher cluster nodes. This will expose the Rancher interface on http port 80. Be aware that clients that are allowed to connect directly to the Rancher cluster will not be encrypted. If you choose to do this we recommend that you restrict direct access at the network level to just your load balancer.
|
||||
|
||||
> **Note:** If you are using a Private CA signed cert, add `--set privateCA=true` and see [Adding TLS Secrets - Private CA Signed - Additional Steps]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/#private-ca-signed---additional-steps) to add the CA cert for Rancher.
|
||||
|
||||
Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.
|
||||
|
||||
> **Note:** The `tls=external` option will expose the Rancher interface on http port 80. Clients that are allowed to connect directly to the Rancher cluster will not be encrypted. We recommend that you restrict direct access at the network level to just your load balancer.
|
||||
|
||||
#### Required headers
|
||||
#### Required Headers
|
||||
|
||||
* `Host`
|
||||
* `X-Forwarded-Proto`
|
||||
* `X-Forwarded-Port`
|
||||
* `X-Forwarded-For`
|
||||
|
||||
#### Health checks
|
||||
#### Recommended Timeouts
|
||||
|
||||
* Read Timeout: `1800 seconds`
|
||||
* Write Timeout: `1800 seconds`
|
||||
* Connect Timeout: `30 seconds`
|
||||
|
||||
#### Health Checks
|
||||
|
||||
Rancher will respond `200` to health checks on the `/healthz` endpoint.
|
||||
|
||||
@@ -24,6 +24,19 @@ The following instructions will guide you through upgrading a high-availability
|
||||
|
||||
[Install or update](https://docs.helm.sh/using_helm/#installing-helm) Helm to the latest version.
|
||||
|
||||
## Chart Versioning Notes
|
||||
|
||||
Up until the initial helm chart release for v2.1.0, the helm chart version matched the Rancher version (i.e `appVersion`).
|
||||
|
||||
Since there are times where the helm chart will require changes without any changes to the Rancher version, we have moved to a `yyyy.mm.<build-number>` helm chart version.
|
||||
|
||||
Run `helm search rancher` to view which Rancher version will be launched for the specific helm chart version.
|
||||
|
||||
```
|
||||
NAME CHART VERSION APP VERSION DESCRIPTION
|
||||
rancher-stable/rancher 2018.10.1 v2.1.0 Install Rancher Server to manage Kubernetes clusters acro...
|
||||
```
|
||||
|
||||
## Upgrade Rancher
|
||||
|
||||
1. Update your local helm repo cache.
|
||||
|
||||
@@ -26,7 +26,7 @@ The following instructions will guide you through upgrading a high-availability
|
||||
|
||||
Follow the kubectl [configuration instructions]({{< baseurl >}}/rancher/v2.x/en/faq/kubectl) and confirm that you can connect to the Kubernetes cluster running Rancher server.
|
||||
|
||||
- **Helm**
|
||||
- **Helm**
|
||||
|
||||
[Install or update](https://docs.helm.sh/using_helm/#installing-helm) Helm to the latest version.
|
||||
|
||||
@@ -38,6 +38,19 @@ The following instructions will guide you through upgrading a high-availability
|
||||
helm init --upgrade --service-account tiller
|
||||
```
|
||||
|
||||
## Chart Versioning Notes
|
||||
|
||||
Up until the initial helm chart release for v2.1.0, the helm chart version matched the Rancher version (i.e `appVersion`).
|
||||
|
||||
Since there are times where the helm chart will require changes without any changes to the Rancher version, we have moved to a `yyyy.mm.<build-number>` helm chart version.
|
||||
|
||||
Run `helm search rancher` to view which Rancher version will be launched for the specific helm chart version.
|
||||
|
||||
```
|
||||
NAME CHART VERSION APP VERSION DESCRIPTION
|
||||
rancher-stable/rancher 2018.10.1 v2.1.0 Install Rancher Server to manage Kubernetes clusters acro...
|
||||
```
|
||||
|
||||
## Upgrade Rancher
|
||||
|
||||
> **Note:** For Air Gap installs see [Upgrading HA Rancher - Air Gap]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#upgrading-rancher)
|
||||
@@ -56,12 +69,16 @@ The following instructions will guide you through upgrading a high-availability
|
||||
hostname: rancher.my.org
|
||||
```
|
||||
|
||||
3. Take the values above and use `helm` with `--set` options to upgrade Rancher to the latest version.
|
||||
> **Note:** There may be more values that are listed with this command depending on which [SSL configuration option you selected]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/#choose-your-ssl-configuration) when installing Rancher.
|
||||
|
||||
3. Take all values from the previous command and use `helm` with `--set` options to upgrade Rancher to the latest version.
|
||||
|
||||
```
|
||||
helm upgrade rancher rancher-stable/rancher --set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
> **Important:** For any values listed from Step 2, you must use `--set key=value` to apply the same values to the helm chart.
|
||||
|
||||
## Rolling Back
|
||||
|
||||
Should something go wrong, follow the [HA Rollback]({{< baseurl >}}/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/) instructions to restore the snapshot you took before you preformed the upgrade.
|
||||
|
||||
Reference in New Issue
Block a user