Merge pull request #56 from gomesjason/docs

Update Parameters Doc with MAZ Parameters

Author: k8s-ci-robot

README.md

@@ -50,7 +50,7 @@ This policy is non-binding and subject to change.
 The FSx for OpenZFS CSI Driver is compatible with Kubernetes versions v1.17+ and implements the CSI Specification v1.1.0.
 
 ### Documentation
-Please read the FAQ before using the FSx for OpenZFS CSI Driver.
+Please read the documentation below before using the FSx for OpenZFS CSI Driver.
 * [FAQ](docs/FAQ.md)
 * [Driver Installation](docs/install.md)
 * [Driver Launch Options](docs/options.md)

docs/FAQ.md

@@ -1,6 +1,8 @@
 # Frequently Asked Questions
 The purpose of this document is to answer questions surrounding the unique design decisions and limitations of the FSx for OpenZFS CSI Driver.
 
+## General
+
 ### What does it mean to provision an FSx for OpenZFS file system as a persistent volume in my cluster? What is actually mounted?
 In general, Persistent Volumes created with the "filesystem" `ResourceType` point at the file system's root volume.
 Dynamically provisioning a new FSx for OpenZFS file system as a Persistent Volume (PV) will create the FSx for OpenZFS file system resource,
@@ -9,41 +11,77 @@ of the PV will create an FSx for OpenZFS snapshot of the file system's root volu
 increasing the requested storage request on a PVC bound to a PV that points at an FSx for OpenZFS file system will increase the storage capacity
 of the overarching file system.
 
-### How do I request storage when dynamically provisioning a new FSx for OpenZFS volume as a persistent volume in my cluster?
-When dynamically provisioning a new FSx for OpenZFS volume, the FSx for OpenZFS CSI driver ignores the storage requested in the Persistent Volume Claim (PVC).
-Instead, the driver configures storage requirements via the storageCapacityReservation and storageCapacityQuota parameters, which are defined in the storage class.
-To minimize operator confusion, **the driver will fail to create a volume if the user specifies a value other than the default 1Gi**.
+## Parameters
 
-### What happens when I expand the size of my Persistent Volumes?
-You may expand the size of a PV bound to an FSx for OpenZFS file system by increasing the requested storage in the PVC.
-This will increase the size of the file system's storage capacity to the value requested in the PVC.
-Currently, there is no way to adjust the storage requirements of a PV bound to an FSx for OpenZFS volume via the CSI driver.
-To do this, you will need to update the volume via the [FSx API](https://docs.aws.amazon.com/cli/latest/reference/fsx/index.html#cli-aws-fsx) outside the context of your cluster.
-See [here](../examples/kubernetes/volume-expansion/README.md) for more details.
+### Why is SkipFinalBackupOnDeletion required by the CSI Driver, and not the API?
+The default behavior of the API is to set this value as false, which thus creates a resource after deletion.
+To prevent users from creating dangling resources that the driver doesn't maintain, we force users to input this value.
 
 ### What happens if I do not provide a particular parameter in the Storage Class? What if I provide an invalid parameter?
 If you fail to provide a required parameter on the storage class or provide an invalid parameter, any attempted creates using that storage class will fail.
 The FSx for OpenZFS CSI driver will provide relevant logging detailing the failure mode/reason on the PVC or in the plugin logging.
 If you fail to provide an optional parameter in the storage class, the driver will use the default value specified in the [FSx API](https://docs.aws.amazon.com/cli/latest/reference/fsx/index.html#cli-aws-fsx).
 
 ### How strict is the parameter validation for the parameters provided in the Storage Class?
-The parameter validation conducted by the FSx for OpenZFS CSI driver is as strict as the [FSx API](https://docs.aws.amazon.com/cli/latest/reference/fsx/index.html#cli-aws-fsx). 
-This means that incorrectly spelled parameters and incorrectly formatted parameter values will cause the creation to fail. 
+The parameter validation conducted by the FSx for OpenZFS CSI driver is as strict as the [FSx API](https://docs.aws.amazon.com/cli/latest/reference/fsx/index.html#cli-aws-fsx).
+This means that incorrectly spelled parameters and incorrectly formatted parameter values will cause the creation to fail.
 Additionally, parameter values must exactly match the enums specified in the FSx API.
 
+### Can I modify parameters defined in the StorageClass after a resource is created?
+Unfortunately there is no way to modify these parameters due to the nature of the CSI driver.
+If a user wishes to modify a particular parameter, they may do so manually, using our API.
+This includes parameters such as ThroughputCapacity, StorageCapacityReservation, and StorageCapacityQuota.
+
+### Why are the parameters formatted the way they are?
+FSx for OpenZFS shares its API with other types in the FSx family.
+Because of this, most configuration options are nested under an `OpenZFSConfiguration` object.
+Since this driver is not shared, we decided it would be best to flatten this object at the top level to enhance readability.
+Due to the complex nature of our configurations, we also decided it would be best to align with our API and by requiring parameter values be in JSON format.
+
+## Storage Capacity
+
+### Why must I set storage on a PersistentVolumeClaim to 1 for volumes?
+FSx for OpenZFS allows users to set StorageCapacityReservation and StorageCapacityQuota which can impact the storage requirements of a given volume.
+There is truly no one size fits all, as there are different requirements based on use case.
+Because of this, we decided to ignore the storage value is when creating the volume, and instead have users utilize the StorageClass parameters.
+To minimize operator confusion, and to keep the door open for possible changes, **the driver will fail to create or modify a volume if the user specifies a value other than 1Gi**.
+
+## Volume Expansion
+
+### Can I expand the storage capacity of my filesystem?
+You may expand the size of a PV bound to an FSx for OpenZFS file system by increasing the requested storage in the PVC.
+This will increase the size of the file system's storage capacity to the value requested in the PVC.
+Currently, there is no way to adjust the storage requirements of a PV bound to an FSx for OpenZFS volume via the CSI driver.
+
+### Why can't I decrease the storage capacity of my filesystem? Why must I increase the capacity by at least 10%?
+These requirements set by the API.
+See this [document](https://docs.aws.amazon.com/fsx/latest/OpenZFSGuide/managing-storage-capacity.html) for more information.
+
+## Snapshots
+
+### When I take a snapshot, what FSx resource is created?
+When you take a snapshot, the CSI driver will take an FSx Snapshot.
+Snapshots occur at the volume level.
+If you take a snapshot of a filesystem, it will occur on the root volume of that filesystem.
+Therefore, when restoring snapshots, they must be restored as a volume type.
+
+### Can I take an FSx backup using the CSI Driver?
+Currently, there is no way to take an FSx backup of a filesystem using the driver.
+Any backups must be manually created and deleted using the API.
+There is also no way to dynamically create a filesystem from a backup.
+
+## Deletion Parameters
+
 ### How do I configure deletion parameters on my Persistent Volumes?
-Due to limitations in the CSI specification, there is no way to configure deletion parameters for PVs at deletion time. 
-As such, you will only be able to configure deletion parameters at creation time. This may be done by setting 
-`skipFinalBackupOnDeletion` and `optionsOnDeletion` on the storage class manifests; see [parameters.md](parameters.md) for more information.
-These deletion parameters are configured by applying tags on the underlying FSx resource. 
-If you wish to revise the deletion behavior of the volume after creation, you will need to edit these tags on the FSx resource. 
+Due to limitations in the CSI specification, there is no way to configure deletion parameters for PVs at deletion time.
+Therefore, we allow users to input these parameters in the StorageClass during initialization.
+See [parameters.md](parameters.md) for information on setting these parameters.
+
+### How do I edit a deletion parameter after my resource is already created?
+Deletion parameters are saved by applying a tag for each parameter on the underlying FSx resource.
+If you wish to revise deletion behavior after creation, you will need to manually edit these tags.
 This will need to be done outside the context of the CSI driver.
 If the these tags are missing from the underlying FSx for OpenZFS resource or the tag does not have a valid value, 
 the driver will use the default behavior specified in the [FSx API](https://docs.aws.amazon.com/cli/latest/reference/fsx/index.html#cli-aws-fsx).
 Deletion parameters with JSON special characters `"[]{},` are encoded due to [AWS tagging limitations](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html#tag-conventions).
 See [tagging](tagging.md) for more details.
-
-### Is there a way to tag FSx resources created via the CSI driver?
-The AWS FSx for OpenZFS CSI Driver supports tagging via the `StorageClass.parameters` and `VolumeSnapshotClass.parameters`.
-Any resource created by the FSx for OpenZFS CSI driver is provided default tags to allow you to track which 
-FSx resources were created via the CSI driver. See [tagging](tagging.md) for more details.

docs/debugging.md

@@ -0,0 +1,29 @@
+# Debugging
+
+## Dynamic Provisioning
+
+### Why isn't the driver dynamically provisioning my resource?
+Typically, this is due to syntax or request errors based on the parameters provided in the StorageClass.
+Run `kubectl get pods -n kube-system` and `kubectl logs ${driver_leader} -n kube-system` to grab the driver's logs.
+These logs should output the cause of failure.
+
+### Why is the driver throwing an error for a parameter that is correct?
+Double check you are using the most up-to-date driver version.
+If you are, the driver's SDK version may be outdated.
+Please cut a ticket for us to bump the SDK version, as it will allow the driver to pull any API changes.
+
+## Mounting
+
+### Why can't I mount my resource?
+Typically, this is due to a network or environmental issue.
+Verify that the DNS is reachable from your pod.
+Double check that filesystem lives in the same VPC as your cluster, the security group policy allow ingress NFS traffic, and the route tables are associated with the cluster's subnets.
+See this [document](https://docs.aws.amazon.com/fsx/latest/OpenZFSGuide/access-within-aws.html) for more information.
+
+## Maintenance
+
+### How do I know what resources in my account are maintained by the driver?
+Any resource created by the FSx for OpenZFS CSI driver is given tag.
+Assuming these tags are not manually changes, you can find all resources under your account using this [hack](../hack/print-resources).
+See [tagging](tagging.md) for more details.
+ 

docs/install.md

@@ -114,6 +114,7 @@ helm repo update
 ```sh
 helm upgrade --install aws-fsx-openzfs-csi-driver \
     --namespace kube-system \
+    --set controller.serviceAccount.create=false \
     aws-fsx-openzfs-csi-driver/aws-fsx-openzfs-csi-driver
 ```