Merge pull request #119 in ESSOL-BB/beegfs-csi-driver from jmccormi_v…

…1.1.0_changelog_fix to master * commit '72354d5228d7bf7b68393bc25abe184498da698d': Add anchor links throughout to improve compatibility with version control systems.
ThinkParQ · May 10, 2021 · c65b537 · c65b537
2 parents 7572827 + 72354d5
commit c65b537
Show file tree

Hide file tree

Showing 6 changed files with 84 additions and 39 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,7 +1,7 @@
 # Changelog
 Notable changes to the BeeGFS CSI driver will be documented in this file. 
 
-[1.1.0] - 2021-05-07
+[1.1.0] - 2021-05-10
 --------------------
 ### Added 
 - Automated [end-to-end (E2E) testing](test/e2e/README.md) leveraging the
@@ -11,7 +11,7 @@ Notable changes to the BeeGFS CSI driver will be documented in this file.
 - Support for BeeGFS v7.2.1 and Kubernetes v1.18 and v1.20. 
 - The ability to specify [permissions](docs/usage.md#permissions) in BeeGFS from
   Storage Classes in Kubernetes. This simplifies integration with [BeeGFS
-  quotas](Quotas). 
+  quotas](docs/quotas.md). 
 
 ### Changed
 - Explicitly set the CSI driver's `fsGroupPolicy` to `None` disabling

diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # BeeGFS CSI Driver
 
-## Contents 
+## Contents
+<a name="contents"></a>
+
 * [Overview](#overview)
 * [Getting Started](#getting-started)
 * [Basic Use and Examples](#basic-use)
@@ -10,15 +12,15 @@
 * [Maintainers](#maintainers)
 
 ## Overview 
-
+<a name="overview"></a>
 The BeeGFS Container Storage Interface (CSI) driver provides high performing and
 scalable storage for workloads running in container orchestrators like
 Kubernetes. This driver allows containers to access existing datasets or request
 on-demand ephemeral or persistent high speed storage backed by [BeeGFS parallel
 file systems](https://blog.netapp.com/beegfs-for-beginners/). 
 
 ### Notable Features
-
+<a name="notable-features"></a>
 * Integration of [Storage Classes in Kubernetes](docs/usage.md#create-a-storage-class) with [storage
   pools](https://doc.beegfs.io/latest/advanced_topics/storage_pools.html) in
   BeeGFS, allowing different tiers of storage within the same file system to be
@@ -40,6 +42,7 @@ file systems](https://blog.netapp.com/beegfs-for-beginners/).
   access to common datasets.
 
 ### Interoperability and CSI Feature Matrix
+<a name="interoperability-and-csi-feature-matrix"></a>
 | beegfs.csi.netapp.com  | K8s Versions     | BeeGFS Versions | CSI Version  | Persistence | Supported Access Modes   | Dynamic Provisioning |
 | -----------------------| ---------------- | --------------- | ------------ | ----------- | ------------------------ | -------------------- |
 | v1.0.0                 | 1.19             | 7.2, 7.1.5      | v1.3.0       | Persistent  | Read/Write Multiple Pods | Yes                  |  
@@ -55,9 +58,10 @@ Additional Notes:
   7.2.x, Kubernetes nodes should have the 7.2 BeeGFS DKMS client installed.
 
 ## Getting Started 
+<a name="getting-started"></a>
 
 ### Prerequisite(s) 
-
+<a name="prerequisites"></a>
 * Deploying the driver requires access to a terminal with kubectl. 
 * The [BeeGFS DKMS
   client](https://doc.beegfs.io/latest/advanced_topics/client_dkms.html) must be
@@ -76,6 +80,7 @@ Additional Notes:
   required to deploy the driver).
 
 ### Quick Start
+<a name="quick-start"></a>
 The steps in this section allow you to get the driver up and running quickly.
 For production use cases or air-gapped environments it is recommended to read
 through the full [deployment guide](docs/deployment.md). 
@@ -98,7 +103,7 @@ Provided all Pods are running the driver is now ready for use. See the following
 sections for how to get started using the driver.
 
 ## Basic Use
-
+<a name="basic-use"></a>
  This section provides a quick summary of basic driver use and functionality.
  Please see the full [usage documentation](docs/usage.md) for a complete
  overview of all available functionality. The driver was designed to support
@@ -111,36 +116,36 @@ sections for how to get started using the driver.
  system when desired. 
 
 ### Dynamic Storage Provisioning:
-
+<a name="dynamic-storage-provisioning"></a>
 Administrators create a Storage Class in Kubernetes referencing at minimum a
 specific BeeGFS file system and parent directory within that file system. Users
 can then submit PVCs against the Storage Class, and are provided isolated access
 to new directories under the parent specified in the Storage Class. 
 
 ### Static Provisioning:
-
+<a name="static-provisioning"></a>
 Administrators create a PV and PVC representing an existing directory in a
 BeeGFS file system. This is useful for exposing some existing dataset or shared
 directory to Kubernetes users and applications.
 
 ### Examples
-
+<a name="examples"></a>
 [Example Kubernetes manifests](examples/README.md) of how to use the driver are
 provided. These are meant to be repurposed to simplify creating objects related
 to the driver including Storage Classes, Persistent Volumes, and Persistent
 Volume Claims in your environment.
 
 ## Requesting Enhancements and Reporting Issues 
-
+<a name="requesting-enhancements-and-reporting-issues"></a>
 If you have any questions, feature requests, or would like to report an issue
 please submit them at https://github.com/NetApp/beegfs-csi-driver/issues. 
 
 ## License 
-
+<a name="license"></a>
 Apache License 2.0
 
 ## Maintainers 
-
+<a name="maintainers"></a>
 * Austin Major (@austinmajor).
 * Eric Weber (@ejweber).
 * Jason Eastburn

diff --git a/docs/deployment.md b/docs/deployment.md
@@ -1,6 +1,8 @@
 # BeeGFS CSI Driver Deployment
 
 ## Contents
+<a name="contents"></a>
+
 * [Deploying to Kubernetes](#deploying-to-kubernetes)
   * [Kubernetes Node Preparation](#kubernetes-node-preparation)
   * [Kubernetes Deployment](#kubernetes-deployment)
@@ -9,12 +11,14 @@
 * [Managing BeeGFS Client Configuration](#managing-beegfs-client-configuration)
   * [General Configuration](#general-configuration)
   * [Kubernetes Configuration](#kubernetes-configuration)
-  * [BeeGFS Client Parameters](#beegfs-client-parameters-(beeGFSClientConf)) 
+  * [BeeGFS Client Parameters](#beegfs-client-parameters) 
 * [Removing the Driver from Kubernetes](#removing-the-driver-from-kubernetes)
 
 ## Deploying to Kubernetes
+<a name="deploying-to-kubernetes"></a>
 
 ### Kubernetes Node Preparation
+<a name="kubernetes-node-preparation"></a>
 The following MUST be completed on any Kubernetes node (master OR worker) that
 runs a component of the driver:
 * Download the [BeeGFS repository
@@ -33,6 +37,7 @@ IMPORTANT: By default the driver uses the beegfs-client.conf file at
 of this file is not currently supported without changing kustomization files. 
 
 ### Kubernetes Deployment
+<a name="kubernetes-deployment"></a>
 Deployment manifests are provided in this repository under *deploy/* along with
 a default BeeGFS Client ConfigMap. The driver is deployed using `kubectl apply
 -k` (kustomize). 
@@ -50,8 +55,8 @@ Steps:
 * If you are using [BeeGFS Connection Based Authentication](https://doc.beegfs.io/latest/advanced_topics/authentication.html) 
   fill in the empty Secret config file at *deploy/prod/csi-beegfs-connauth.yaml*.
   * An example Secret config file is provided at 
-  *deploy/prod/csi-beegfs-connauth-example.yaml* Please see the section on 
-  [ConnAuth Configuration](connauth-configuration) for full details. 
+  *deploy/prod/csi-beegfs-connauth-example.yaml*. Please see the section on 
+  [ConnAuth Configuration](#connauth-configuration) for full details. 
 * Change to the BeeGFS CSI driver directory (`cd beegfs-csi-driver`) and run:
   `kubectl apply -k deploy/prod`
   * Note by default the beegfs-csi-driver image will be pulled from
@@ -95,6 +100,7 @@ Next Steps:
   documentation.
 
 ### Air-Gapped Kubernetes Deployment
+<a name="air-gapped-kubernetes-deployment"></a>
 This section provides guidance on deploying the BeeGFS CSI driver in
 environments where Kubernetes nodes do not have internet access. 
 
@@ -117,7 +123,7 @@ exist on the Kubernetes nodes or reference your internal registry. Then follow
 the above commands for Kubernetes deployment.
 
 ## Example Application Deployment
-
+<a name="example-application-deployment"></a>
 Verify that a BeeGFS file system is accessible from the Kubernetes nodes.
 Minimally, verify that the BeeGFS servers are up and listening from a
 workstation that can access them:
@@ -319,7 +325,7 @@ directly out of a beegfs-client.conf configuration file. In particular, the
 beegfs-client.conf file contains a number of references to other files (e.g.
 `connInterfacesFile`). The CSI configuration file instead expects a YAML list,
 which it uses to generate the expected file. See [BeeGFS Client
-Parameters](#beegfs-client-parameters-(beeGFSClientConf)) for more detail about
+Parameters](#beegfs-client-parameters) for more detail about
 supported `beegfsClientConf` parameters.
 
 The order of precedence for configuration option overrides is described by
@@ -382,7 +388,7 @@ nodeSpecificConfigs:  # OPTIONAL
 ```
 
 #### ConnAuth Configuration
-
+<a name="connauth-configuration"></a>
 For security purposes, the contents of BeeGFS connAuthFiles are stored in a
 separate file. This file is optional, and should only be used if the
 connAuthFile configuration option is used on a file system's other services.
@@ -403,7 +409,7 @@ per file system level. There is no default connAuth and the concept of a node
 specific connAuth doesn't make sense.
 
 ### Kubernetes Configuration
-
+<a name="kubernetes-configuration"></a>
 When deployed into Kubernetes, a single Kubernetes ConfigMap contains the
 configuration for all Kubernetes nodes. When the driver starts up on a node, it
 uses the node's name to filter the global ConfigMap down to a node-specific
@@ -427,23 +433,23 @@ driver on all nodes.
 
 To update configuration after initial deployment, modify
 *deploy/prod/csi-beegfs-config.yaml* or *deploy/prod/csi-beegfs-connauth.yaml*
-and repeat the kubectl deployment step from[Kubernetes Deployment](#kubernetes-deployment). 
+and repeat the kubectl deployment step from [Kubernetes Deployment](#kubernetes-deployment). 
 Kustomize will automatically update all components and restart the driver on 
 all nodes so that it picks up the latest changes.
 
 NOTE: To validate the BeeGFS Client configuration file used for a specific PVC, 
-see the [Troubleshooting Guide](troubleshooting.md#determining-the-beegfs-client-configuration-for-a-pvc)
+see the [Troubleshooting Guide](troubleshooting.md#k8s-determining-the-beegfs-client-conf-for-a-pvc)
 
 ### BeeGFS Client Parameters (beegfsClientConf)
-
+<a name="beegfs-client-parameters"></a>
 The following beegfs-client.conf parameters appear in the BeeGFS v7.2
 [beegfs-client.conf
 file](https://git.beegfs.io/pub/v7/-/blob/7.2/client_module/build/dist/etc/beegfs-client.conf).
 Other parameters may exist for newer or older BeeGFS versions. The list a
 parameter falls under determines its level of support in the driver.
 
 #### No Effect
-
+<a name="no-effect"></a>
 These parameters are specified elsewhere (a Kubernetes StorageClass, etc.) or
 are determined dynamically and have no effect when specified in the
 `beeGFSClientConf` configuration section.
@@ -461,7 +467,7 @@ are determined dynamically and have no effect when specified in the
 * `connPortShift`
 
 #### Unsupported
-
+<a name="unsupported"></a>
 These parameters are specified elsewhere and may exhibit undocumented behavior
 if specified here.
 
@@ -474,13 +480,13 @@ if specified here.
   file.
 
 ### Tested
-
+<a name="tested"></a>
 These parameters have been tested and verified to have the desired effect.
 
 * `quotaEnabled` - Documented in [Quotas](quotas.md).
 
 #### Untested
-
+<a name="untested"></a>
 These parameters SHOULD result in the desired effect but have not been tested.
 
 * `connHelperdPortTCP`
@@ -515,7 +521,7 @@ These parameters SHOULD result in the desired effect but have not been tested.
 * `sysACLsEnabled`
 
 ## Removing the Driver from Kubernetes
-
+<a name="removing-the-driver-from-kubernetes"></a>
 If you're experiencing any issues, find functionality lacking, or our
 documentation is unclear, we'd appreciate if you let us know:
 https://github.com/NetApp/beegfs-csi-driver/issues. 

diff --git a/docs/quotas.md b/docs/quotas.md
@@ -1,8 +1,15 @@
-Using BeeGFS Quotas with the CSI Driver
----------------------------------------
+# Using BeeGFS Quotas with the CSI Driver
 
-## Overview 
+## Contents
+<a name="contents"></a>
+
+* [Overview](#overview)
+* [Prerequisites](#prerequisites)
+* [Enabling Quotas](#enabling-quotas)
+* [Tracking BeeGFS Consumption by Storage Class](#tracking-beegfs-consumption-by-sc)
 
+## Overview 
+<a name="overview"></a>
 To provide administrators visibility and control over file system utilization,
 BeeGFS supports both [quota
 tracking](https://doc.beegfs.io/latest/advanced_topics/quota.html#quota-tracking)
@@ -18,7 +25,7 @@ will also demonstrate how to leverage quotas to track BeeGFS consumption with an
 example that can be extended to any number of use cases.
 
 ## Prerequisites
-
+<a name="prerequisites"></a>
 * The BeeGFS server nodes (Management, Metadata, and Storage) must already have
   quota tracking and optionally quota enforcement enabled. See the [BeeGFS
   documentation](https://doc.beegfs.io/latest/advanced_topics/quota.html) if you
@@ -30,7 +37,7 @@ example that can be extended to any number of use cases.
   use in production.
 
 ## Enabling Quotas
-
+<a name="enabling-quotas"></a>
 In addition to the prerequisite steps for BeeGFS server nodes, to enable quotas
 each client must set `quotaEnabled = true` in the configuration file
 corresponding with the mount point for that file system. For container
@@ -43,7 +50,7 @@ appropriate section of your BeeGFS CSI driver configuration file (for Kubernetes
 this is at `deploy/prod/csi-beegfs-config.yaml`). The appropriate section
 depends if you want it to apply to all BeeGFS file systems, specific file
 systems, or specific clients. See [General
-Configuration](deployment.md/#general-configuration) for full details. The
+Configuration](deployment.md#general-configuration) for full details. The
 following example shows how to set an unrelated parameter (`connUseRDMA: true`)
 on all file systems, then only enable quotas for the BeeGFS file system with a
 management IP of `192.168.1.100`: 
@@ -68,9 +75,10 @@ all I/O will continue to affect the quota consumption of the root user, instead
 of the actual caller.
 
 ## Tracking BeeGFS Consumption by Storage Class
+<a name="tracking-beegfs-consumption-by-sc"></a>
 
 ### Introduction 
-
+<a name="tracking-beegfs-consumption-by-sc-intro"></a>
 If your containers are running with a meaningful user ID from a quota
 perspective, the above configuration is all that is needed to take advantage of
 BeeGFS quotas. However in some environments the user in a container may vary,
@@ -106,7 +114,7 @@ Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/)
 for ways to prevent users from running containers as root if desired. 
 
 ### Linux User/Group IDs and Containers
-
+<a name="tracking-beegfs-consumption-by-sc-linux-uid-gid-and-containers"></a>
 Typically BeeGFS
 [recommends](https://doc.beegfs.io/latest/advanced_topics/quota.html#requirements-and-general-notes)
 ensuring the local systems of all nodes are configured correctly to query passwd
@@ -126,7 +134,7 @@ query/set BeeGFS quota information using `beegfs-ctl`, should have a
 synchronized view of this mapping to avoid confusion. 
 
 ### Example Steps to setup a Storage Class that use setgid to set a specific group
-
+<a name="tracking-beegfs-consumption-by-sc-example-steps"></a>
 Note: Any steps specific to creating groups or querying quota information should
 take place on a node with a synchronized view of the user and group IDs as
 described in the last section. 

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -1,14 +1,25 @@
 # Troubleshooting Guide
 
+## Contents
+<a name="contents"></a>
+
+* [Overview](#overview)
+* [Kubernetes](#kubernetes)
+  * [Determining the BeeGFS Client Configuration 
+  for a PVC](#k8s-determining-the-beegfs-client-conf-for-a-pvc)
+
+## Overview
+<a name="overview"></a>
 This section provides guidance and tips around troubleshooting issues that
 come up using the driver. For anything not covered here, please [submit an
 issue](https://github.com/NetApp/beegfs-csi-driver/issues) using the label
 "question". Suspected bugs should be submitted with the label "bug". 
 
 ## Kubernetes
+<a name="kubernetes"></a>
 
 ### Determining the BeeGFS Client Configuration for a PVC
-<a name="determining-the-beegfs-client-configuration-for-a-pvc"></a>
+<a name="k8s-determining-the-beegfs-client-conf-for-a-pvc"></a>
 
 BeeGFS Client configuration is specified in a Kubernetes ConfigMap, that is
 parsed out to generate the client configuration that applies to a PVC for a