github.com/verrazzano/verrazzano@v1.7.0/platform-operator/thirdparty/charts/rancher/README.md (about) 1 By installing this application, you accept the [End User License Agreement & Terms & Conditions](https://www.suse.com/licensing/eula/). 2 3 # Rancher 4 5 ***Rancher*** is open source software that combines everything an organization needs to adopt and run containers in production. Built on Kubernetes, Rancher makes it easy for DevOps teams to test, deploy and manage their applications. 6 7 ### Introduction 8 9 This chart bootstraps a [Rancher Server](https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster) on a Kubernetes cluster using the [Helm](https://helm.sh/) package manager. For a Rancher Supported Deployment please follow our [HA install instructions](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs). 10 11 12 ### Prerequisites Details 13 14 *For installations covered under [Rancher Support SLA](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions) the target cluster must be **[RKE1](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher)**, **[RKE2](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher)**, **[K3s](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher)**, **[AKS](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks)**, **[EKS](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks)**, or **[GKE](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke)**.* 15 16 Make sure the node(s) for the Rancher server fulfill the following requirements: 17 18 [Operating Systems and Container Runtime Requirements](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-requirements#operating-systems-and-container-runtime-requirements) 19 [Hardware Requirements](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-requirements#hardware-requirements) 20 21 - [CPU and Memory](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-requirements#cpu-and-memory) 22 - [Ingress](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-requirements#ingress) 23 - [Disks](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-requirements#disks) 24 25 [Networking Requirements](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-requirements#networking-requirements) 26 - [Node IP Addresses](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-requirements#node-ip-addresses) 27 - [Port Requirements](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-requirements#port-requirements) 28 29 [Install the Required CLI Tools](https://ranchermanager.docs.rancher.com/pages-for-subheaders/cli-with-rancher) 30 31 - [kubectl](https://ranchermanager.docs.rancher.com/reference-guides/cli-with-rancher/kubectl-utility) - Kubernetes command-line tool. 32 - [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/resources/helm-version-requirements) to choose a version of Helm to install Rancher. 33 34 For a list of best practices that we recommend for running the Rancher server in production, refer to the [best practices section](https://ranchermanager.docs.rancher.com/pages-for-subheaders/best-practices). 35 36 ## Installing Rancher 37 38 For production environments, we recommend installing Rancher in a [high-availability Kubernetes installation](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs) 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. 39 40 Optional: Installing Rancher on a [Single-node](https://ranchermanager.docs.rancher.com/pages-for-subheaders/rancher-on-a-single-node-with-docker) Kubernetes Cluster 41 42 #### Add the Helm Chart Repository 43 44 Use [helm repo add](https://helm.sh/docs/helm/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. 45 46 ```bash 47 helm repo add rancher-latest https://releases.rancher.com/server-charts/latest 48 ``` 49 50 #### Create a Namespace for Rancher 51 52 We’ll need to define a Kubernetes namespace where the resources created by the Chart should be installed. This should always be cattle-system: 53 54 ```bash 55 kubectl create namespace cattle-system 56 ``` 57 58 #### Choose your SSL Configuration 59 60 The Rancher management server is designed to be secure by default and requires SSL/TLS configuration. 61 62 There are three recommended options for the source of the certificate used for TLS termination at the Rancher server: 63 64 - [Rancher-generated TLS certificate](https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster#3-choose-your-ssl-configuration) 65 - [Let’s Encrypt](https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster#3-choose-your-ssl-configuration) 66 - [Bring your own certificate](https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster#3-choose-your-ssl-configuration) 67 68 #### Install cert-manager 69 70 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)`**. 71 72 [These instructions are adapted from the official cert-manager documentation.](https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster#4-install-cert-manager) 73 74 #### Install Rancher with Helm and Your Chosen Certificate Option 75 76 - [Rancher to generated certificates](https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster#5-install-rancher-with-helm-and-your-chosen-certificate-option) 77 ```bash 78 helm install rancher rancher-latest/rancher \ 79 --namespace cattle-system \ 80 --set hostname=rancher.my.org 81 ``` 82 83 - [Let’s Encrypt](https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster#5-install-rancher-with-helm-and-your-chosen-certificate-option) 84 85 ```bash 86 helm install rancher rancher-latest/rancher \ 87 --namespace cattle-system \ 88 --set hostname=rancher.my.org \ 89 --set ingress.tls.source=letsEncrypt \ 90 --set letsEncrypt.email=me@example.org 91 ``` 92 93 - [Certificates from Files](https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster#5-install-rancher-with-helm-and-your-chosen-certificate-option) 94 95 ```bash 96 helm install rancher rancher-latest/rancher \ 97 --namespace cattle-system \ 98 --set hostname=rancher.my.org \ 99 --set ingress.tls.source=secret 100 ``` 101 102 *If you are using a Private CA signed certificate , add **--set privateCA=true** to the command:`* 103 104 ```bash 105 helm install rancher rancher-latest/rancher \ 106 --namespace cattle-system \ 107 --set hostname=rancher.my.org \ 108 --set ingress.tls.source=secret \ 109 --set privateCA=true 110 ``` 111 112 #### Verify that the Rancher Server is Successfully Deployed 113 114 After adding the secrets, check if Rancher was rolled out successfully: 115 116 ```bash 117 kubectl -n cattle-system rollout status deploy/rancher 118 Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... 119 deployment "rancher" successfully rolled out 120 ``` 121 122 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: 123 124 ```bash 125 kubectl -n cattle-system get deploy rancher 126 NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE 127 rancher 3 3 3 3 3m 128 ``` 129 130 It should show the same count for **`DESIRED`** and **`AVAILABLE`**. 131 132 #### Save Your Options 133 134 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. 135 136 #### Finishing Up 137 138 That’s it. You should have a functional Rancher server. 139 140 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. 141 142 Doesn’t work? Take a look at the [Troubleshooting Page](https://ranchermanager.docs.rancher.com/troubleshooting/general-troubleshooting) 143 144 ***All of these instructions are defined in detailed in the [Rancher Documentation](https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster#install-the-rancher-helm-chart).*** 145 146 ### Helm Chart Options for Kubernetes Installations 147 148 The full [Helm Chart Options](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/installation-references/helm-chart-options) can be found here. 149 150 Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. 151 152 #### Common Options 153 154 | Parameter | Default Value | Description | 155 | ------------------------- | ------------- | -------------------------------------------------------------------------------------------- | 156 | `hostname` | " " | ***string*** - the Fully Qualified Domain Name for your Rancher Server | 157 | `ingress.tls.source` | "rancher" | ***string*** - Where to get the cert for the ingress. - "***rancher, letsEncrypt, secret***" | 158 | `letsEncrypt.email` | " " | ***string*** - Your email address | 159 | `letsEncrypt.environment` | "production" | ***string*** - Valid options: "***staging, production***" | 160 | `privateCA` | false | ***bool*** - Set to true if your cert is signed by a private CA | 161 162 #### Advanced Options 163 164 | Parameter | Default Value | Description | 165 | ---------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 166 | `additionalTrustedCAs` | false | ***bool*** - [See Additional Trusted CAs Server](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/installation-references/helm-chart-options#additional-trusted-cas) | 167 | `addLocal` | "true" | ***string*** - As of Rancher v2.5.0 this flag is deprecated and must be set to "true" | 168 | `antiAffinity` | "preferred" | ***string*** - AntiAffinity rule for Rancher pods - *"preferred, required"* | 169 | `replicas` | 3 | ***int*** - Number of replicas of Rancher pods | 170 | `auditLog.destination` | "sidecar" | ***string*** - Stream to sidecar container console or hostPath volume - *"sidecar, hostPath"* | 171 | `auditLog.hostPath` | "/var/log/rancher/audit" | ***string*** - log file destination on host (only applies when **auditLog.destination** is set to **hostPath**) | 172 | `auditLog.level` | 0 | ***int*** - set the [API Audit Log level](https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-api-audit-log#audit-log-levels). 0 is off. [0-3] | 173 | `auditLog.maxAge` | 1 | ***int*** - maximum number of days to retain old audit log files (only applies when **auditLog.destination** is set to **hostPath**) | 174 | `auditLog.maxBackup` | 1 | int - maximum number of audit log files to retain (only applies when **auditLog.destination** is set to **hostPath**) | 175 | `auditLog.maxSize` | 100 | ***int*** - maximum size in megabytes of the audit log file before it gets rotated (only applies when **auditLog.destination** is set to **hostPath**) | 176 | `auditLog.image.repository` | "rancher/mirrored-bci-micro" | ***string*** - Location for the image used to collect audit logs *Note: Available as of v2.7.0* | 177 | `auditLog.image.tag` | "15.4.14.3" | ***string*** - Tag for the image used to collect audit logs *Note: Available as of v2.7.0* | 178 | `auditLog.image.pullPolicy` | "IfNotPresent" | ***string*** - Override imagePullPolicy for auditLog images - *"Always", "Never", "IfNotPresent"* *Note: Available as of v2.7.0* | 179 | `busyboxImage` | "" | ***string*** - *Deprecated `auditlog.image.repository` should be used to control auditing sidecar image.* Image location for busybox image used to collect audit logs *Note: Available as of v2.2.0, and Deprecated as of v2.7.0* | 180 | `busyboxImagePullPolicy` | "IfNotPresent" | ***string*** - - *Deprecated `auditlog.image.pullPolicy` should be used to control auditing sidecar image.* Override imagePullPolicy for busybox images - *"Always", "Never", "IfNotPresent"* *Deprecated as of v2.7.0* | 181 | `debug` | false | ***bool*** - set debug flag on rancher server | 182 | `certmanager.version` | " " | ***string*** - set cert-manager compatibility | 183 | `extraEnv` | [] | ***list*** - set additional environment variables for Rancher Note: *Available as of v2.2.0* | 184 | `imagePullSecrets` | [] | ***list*** - list of names of Secret resource containing private registry credentials | 185 | `ingress.enabled` | true | ***bool*** - install ingress resource | 186 | `ingress.ingressClassName` | " " | ***string*** - class name of ingress if not set manually or by the ingress controller's defaults | 187 | `ingress.includeDefaultExtraAnnotations` | true | ***bool*** - Add default nginx annotations | 188 | `ingress.extraAnnotations` | {} | ***map*** - additional annotations to customize the ingress | 189 | `ingress.configurationSnippet` | " " | ***string*** - Add additional Nginx configuration. Can be used for proxy configuration. Note: *Available as of v2.0.15, v2.1.10 and v2.2.4* | 190 | `service.annotations` | {} | ***map*** - annotations to customize the service | 191 | `service.type` | " " | ***string*** - Override the type used for the service - *"NodePort", "LoadBalancer", "ClusterIP"* | 192 | `letsEncrypt.ingress.class` | " " | ***string*** - optional ingress class for the cert-manager acmesolver ingress that responds to the Let’s *Encrypt ACME challenges* | 193 | `proxy` | " " | ***string** - HTTP[S] proxy server for Rancher | 194 | `noProxy` | "127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local" | ***string*** - comma separated list of hostnames or ip address not to use the proxy | 195 | `resources` | {} | ***map*** - rancher pod resource requests & limits | 196 | `rancherImage` | "rancher/rancher" | ***string*** - rancher image source | 197 | `rancherImageTag` | same as chart version | ***string*** - rancher/rancher image tag | 198 | `rancherImagePullPolicy` | "IfNotPresent" | ***string*** - Override imagePullPolicy for rancher server images - *"Always", "Never", "IfNotPresent"* | 199 | `tls` | "ingress" | ***string*** - See External TLS Termination for details. - *"ingress, external"* | 200 | `systemDefaultRegistry` | "" | ***string*** - private registry to be used for all system Docker images, e.g., [http://registry.example.com/] *Available as of v2.3.0* | 201 | `useBundledSystemChart` | false | ***bool*** - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations. *Available as of v2.3.0* | 202 | `customLogos.enabled` | false | ***bool*** - Enabled [Ember Rancher UI (cluster manager) custom logos](https://github.com/rancher/ui/tree/master/public/assets/images/logos) and [Vue Rancher UI (cluster explorer) custom logos](https://github.com/rancher/dashboard/tree/master/assets/images/pl) persistence volume | 203 | `customLogos.volumeSubpaths.emberUi` | "ember" | ***string*** - Volume subpath for [Ember Rancher UI (cluster manager) custom logos](https://github.com/rancher/ui/tree/master/public/assets/images/logos) persistence | 204 | `customLogos.volumeSubpaths.vueUi` | "vue" | ***string*** - Volume subpath for [Vue Rancher UI (cluster explorer) custom logos](https://github.com/rancher/dashboard/tree/master/assets/images/pl) persistence | 205 | `customLogos.volumeName` | "" | ***string*** - Use an existing volume. Custom logos should be copied to the proper `volume/subpath` folder by the user. Optional for persistentVolumeClaim, required for configMap | 206 | `customLogos.storageClass` | "" | ***string*** - Set custom logos persistentVolumeClaim storage class. Required for dynamic pv | 207 | `customLogos.accessMode` | "ReadWriteOnce" | ***string*** - Set custom persistentVolumeClaim access mode | 208 | `customLogos.size` | "1Gi" | ***string*** - Set custom persistentVolumeClaim size |