文档中心

容器服务

FSX 访问方式

通过 FSX 客户端使用 TOS 静态存储卷

FSX 支持对接 TOS 文件系统，作为 TOS 高可用 POSIX 文件系统客户端。通过此客户端，可将 TOS 存储桶挂载到 Linux 系统，使得存储桶可以作为 Linux 系统的本地文件系统，实现数据的存储和管理。本文为您介绍如何通过 FSX 客户端使用 TOS 静态存储卷。

前提条件

已安装 csi-fsx 和 fsxset-controller 组件，并升级至最新版本。详情请参见 csi-fsx、fsxset-controller。

已创建 TOS 存储桶，详情请参见创建存储桶。

已完成存储卷挂载鉴权配置。详情请参见 FSX 鉴权方式。

AK/SK 鉴权：已创建密钥所需的 AK/SK，用于挂载 TOS 存储，账号 AK/SK 获取方法参见：如何获取 API 访问密钥。若使用临时 Token 鉴权，需要自主实现刷新 Token 的逻辑。

IRSA 鉴权：已开启 csi-fsx 组件的 IRSA 鉴权。详情请参见使用 IRSA 实现存储挂载鉴权。

（可选）若使用 YAML 配置，请确保已经在本地环境中安装 kubectl 工具，连接至目标集群。详情请参见连接集群。

使用限制

有状态负载需要独占一个卷，暂不支持使用手动创建的存储卷声明。

FSX 客户端当前仅支持 x86_64 的体系结构，暂不支持在 Windows 和 macOS 环境使用。详情请参见运行环境。

暂不支持 Kubernetes v1.20 及以下版本的集群使用。

若使用 Kubernetes v1.26.x 版本集群，禁止使用名称中带符号.的 Secret 密钥，否则会导致 PV 创建失败。

通过控制台配置

步骤一：创建存储卷（PV）

登录容器服务控制台。

在左侧导航栏中，选择集群。单击目标集群名称，进入集群管理页面。

在集群管理页面左侧导航栏中，选择存储管理 > 存储卷。

单击创建存储卷，创建 FSX 访问类型的 TOS 存储卷。

配置项	说明
创建方式	选择存储卷的创建方式，目前支持静态创建。
名称	根据系统提示，自定义存储卷的名称，需确保存储卷名称在集群内唯一。
存储类型	选择存储类型，本场景选择对象存储。
访问类型	存储卷的访问类型，本场景选择 FSX。 FSX：针对非结构化数据存储提供的统一文件访问客户端，支持标准 POSIX 语义。 S3FS：基于 FUSE 的文件系统，允许通过挂载方式把支持 S3 协议的对象存储服务当作本地文件系统来使用。注意 FSX 访问方式目前仅支持云服务器，不支持弹性容器。 FSX 访问方式的性能更强劲、可用性更高，将逐步替换 S3fs，详细说明参见：对象存储 CSI 能力升级说明。
访问模式	选择存储卷的访问方式，目前支持 ReadWriteMany，表示多点读写。
访问密钥	选择对象存储的访问密钥。当集群中的 csi-fsx 组件开启了 IRSA 鉴权（开启方式详见：使用 IRSA 实现存储挂载鉴权）时，访问密钥为非必填。该参数为空时，将使用 csi-fsx 组件关联的 IAM 角色进行鉴权。该参数填写后，鉴权优先级：PV 级别 Secret（如有）> 组件级别 IRSA（如有），都无则失败。当集群中的 csi-fsx 组件未开启 IRSA 鉴权时，访问密钥必填。使用此处指定的访问密钥，授权容器服务访问对象存储。若无可使用的访问密钥，请单击创建密钥，根据系统提示配置密钥名称、所属空间和 IAM 账号的 AK/SK。注意若使用 Kubernetes v1.26.x 版本集群，禁止使用名称中带符号.的 Secret 密钥，否则会导致 PV 创建失败。
服务端加密	勾选启用，开启 TOS 存储卷的服务端加密功能。允许在写入或读取数据时进行加密和解密。详情请参见加密 TOS 存储卷。
存储桶	选择对象存储中已创建的 TOS 存储桶。
子目录	配置存储桶子目录。说明建议填写已经存在的文件目录，否则系统将根据您填写的子目录，自动创建新的文件目录。
高级配置
挂载参数	TOS 存储卷挂载参数，支持动态修改，仅对新挂载的存储卷生效，对已挂载的存储卷不生效。详情请参见存储卷挂载参数。

