StorageCluster CRD reference

The Portworx CSI cluster configuration is defined by a Kubernetes CustomResourceDefinition (CRD) called StorageCluster. This object specifies the Portworx Cluster.

The StorageCluster object offers a Kubernetes-native experience, allowing you to manage your Portworx cluster like any other Kubernetes application. When you create or modify the StorageCluster object, the Operator will automatically create or update the Portworx cluster in the background.

To generate a StorageCluster specification tailored to your environment, visit Portworx Central and click Install and Run. This will launch the Portworx specification generator, which will guide you through the steps to create a customized StorageCluster specification.

Using the Portworx specification generator is the recommended method for generating a StorageCluster specification. If you prefer to create the specification manually, refer to the StorageCluster Schema section.

StorageCluster schema

This section explains the fields used to configure the StorageCluster object.

Field	Description	Type	Default
spec.image	Specifies the Portworx monitor image.	string	None
spec.imagePullPolicy	Specifies the image pull policy for all the images deployed by the operator. It can take one of the following values: Always or IfNotPresent	string	Always
spec.imagePullSecret	If Portworx pulls images from a secure repository, you can use this field to pass it the name of the secret. Note that the secret should be in the same namespace as the StorageCluster object.	string	None
spec.customImageRegistry	The custom container registry server Portworx uses to fetch the Docker images. You may include the repository as well.	string	None
spec.env[]	A list of Kubernetes like environment variables. Similar to how environment variables are provided in Kubernetes, you can directly provide values to Portworx or import them from a source like a Secret, ConfigMap, etc.	[]object	None
spec.metadata.annotations	A map of components and custom annotations.	map[string]map[string]string	None
spec.metadata.labels	A map of components and custom labels.	map[string]map[string]string	None
spec.priorityClassName	Specifies the name of the PriorityClass to use for controller plugin pods and node plugin pods. This setting controls the scheduling priority and preemption behavior of Container Storage Interface (CSI) pods relative to other pods in the cluster. Pods with a higher priority are scheduled before lower-priority pods and can preempt lower-priority pods when resources are constrained. For more information, see Kubernetes PriorityClass documentation.	string	None

Monitoring configuration

This section provides details on how to enable monitoring for Portworx.

Field	Description	Type	Default
spec.monitoring.telemetry.enabled	Enables sending telemetry data to Pure1.	boolean	false
spec.monitoring.prometheus.enabled	Deploys the Prometheus Operator and Prometheus instance to collect metrics. Set to true to deploy the monitoring stack on standard Kubernetes. On OpenShift, set to false to use the OpenShift-managed Prometheus instance.	boolean	false
spec.monitoring.prometheus.exportMetrics	Exports PX-CSI metrics to Prometheus by creating ServiceMonitor resources. Set to true to enable Prometheus (either PX-CSI deployed or external, such as OpenShift Prometheus) to scrape PX-CSI metrics.	boolean	false

CSI configuration

This section provides details on how to configure CSI for the StorageCluster. Note this is for Operator 1.8 and higher only.

Field	Description	Type	Default
spec.csi.enabled	Flag indicating whether CSI needs to be installed for the storage cluster.	boolean	true
spec.csi.installSnapshotController	Flag indicating whether CSI Snapshot Controller needs to be installed for the storage cluster.	boolean	false

Node specific configuration

This section provides details on how to override certain cluster level configuration for individual or group of nodes.

Field	Description	Type	Default
spec.nodes[]	A list of node specific configurations.	[]object	None
spec.nodes[].selector	Selector for the node(s) to which the configuration in this section will be applied.	object	None
spec.nodes[].selector.nodeName	Name of the node to which this configuration will be applied. Node name takes precedence over selector.labelSelector.	string	None
spec.nodes[].selector.labelSelector	Kubernetes style label selector for nodes to which this configuration will be applied.	object	None
spec.nodes[].env	Specify extra environment variables for the selected nodes. Cluster level environment variables are combined with these and sent to the selected nodes. If same variable is present at cluster level, then the node level variable takes precedence.	object	None

Environment variables

This section provides configuration details for setting FlashArray and FlashBlade environment variables. All fields are objects under the spec.env[] list:

