Merge pull request #39 from hughdanliu/documentation-updates

Minor documentation adjustments

Author: k8s-ci-robot

README.md

@@ -12,8 +12,8 @@ The [Amazon FSx for OpenZFS](https://aws.amazon.com/fsx/openzfs/) Container Stor
 * **Static Provisioning** - Associate an externally-created FSx for OpenZFS file system or volume with a [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) (PV) for consumption within Kubernetes.
 * **Dynamic Provisioning** - Automatically create FSx for OpenZFS file systems or volumes and associated [PersistentVolumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) (PV) from [PersistentVolumeClaims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#dynamic) (PVC). Parameters can be passed via a [StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/#the-storageclass-resource) for fine-grained control over volume creation.
 * **Mount Options** - NFS Mount options can be specified in the [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) (PV) resource to define how the volume should be mounted.
-* **Volume Snapshots** - Create and restore [snapshots](https://kubernetes.io/docs/concepts/storage/volume-snapshots/) taken from a volume in Kubernetes.
-* **Volume Resizing** - Expand the Persistent Volume by specifying a new size in the [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#expanding-persistent-volumes-claims) (PVC).
+* **Volume Snapshots** - Create and restore [snapshots](https://kubernetes.io/docs/concepts/storage/volume-snapshots/) taken from a volume in Kubernetes. These snapshots can then be used to create new FSx for OpenZFS volumes.
+* **Volume Resizing** - Expand an FSx for OpenZFS file system by specifying a new size in the [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#expanding-persistent-volumes-claims) (PVC).
 
 ### CSI Interfaces
 * Controller Service: ControllerGetCapabilities, CreateVolume, DeleteVolume, CreateSnapshot, DeleteSnapshot, ControllerExpandVolume

docs/install.md

@@ -3,16 +3,15 @@
 ## Prerequisites
 
 * Kubernetes Version >= 1.20
-
-* If you are using a self managed cluster, ensure the flag `--allow-privileged=true` for `kube-apiserver`.
+* Cluster running in EKS - the FSx for OpenZFS CSI driver currently does not support usage with self-managed clusters.
 
 * Important: If you intend to use the Volume Snapshot feature, the [Kubernetes Volume Snapshot CRDs](https://github.com/kubernetes-csi/external-snapshotter/tree/master/client/config/crd) must be installed **before** the FSx for OpenZFS CSI driver. For installation instructions, see [CSI Snapshotter Usage](https://github.com/kubernetes-csi/external-snapshotter#usage).
 
 ## Installation
 ### Set up driver permissions
-The driver requires IAM permissions to interact with the Amazon FSx for OpenZFS service to create/delete file systems, volumes, and snapshots on user's behalf. 
+The driver requires IAM permissions to interact with the Amazon FSx for OpenZFS service to create/delete file systems, volumes, and snapshots on the user's behalf. 
 There are several methods to grant the driver IAM permissions:
-* Using [IAM roles for ServiceAccounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) (**Recommended**) - Create a Kubernetes service account for the driver and attach the AmazonFSxFullAccess AWS-managed policy to it with the following command. If your cluster is in the AWS GovCloud Regions, then replace arn:aws: with arn:aws-us-gov. Likewise, if your cluster is in the AWS China Regions, replace arn:aws: with arn:aws-cn:
+* Using [IAM roles for ServiceAccounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) (**Recommended**) - Create a Kubernetes service account for the driver and attach the AmazonFSxFullAccess AWS-managed policy to it with the following command. If your cluster is in the AWS GovCloud Regions, then replace arn:aws: with arn:aws-us-gov. Likewise, if your cluster is in the AWS China Regions, replace arn:aws: with arn:aws-cn.
 ```sh
 eksctl create iamserviceaccount \
     --name fsx-openzfs-csi-controller-sa \
@@ -74,10 +73,10 @@ See [here](https://docs.aws.amazon.com/eks/latest/userguide/create-node-role.htm
 ```
 
 ### Configure driver toleration settings
-By default, the driver controller tolerates taint `CriticalAddonsOnly` and has `tolerationSeconds` configured as `300`. 
-Additionally, the driver node tolerates all taints. 
-If you do not wish to deploy the driver node on all nodes, please set Helm `Value.node.tolerateAllTaints` to false before deployment. 
-Add policies to `Value.node.tolerations` to configure customized toleration for nodes.
+By default, the driver controller pod tolerates taint `CriticalAddonsOnly` and has `tolerationSeconds` configured as `300`. 
+Additionally, the driver node pod tolerates all taints. 
+If you do not wish to deploy the driver node pod on all nodes, please set Helm `Value.node.tolerateAllTaints` to false before deployment. 
+You may then add policies to `Value.node.tolerations` to configure customized tolerations for nodes.
 
 ### Configure node startup taint
 There are potential race conditions on node startup (especially when a node is first joining the cluster) 
@@ -92,7 +91,7 @@ kubectl taint nodes $NODE_NAME fsx.openzfs.csi.aws.com/agent-not-ready:NoExecute
 ```
 Note that any effect will work, but `NoExecute` is recommended. 
 
-For example, EKS Managed Node Groups [support automatically tainting nodes](https://docs.aws.amazon.com/eks/latest/userguide/node-taints-managed-node-groups.html).
+EKS Managed Node Groups support automatically tainting nodes, see [here](https://docs.aws.amazon.com/eks/latest/userguide/node-taints-managed-node-groups.html) for more details.
 
 ### Deploy driver
 You may deploy the FSx for OpenZFS CSI driver via Kustomize or Helm

docs/options.md

@@ -1,5 +1,5 @@
 # Driver Options
-There are several driver options that can be passed as arguments when deploying the driver.
+There are several driver options that may be passed as arguments when deploying the driver.
 
 | Option argument             | value sample                                      | default                                             | Description                                             |
 |-----------------------------|---------------------------------------------------|-----------------------------------------------------|---------------------------------------------------------|

docs/parameters.md

@@ -4,22 +4,22 @@ The AWS FSx for OpenZFS CSI Driver supports the dynamic provisioning of both FSx
 To do this, the driver accepts **TWO** forms of storage classes: one for provisioning new file systems, and one for provisioning new volumes.
 A universal `ResourceType` parameter denotes which type of resource is being provisioned.
 
-The parameters that can be inputted to the storage class depends on the respective create and delete APIs.
+The parameters that can be inputted to the storage class depend on the respective create and delete APIs.
 Parameters under key `OpenZFSConfiguration` are flattened as top layer parameters.
 Parameter values should be in JSON format, excluding the CSI specific `ResourceType` parameter which is a plain string.
 Mistakes in parameters such as incorrect keys or values will produce errors.
-Delete parameters must include the suffix `OnDeletion` on the parameter name.
+Delete parameters must include the suffix `OnDeletion` in the parameter name.
 Some fields are populated by the CSI driver, and therefore should not be specified.
 
 ## File System Parameters
 
 ###### [FSx CreateFileSystem API](https://docs.aws.amazon.com/fsx/latest/APIReference/API_CreateFileSystem.html)
 ###### [FSx DeleteFileSystem API](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DeleteFileSystem.html)
 
-#### Parameters the driver populates
+#### Parameters the driver populates for the user (these are NOT defined in the storage class)
 - ClientRequestToken
 - FileSystemType
-- StorageCapacity
+- StorageCapacity (pulled from the PVC)
 
 Parameters a user can specify when provisioning an FSx OpenZFS file system:
 
@@ -47,7 +47,7 @@ Parameters a user can specify when provisioning an FSx OpenZFS file system:
 ###### [FSx CreateVolume API](https://docs.aws.amazon.com/fsx/latest/APIReference/API_CreateVolume.html)
 ###### [FSx DeleteVolume API](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DeleteVolume.html)
 
-#### Parameters the driver populates
+#### Parameters the driver populates for the user (these are NOT defined in the storage class)
 - ClientRequestToken
 - Name
 - VolumeType
@@ -73,7 +73,7 @@ Parameters a user can specify when provisioning an FSx OpenZFS volume:
 
 ###### [FSx CreateSnapshot API](https://docs.aws.amazon.com/fsx/latest/APIReference/API_CreateSnapshot.html)
 
-#### Parameters the driver populates
+#### Parameters the driver populates for the user (these are NOT defined in the storage class)
 - ClientRequestToken
 - Name
 - VolumeId

docs/tagging.md

@@ -1,25 +1,27 @@
 # Tagging
-Alongside tags a user defines, the CSI driver adds additional tags.
-The types of tags the CSI driver adds includes driver and deletion tags.
+The FSx for OpenZFS CSI driver automatically configures particular tags on FSx resources, in addition to user-provided tags.
+
+This includes a general tag added to all dynamically created FSx resources, 
+as well as deletion tags that are utilized to support deletion options.
 
 ## Driver Tags
 
-The FSx for OpenZFS CSI driver will automatically add unique tag(s) to denote the resources it manages.
-These tags are not used by the driver, and is only for aiding the user in resource management.
+The FSx for OpenZFS CSI driver will automatically add a unique tag to denote the resources it creates.
+This tag is not used by the driver and is only provided to aid the user in resource management.
 
-The CSI driver attaches the following tag(s) to resources created:
+The CSI driver attaches the following tag to the resources it creates:
 
-| Key                             | Value                       | Description                                     |
-|---------------------------------|-----------------------------|-------------------------------------------------|
-| fsx.openzfs.csi.aws.com/cluster | true                        | Attached to all FSx OpenZFS resources created.  |                                                                                      |
+| Key                             | Value                       | Description                                               |
+|---------------------------------|-----------------------------|-----------------------------------------------------------|
+| fsx.openzfs.csi.aws.com/cluster | true                        | Attached to all FSx OpenZFS resources the driver creates. |                                                                                      |
 
 ## Deletion Tags
 
 The CSI driver also adds deletion parameters that were provided by the user.
-Due to CSI limitations, parameters can't be defined when deleting resources.
-To get around this, any parameter specified with the `OnDeletion` suffix is saved as a Key-Value pair.
+Due to CSI limitations, parameters cannot be defined when deleting resources.
+To get around this, any parameter specified with the `OnDeletion` suffix is saved as a tag on the resource via a Key-Value pair.
 
-Due to restriction in tags, special characters used in JSON such as `",[]{}` must be encoded.
+Due to restrictions in tags, special characters used in JSON such as `",[]{}` must be encoded.
 The following chart contains the translation between JSON characters and their respective tag representation.
 To prevent mistranslation when decoding parameters that contain translate characters, a space is added before and after the tag representation.
 
@@ -37,11 +39,11 @@ To prevent mistranslation when decoding parameters that contain translate charac
 
 JSON Representation:
 ```json
-[{"Key": "OPENZFS", "Value": "OPENZFS"}]
+["DELETE_CHILD_VOLUMES_AND_SNAPSHOTS"]
 ```
 Tag Representation:
 ```
- -  +  @ Key @ :  @ OPENZFS @  .  @ Value @ :  @ OPENZFS @  =  _ 
+- @ DELETE_CHILD_VOLUMES_AND_SNAPSHOTS @ _
 ```
 
 Deletion tags may be manually modified or added to change the delete behavior for a specific resource.