单击确定，完成配置。

步骤二：创建存储卷声明（PVC）

单击目标集群名称，在集群管理页面选择存储管理 > 存储卷声明。

在存储卷管理页面，单击创建存储卷声明，配置 TOS 存储卷声明。

配置项	说明
命名空间	选择存储卷声明所属的命名空间。建议选择您自定义的命名空间，或系统默认创建的 default 命名空间。命名空间相关介绍，请参见命名空间概述。
名称	自定义存储卷声明的名称，需确保存储卷声明名称在集群内唯一。
存储类型	选择存储类型，本场景选择对象存储。
访问模式	选择存储卷声明的访问方式，目前支持 ReadWriteMany，表示多点读写。
计费类型	按需选择资源计费类型，目前仅支持按量计费。
存储卷	选择本文上方步骤创建的存储卷进行关联挂载。

单击确定，完成配置。

步骤三：创建应用并挂载存储卷

对象存储静态存储卷创建完成后，可通过添加卷的方式挂载到工作负载使用，包括：无状态负载、有状态负载、任务、定时任务、守护进程。

可通过创建工作负载或更新工作负载操作的容器配置步骤，为工作负载添加卷并挂载卷。详细操作参见：工作负载。

通过 kubectl 命令行配置

已经连接集群的情况下，可通过 kubectl 命令行使用 TOS 文件存储静态存储卷。

步骤一：（可选）创建策略

说明

若使用主账号 AK/SK，可跳过此步骤。

如需实现动态刷新临时 Token 的逻辑，参考 AssumeRole 接口。

创建策略的操作步骤参见新建自定义策略。其中，使用 IAM 用户挂载存储桶并执行相应操作时，所需的权限参见：挂载存储桶所需要的权限。

创建 TOS 策略的 Json 示例如下：

步骤二：（可选）创建保密字典（Secret）

说明

当 csi-fsx 组件开启 IRSA 鉴权时，可跳过该配置步骤。

创建 Secret 的 Yaml 文件vke-tos-fsx-secret.yaml，示例代码如下：

apiVersion: v1
kind: Secret
metadata:
name: tos-fsx-key # 保密字典名称。若使用 1.26.x 版本集群，名称中禁止使用符号.，其他版本不受影响
namespace: default # 保密字典所属命名空间
type: Opaque # 保密字典类型，本例中选择通用类型，存储任意键值对
data:
AccessKeyId: ${ak} # Base64 编码后的账号 AK，需要替换为真实信息
SecretAccessKey: ${sk} # Base64 编码后的账号 SK，与上述 AK 匹配，需要替换为真实信息
ExpiredTime: ${Temporary Token expiration time} # Base64 编码后的临时 Token 过期时间，如果使用账号 AK/SK，不需要指定
SessionToken: ${Temporary Token content} # Base64 编码后的临时 Token 内容，如果使用账号 AK/SK，不需要指定

说明

您可以使用echo -n "${ak}" | base64命令对 AK、SK 等进行 Base64 编码，请将${ak}替换为您自己的实际值。例如当${ak}取值为demo时，编码命令为echo -n "demo" | base64，编码后的值为ZGVtbw==。

执行以下命令，创建 Secret。

kubectl create -f vke-tos-fsx-secret.yaml

步骤三：创建存储卷（PV）

创建 PV 的 Yaml 文件文件vke-tos-fsx-static-pv.yaml，示例代码如下：

apiVersion: v1
kind: PersistentVolume
metadata:
name: vke-tos-fsx-static-pv
spec:
accessModes: # 存储卷访问方式，仅支持 ReadWriteMany，表示多点读写
- ReadWriteMany
capacity:
storage: 20Gi # 存储卷容量，单位为 Gi
csi:
driver: fsx.csi.volcengine.com # 存储挂载依赖的驱动
volumeAttributes:
type: TOS # 存储卷类型，本文中选择 TOS，表示对象存储
server: tos-cn-shanghai.ivolces.com # 已创建的 TOS 桶 Endpoint（地域节点），请勿填写为 Bucket 域名
region: cn-shanghai # 已创建的 TOS 存储桶所在地域，若 TOS 与集群所在地域相同，该配置项可省略
bucket: doc-tos-demo # 已创建的 TOS 存储桶名称
path: / # 指定 TOS 存储桶的根目录，请确保该目录存在，否则挂载会失败
secretName: tos-fsx-key # 与步骤二中 Secret 的名称保持一致。如果使用 IRSA 鉴权，该配置项可省略
secretNamespace: default # 与步骤二中 Secret 的命名空间保持一致。如果使用 IRSA 鉴权，该配置项可省略
volumeHandle: vke-tos-fsx-static-pv # 与存储卷（PV）名称保持一致
persistentVolumeReclaimPolicy: Delete # 回收策略。取值：Retain（保留策略），Delete（删除策略）
mountOptions: # TOS 存储卷挂载参数，支持动态修改，仅对新挂载的存储卷生效，对已挂载的存储卷不生效。挂载参数详情，请参见存储卷挂载参数
- no_writeback_cache
- tos_allow_delete=true
- num_meta_threads=64
- num_io_threads=1024
- num_bg_threads=128
- num_prefetch_threads=64
- tos_enable_cto=false
- tos_symlink_mode=1

关键参数说明，如下表所示。

参数	说明
accessModes	存储卷访问方式，仅支持 ReadWriteMany，表示多点读写，即存储卷仅能被多个 Pod 以读写方式挂载。
storage	存储卷容量，单位为 Gi。
driver	存储卷挂载依赖的驱动，本文中需要配置为 fsx.csi.volcengine.com，表示 csi-fsx 插件。
type	存储卷类型，本文中选择 TOS，表示对象存储。
server	已创建的 TOS 桶 Endpoint（地域节点），请勿填写为 Bucket 域名。说明您可以在对象存储控制台，查看已创建的 TOS 存储桶域名信息。详情请参见查看桶信息。当 VKE 集群和 TOS 桶在相同地域时，推荐使用内网访问的 Endpoint 访问。当 VKE 集群和 TOS 桶在不同地域时，可以使用外网访问的 Endpoint 访问。此时，请保证 VKE 集群具备公网访问能力。
region	已创建的 TOS 存储桶所在地域，例如cn-shanghai。若 TOS 存储桶与集群所在地域相同，该配置项可省略。
bucket	已创建的 TOS 存储桶名称。
path	指定 TOS 存储桶的根目录，请确保该目录存在，否则挂载会失败。
secretName	使用 AK/SK 鉴权时，已创建的 Secret 名称。如果使用 IRSA 鉴权，该配置项可省略。
secretNamespace	使用 AK/SK 鉴权时，已创建的 Secret 所属命名空间。如果使用 IRSA 鉴权，该配置项可省略。
volumeHandle	与存储卷（PV）名称保持一致即可。
mountOptions	TOS 存储卷挂载参数，支持动态修改，仅对新挂载的存储卷生效，对已挂载的存储卷不生效。详情请参见存储卷挂载参数。

执行以下命令，创建 PV。

kubectl create -f vke-tos-fsx-static-pv.yaml

步骤四：创建存储卷声明（PVC）