Name	Value	Type	Default
PURE_ISCSI_ALLOWED_CIDRS	Use this when the FlashArray has multiple iSCSI network interfaces with different subnets and you need to connect to a specific subnet. Separate multiple entries with commas—for example, 10.0.0.0/24,10.1.0.0/16. An empty string connects to all enabled iSCSI interfaces.	string	"" (empty string)
PURE_NVME_ALLOWED_CIDRS	Use this when the FlashArray has multiple NVMe network interfaces with different subnets and you need to connect to a specific subnet. Use commas as the separator, e.g. 10.0.0.0/24,10.1.0.0/16. An empty string connects to all enabled NVMe interfaces.	string	"" (empty string)
NODE_STAGE_CONCURRENCY	Use this to control how many NodeStageVolume operations the CSI driver can process concurrently on a single node.	string	"25"
PURE_FLASHARRAY_SAN_TYPE	Specifies the SAN transport protocol that Portworx CSI uses to communicate with FlashArray. Supported values are ISCSI, NVMEOF-TCP, NVMEOF-RDMA, and FC.	string	"ISCSI"
PURE_ISCSI_ALLOWED_IFACES	Restricts iSCSI sessions to specific network interfaces on the host. Use commas to separate multiple interface names, for example, eth0,eth1. An empty string allows all interfaces.	string	"" (empty string)
ENABLE_SUBNET_AWARE_ISCSI_LOGIN	Configures subnet-aware iSCSI login to ensure that each iSCSI initiator interface communicates only with FlashArray target interfaces within the same subnet. When set to true, PX-CSI limits iSCSI discovery and login to interfaces that share the same subnet, preventing cross-subnet communication. This is useful in environments with network policies that restrict cross-subnet connectivity. When set to false or unset, PX-CSI uses the default behavior and attempts to connect to all available iSCSI targets.	string	"false"
ENABLE_MULTIPATH_RECONCILER	Enables or disables the multipath reconciler for FlashArray volumes. The multipath reconciler periodically checks attached FlashArray volumes to make sure all expected multipath paths are active and healthy. This helps maintain optimal connectivity and automatically recovers from temporary path failures. Set to false to disable it. This setting is ignored for NVMe-oF volumes because the kernel manages multipath automatically.	string	Enabled by default (behaves as true when unset)

| PURE_DEVICE_PATH_TIMEOUT | Specifies the timeout in seconds for device path operations when discovering and connecting to FlashArray block devices. | string | "1" | | PURE_DEVICE_PATH_RETRIES | Specifies the number of retry attempts for device path operations when discovering and connecting to FlashArray block devices. | string | "10" | | PURE_REST_TIMEOUT | Specifies the timeout in seconds for REST API calls to FlashArray and FlashBlade management endpoints. | string | "8" | | PURE_PREEMPT_RWO_ATTACHMENTS_DEFAULT | If set to true, PX-CSI automatically preempts (forcefully detaches) ReadWriteOnce (RWO) volumes from one node when they need to be attached to another node. This is useful in pod rescheduling scenarios. If set to false, preemption must be explicitly requested. | string | "true" | | PURE_ATTACHMENT_PREEMPT_TIMEOUT | Specifies the timeout in seconds for volume attachment preemption operations. PX-CSI waits this long when attempting to detach a volume from one node before attaching it to another. | string | "15" | | PURE_MGMT_PORT_MAX_TIMEOUT_MINUTES | Specifies the maximum timeout in minutes, for management port operations when communicating with FlashArray and FlashBlade management endpoints. | string | "16" | | PURE_STATISTICS_CACHE_TTL | Specifies the time-to-live (TTL) for cached statistics from FlashArray and FlashBlade. Use duration format such as 15m, 1h, or 30s. A longer TTL reduces load on backend arrays. | string | "15m" | | PURE_PATH_TIMEOUT | Specifies the timeout in seconds for multipath operations when establishing paths to FlashArray devices. | string | "1" | | PURE_PATH_RETRIES | Specifies the number of retry attempts for multipath operations when establishing paths to FlashArray devices. | string | "10" | | PURE_CIRCUIT_BREAKER_RETRIES | Specifies the number of retry attempts before the circuit breaker opens and halts operations to a failing FlashArray or FlashBlade. This setting helps prevent cascading failures by temporarily stopping requests to unhealthy backends. | string | "10" | | PURE_CIRCUIT_BREAKER_TIMEOUT_SECONDS | Specifies the timeout in seconds before the circuit breaker attempts to close and resume operations to a previously failing FlashArray or FlashBlade. | string | "120" | | PX_LOGLEVEL| Controls the log verbosity level for the Portworx CSI driver. Use values such as error, warn, info, debug, or trace to adjust the logging detail. | string | "info" |

StorageCluster Annotations

Annotation	Description
portworx.io/misc-args	Arguments that you specify in this annotation are passed to portworx container verbatim. Note that you cannot use = to specify the value of an argument. Some of the arguments that you can specify in the annotation are listed below: --oem px-csi - Specifies that Portworx will be installed with the CSI FA/FB license, determining the type of build and license for the installation.
portworx.io/disable-storage-class	When applied to a StorageCluster object and set to true, this annotation instructs the Portworx Operator to disable and remove the default storage classes created during Portworx setup. For example: portworx.io/disable-storage-class: "true"
portworx.io/health-check	Annotation created by the Operator to save the state of the health checks. If the health checks pass, the Operator writes a value of passed. If the health checks fail, the Operator writes a value of failed and reruns the checks periodically. You can control the health checks manually by setting the value to skip to bypass the health checks, or removing the annotation to instruct the Operator to rerun the checks immediately.