Add aws out of tree cloud provider install/upgrade docs (#844)

* Add aws out of tree cloud provider install/upgrade docs * Add aws out of tree cloud provider install/upgrade docs * Add info for aws cloud provider * indentation fix * Address review comments * addressing review comments * Address review comments * syntax annotations, re-org sections, copy edits * even more copy edits * copy edits to note at top * addressing suggestions from slickwarren * Address review comments * copyedits * Fix numbering * Update docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md * update helm installation steps * 2.8 versioning * rm 'new in 2.7' from 2.8 * Update versioned_docs/version-2.8/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md * revert -- change intended for other branch * typo fixes * fix headings, fix casing * apply prev commit to 2.8 * Reorganizing AWS migration pages (#1015) This partially addresses #991 (rename file `migrating-from-in-tree-to-out-of-tree` to shorter and reference vsphere) and also fixes problems on the open PR: Duplicate sections (removed), difficulty navigating the file (split into two), sections with similar titles (opting for tabs instead of headings). I created this on its own working branch because moving around large blocks of text was unwieldly and I didn't want to mess up my local version of 763-document-aws-out-of-tree-v2prov. The last tab block (Helm Chart Installation through UI) contains contain that seems to be entirely the same for RKE and RKE2. --------- Co-authored-by: Kinara Shah <[email protected]> Co-authored-by: martyav <[email protected]>
rancher · Dec 6, 2023 · 79ac876 · 79ac876
1 parent 3d89188
commit 79ac876
Show file tree

Hide file tree

Showing 9 changed files with 1,744 additions and 191 deletions.
diff --git a/...er-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md b/...er-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md
diff --git a/...usters-in-rancher-setup/set-up-cloud-providers/migrate-to-out-of-tree-amazon.md b/...usters-in-rancher-setup/set-up-cloud-providers/migrate-to-out-of-tree-amazon.md
@@ -0,0 +1,196 @@
+---
+title: Migrating Amazon In-tree to Out-of-tree
+---
+
+<head>
+  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-to-out-of-tree-amazon"/>
+</head>
+
+Kubernetes is moving away from maintaining cloud providers in-tree. In Kubernetes 1.27 and later, the in-tree cloud providers have been removed.
+
+You can migrate from an in-tree to an out-of-tree AWS cloud provider on Kubernetes 1.26 and earlier. All existing clusters must migrate prior to upgrading to v1.27 in order to stay functional.
+
+To migrate from the in-tree cloud provider to the out-of-tree AWS cloud provider, you must stop the existing cluster's kube controller manager and install the AWS cloud controller manager. There are many ways to do this. Refer to the official AWS documentation on the [external cloud controller manager](https://cloud-provider-aws.sigs.k8s.io/getting_started/) for details.
+
+If it's acceptable to have some downtime, you can [switch to an external cloud provider](./amazon.md#using-the-out-of-tree-aws-cloud-provider-for-rke), which removes in-tree components and then deploy charts to install the AWS cloud controller manager.
+
+If your setup can't tolerate any control plane downtime, you must enable leader migration. This facilitates a smooth transition from the controllers in the kube controller manager to their counterparts in the cloud controller manager. Refer to the official AWS documentation on [Using leader migration](https://cloud-provider-aws.sigs.k8s.io/getting_started/) for more details.
+
+:::note Important:
+The Kubernetes [cloud controller migration documentation](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#before-you-begin) states that it's possible to migrate with the same Kubernetes version, but assumes that the migration is part of a  Kubernetes upgrade. Refer to the Kubernetes documentation on [migrating to use the cloud controller manager](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/) to see if you need to customize your setup before migrating. Confirm your [migration configuration values](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#default-configuration). If your cloud provider provides an implementation of the Node IPAM controller,  you also need to [migrate the IPAM controller](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#node-ipam-controller-migration).
+:::
+
+<Tabs>
+<TabItem value="RKE2">
+
+1. Update the cluster config to enable leader migration:
+
+```yaml
+spec:
+  rkeConfig:
+    machineSelectorConfig:
+      - config:
+          kube-controller-manager-arg:
+            - enable-leader-migration
+        machineLabelSelector:
+          matchExpressions:
+            - key: rke.cattle.io/control-plane-role
+              operator: In
+              values:
+                - 'true'
+```
+
+Note that the cloud provider is still `aws` at this step:
+
+```yaml
+spec:
+  rkeConfig:
+    machineGlobalConfig:
+      cloud-provider-name: aws
+```
+
+2. Cordon control plane nodes so that AWS cloud controller pods run on nodes only after upgrading to the external cloud provider:
+
+```shell
+kubectl cordon -l "node-role.kubernetes.io/controlplane=true"
+```
+
+3. To install the AWS cloud controller manager with leader migration enabled, follow Steps 1-3 for [deploying the cloud controller manager chart](./amazon.md#using-out-of-tree-aws-cloud-provider-for-rke2)
+From Kubernetes 1.22 onwards, the kube-controller-manager will utilize a default configuration which will satisfy the controller-to-manager migration. 
+Update container args of the `aws-cloud-controller-manager` under `spec.rkeConfig.additionalManifest` to enable leader migration:
+
+```shell
+- '--enable-leader-migration=true' 
+```
+
+4. Install the chart and confirm that the Daemonset `aws-cloud-controller-manager` successfully deployed:
+
+```shell
+kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager
+```
+
+5. Update the provisioning cluster to change the cloud provider and remove leader migration args from the kube controller. 
+If upgrading the Kubernetes version, set the Kubernetes version as well in the `spec.kubernetesVersion` section of the cluster YAML file
+
+:::note Important
+
+Only remove `cloud-provider-name: aws` if not relying on the rke2 supervisor to correctly set the providerID.
+
+:::
+
+Remove `enable-leader-migration` if you don't want it enabled in your cluster:
+
+```yaml
+spec:
+  rkeConfig:
+    machineGlobalConfig:
+      cloud-provider-name: external
+```
+
+Remove `enable-leader-migration` from:
+
+```yaml
+spec:
+  rkeConfig:
+    machineSelectorConfig:
+      - config:
+          kube-controller-manager-arg:
+            - enable-leader-migration
+        machineLabelSelector:
+          matchExpressions:
+            - key: rke.cattle.io/control-plane-role
+              operator: In
+              values:
+                - 'true'
+```
+
+:::tip
+You can also disable leader migration after the upgrade, as leader migration is no longer required due to only one cloud-controller-manager and can be removed.
+Upgrade the chart and remove the following section from the container arguments:
+
+```yaml
+- --enable-leader-migration=true 
+```
+:::
+
+Verify the cloud controller manager update was successfully rolled out with the following command:
+
+```shell
+kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager
+```
+
+6. The cloud provider is responsible for setting the ProviderID of the node. Check if all nodes are initialized with the ProviderID:
+
+```shell
+kubectl describe nodes | grep "ProviderID"
+```
+
+</TabItem>
+
+<TabItem value="RKE">
+
+1. Update the cluster config to enable leader migration in `cluster.yml`:
+
+```yaml
+services:
+  kube-controller:
+    extra_args:
+      enable-leader-migration: "true"
+```
+
+Note that the cloud provider is still `aws` at this step:
+
+```yaml
+cloud_provider:
+  name: aws
+```
+
+2. Cordon the control plane nodes, so that AWS cloud controller pods run on nodes only after upgrading to the external cloud provider:
+
+```shell
+kubectl cordon -l "node-role.kubernetes.io/controlplane=true"
+```
+
+3. To install the AWS cloud controller manager, you must enable leader migration and follow the same steps as when installing AWS on a new cluster. To enable leader migration, add the following to the container arguments in step 7 while following the [steps to install the chart](./amazon.md#helm-chart-installation-from-ui-for-rke):
+
+```yaml
+- '--enable-leader-migration=true' 
+```
+
+4. Confirm that the chart is installed but that the new pods aren't running yet due to cordoned controlplane nodes. After updating the cluster in the next step, RKE will upgrade and uncordon each node, and schedule `aws-controller-manager` pods.
+
+5. Update `cluster.yml` to change the cloud provider and remove the leader migration arguments from the kube-controller.
+
+  Selecting **External Amazon (out-of-tree)** sets `--cloud-provider=external` and lets you enable `useInstanceMetadataHostname`. You must enable `useInstanceMetadataHostname` for node-driver clusters and for custom clusters if not you don't provide a custom node name via `--node-name`. Enabling `useInstanceMetadataHostname` will query ec2 metadata service and set `/hostname` as `hostname-override` for `kubelet` and `kube-proxy`:
+
+```yaml
+rancher_kubernetes_engine_config:
+  cloud_provider:
+    name: external-aws
+    useInstanceMetadataHostname: true/false
+```
+
+  Remove `enable-leader-migration` if you don't want it enabled in your cluster:
+
+  ```yaml
+  services:
+    kube-controller:
+      extra_args:
+        enable-leader-migration: "true"
+  ```
+
+:::tip
+You can also disable leader migration after you finish the migration. Upgrade the chart and remove the following section from the container arguments:
+
+```yaml
+- --enable-leader-migration=true 
+```
+:::
+
+6. If  you're upgrading the cluster's Kubernetes version, set the Kubernetes version as well.
+
+7. Update the cluster. The `aws-cloud-controller-manager` pods should now be running.
+
+</TabItem>
+</Tabs>
+
diff --git a/...rs/migrate-from-in-tree-to-out-of-tree.md → ...oviders/migrate-to-out-of-tree-vsphere.md b/...rs/migrate-from-in-tree-to-out-of-tree.md → ...oviders/migrate-to-out-of-tree-vsphere.md
@@ -1,5 +1,5 @@
 ---
-title: Migrating vSphere In-tree Volumes to Out-of-tree
+title: Migrating vSphere In-tree to Out-of-tree
 ---
 
 <head>
@@ -64,7 +64,7 @@ Once all nodes are tainted by the running the script, launch the Helm vSphere CP
 1. Click **☰ > Cluster Management**.
 1. Go to the cluster where the vSphere CPI chart will be installed and click **Explore**.
 1. Click **Apps > Charts**.
-1. Click **vSphere CPI**..
+1. Click **vSphere CPI**.
 1. Click **Install**.
 1. Fill out the required vCenter details and click **Install**.
 
@@ -81,7 +81,7 @@ kubectl describe nodes | grep "ProviderID"
 1. Click **☰ > Cluster Management**.
 1. Go to the cluster where the vSphere CSI chart will be installed and click **Explore**.
 1. Click **Apps > Charts**.
-1. Click **vSphere CSI**..
+1. Click **vSphere CSI**.
 1. Click **Install**.
 1. Fill out the required vCenter details and click **Install**.
 1. Check **Customize Helm options before install** and click **Next**.

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -582,9 +582,12 @@ module.exports = {
             from: '/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere'
           },
           {
-            to: '/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-from-in-tree-to-out-of-tree',
+            to: '/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-to-out-of-tree-vsphere',
             from: '/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree'
           },
+          { to: '/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-to-out-of-tree-vsphere', 
+            from: '/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-from-in-tree-to-out-of-tree'
+          },
           {
             to: '/how-to-guides/new-user-guides/add-users-to-projects',
             from: '/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects'

diff --git a/sidebars.js b/sidebars.js
@@ -493,11 +493,12 @@ const sidebars = {
                   },
                   items: [
                     "how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon",
+                    "how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-to-out-of-tree-amazon",
                     "how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure",
                     "how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/google-compute-engine",
                     "how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere",
                     "how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere",
-                    "how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-from-in-tree-to-out-of-tree",
+                    "how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-to-out-of-tree-vsphere",
                   ]
                 },
                 "how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters",