refactoring notes

2026-05-31 09:05:32 +00:00 · 2022-07-07 13:46:58 -04:00
parent 19e3824185
commit 2922d9d6c3
9 changed files with 67 additions and 29 deletions
@@ -36,7 +36,11 @@ Snapshots are composed of the cluster data in etcd, the Kubernetes version, and

 When rolling back to a prior Kubernetes version, the [upgrade strategy options]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/upgrading-kubernetes/#configuring-the-upgrade-strategy) are ignored. Worker nodes are not cordoned or drained before being reverted to the older Kubernetes version, so that an unhealthy cluster can be more quickly restored to a healthy state.

-> **Prerequisite:** To restore snapshots from S3, the cluster needs to be configured to [take recurring snapshots on S3.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/backing-up-etcd/#configuring-recurring-snapshots)
+:::note Prerequisite:
+
+To restore snapshots from S3, the cluster needs to be configured to [take recurring snapshots on S3.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/backing-up-etcd/#configuring-recurring-snapshots)
+
+:::

 1. In the upper left corner, click **☰ > Cluster Management**.
 1. In the **Clusters** page, go to the cluster where you want to view the snapshots and click the name of the cluster.
@@ -45,10 +45,12 @@ The restore operation will work on a cluster that is not in a healthy or active

 # Upgrading the Kubernetes Version

-> **Prerequisites:**
->
-> - The options below are available only for [Rancher-launched RKE Kubernetes clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) and [Registered K3s Kubernetes clusters.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/registered-clusters/#additional-features-for-registered-k3s-clusters)
-> - Before upgrading Kubernetes, [back up your cluster.]({{<baseurl>}}/rancher/v2.6/en/backups)
+:::note Prerequisites:
+
+- The options below are available only for [Rancher-launched RKE Kubernetes clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) and [Registered K3s Kubernetes clusters.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/registered-clusters/#additional-features-for-registered-k3s-clusters)
+- Before upgrading Kubernetes, [back up your cluster.]({{<baseurl>}}/rancher/v2.6/en/backups)
+
+:::

 1. In the upper left corner, click **☰ > Cluster Management**.
 1. On the **Clusters** page, go to the cluster you want to upgrade and click **⋮ > Edit Config**.
@@ -102,7 +104,11 @@ To enable draining each node during a cluster upgrade,

 **Result:** The cluster is updated to use the new upgrade strategy.

-> **Note:** As of Rancher v2.4.0, there is a [known issue](https://github.com/rancher/rancher/issues/25478) in which the Rancher UI doesn't show state of etcd and controlplane as drained, even though they are being drained.
+:::note
+
+As of Rancher v2.4.0, there is a [known issue](https://github.com/rancher/rancher/issues/25478) in which the Rancher UI doesn't show state of etcd and controlplane as drained, even though they are being drained.
+
+:::

 ### Maintaining Availability for Applications During Upgrades

@@ -5,7 +5,11 @@ weight: 1

 This section describes how to set up existing persistent storage for workloads in Rancher.

-> This section assumes that you understand the Kubernetes concepts of persistent volumes and persistent volume claims. For more information, refer to the section on [how storage works.](../how-storage-works)
+:::note
+
+This section assumes that you understand the Kubernetes concepts of persistent volumes and persistent volume claims. For more information, refer to the section on [how storage works.](../how-storage-works)
+
+:::

 To set up storage, follow these steps:

@@ -47,7 +47,11 @@ For more information about the `extra_binds` directive, refer to [this section.]

 # Installing the ceph-csi driver on an RKE2 cluster

-> **Note:** These steps are needed for dynamic RBD provisioning only.
+:::note
+
+These steps are needed for dynamic RBD provisioning only.
+
+:::

 For more information about the `ceph-csi-rbd` chart, refer to [this page.](https://github.com/ceph/ceph-csi/blob/devel/charts/ceph-csi-rbd/README.md)

@@ -5,13 +5,19 @@ weight: 3054

 Before you can use the NFS storage volume plug-in with Rancher deployments, you need to provision an NFS server.

->**Note:**
->
->- If you already have an NFS share, you don't need to provision a new NFS server to use the NFS volume plugin within Rancher. Instead, skip the rest of this procedure and complete [adding storage]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/).
->
->- This procedure demonstrates how to set up an NFS server using Ubuntu, although you should be able to use these instructions for other Linux distros (e.g. Debian, RHEL, Arch Linux, etc.). For official instruction on how to create an NFS server using another Linux distro, consult the distro's documentation.
+:::note

->**Recommended:** To simplify the process of managing firewall rules, use NFSv4.
+- If you already have an NFS share, you don't need to provision a new NFS server to use the NFS volume plugin within Rancher. Instead, skip the rest of this procedure and complete [adding storage]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/).
+
+- This procedure demonstrates how to set up an NFS server using Ubuntu, although you should be able to use these instructions for other Linux distros (e.g. Debian, RHEL, Arch Linux, etc.). For official instruction on how to create an NFS server using another Linux distro, consult the distro's documentation.
+
+:::
+
+:::note Recommended:
+
+To simplify the process of managing firewall rules, use NFSv4.
+
+:::

 1. Using a remote Terminal connection, log into the Ubuntu server that you intend to use for NFS storage.

@@ -19,9 +19,11 @@ In order to provision vSphere volumes in a cluster created with the [Rancher Kub

 ### Creating a StorageClass

-> **Note:**
->
-> The following steps can also be performed using the `kubectl` command line tool. See [Kubernetes documentation on persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for details.
+:::tip
+
+The following steps can also be performed using the `kubectl` command line tool. See [Kubernetes documentation on persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for details.
+
+:::

 1. Click **☰ > Cluster Management**.
 1. Go to the cluster where you want to provide vSphere storage.
@@ -3,7 +3,11 @@ title: GlusterFS Volumes
 weight: 5000
 ---

-> This section only applies to [RKE clusters.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/)
+:::note
+
+This section only applies to [RKE clusters.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/)
+
+:::

 In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the `kubelet`. The logging of the `kubelet` will show: `transport endpoint is not connected`. To prevent this from happening, you can configure your cluster to mount the `systemd-run` binary in the `kubelet` container. There are two requirements before you can change the cluster configuration:

@@ -14,9 +18,11 @@ In clusters that store data on GlusterFS volumes, you may experience an issue wh
 docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version
 ```

->**Note:**
->
->Before updating your Kubernetes YAML to mount the `systemd-run` binary, make sure the `systemd` package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.
+:::caution
+
+Before updating your Kubernetes YAML to mount the `systemd-run` binary, make sure the `systemd` package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.
+
+:::

 ```
 services:
@@ -54,7 +54,11 @@ PVs can represent a physical disk or file system that you host on premise, or a

 Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned.

-> **Important:** PVs are created at the cluster level, which means that in a multi-tenant cluster, teams with access to separate namespaces could have access to the same PV.
+:::note Important:
+
+PVs are created at the cluster level, which means that in a multi-tenant cluster, teams with access to separate namespaces could have access to the same PV.
+
+:::

 ### Binding PVs to PVCs

@@ -62,7 +66,7 @@ When pods are set up to use persistent storage, they mount a persistent volume c

 > Claims will remain unbound indefinitely if a matching volume does not exist. Claims will be bound as matching volumes become available. For example, a cluster provisioned with many 50Gi PVs would not match a PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the cluster.

-In other words, you can create unlimited PVCs, but they will only be bound to PVs if the Kubernetes master can find a sufficient PVs that has at least the amount of disk space required by the PVC.
+In other words, you can create unlimited PVCs, but they will only be bound to PVs if the Kubernetes master can find a sufficient PV that has at least the amount of disk space required by the PVC.

 To dynamically provision new storage, the PVC mounted in the pod would have to correspond to a storage class instead of a persistent volume.

@@ -17,12 +17,14 @@ If you encounter this issue, you can work around it by installing the initiator

 After installing the initiator tool on your nodes, edit the YAML for your cluster, editing the kubelet configuration to mount the iSCSI binary and configuration, as shown in the sample below.

->**Notes:**
->  
->- Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the `open-iscsi` (deb) or `iscsi-initiator-utils` (yum) package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.</br>
-></br> 
->
->- The example YAML below does not apply to K3s, but only to RKE clusters. Since the K3s kubelet does not run in a container, adding extra binds is not necessary. However, all iSCSI tools must still be installed on your K3s nodes.
+:::note Notes
+  
+- Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the `open-iscsi` (deb) or `iscsi-initiator-utils` (yum) package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.</br>
+</br> 
+
+- The example YAML below does not apply to K3s, but only to RKE clusters. Since the K3s kubelet does not run in a container, adding extra binds is not necessary. However, all iSCSI tools must still be installed on your K3s nodes.
+
+:::

 ```
 services: