diff --git a/docs/deployment-preparation/software-requirements.md b/docs/deployment-preparation/software-requirements.md index 35b55cb3..e57103ed 100644 --- a/docs/deployment-preparation/software-requirements.md +++ b/docs/deployment-preparation/software-requirements.md @@ -39,9 +39,16 @@ For Kubernetes-based deployments, the following Kubernetes environments and dist | Amazon EKS | 1.30 and higher | | Google GKE | 1.30 and higher - non production only! | | K3s | 1.33 and higher | +| RKE2 | 1.33 and higher | | Kubernetes (vanilla) | 1.33 and higher | | Talos | 1.6.7 and higher | | OpenShift | 4.19 and higher | +| SUSE Rancher | 2.12 and higher | + +!!! info + SUSE Rancher is a management plane, not a Kubernetes distribution. Simplyblock is installed into the downstream + cluster it manages, which must run a supported RKE2 or K3s version. For details, see + [SUSE Rancher and RKE2](../kubernetes/rancher.md). Additionally, there are verified and supported operating systems for the Kubernetes worker nodes. A full reference is available at the [Supported Linux Distributions](../reference/supported-linux-distributions.md#kubernetes-hyper-converged-control-plane-and-storage-plane) diff --git a/docs/kubernetes/installation/index.md b/docs/kubernetes/installation/index.md index c28e2a8a..5fac04a8 100644 --- a/docs/kubernetes/installation/index.md +++ b/docs/kubernetes/installation/index.md @@ -47,5 +47,6 @@ For detailed CRD documentation, see [Simplyblock Operator](../../reference/opera ## Platform-Specific Notes - [OpenShift](openshift.md): Additional configuration for OpenShift clusters. +- [SUSE Rancher and RKE2](rancher.md) — kubelet and permission configuration for RKE2 and K3s clusters. - [Talos](talos.md): Specifics for Talos-based OS images. - [Volume Encryption](../usage/volume-encryption.md): End-to-end encryption with customer-managed keys. diff --git a/docs/kubernetes/installation/rancher.md b/docs/kubernetes/installation/rancher.md new file mode 100644 index 00000000..7b16a7de --- /dev/null +++ b/docs/kubernetes/installation/rancher.md @@ -0,0 +1,93 @@ +--- +title: "SUSE Rancher and RKE2" +description: "Installing simplyblock into RKE2 or K3s clusters managed by SUSE Rancher, including the permissions required on CIS-hardened clusters." +weight: 40150 +--- + +[SUSE Rancher](https://www.rancher.com/){:target="_blank" rel="noopener"} (Rancher Manager, Rancher Prime) is a +management plane for Kubernetes clusters. Simplyblock is installed into the downstream cluster managed by Rancher, not +into the Rancher management cluster. + +A Rancher-based deployment consists of three layers, each with its own simplyblock requirements: + +| Layer | Examples | Simplyblock requirements | +|-------------------------|-------------------------------------------------------------------------------------------------------------------------|----------------------------------------------| +| Management plane | Rancher Manager, Rancher Prime | None | +| Kubernetes distribution | [RKE2](https://docs.rke2.io/){:target="_blank" rel="noopener"}, [K3s](https://k3s.io/){:target="_blank" rel="noopener"} | Privileged permissions on hardened clusters | +| Worker node OS | SUSE Linux Enterprise, SUSE Linux Micro, RHEL, Ubuntu | Supported Linux distribution | + +!!! info + Not all worker nodes of a downstream cluster must host storage components. + Simplyblock uses node labels to identify nodes that participate in the storage cluster. + You can isolate storage workloads on dedicated worker nodes or node pools. + +## Prerequisites + +The downstream cluster must be operational, `kubectl` must be configured against it using the kubeconfig available from +the Rancher UI, and cluster administrator privileges are required. + +The cluster and its worker nodes must meet the general simplyblock requirements: + +- [Software Requirements](../deployment-preparation/software-requirements.md) +- [Hardware Requirements](../deployment-preparation/hardware-requirements.md) +- [Supported Linux Distributions](../../reference/supported-linux-distributions.md#kubernetes-hyper-converged-control-plane-and-storage-plane) + +## Required Permissions + +Simplyblock's CSI driver connects NVMe over Fabrics devices, formats them, and mounts them. It therefore runs as a +privileged container. + +By default, RKE2 applies a Pod Security Admission configuration that enforces the `privileged` standard cluster-wide, and +no further action is required. When a cluster is provisioned with the CIS hardening profile, RKE2 enforces the +`restricted` standard instead, exempting only its own system namespaces. On such clusters, the simplyblock namespace +requires the corresponding exemptions. + +```yaml title="Content of simplyblock-namespace.yaml" +apiVersion: v1 +kind: Namespace +metadata: + name: simplyblock + labels: + pod-security.kubernetes.io/enforce: privileged + pod-security.kubernetes.io/enforce-version: latest + pod-security.kubernetes.io/audit: privileged + pod-security.kubernetes.io/audit-version: latest + pod-security.kubernetes.io/warn: privileged + pod-security.kubernetes.io/warn-version: latest +``` + +```bash title="Enable privileged mode for simplyblock" +[demo@demo ~]# kubectl apply -f simplyblock-namespace.yaml +``` + +Create the namespace before installing the operator, so that the Helm chart adopts the labelled namespace instead of +creating an unlabelled one. + +## CPU Topology and Core Isolation + +Simplyblock configures the kubelet CPU topology and core isolation on storage nodes. These are controlled through +the operator's Helm values and require no changes to the RKE2 or K3s cluster definition: + +| Helm value | Purpose | +|----------------------------------------|------------------------------------------------------------| +| `storagenode.enableCpuTopology` | Enables CPU topology configuration on storage nodes | +| `storagenode.isolateCores` | Enables automatic core isolation | +| `storagenode.skipKubeletConfiguration` | Skips kubelet CPU-topology configuration if already set up | +| `storagenode.reservedSystemCpu` | Reserves CPU cores for host and system use | + +For the full list of values, see the [Kubernetes Reference](../../reference/kubernetes/index.md). + +## SUSE Linux Micro Nodes + +[SUSE Linux Micro](https://www.suse.com/products/micro/){:target="_blank" rel="noopener"} (SL Micro, formerly SLE Micro) +is supported as a worker node operating system and requires no image customization. Huge pages are allocated by +simplyblock automatically, and `/etc` is writable, so configuration drop-ins can be applied directly. + +Installing additional packages on a node modifies the read-only root filesystem and therefore requires +`transactional-update` followed by a reboot. + +## Installation of Simplyblock + +To install the simplyblock components on a Rancher-managed cluster, follow the instructions to +[install the Simplyblock Operator](k8s-control-plane.md) and follow the instructions to [deploy the storage nodes and +CSI driver](k8s-storage-plane.md). diff --git a/docs/reference/supported-linux-distributions.md b/docs/reference/supported-linux-distributions.md index 95be5266..cb90fa32 100644 --- a/docs/reference/supported-linux-distributions.md +++ b/docs/reference/supported-linux-distributions.md @@ -6,8 +6,11 @@ weight: 20200 Simplyblock requires a Linux Kernel 5.19 or later with NVMe over Fabrics and NVMe over TCP enabled. However, `{{ cliname }}`, the simplyblock commandline interface, requires some additional tools and expects certain -conventions for configuration files and locations. Therefore, simplyblock officially only supports Red Hat-based Linux -distributions as of now. +conventions for configuration files and locations. For **plain Linux deployments**, which are managed through +`{{ cliname }}`, simplyblock therefore officially only supports Red Hat-based Linux distributions as of now. + +**Kubernetes deployments** do not use `{{ cliname }}` on the nodes. The distributions supported for the Kubernetes +worker nodes are listed below. While others may work, manual intervention may be required, and simplyblock cannot support those. @@ -45,7 +48,13 @@ plane: | Debian | 12 or later | x86-64, ARM64 (Aarch64) | Fully supported | | Amazon Linux 2 (AL2) | - | x86-64, ARM64 (Aarch64) | Fully supported | | Amazon Linux 2023 | - | x86-64, ARM64 (Aarch64) | Fully supported | -| Talos | 1.6.7 or later | x86-64, ARM64 (Aarch64) | Fully supported | +| SUSE Linux Enterprise | 15 SP7 or later | x86-64, ARM64 (Aarch64) | Fully supported | +| SUSE Linux Micro | 6.1 or later | x86-64, ARM64 (Aarch64) | Fully supported | +| Talos | 1.6.7 or later | x86-64, ARM64 (Aarch64) | Fully supported1 | + +1 Talos is an immutable distribution shipping a minimal kernel +module set. It requires a custom node image and additional preparation to load the required kernel modules and reserve +huge pages. See [Talos](../deployments/kubernetes/talos.md) for details. ## Hosts (Initiators accessing Storage Cluster over NVMf) @@ -61,10 +70,10 @@ The following Linux distributions are considered tested and supported as NVMe-oF | Ubuntu | 20.04 | x86-64, ARM64 (Aarch64) | Fully supported | | Ubuntu | 22.04 | x86-64, ARM64 (Aarch64) | Fully supported | | Debian | 12 or later | x86-64, ARM64 (Aarch64) | Fully supported | -| Amazon Linux 2 (AL2) | - | x86-64, ARM64 (Aarch64) | Partially supported1 | -| Amazon Linux 2023 | - | x86-64, ARM64 (Aarch64) | Partially supported1 | +| Amazon Linux 2 (AL2) | - | x86-64, ARM64 (Aarch64) | Partially supported2 | +| Amazon Linux 2023 | - | x86-64, ARM64 (Aarch64) | Partially supported2 | -1 Amazon Linux 2 and Amazon Linux 2023 have a bug with +2 Amazon Linux 2 and Amazon Linux 2023 have a bug with [NVMe over Fabrics Multipathing](../important-notes/terminology.md#multipathing). That means that NVMe over Fabrics on any Amazon Linux operates in a degraded state with the risk of connection outages. Alternatively, multipathing must be configured using the Linux Device Manager (dm) via DM-MPIO.