From 28c7773ac836efcc4c7941352a5eeac838c28336 Mon Sep 17 00:00:00 2001 From: William Jimenez Date: Tue, 3 Dec 2019 15:34:36 -0800 Subject: [PATCH 1/5] Helm 3 docs update --- .../v2.x/en/installation/ha/helm-rancher/_index.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md index ecf5b847dac..a81c3866f8f 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -9,7 +9,7 @@ For systems without direct internet access, see [Air Gap: High Availability Inst Refer to the [Helm version requirements]({{}}/rancher/v2.x/en/installation/helm-version) 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) +> **Note:** The installation instructions assume you are using Helm 3. Migration of installs from Helm 2 to Helm 3 will be documented soon. ### Add the Helm Chart Repository @@ -21,6 +21,13 @@ Use `helm repo add` command to add the Helm chart repository that contains chart helm repo add rancher- https://releases.rancher.com/server-charts/ ``` +### Create a Namespace for Rancher +We'll need to define a namespace where the resources created by the Chart should be installed. This should always be `cattle-system`: + +``` +kubectl create namespace cattle-system +``` + ### Choose your SSL Configuration Rancher Server is designed to be secure by default and requires SSL/TLS configuration. @@ -77,7 +84,6 @@ These instructions are adapted from the [official cert-manager documentation](ht 1. Install the cert-manager Helm chart ```plain helm install \ - --name cert-manager \ --namespace cert-manager \ --version v0.9.1 \ jetstack/cert-manager @@ -108,7 +114,6 @@ The default is for Rancher to generate a CA and uses `cert-manager` to issue the ``` helm install rancher-/rancher \ - --name rancher \ --namespace cattle-system \ --set hostname=rancher.my.org ``` @@ -131,7 +136,6 @@ This option uses `cert-manager` to automatically request and renew [Let's Encryp ``` helm install rancher-/rancher \ - --name rancher \ --namespace cattle-system \ --set hostname=rancher.my.org \ --set ingress.tls.source=letsEncrypt \ @@ -158,7 +162,6 @@ Create Kubernetes secrets from your own certificates for Rancher to use. ``` helm install rancher-/rancher \ - --name rancher \ --namespace cattle-system \ --set hostname=rancher.my.org \ --set ingress.tls.source=secret From 76011a57092b64b08d528228a283803407ee7043 Mon Sep 17 00:00:00 2001 From: William Jimenez Date: Tue, 3 Dec 2019 15:41:29 -0800 Subject: [PATCH 2/5] collapse content from helm init page into helm install --- .../en/installation/ha/helm-init/_index.md | 65 ------------------- .../ha/helm-init/troubleshooting/_index.md | 23 ------- .../en/installation/ha/helm-rancher/_index.md | 6 +- 3 files changed, 5 insertions(+), 89 deletions(-) delete mode 100644 content/rancher/v2.x/en/installation/ha/helm-init/_index.md delete mode 100644 content/rancher/v2.x/en/installation/ha/helm-init/troubleshooting/_index.md diff --git a/content/rancher/v2.x/en/installation/ha/helm-init/_index.md b/content/rancher/v2.x/en/installation/ha/helm-init/_index.md deleted file mode 100644 index e0793246f7f..00000000000 --- a/content/rancher/v2.x/en/installation/ha/helm-init/_index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "3. Initialize Helm (Install Tiller)" -weight: 195 ---- - -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]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#helm) for install details. - -Refer to the [Helm version requirements]({{}}/rancher/v2.x/en/installation/helm-version) 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: -``` - -> **Note:** This`tiller`install has full cluster access, which should be acceptable if the cluster is dedicated to Rancher server. Check out the [helm docs](https://docs.helm.sh/using_helm/#role-based-access-control) for 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]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-init/troubleshooting/) page. - -### [Next: Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/) diff --git a/content/rancher/v2.x/en/installation/ha/helm-init/troubleshooting/_index.md b/content/rancher/v2.x/en/installation/ha/helm-init/troubleshooting/_index.md deleted file mode 100644 index c73013b5cb8..00000000000 --- a/content/rancher/v2.x/en/installation/ha/helm-init/troubleshooting/_index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Troubleshooting -weight: 276 ---- - -### Helm commands show forbidden - -When Helm is initiated in the cluster without specifying the correct `ServiceAccount`, the command `helm init` will succeed but you won't be able to execute most of the other `helm` commands. The following error will be shown: - -``` -Error: configmaps is forbidden: User "system:serviceaccount:kube-system:default" cannot list configmaps in the namespace "kube-system" -``` - -To resolve this, the server component (`tiller`) needs to be removed and added with the correct `ServiceAccount`. You can use `helm reset --force` to remove the `tiller` from the cluster. Please check if it is removed using `helm version --server`. - -``` -helm reset --force -Tiller (the Helm server-side component) has been uninstalled from your Kubernetes Cluster. -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)]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-init/) to install `tiller` with the correct `ServiceAccount`. diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md index a81c3866f8f..49bd4062e41 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -3,7 +3,7 @@ title: "4. Install Rancher" weight: 200 --- -Rancher installation is managed using the Helm package manager for Kubernetes. Use `helm` to install the prerequisite and charts to install Rancher. +Rancher installation is managed 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: High Availability Install]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/). @@ -11,6 +11,10 @@ Refer to the [Helm version requirements]({{}}/rancher/v2.x/en/installat > **Note:** The installation instructions assume you are using Helm 3. Migration of installs from Helm 2 to Helm 3 will be documented soon. +### Install Helm + +Helm requires a simple CLI tool to be installed. Refer to the [instructions provided by the Helm project](https://helm.sh/docs/intro/install/) for your specific platofrm. + ### 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]({{< baseurl >}}/rancher/v2.x/en/installation/server-tags/#helm-chart-repositories). From b2ef914ed7262f6fb8b4918ad7eb2cea26758486 Mon Sep 17 00:00:00 2001 From: William Jimenez Date: Tue, 3 Dec 2019 15:47:28 -0800 Subject: [PATCH 3/5] mention migration path to helm3 --- content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md index 49bd4062e41..ec68d1ae75e 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -9,7 +9,7 @@ For systems without direct internet access, see [Air Gap: High Availability Inst Refer to the [Helm version requirements]({{}}/rancher/v2.x/en/installation/helm-version) to choose a version of Helm to install Rancher. -> **Note:** The installation instructions assume you are using Helm 3. Migration of installs from Helm 2 to Helm 3 will be documented soon. +> **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/) ### Install Helm From f00f114a84decc7d4ae383c73cab94e5b4f15a2d Mon Sep 17 00:00:00 2001 From: William Jimenez Date: Tue, 3 Dec 2019 15:49:36 -0800 Subject: [PATCH 4/5] forgot to remove tiller from TOC --- content/rancher/v2.x/en/installation/ha/_index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/rancher/v2.x/en/installation/ha/_index.md b/content/rancher/v2.x/en/installation/ha/_index.md index 5c720e2373d..70bfe70357f 100644 --- a/content/rancher/v2.x/en/installation/ha/_index.md +++ b/content/rancher/v2.x/en/installation/ha/_index.md @@ -34,7 +34,6 @@ The following CLI tools are required for this install. Please make sure these to - [Create Nodes and Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/ha/create-nodes-lb/) - [Install Kubernetes with RKE]({{< baseurl >}}/rancher/v2.x/en/installation/ha/kubernetes-rke/) -- [Initialize Helm (tiller)]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-init/) - [Install Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/) ## Additional Install Options From 82edc927d1abf1abaca46435d0fddbdcd630b568 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 5 Dec 2019 11:43:30 -0700 Subject: [PATCH 5/5] Fix Helm command according to Gaurav's feedback --- .../rancher/v2.x/en/installation/ha/helm-rancher/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md index ec68d1ae75e..b35f6af9215 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -117,7 +117,7 @@ The default is for Rancher to generate a CA and uses `cert-manager` to issue the - Set the `hostname` to the DNS name you pointed at your load balancer. ``` -helm install rancher-/rancher \ +helm install rancher rancher-/rancher \ --namespace cattle-system \ --set hostname=rancher.my.org ``` @@ -139,7 +139,7 @@ This option uses `cert-manager` to automatically request and renew [Let's Encryp - Set `hostname` to the public DNS record, set `ingress.tls.source` to `letsEncrypt` and `letsEncrypt.email` to the email address used for communication about your certificate (for example, expiry notices) ``` -helm install rancher-/rancher \ +helm install rancher rancher-/rancher \ --namespace cattle-system \ --set hostname=rancher.my.org \ --set ingress.tls.source=letsEncrypt \ @@ -165,7 +165,7 @@ Create Kubernetes secrets from your own certificates for Rancher to use. - If you are using a Private CA signed certificate , add `--set privateCA=true` to the command shown below. ``` -helm install rancher-/rancher \ +helm install rancher rancher-/rancher \ --namespace cattle-system \ --set hostname=rancher.my.org \ --set ingress.tls.source=secret