Merge pull request #86077 from pohly/external-docs

e2e storage: improve instructions for external driver testing

test/e2e/storage/external/README.md

@@ -1,25 +1,29 @@
 When a test suite like test/e2e/e2e.test from Kubernetes includes this
-package, the -storage.testdriver parameter can be used one or more
+package, the `-storage.testdriver` parameter can be used one or more
 times to enabling testing of a certain pre-installed storage driver.
 
 The parameter takes as argument the name of a .yaml or .json file. The
-filename can be absolute or relative to --repo-root. The content of
+filename can be absolute or relative to `--repo-root`. The content of
 the file is used to populate a struct that defines how to test the
-driver. For a full definition of the struct see the external.go file.
+driver. For a full definition of the content see:
+- `struct driverDefinition` in [external.go](./external.go)
+- `struct TestDriver` and the `Cap` capability constants in [testdriver.go](../testsuites/testdriver.go)
 
-Here is an example for the CSI hostpath driver:
+Here is a minimal example for the CSI hostpath driver:
 
-    ShortName: mytest
     StorageClass:
       FromName: true
     SnapshotClass:
       FromName: true
     DriverInfo:
-      Name: csi-hostpath
+      Name: hostpath.csi.k8s.io
       Capabilities:
         persistence: true
-        dataSource: true
+
-        multipods: true
+The `prow.sh` script of the different CSI hostpath driver releases
+generates the actual definition that is used during CI testing, for
+example in
+[v1.2.0](https://github.com/kubernetes-csi/csi-driver-host-path/blob/v1.2.0/release-tools/prow.sh#L748-L763).
 
 Currently there is no checking for unknown fields, i.e. only file
 entries that match with struct entries are used and other entries are

test/e2e/storage/external/external.go

@@ -39,6 +39,77 @@ import (
 	"github.com/onsi/ginkgo"
 )
 
+// DriverDefinition needs to be filled in via a .yaml or .json
+// file. Its methods then implement the TestDriver interface, using
+// nothing but the information in this struct.
+type driverDefinition struct {
+	// DriverInfo is the static information that the storage testsuite
+	// expects from a test driver. See test/e2e/storage/testsuites/testdriver.go
+	// for details. The only field with a non-zero default is the list of
+	// supported file systems (SupportedFsType): it is set so that tests using
+	// the default file system are enabled.
+	DriverInfo testsuites.DriverInfo
+
+	// StorageClass must be set to enable dynamic provisioning tests.
+	// The default is to not run those tests.
+	StorageClass struct {
+		// FromName set to true enables the usage of a storage
+		// class with DriverInfo.Name as provisioner and no
+		// parameters.
+		FromName bool
+
+		// FromFile is used only when FromName is false.  It
+		// loads a storage class from the given .yaml or .json
+		// file. File names are resolved by the
+		// framework.testfiles package, which typically means
+		// that they can be absolute or relative to the test
+		// suite's --repo-root parameter.
+		//
+		// This can be used when the storage class is meant to have
+		// additional parameters.
+		FromFile string
+	}
+
+	// SnapshotClass must be set to enable snapshotting tests.
+	// The default is to not run those tests.
+	SnapshotClass struct {
+		// FromName set to true enables the usage of a
+		// snapshotter class with DriverInfo.Name as provisioner.
+		FromName bool
+
+		// TODO (?): load from file
+	}
+
+	// InlineVolumes defines one or more volumes for use as inline
+	// ephemeral volumes. At least one such volume has to be
+	// defined to enable testing of inline ephemeral volumes.  If
+	// a test needs more volumes than defined, some of the defined
+	// volumes will be used multiple times.
+	//
+	// DriverInfo.Name is used as name of the driver in the inline volume.
+	InlineVolumes []struct {
+		// Attributes are passed as NodePublishVolumeReq.volume_context.
+		// Can be empty.
+		Attributes map[string]string
+		// Shared defines whether the resulting volume is
+		// shared between different pods (i.e.  changes made
+		// in one pod are visible in another)
+		Shared bool
+		// ReadOnly must be set to true if the driver does not
+		// support mounting as read/write.
+		ReadOnly bool
+	}
+
+	// SupportedSizeRange defines the desired size of dynamically
+	// provisioned volumes.
+	SupportedSizeRange volume.SizeRange
+
+	// ClientNodeName selects a specific node for scheduling test pods.
+	// Can be left empty. Most drivers should not need this and instead
+	// use topology to ensure that pods land on the right node(s).
+	ClientNodeName string
+}
+
 // List of testSuites to be executed for each external driver.
 var csiTestSuites = []func() testsuites.TestSuite{
 	testsuites.InitEphemeralTestSuite,
@@ -142,77 +213,6 @@ var _ testsuites.EphemeralTestDriver = &driverDefinition{}
 // an implementation.
 var _ runtime.Object = &driverDefinition{}
 
-// DriverDefinition needs to be filled in via a .yaml or .json
-// file. It's methods then implement the TestDriver interface, using
-// nothing but the information in this struct.
-type driverDefinition struct {
-	// DriverInfo is the static information that the storage testsuite
-	// expects from a test driver. See test/e2e/storage/testsuites/testdriver.go
-	// for details. The only field with a non-zero default is the list of
-	// supported file systems (SupportedFsType): it is set so that tests using
-	// the default file system are enabled.
-	DriverInfo testsuites.DriverInfo
-
-	// StorageClass must be set to enable dynamic provisioning tests.
-	// The default is to not run those tests.
-	StorageClass struct {
-		// FromName set to true enables the usage of a storage
-		// class with DriverInfo.Name as provisioner and no
-		// parameters.
-		FromName bool
-
-		// FromFile is used only when FromName is false.  It
-		// loads a storage class from the given .yaml or .json
-		// file. File names are resolved by the
-		// framework.testfiles package, which typically means
-		// that they can be absolute or relative to the test
-		// suite's --repo-root parameter.
-		//
-		// This can be used when the storage class is meant to have
-		// additional parameters.
-		FromFile string
-	}
-
-	// SnapshotClass must be set to enable snapshotting tests.
-	// The default is to not run those tests.
-	SnapshotClass struct {
-		// FromName set to true enables the usage of a
-		// snapshotter class with DriverInfo.Name as provisioner.
-		FromName bool
-
-		// TODO (?): load from file
-	}
-
-	// InlineVolumes defines one or more volumes for use as inline
-	// ephemeral volumes. At least one such volume has to be
-	// defined to enable testing of inline ephemeral volumes.  If
-	// a test needs more volumes than defined, some of the defined
-	// volumes will be used multiple times.
-	//
-	// DriverInfo.Name is used as name of the driver in the inline volume.
-	InlineVolumes []struct {
-		// Attributes are passed as NodePublishVolumeReq.volume_context.
-		// Can be empty.
-		Attributes map[string]string
-		// Shared defines whether the resulting volume is
-		// shared between different pods (i.e.  changes made
-		// in one pod are visible in another)
-		Shared bool
-		// ReadOnly must be set to true if the driver does not
-		// support mounting as read/write.
-		ReadOnly bool
-	}
-
-	// SupportedSizeRange defines the desired size of dynamically
-	// provisioned volumes.
-	SupportedSizeRange volume.SizeRange
-
-	// ClientNodeName selects a specific node for scheduling test pods.
-	// Can be left empty. Most drivers should not need this and instead
-	// use topology to ensure that pods land on the right node(s).
-	ClientNodeName string
-}
-
 func (d *driverDefinition) DeepCopyObject() runtime.Object {
 	return nil
 }