创建 PVC 的 Yaml 文件文件vke-tos-fsx-static-pvc.yaml，示例代码如下：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: vke-tos-fsx-static-pvc # PVC 名称
namespace: default
spec:
accessModes: # PVC 访问模式。目前仅支持 ReadWriteMany，即多点读写，需要与 PV 的配置一致
- ReadWriteMany
resources:
requests:
storage: 20Gi # 声明的存储使用量
volumeMode: Filesystem
volumeName: vke-tos-fsx-static-pv # 绑定到该 PVC 的 PV 名称

关键参数说明，如下表所示。

参数	说明
accessModes	存储卷声明的访问方式，仅支持 ReadWriteMany，表示多点读写。需要与 PV 的配置一致。
storage	声明的存储容量，单位为 Gi。
volumeMode	存储卷类型，必须与 PV 中配置的类型一致。包括： Filesystem：（默认值）将存储卷作为文件系统使用。存储卷会被格式化并挂载一个文件系统（如 ext4、xfs），再将该文件系统挂载到容器指定路径。您可以在容器中使用ls命令（例如ls /data）能查看挂载的目录或文件，并可以直接读写文件。 Block：将卷作为块设备使用。直接暴露给容器，不格式化、不挂载文件系统。您可以通过/dev/block/xxx类似的路径操作块设备，应用需支持裸块设备读写。
volumeName	存储卷名称，必须与 PV 中配置的名称一致。

执行以下命令，创建 PVC。

kubectl create -f vke-tos-fsx-static-pvc.yaml

执行以下命令，查看 PVC 与 PV 的静态绑定结果。

kubectl get pvc

预期输出结果如下，表示 PVC 与 PV 静态绑定成功。

NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
vke-tos-fsx-static-pvc Bound vke-tos-fsx-static-pv 20Gi RWX 2m36s

步骤五：创建应用并挂载存储卷

创建 Deployment 的 Yaml 文件vke-tos-fsx-static-deployment.yaml，示例代码如下：

apiVersion: apps/v1
kind: Deployment
metadata:
name: vke-static-tos-fsx-deploy
spec:
replicas: 1
selector:
matchLabels:
app: vke-static-tos-fsx-deploy
template:
metadata:
labels:
app: vke-static-tos-fsx-deploy
spec:
containers:
- name: nginx # 容器名称
image: doc-cn-beijing.cr.volces.com/vke/nginx-demo:v1.0
ports:
- containerPort: 80
name: web
volumeMounts:
- mountPath: /tmp # FSX 文件系统在容器中挂载的位置
name: tos-fsx-pv
volumes:
- name: tos-fsx-pv
persistentVolumeClaim:
claimName: vke-tos-fsx-static-pvc # 已创建的 PVC 名称

执行以下命令创建 Deployment。

kubectl create -f vke-tos-fsx-static-deployment.yaml

结果验证

按照上文示例创建工作负载并挂载存储卷后，您可以通过以下方式验证对象存储的挂载、共享存储和持久化存储。

执行以下命令，查看存储卷是否正确挂载到 Pod 的指定路径。

kubectl exec vke-static-tos-fsx-deploy-5f55*** -- df | grep tmp

预期返回结果如下。

/dev/vdc 20466256 24 20449848 1% /tmp

查看 Pod 中的挂载路径，即查看存储卷中的数据。

kubectl exec vke-static-tos-fsx-deploy-5f55*** -- ls /tmp

预期返回结果如下。

lost+found

登录对象存储控制台。向指定路径中上传文件。详情请参见上传文件。

再次查看 Pod 下的存储卷挂载路径。

kubectl exec vke-static-tos-fsx-deploy-5f55*** -- ls /tmp

预期返回如下，可以看到上传的文件，实现了数据卷的挂载和持久化存储。

lost+found
test

最近更新时间：2026.07.03 16:33:59

这个页面对您有帮助吗？

有用

无用