# 按用户隔离挂载SFS Turbo文件系统 #### 操作场景 在多租户的Agent应用场景下，您的业务系统（如企业服务端）会为每一个终端用户分配一个用户标识（userid），并为每个用户创建独立的运行环境（沙箱）。不同用户之间需要共享同一份SFS Turbo文件存储资源，但每个用户只能访问自己专属的存储目录，以避免用户间数据越权访问。 本文介绍如何通过Agent Identity与SFS Turbo的集成，实现SFS Turbo目录按用户隔离挂载： - 根据指定的userid挂载对应的SFS Turbo隔离目录，若该目录不存在则自动创建。 - 限制该userid只能挂载其专属目录，无权限挂载其他用户的目录。 #### 约束与限制 - 购买SFS Turbo实例后，需要提交工单开启该SFS Turbo实例的隔离挂载能力。 - SFS Turbo隔离挂载只支持Sandbox级别，不支持Template级别挂载。 - SFS Turbo隔离挂载场景下，Sandbox只能挂载1个目录。 - SFS Turbo实例开启隔离挂载后则不支持共享挂载，在使用Sandbox隔离挂载目录的同时，可以通过Template配置共享挂载目录。 #### 步骤一：为IAM子用户配置临时凭证权限 授予IAM子用户访问Agent Identity服务，换取代表隔离用户的临时凭证（Workload Access Token, WAT）的权限。 ![](https://support.huaweicloud.com/bestpractice-agentsphere/public_sys-resources/note_3.0-zh-cn.png) 仅IAM子用户需要执行本步骤；主账号无需配置，默认拥有权限。 1. **创建身份策略** 1. 使用管理员账号登录[统一身份认证服务新版控制台](https://console.huaweicloud.com/iam5)。 2. 在左侧导航栏中选择"身份策略"，单击"创建自定义身份策略"。 3. 配置策略信息： | 参数 | 说明 | |:---|:---| | 策略名称 | 本示例填写test-WAT-full。 | | 策略配置方式 | 选择"JSON视图"。 | | 策略内容 | 参考下方示例，允许IAM子用户换取隔离用户临时凭证。 ``` { "Version": "5.0", "Statement": [ { "Effect": "Allow", "Action": [ "agentIdentity::createWorkloadAccessTokenForUserId" ] } ] } ``` | 2. **授权策略给IAM子用户** 1. 单击上一步创建的test-WAT-full策略名称，切换至"授权记录"页签。 2. 单击"附加"，然后选择对应的IAM子用户，单击"确定"。 #### 步骤二：授权AgentSphere获取STS Token 创建运行时委托（Runtime agency），允许AgentSphere代表用户获取运行环境访问Agent Identity服务的临时凭证。 1. **创建身份策略** 1. 使用用户A的账号登录[统一身份认证服务新版控制台](https://console.huaweicloud.com/iam5)。 2. 在左侧导航栏中选择"身份策略"，单击"创建自定义身份策略"。 3. 配置策略信息： | 参数 | 说明 | |:---|:---| | 策略名称 | 本示例填写policy-WAT。 | | 策略配置方式 | 选择"JSON视图"。 | | 策略内容 | 参考下方示例，允许沙箱获取访问Agent Identity服务的STS Token。 ``` { "Version": "5.0", "Statement": [ { "Effect": "Allow", "Action": [ "agentIdentity::getResourceStsToken" ] } ] } ``` | 2. **创建委托** 1. 在左侧导航栏中选择"委托"，单击"创建信任委托"。 2. 配置委托信息： | 参数 | 说明 | |:---|:---| | 委托名称 | 本示例填写test_metadata_trust_agency。 | | 信任主体类型 | 选择"自定义信任策略"。 | | 信任策略 | 参考下方示例，允许沙箱元数据服务使用该委托。 ``` { "Version": "5.0", "Statement": [ { "Action": [ "sts:agencies:assume", "sts::tagSession" ], "Effect": "Allow", "Principal": { "Service": [ "service.WorkloadSandboxMetadata" ] } } ] } ``` | 3. **为委托授权身份策略** 1. 找到上一步创建的委托，单击"授权"。 2. 选择步骤1中创建的策略policy-WAT，单击"确定"。 #### 步骤三：授权Agent Identity获取挂载SFS Turbo目录权限 允许Agent Identity获取SFS Turbo目录挂载权限，并限制只能挂载用户专属目录（通过${g:AgentIdentity/InboundUserId}动态解析，实现每个用户只能挂载以自身userid命名的目录）。 1. **创建身份策略** 1. 使用用户A的账号登录[统一身份认证服务新版控制台](https://console.huaweicloud.com/iam5)。 2. 在左侧导航栏中选择"身份策略"，单击"创建自定义身份策略"。 3. 配置策略信息： | 参数 | 说明 | |:---|:---| | 策略名称 | 本示例填写policy-sfs1。 | | 策略配置方式 | 选择"JSON视图"。 | | 策略内容 | 参考下方示例，允许挂载SFS Turbo访问点下以userid命名的目录。 ``` { "Version": "5.0", "Statement": [ { "Effect": "Allow", "Action": [ "sfsturbo:accesspoint:mount" ], "Resource": [ "sfsturbo:*:*:accesspoint:eb2dba3c-bbd4-11f1-bb9d-fa163e188044/test/${g:AgentIdentity/InboundUserId}" ] } ] } ``` Resource字段格式为*sfsturbo:\:\:accesspoint:\/\* ，其中*\* 为SFS Turbo实例ID，*\* 末段固定以*${g:AgentIdentity/InboundUserId}*标识用户专属目录。 | 2. **创建委托** 1. 在左侧导航栏中选择"委托"，单击"创建信任委托"。 2. 配置委托信息： | 参数 | 说明 | |:---|:---| | 委托名称 | 本示例填写agency-identity。 | | 信任主体类型 | 选择"自定义信任策略"。 | | 信任策略 | 参考下方示例，允许Agent Identity服务使用该委托。 ``` { "Version": "5.0", "Statement": [ { "Action": [ "sts:agencies:assume", "sts::SetContext", "sts::setSourceIdentity", "sts::tagSession" ], "Effect": "Allow", "Principal": { "Service": [ "service.AgentIdentity" ] } } ] } ``` | 3. **为委托授权身份策略** 1. 找到上一步创建的委托，单击"授权"。 2. 选择步骤1中创建的策略policy-sfs1，单击"确定"。 #### 步骤四：创建Workload Identity 在Agent Identity服务中创建工作负载身份。工作负载身份是分配给沙箱模板、网关和Agent等工作负载的身份，用于沙箱访问Agent Identity服务时的身份验证。 1. 登录[Agent Identity控制台](https://console.huaweicloud.com/agent-identity)。 2. "工作负载身份"，单击"创建工作负载身份"。 3. 填写必要的工作负载身份信息： | 参数 | 说明 | |:---|:---| | 身份名称 | 本示例填写workload-test。 | | 入站身份认证 | 选择"API Key认证"，沙箱通过API Key完成身份认证。 | 4. 单击"立即创建"。 #### 步骤五：创建出站身份并关联出站身份委托 在Agent Identity服务中创建出站身份（Credential Provider），将步骤2中创建的委托（agency-identity）关联到出站身份，使沙箱能够通过Agent Identity认证身份后，使用该委托获取SFS Turbo目录挂载临时凭证。 1. 登录[Agent Identity控制台](https://console.huaweicloud.com/agent-identity)。 2. "出站身份"，单击"创建出站身份"。 3. 填写必要的出站身份信息： | 参数 | 说明 | |:---|:---| | 身份名称 | 本示例填写sfs-turbo。 | | 认证类型 | 选择"IAM委托"。 | | IAM 信任委托 | 选择[步骤三]中创建的委托：agency-identity。 | ![](https://support.huaweicloud.com/bestpractice-agentsphere/zh-cn_image_0000002806186927.png "点击放大") 4. 单击"立即创建"。 #### 步骤六：检查Agent Identity策略集配置 检查Agent Identity策略集配置，防止STS Token换取失败。 1. 登录[Agent Identity控制台](https://console.huaweicloud.com/agent-identity)。 2. 在左侧导航栏中选择"策略集"，检查策略集配置情况： - 如果无策略集，或策略集中无绑定实例，**可忽略本步骤**，无需额外配置。 - 如果已创建策略集且绑定了实例，且执行模式为**拦截模式** ： ![](https://support.huaweicloud.com/bestpractice-agentsphere/zh-cn_image_0000002776827306.png "点击放大") 则需要添加策略放通STS获取权限，策略语句可配置为更细粒度的权限。 ![](https://support.huaweicloud.com/bestpractice-agentsphere/zh-cn_image_0000002806227021.png "点击放大") #### 步骤七：购买VPCEP打通Sandbox与Agent Identity的网络 当Sandbox出站网络为私有网络模式时，您需要通过VPCEP打通Sandbox与Agent Identity服务的网络。 1. 登录[VPC终端节点控制台](https://console.huaweicloud.com/vpc/?#/ep/list)。 2. 在"终端节点"页面，单击"购买终端节点"。 3. 根据界面提示配置必选参数。更多参数说明，请参见[购买终端节点](https://support.huaweicloud.com/usermanual-vpcep/zh-cn_topic_0131645189.html)。 表1终端节点配置参数 | 参数 | 说明 | |:---|:---| | 区域 | 终端节点所在区域，需要与AgentSphere沙箱所在区域保持一致。 | | 计费模式 | 仅支持按需计费。按需计费是后付费模式，按终端节点的实际使用时长计费，可以随时开通/删除终端节点。 | | 服务类别 | 选择"云服务"。 | | 服务名称 | 搜索"agent-identity"，勾选对应的服务名称。 | | 创建内网域名 | 如果您需要以域名的方式访问终端节点，则选择"创建内网域名"，终端节点创建完成后，即可通过内网域名直接访问终端节点。 | | 虚拟私有云 | 需要选择AgentSphere沙箱所在的虚拟私有云。 注意： 选择的VPC和子网需要与SFS Turbo实例和Sandbox保持一致。 | | 路由表 | 选择一个已有的路由表。 | 4. 参数配置完成，单击"立即购买"，进行规格确认。 #### 隔离挂载验证 前置配置完成后，您可以通过以下步骤验证按用户隔离挂载功能是否生效。 1. 创建沙箱模板（template）并完成模板快照构建，为创建沙箱实例准备模板配置，详情请参见[创建沙箱模板](https://support.huaweicloud.com/usermanual-agentsphere/agentsphere_03_0006.html)。 其中VPC和子网需要与后续SFS Turbo实例的VPC相同，"运行时信任委托"配置为[步骤二]中创建的委托test_metadata_trust_agency。 ![](https://support.huaweicloud.com/bestpractice-agentsphere/public_sys-resources/note_3.0-zh-cn.png) 若要使用Sandbox隔离挂载目录的同时使用共享挂载目录，可以在模板中配置template级别的SFS Turbo共享目录挂载。 2. 通过API创建Sandbox，并携带以下3个隔离挂载Header头，实现按userid隔离挂载SFS Turbo目录。 表2隔离挂载header头说明 | Header头 | 说明 | |:---|:---| | X-HW-AgentSandbox-UserId | SFS Turbo隔离挂载的用户ID，用于标识SFS Turbo隔离目录。挂载目录时sharePath的末段须与该值一致，系统将基于该值获取此隔离目录的临时挂载凭证。 | | X-HW-AgentSandbox-Credential-Provider-Name | [步骤五]中创建的出站身份名称，本示例为sfs-turbo。 | | X-HW-AgentSandbox-Workload-Identity-Name | [步骤四]中创建的工作负载身份名称，本示例为workload-test。 | ![](https://support.huaweicloud.com/bestpractice-agentsphere/public_sys-resources/caution_3.0-zh-cn.png) 上述3个隔离挂载Header头必须齐全；若Header头不齐全，将按普通挂载方式创建沙箱，不会启用隔离挂载。 表3请求参数说明 | 参数 | 说明 | |:---|:---| | templateID | 验证[1]中创建的模板ID（templateID）和快照ID（buildID），格式为templateID:buildID。 | | sfsTurboId | SFS Turbo实例ID，该实例VPC需要与沙箱模板中配置的VPC一致。 | | sharePath | 挂载目录路径，子目录需与userid一致（本示例为sandbox-002），否则会校验报错。 | 请求Header示例： ``` -H "X-HW-AgentSandbox-UserId: sandbox-002" -H "X-HW-AgentSandbox-Credential-Provider-Name: sfs-turbo" -H "X-HW-AgentSandbox-Workload-Identity-Name: workload-test" ``` body示例： ``` { "templateID": "00c73584-cb75-450e-a604-c692c5693473:c64f42d2-145e-4726-ab23-477c95c844de", "sfsTurboId": "eb2dba3c-bbd4-11f1-bb9d-fa163e188044", "sharePath": "/test/sandbox-002" } ``` 3. 创建成功后，沙箱激活，并挂载目录/test/sandbox-002，说明隔离挂载成功。 ![](https://support.huaweicloud.com/bestpractice-agentsphere/public_sys-resources/caution_3.0-zh-cn.png) SFS Turbo隔离挂载若传入的sharePath不存在，会自动创建该sharePath。 #### 挂载无访问权限目录拦截验证 验证隔离挂载的权限校验能力，确认Sandbox无法挂载无访问权限的目录。 - **场景1：sharePath根目录与出站身份关联的访问权限目录不一致** 请求示例： ``` -H "X-HW-AgentSandbox-UserId: sandbox-002" -H "X-HW-AgentSandbox-Credential-Provider-Name: sfs-turbo" -H "X-HW-AgentSandbox-Workload-Identity-Name: workload-test" -H "X-API-KEY: e2b_xxx" ``` body示例： ``` { "templateID": "00c73584-cb75-450e-a604-c692c5693473:c64f42d2-145e-4726-ab23-477c95c844de", "name": "sandbox-test2", "secure": true, "autoPause": false, "autoResume": { "enable": false }, "storageConfig": { "sfsTurboMounts": [ { "sfsTurboId": "eb2dba3c-bbd4-11f1-bb9d-fa163e188044", "sharePath": "/test-another/sandbox-002" } ] } } ``` 预期返回结果：挂载被拦截，提示无挂载权限。 ``` { "code": 403, "message": "no permission to mount SFS Turbo share path", "error_code": "AgentSphere.0108" } ``` - **场景2：sharePath子目录与userid不一致** body示例（sharePath子目录为sandbox-011，与userid sandbox-002不一致）： ``` { "templateID": "00c73584-cb75-450e-a604-c692c5693473:c64f42d2-145e-4726-ab23-477c95c844de", "name": "sandbox-test2", "secure": true, "autoPause": false, "autoResume": { "enable": false }, "storageConfig": { "sfsTurboMounts": [ { "sfsTurboId": "eb2dba3c-bbd4-11f1-bb9d-fa163e188044", "sharePath": "/test/sandbox-011" } ] } } ``` 预期返回结果：校验失败，sharePath与userId不匹配。 ``` { "code": 400, "message": "sharePath does not match userId", "error_code": "AgentSphere.0505" } ``` #### 进阶配置：限制IAM子用户隔离挂载权限 上文中已授权IAM子用户换取WAT的权限。如果需要进一步限制IAM子用户只能使用指定的Workload Identity和userid，可以参考本节配置，实现IAM子用户级别的隔离挂载权限管控。 1. **限制IAM子用户WAT换取权限** 创建身份策略，限制IAM子用户换取WAT的权限范围，可以从resource（workload identity）和condition（userid）两个维度进行配置。 1. 使用管理员账号登录[统一身份认证服务新版控制台](https://console.huaweicloud.com/iam5)。 2. 在左侧导航栏中选择"身份策略"，单击"创建自定义身份策略"。 3. 配置策略信息： | 参数 | 说明 | |:---|:---| | 策略名称 | 本示例填写test-WAT。 | | 策略配置方式 | 选择"JSON视图"。 | | 策略内容 | 参考下方示例，仅允许使用sandbox-test1这个工作负载身份为sandbox-123这个userid换取Workload Access Token。 ``` { "Version": "5.0", "Statement": [ { "Effect": "Allow", "Action": [ "agentIdentity::createWorkloadAccessTokenForUserId" ], "Resource": [ "agentidentity:*:*:workloadIdentity:workloadIdentityDirectory/default/sandbox-test1", "agentidentity:*:*:workloadIdentityDirectory:default" ], "Condition": { "StringEquals": { "agentIdentity:userId": [ "sandbox-123" ] } } } ] } ``` | 4. 授权策略给IAM子用户 1. 单击上一步创建的test-WAT策略名称，切换至"授权记录"页签。 2. 单击"附加"，然后选择对应的IAM子用户，单击"确定"。 ![](https://support.huaweicloud.com/bestpractice-agentsphere/public_sys-resources/note_3.0-zh-cn.png) 授权子用户test-WAT时，需要确保前文中设置的test-WAT-full权限已移除，否则限制不生效。 2. **验证策略是否生效** - **验证场景1：userid与策略中的不一致** 请求中携带的userid为sandbox-001，与策略中授权的sandbox-123不一致，预期返回无权限。 ``` -H "X-HW-AgentSandbox-UserId: sandbox-001" -H "X-API-KEY: {授权子用户的API-KEY}" ``` 预期返回结果： ``` { "code": 403, "message": "AgentIdentity denied WAT access, please check identity policy permissions" } ``` - **验证场景2：workload identity与策略中授权的不一致** 请求中携带的workload identity为sandbox-test2，与策略中授权的sandbox-test1不一致，预期返回无权限。 ``` -H "X-HW-AgentSandbox-UserId: sandbox-123" -H "X-HW-AgentSandbox-Workload-Identity-Name: sandbox-test2" -H "X-API-KEY: {授权子用户的API-KEY}" ``` 预期返回结果： ``` { "code": 403, "message": "AgentIdentity denied WAT access, please check identity policy permissions" } ```