From 25ac7d75231147cb35a414f2e21760ec9f2dc715 Mon Sep 17 00:00:00 2001 From: Joe McCormick <31295332+iamjoemccormick@users.noreply.github.com> Date: Wed, 28 Feb 2024 20:35:22 +0000 Subject: [PATCH] Documentation updates for v1.6.0 --- CHANGELOG.md | 18 +++++++- README.md | 32 +++++++------ docs/deployment.md | 113 +++++++++++++++++++++++---------------------- 3 files changed, 93 insertions(+), 70 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 520ecdb0..99d73c4f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog -Notable changes to the BeeGFS CSI driver will be documented in this file. +Notable changes to the BeeGFS CSI driver will be documented in this file. + +[1.6.0] - 2024-02-28 +-------------------- + +### Added +- Support for BeeGFS v7.4.2 and Kubernetes v1.28. +- Support for arm64 and official multi-arch container images for all supported platforms + (linux/amd64 and linux/arm64). + +### Deprecated +- Kubernetes v1.25 and v1.26 support will be dropped in the next driver release according to our + [support + policy](docs/compatibility.md#dropping-compatibility-support-for-old-kubernetes-releases). + +### Removed +- Support/testing for Kubernetes v1.23 and v1.24. [1.5.0] - 2023-09-11 -------------------- diff --git a/README.md b/README.md index 4a9d874c..faf00c9e 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,8 @@ The driver can be easily deployed using the provided Kubernetes manifests. Optionally the [BeeGFS CSI Driver Operator](operator/README.md) can be used to automate day-1 (install/ configure) and day-2 (reconfigure/update) tasks for the driver. This especially simplifies discovery and installation from Operator -Lifecycle Manger (OLM) enabled clusters. +Lifecycle Manger (OLM) enabled clusters. Multi-arch images supporting amd64 and +arm64 Kubernetes nodes are provided for the BeeGFS CSI driver and operator. ### Notable Features @@ -77,23 +78,26 @@ table describes the versions of each component used in testing each release of the BeeGFS CSI driver. These configurations should be considered compatible and supported. -| beegfs.csi.netapp.com | K8s Versions | Red Hat OpenShift Versions | BeeGFS Client Versions | CSI Version | -| --------------------- | ----------------------------------------- | ---------------------------------------------------- | ---------------------- | ----------- | -| v1.5.0 | 1.23.17, 1.24.15, 1.25.11, 1.26.3, 1.27.3 | [No longer tested.](docs/compatibility.md#openshift) | 7.3.4, v7.4.0 | v1.7.0 | -| v1.4.0 | 1.22.6, 1.23.5, 1.24.1, 1.25.2 | 4.11 (RHEL only; RHCOS experimental) | 7.3.2, 7.2.8 | v1.7.0 | -| v1.3.0 | 1.21.4, 1.22.3, 1.23.1, 1.24.1 | 4.10 (RHEL only; RHCOS experimental) | 7.3.1, 7.2.7 | v1.6.0 | -| v1.2.2 | 1.20.11, 1.21.4, 1.22.3, 1.23.1 | 4.10 (RHEL only; RHCOS experimental) | 7.3.0, 7.2.6 [^1] | v1.5.0 | -| v1.2.1 | 1.19.15, 1.20.11, 1.21.4, 1.22.3 | 4.9 (RHEL only) | 7.2.5 [^1] | v1.5.0 | -| v1.2.0 | 1.18, 1.19, 1.20, 1.21 | 4.8 (RHEL only) | 7.2.4 [^1] | v1.5.0 | -| v1.1.0 | 1.18, 1.19, 1.20 | | 7.2.1 [^1] | v1.3.0 | -| v1.0.0 | 1.19 | | 7.2 [^1] | v1.3.0 | +| BeeGFS CSI Driver | K8s Versions | BeeGFS Client Versions | CSI Version | +| ----------------- | ----------------------------------------- | ---------------------- | ----------- | +| v1.6.0 | 1.25.16, 1.26.14, 1.27.11, 1.28.7 | 7.3.4, 7.4.2 | v1.8.0 | +| v1.5.0 | 1.23.17, 1.24.15, 1.25.11, 1.26.3, 1.27.3 | 7.3.4, 7.4.0 | v1.7.0 | +| v1.4.0 | 1.22.6, 1.23.5, 1.24.1, 1.25.2 | 7.3.2, 7.2.8 | v1.7.0 | +| v1.3.0 | 1.21.4, 1.22.3, 1.23.1, 1.24.1 | 7.3.1, 7.2.7 | v1.6.0 | +| v1.2.2 | 1.20.11, 1.21.4, 1.22.3, 1.23.1 | 7.3.0, 7.2.6 [^1] | v1.5.0 | +| v1.2.1 | 1.19.15, 1.20.11, 1.21.4, 1.22.3 | 7.2.5 [^1] | v1.5.0 | +| v1.2.0 | 1.18, 1.19, 1.20, 1.21 | 7.2.4 [^1] | v1.5.0 | +| v1.1.0 | 1.18, 1.19, 1.20 | 7.2.1 [^1] | v1.3.0 | +| v1.0.0 | 1.19 | 7.2 [^1] | v1.3.0 | + +Additional notes: +* Starting with v1.6.0 official multi-arch container images are provided for both amd64 and arm64. +* The BeeGFS CSI driver offers experimental support for [Hashicorp Nomad](docs/nomad.md). +* As of v1.5.0 the BeeGFS CSI driver is [no longer tested](docs/compatibility.md#openshift) with Red Hat OpenShift. See the [compatibility guide](docs/compatibility.md) for more details on expectations of compatibility for the BeeGFS CSI driver. -The BeeGFS CSI driver is also tested for use with Hashicorp Nomad. See our -[Nomad documentation](docs/nomad.md) for details. - ### Known Incompatibilities #### BeeGFS CSI Driver compatibility with BeeGFS 7.2.7+ and 7.3.1+ diff --git a/docs/deployment.md b/docs/deployment.md index 7a399788..11018559 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -77,14 +77,23 @@ OPTION 1: Validate the image using the version tag: ``` cosign verify --key ghcr.io/thinkparq/beegfs-csi-driver: ``` -Example: `cosign verify --key cosign.pub ghcr.io/thinkparq/beegfs-csi-driver:v1.5.0` +Examples: +``` +cosign verify --key cosign.pub ghcr.io/thinkparq/beegfs-csi-driver:v1.6.0 +cosign verify --key https://raw.githubusercontent.com/ThinkParQ/beegfs-csi-driver/master/release/cosign.pub ghcr.io/thinkparq/beegfs-csi-driver:v1.6.0 +``` OPTION 2: Validate the image using the version tag and digest: ``` cosign verify --key ghcr.io/thinkparq/beegfs-csi-driver:@SHA256: ``` -Example: `cosign verify --key cosign.pub ghcr.io/thinkparq/beegfs-csi-driver:v1.5.0@SHA256:a6efb4f870003f28a2ee421690f4f9d0e5b8eed0e24b3881fb816a760eb6dfea` +Examples: + +``` +cosign verify --key cosign.pub ghcr.io/thinkparq/beegfs-csi-driver:v1.5.0@SHA256:a6efb4f870003f28a2ee421690f4f9d0e5b8eed0e24b3881fb816a760eb6dfea +cosign verify --key https://raw.githubusercontent.com/ThinkParQ/beegfs-csi-driver/master/release/cosign.pub ghcr.io/thinkparq/beegfs-csi-driver:v1.5.0@SHA256:a6efb4f870003f28a2ee421690f4f9d0e5b8eed0e24b3881fb816a760eb6dfea +``` ### Automating Image Verification with Admission Controllers @@ -575,20 +584,17 @@ manifests handle this automatically. #### ConnAuth Configuration -As of BeeGFS `v7.3.1+` and `v7.2.7+`, connection based authentication is enabled by -default unless explicitly disabled. See the [BeeGFS -docs](https://doc.beegfs.io/latest/advanced_topics/authentication.html) for more -details. - -Version `v1.5.0` introduced the acceptance of base64 encoded connAuthFile secrets. -See [Base64 Encoded Secrets](#base64-encoded-secrets) for more details. +As of BeeGFS `v7.3.1+` and `v7.2.7+`, connection based authentication is enabled by default unless +explicitly disabled. See the [BeeGFS +docs](https://doc.beegfs.io/latest/advanced_topics/authentication.html) for more details. When using +raw string secrets, the driver will function as previously expected. Care should be taken when +creating raw string secrets as different text editors behave differently. Specifically, some editors +add newlines to the end of files. This may produce mis-match connAuthFile secrets between the client +and BeeGFS services causing the driver to fail. -NOTE: When using raw string secrets, the driver will function as previously expected. -Care should be taken when creating raw string secrets as different text editors -behave differently. Specifically, some editors add newlines to the end of files. -This may produce mis-match connAuthFile secrets between the client and BeeGFS -services causing the driver to fail. To ensure your secret is correct, it is -recommended to use base64 encoded secrets. +With version `v1.5.0` the CSI driver added support for base64 encoded connAuthFile secrets. See +[Base64 Encoded Secrets](#base64-encoded-secrets) for more details. To ensure your secret is +correct, it is recommended to use base64 encoded secrets. NOTE: Utilizing raw string secrets does not require an `encoding` field, but can be explicitly set using `encoding: raw`. @@ -608,48 +614,32 @@ connAuthFile configuration option is used on a file system's other services. encoding: # raw or base64 ``` -NOTE: Unlike general configuration, connAuth configuration is only applied at a +NOTES: +* Unlike general configuration, connAuth configuration is only applied at a per file system level. There is no default connAuth and the concept of a node specific connAuth doesn't make sense. - -NOTE: When running the driver directly, the connAuth configuration file is +* When running the driver directly, the connAuth configuration file is specified by the `--connauth-path` command line argument. For Kubernetes, the deployment manifests handle this automatically. - -NOTE: It is also possible to create a connAuthFile and set the connAuthFile +* It is also possible to create a connAuthFile and set the connAuthFile parameter in the default beegfs-client.conf file on every node. This option makes the most sense if also [configuring beegfs-helperd](#beegfs-helperd-configuration) to use connection authentication, as this requires per-node configuration of beegfs-helperd.conf. -##### Option 2: Disable Connection Authentication - -Only if you are using BeeGFS v7.3.1+ or v7.2.7+ and do not want to use -connection authentication, you must explicitly disable it by setting the -following. - -```yaml -config: - beegfsClientConf: - connDisableAuthentication: "true" -``` - -NOTE: This parameter does not exist in previous BeeGFS versions and BeeGFS will -fail to mount if it is provided for a file system that does not support it. - -##### Base64 Encoded Secrets +Using Base64 Encoded Secrets: It is recommended to use binary connAuthFile secrets utilizing base64 encoding as this aligns with [BeeGFS's](https://doc.beegfs.io/latest/advanced_topics/authentication.html?highlight=authentication) recommended format. The following are steps to implement base64 encoded secrets. -Follow the +1. Follow the [BeeGFS Authentication](https://doc.beegfs.io/latest/advanced_topics/authentication.html?highlight=authentication) steps to create a connAuthFile that contains a binary secret. -Once created, navigate to the location of your connAuthFile and encode the +1. Once created, navigate to the location of your connAuthFile and encode the file utilizing base64 encoding. ``` -> cd /etc/beegfs/ @@ -658,29 +648,42 @@ DbQqb8py78SrmHfpLBR1E0/eEJ5kQBXy9wPtY7umL46s3X0ILlrTednZQOMb+/9/gBIxFqNpyzOn tHyiNQNMEVNjXsihw11S5G4UbFw3Olcx8ehhnGTjWo0OoGKqM0TEL2FR8p3t1An0l1LUwYj1lrIG PQ== ``` -Copy and paste the output into `csi-beegfs-connauth.yaml`. +3. Copy and paste the output into `csi-beegfs-connauth.yaml`. Include the `encoding: base64` key-value pair inside `csi-beegfs-connauth.yaml` to -ensure decoding of your secret. +ensure decoding of your secret. The `csi-beegfs-connauth.yaml` should look similar to the following. -The `csi-beegfs-connauth.yaml` should look similar to the following. + ```yaml + # Copyright 2021 NetApp, Inc. All Rights Reserved. + # Licensed under the Apache License, Version 2.0. + + # Use this file as instructed in the ConnAuth Configuration section of /docs/deployment.md. See + # /deploy/k8s/examples/csi-beegfs-connauth.yaml for an example of what to put in this file. Kustomize will + # automatically transform this file into a correct Secret readable by the deployed driver. If this file is left + # unmodified, the driver will deploy correctly with no custom configuration. + + - sysMgmtdHost: 10.10.10.10 + connAuth: |+ + DbQqb8py78SrmHfpLBR1E0/eEJ5kQBXy9wPtY7umL46s3X0ILlrTednZQOMb+/9/gBIxFqNpyzOn + tHyiNQNMEVNjXsihw11S5G4UbFw3Olcx8ehhnGTjWo0OoGKqM0TEL2FR8p3t1An0l1LUwYj1lrIG + PQ== + encoding: base64 + ``` + +##### Option 2: Disable Connection Authentication + +Only if you are using BeeGFS v7.3.1+ or v7.2.7+ and do not want to use +connection authentication, you must explicitly disable it by setting the +following. ```yaml -# Copyright 2021 NetApp, Inc. All Rights Reserved. -# Licensed under the Apache License, Version 2.0. - -# Use this file as instructed in the ConnAuth Configuration section of /docs/deployment.md. See -# /deploy/k8s/examples/csi-beegfs-connauth.yaml for an example of what to put in this file. Kustomize will -# automatically transform this file into a correct Secret readable by the deployed driver. If this file is left -# unmodified, the driver will deploy correctly with no custom configuration. - -- sysMgmtdHost: 10.10.10.10 - connAuth: |+ - DbQqb8py78SrmHfpLBR1E0/eEJ5kQBXy9wPtY7umL46s3X0ILlrTednZQOMb+/9/gBIxFqNpyzOn - tHyiNQNMEVNjXsihw11S5G4UbFw3Olcx8ehhnGTjWo0OoGKqM0TEL2FR8p3t1An0l1LUwYj1lrIG - PQ== - encoding: base64 +config: + beegfsClientConf: + connDisableAuthentication: "true" ``` +NOTE: This parameter does not exist in previous BeeGFS versions and BeeGFS will +fail to mount if it is provided for a file system that does not support it. + #### BeeGFS Helperd Configuration