FSXSet is a Kubernetes CRD for managing FSX clients. It can manage client deployment, versions, and upgrade policies by node group. This is suitable for scenarios requiring differentiated configurations, on‑demand creation, and client upgrades. This topic describes the basic concepts and configurations of FSXSet resources.

Resource overview

FSXSet is a cluster‑level Kubernetes CRD that performs centralized lifecycle management on FSX clients, such as creation, deletion, and hot upgrades. In addition, you can create one or more FSXSet objects to control the configurations of FSX clients on different nodes, such as resource specifications, image versions, and upgrade methods. FSXSet meets the requirements of the following scenarios:

Smooth node-level canary upgrade: You can create differentiated FSXSet configurations as needed and apply them only to a few designated test nodes. After validation, the new version can be rolled out to the entire cluster to achieve controllable canary hot upgrades.

Custom configurations for heterogeneous nodes: You can specify different FSXSet configurations for different node pools. For example, for AI‑compute node pools, you can increase the CPU/memory quotas for the client. For idle nodes, you can enable automatic cleanup policies to reclaim resources.

Core feature

FSXSet provides the following core features for managing FSX clients.

Core feature	Description	Related documentation
Node grouping and on‑demand management	Use the node label fsx.csi.volcengine.com/group to divide nodes into logical groups so that different FSX client configurations can be applied to different groups. Different FSX client creation modes are supported, including Immediate (clients created immediately after nodes join groups) and WaitForFirstConsumer (clients created on‑demand). Select an appropriate mode flexibly based on your business requirements. On‑demand automatic reclamation is supported to release node resources. This applies to resource-constrained scenarios. Persistent client deployment is supported to accelerate the first mount.	Using FSXSet to implement on-demand client creation
Differentiated configuration	Create multiple FSXSet resources to configure differentiated Pod specifications (such as CPU, memory, and network resources) for different node groups. For example, assign different FSX client configurations to nodes with varying specifications in the cluster. Use parameterTemplate to flexibly define FSX client templates.	Using FSXSet to implement differentiated configurations for clients
Hot upgrade	The rolling upgrade and canary upgrade policies are supported. You can trigger upgrades by modifying the image field in FSXSet. The controller automatically orchestrates the transition between old and new Pods. maxSurge and maxUnavailable are supported to control upgrade concurrency.	Using FSXSet to implement smooth client upgrades

Description

When you install the fsxset-controller add-on in a cluster, the system will automatically install FSXSet custom resources. For details, see fsxset-controller. You can view or configure the corresponding FSXSet resources by using the following methods.

Configure through the console

Configure through kubectl

Log in to the VKE console.

In the left navigation bar, click Cluster. Click the target cluster name to go to the management page of this cluster.

In the left navigation pane, select Addons and click the Storage tab.

In the lower-right corner of the csi-fsx add-on card, click ... > Client configuration.

In the Client configuration panel, view the FSXSet resources in the cluster.

Find the target resource and click Update in the Actions column to view or update the FSXSet resource.

tip

To configure additional features, go to Workload > Resource Explorer to view or modify the YAML file of the FSXSet resources.

The following sample code shows how to view or configure FSXSet resources.

The following table describes the key parameters of FSXSet resources.

Type	Parameter	Required	Description
Basic	metadata.name	Yes	The FSXSet resource name. It needs to be unique within the same cluster.
		spec.groupName	No	The logical group name, which corresponds to the node label fsx.csi.volcengine.com/group. The system selects nodes on which to apply this FSXSet configuration based on this name. This achieves differentiated client configuration. This parameter cannot be left empty. If this parameter is not specified, the system uses the default FSXSet configuration named default. tip For example, if this parameter is set to doc, the current FSXSet configuration will be applied to only nodes with the node label fsx.csi.volcengine.com/group=doc. For details, see Using FSXSet to implement client-differentiated configuration.
		spec.isDefault	No	Whether it is the cluster default FSXSet, which is used to take over nodes that do not match any other grouping rules. true: It is the cluster default FSXSet. false: (Default) It is not the cluster default FSXSet. tip Only one resource object with isDefault set to true can exist in the cluster. If this parameter is not configured, the default value is false. This indicates that it is not the system default FSXSet.
Management policy	spec.createMode	No	The FSX client creation mode. Immediate: The FSX client is created immediately after the target node is assigned to a resource group. WaitForFirstConsumer: (Default) The FSX client is created only when a workload that depends on FSX is first deployed on the target node. Note If this parameter is set to Immediate, scaleDownAfterNoDependency cannot be set to true.
		spec.scaleDownAfterNoDependency	No	Whether to automatically reclaim FSX client Pods when no workloads depend on FSX on the node. true: Automatically reclaim FSX client Pods. This is suitable for scenarios where idle resource usage needs to be reduced. false: (Default value) Do not automatically reclaim FSX client Pods. In this mode, the first mount of the ECS instance is faster. Note If this parameter is set to true, createMode cannot be set to Immediate.
		spec.scaleDownAfterIdleDuration	No	The idle wait duration before automatic reclamation of FSX client Pods. The value is a string that uses Go duration format. Supported units include s, m, and h. For example, 5m means 5 minutes. The default value is 3m if this parameter is not specified.
		spec.upgradeStrategy.type	No	The upgrade policy of the FSX client. RollingUpdate: Rolling upgrade. OnLabel: Canary or rotation upgrade. warning For the steps and considerations of the FSX client upgrade, see Upgrading FSX clients. In the system‑created default FSXSet resource (named default), the default value of this parameter is OnLabel. In user‑created FSXSet resources, the default value of this parameter is RollingUpdate.
		spec.upgradeStrategy.maxSurge	No	The number of additional Pods that can be temporarily created during a rolling upgrade. This parameter is required only if spec.upgradeStrategy.type is set to RollingUpdate. The value is an integer. Default value: 1. When the value is set to 0, the system does not create new Pods. Instead, it deletes the old Pods first. This does not consume extra resources, but each node may experience a brief interruption during the transition.
		spec.upgradeStrategy.maxUnavailable	No	The maximum number of nodes that can be unavailable simultaneously during a rolling upgrade. For example, the value 1 indicates that only one node is upgraded each time. This parameter is required only if spec.upgradeStrategy.type is set to RollingUpdate. The default value is 1 if this parameter is not specified.
Client configuration	template.parameterTemplate.image	Yes	The image address and version of the FSX client. warning In RollingUpdate mode, modifying the image version directly triggers an upgrade of the FSX client. You can obtain the supported image addresses and versions from the add-on configuration page. For details, see csi-fsx.
		template.parameterTemplate.resources	No	The resource quotas for the FSX client Pod. If this parameter is not specified, the global default configuration is used.
		template.parameterTemplate.hostWorkDirectory	No	The working directory on the host for the FSX client. This is used for storing caches and temporary files and is mounted to /tmp/fsx in the container. In the system‑created default FSXSet resource (named default), the cacheDirectory configuration of the controller is inherited, which is /tmp/fsx by default. In user‑created FSXSet resources, if this parameter is not specified, this directory will not be mounted.

Volcengine Kubernetes Engine