ossfs 2.0儲存卷FAQ - Container Service for Kubernetes

本文介紹使用ossfs 2.0儲存卷的常見問題和解決方案。

問題導航

類型	問題
掛載	OSS儲存卷掛載失敗如何通過OSS儲存卷僅掛載OSS中的某個檔案如何跨帳號掛載OSS Bucket？如何使用CoreDNS解析OSS訪問端點？如何在RRSA鑒權方式中使用指定的ARNs或ServiceAccount？
擴容	實際儲存容量超出OSS儲存卷的配置時，是否需要擴容儲存卷
使用	如何重啟ossfs 2.0進程

掛載

OSS儲存卷掛載失敗

問題現象

通過ossfs 2.0掛載OSS儲存卷失敗，Pod無法啟動，Event提示FailedMount。

問題原因

原因1：AccessKey許可權不足導致掛載失敗。
原因2：Event的內容中包含failed to get secret secrets "xxx" is forbidden: User "serverless-xxx" cannot get resource "secrets" in API group "" in the namespace "xxx"。對於建立在虛擬節點（ACS Pod）上的應用，當PVC需要通過nodePublishSecretRef欄位來指定鑒權資訊時，Secret必須與PVC位於同一個命名空間。
原因3：Event的內容中包含FailedMount /run/fuse.ossfs/xxxxxx/mounter.sock: connect: no such file or directory，原因為ossfs 2.0所在Pod未正常拉起或被意外刪除。
原因4：OSS Bucket配置了鏡像回源，掛載目錄未從來源站點同步。
原因5：OSS Bucket配置了靜態網站託管，ossfs 2.0檢查OSS端掛載目錄時，請求轉寄到index.html等檔案中。

解決方案

原因1解決方案
- 確認掛載使用的RAM使用者的策略許可權滿足要求。具體請參見使用ossfs 2.0靜態儲存卷。
- 確認掛載時使用的AccessKey是否被禁用或已輪轉。
  重要
  僅修改在PV中通過nodePublishSecretRef欄位指定的Secret中的AccessKey資訊無法直接生效，需要重啟ossfs 2.0用戶端Pod。ossfs 2.0用戶端重啟方式，請參見如何重啟ossfs 2.0進程。
原因2解決方案：
請在PVC所在的命名空間下建立所需的Secret，建立PV時，將nodePublishSecretRef指向該Secret。具體操作，請參見方式二：通過RAM使用者AccessKey鑒權方式掛載。
原因3解決方案
1. 確認ossfs 2.0所在Pod存在。
  其中PV_NAME為掛載的OSS PV名稱，NODE_NAME為需掛載儲存卷的業務Pod所在的節點名稱。
```
kubectl -n ack-csi-fuse get pod -l csi.alibabacloud.com/volume-id=<PV_NAME> -owide | grep <NODE_NAME>
```
  - 若Pod存在且狀態異常，請排查Pod的異常原因，確保Pod正常Running後重啟業務Pod觸發重新掛載。
  - 若Pod不存在，請按後續步驟繼續排查。
2. （可選）通過查詢審計日誌等方式確認Pod是否被意外刪除。
  常見的意外刪除原因包括業務指令碼清理、節點排水、節點自愈等。建議您做相關調整，避免問題重現。
3. 確認是否殘留VolumeAttachment資源。
```
kubectl get volumeattachment | grep <PV_NAME> | grep <NODE_NAME>
```
4. 重啟業務Pod觸發重新掛載，並確認ossfs 2.0 Pod有正常建立流程。
原因4解決方案
您需要同步來源站點資料後，再進行掛載。更多資訊，請參見回源配置概述。
原因5解決方案
您需要關閉或調整靜態網站託管的配置，再進行掛載。更多資訊，請參見靜態網站託管。

如何通過OSS儲存卷僅掛載OSS中的某個檔案

ossfs 2.0工具可將OSS的某個路徑以檔案系統的形式掛載到Pod中，但ossfs 2.0本身不支援直接掛載單個檔案。若您希望Pod僅訪問OSS中的某個特定檔案，可通過指定subpath的方式實現。

假設需要掛載的OSS Bucket中/subpath下的a.txt和b.txt檔案到兩個不同的Pod中，在Pod中的存放路徑為/path/to/file/，可參考以下YAML建立對應的PV：

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-oss
spec:
  capacity:
    storage: 5Gi
  accessModes:
    - ReadOnlyMany
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: ossplugin.csi.alibabacloud.com
    volumeHandle: pv-oss 
    volumeAttributes:
      bucket: bucket
      path: subpath #subpath為a.txt與b.txt的父路徑
      url: "oss-cn-hangzhou.aliyuncs.com"
      fuseType: ossfs2

建立對應的PVC後，Pod中掛載PVC相應的VolumeMounts配置為：

  volumeMounts:
    - mountPath: /path/to/file # bucket:/subpath對應Pod中的掛載路徑
      name: oss-pvc # 與Volumes中的名稱一致
      subPath: a.txt # 或者b.txt，bucket:/subpath中檔案的相對路徑

掛載後，Pod中訪問a.txt的完整路徑為/path/to/file/a.txt，實際訪問的是bucket:/subpath/a.txt。

更多資訊，請參見使用ossfs 2.0靜態儲存卷。

如何跨帳號掛載OSS Bucket？

建議通過RRSA鑒權方式跨帳號掛載OSS Bucket。

請確認叢集和CSI組件版本滿足RRSA鑒權要求的版本。

以下操作以在帳號A（叢集所在帳號）中，掛載帳號B（OSS Bucket所在帳號）的Bucket為例。需完成RAM授權相關準備工作後，再正常建立通過RRSA鑒權方式掛載的儲存卷。

在帳號B中的操作：
1. 在帳號B中建立可信實體為帳號A的RAM角色roleB，詳情請參見建立可信實體為阿里雲帳號的RAM角色。
2. 為roleB授權需要掛載的OSS Bucket許可權。
3. 在RAM控制台，訪問roleB的角色詳情頁，複製其ARN，如acs:ram::130xxxxxxxx:role/roleB。
在帳號A中的操作：
1. 為應用建立一個用於 RRSA 鑒權的 RAM 角色roleA，信任主體類型為OIDC身份供應商。
2. 為 roleA 授予代入 roleB 的許可權。具體操作請參見1. 在叢集中啟用RRSA（靜態卷）或使用ossfs 1.0動態儲存裝置卷（動態磁碟區）。
  roleA無需再授權OSS相關權限原則，但需要授權包含sts:AssumeRoleAPI的權限原則，如系統策略AliyunSTSAssumeRoleAccess。
在叢集中配置儲存卷：
在建立儲存卷時，將 roleB的 ARN 配置到 assumeRoleArn參數中：
- 靜態卷 (PV)：在 volumeAttributes中添加：
```
assumeRoleArn: <roleB的ARN>
```
- 動態磁碟區 (StorageClass)：在 parameters中添加：
```
assumeRoleArn: <roleB的ARN>
```

如何使用CoreDNS解析OSS訪問端點？

如需將 OSS 的訪問端點（Endpoint）指向一個叢集內部網域名稱，可為 ossfs 所啟動並執行 Pod 配置特定的 DNS 策略，強制它在掛載時優先使用叢集的 CoreDNS。

本功能僅支援v1.34.2及以上版本的CSI組件。如需升級，請參見升級CSI組件。

靜態卷 (PV)：在 PV 的 spec.csi.volumeAttributes欄位中添加 dnsPolicy。
```
dnsPolicy: ClusterFirstWithHostNet
```
動態磁碟區 (StorageClass)：在 StorageClass 的 parameters欄位中添加 dnsPolicy。
```
dnsPolicy: ClusterFirstWithHostNet
```

如何在RRSA鑒權方式中使用指定的ARNs或ServiceAccount？

通過RRSA方式的OSS儲存卷鑒權時，無法滿足例如使用第三方OIDC身份供應商、使用非預設ServiceAccount等需求。

此時，只需在PV中通過roleName配置項指定RAM角色名稱，即可由CSI儲存外掛程式擷取預設的Role ARN及OIDC Provider ARN。如需實現定製化的RRSA鑒權，則需要更改PV的配置資訊如下。

其中，roleArn與oidcProviderArn需要一起配置，配置後無需再配置roleName。

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-oss
spec:
  capacity:
    storage: 5Gi
  accessModes:
    - ReadOnlyMany
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: ossplugin.csi.alibabacloud.com
    volumeHandle: pv-oss # 需要和PV名字一致。
    volumeAttributes:
      bucket: "oss"
      url: "oss-cn-hangzhou.aliyuncs.com"
      authType: "rrsa"
      fuseType: "ossfs2"
      oidcProviderArn: "<oidc-provider-arn>"
      roleArn: "<role-arn>"
      #roleName: "<role-name>" #配置roleArn和oidcProviderArn後，roleName失效。
      serviceAccountName: "csi-fuse-<service-account-name>"

參數	說明
`oidcProviderArn`	需要在建立OIDC身份供應商後擷取，請參見管理OIDC身份供應商。
`roleArn`	需要在建立可信實體為上述OIDC身份供應商的RAM角色後擷取，請參見使用OIDC進行角色SSO的樣本。
`serviceAccountName`	可選，ossfs容器所在的Pod使用ServiceAccount名稱，必須以csi-fuse-開頭，需要預先建立。配置為空白時，使用CSI維護的預設ServiceAccount。

擴容

實際儲存容量超出OSS儲存卷的配置時，是否需要擴容儲存卷

OSS不限制Bucket或子路徑的容量，且不提供容量配額功能，因此PV的.spec.capacity欄位和PVC的.spec.resources.requests.storage欄位的配置將被忽略，不會生效，您只需確保互相綁定的PV與PVC的容量配置值保持一致即可。

實際儲存容量超出配置時，不影響正常使用，您無需擴容儲存卷。

使用

如何重啟ossfs 2.0進程

問題現象

修改鑒權資訊或ossfs 2.0版本後，已經在啟動並執行ossfs 2.0進程無法自動變更。

問題原因

ossfs 2.0運行後無法變更鑒權資訊等配置，變更配置後，需要重啟ossfs 2.0進程（即為ack-csi-fuse命名空間下名為csi-fuse-ossfs2-*的Pod）與對應的應用Pod，造成業務中斷。因此，預設情況下CSI不會對已經啟動並執行ossfs 2.0進行變更。
在正常操作流程中，ossfs 2.0儲存卷的建立與刪除完全由CSI管理。若手動終止了運行ossfs 2.0的Pod，CSI將無法觸發儲存卷的自動回復或重建。

解決方案

重要

重啟ossfs 2.0進程的流程中需要重啟掛載對應OSS儲存卷的業務Pod，請謹慎操作。

確認當前FUSE Pod被哪些應用Pod使用。

確認需要變更的csi-fuse-ossfs2-* Pod。
其中<pv-name>為PV名稱，<node-name>為節點名稱。
```
kubectl -n ack-csi-fuse get pod -lcsi.alibabacloud.com/volume-id=<pv-name> -owide | grep <node-name>
```

確認正在掛載該OSS儲存卷的所有Pod。

其中<ns>為命名空間名稱，<pvc-name>為PVC名稱。

kubectl -n <ns> describe pvc <pvc-name>

預期輸出（包含Used By）：

Used By:       oss-static-94849f647-4****
               oss-static-94849f647-6****
               oss-static-94849f647-h****
               oss-static-94849f647-v****
               oss-static-94849f647-x****

擷取通過csi-fuse-ossfs2-xxxx掛載的Pod，即與csi-fuse-ossfs2-xxxx運行在同一節點的Pod。

kubectl -n <ns> get pod -owide | grep cn-beijing.192.168.XX.XX

預期輸出：

NAME                         READY   STATUS    RESTARTS   AGE     IP               NODE                         NOMINATED NODE   READINESS GATES
oss-static-94849f647-4****   1/1     Running   0          10d     192.168.xx.xx    cn-beijing.192.168.xx.xx     <none>           <none>
oss-static-94849f647-6****   1/1     Running   0          7m36s   192.168.xx.xx    cn-beijing.192.168.xx.xx     <none>           <none>

重啟業務與ossfs 2.0進程。
將應用Pod（上述樣本中為oss-static-94849f647-4****和oss-static-94849f647-6****）通過kubectl scale等方式同時刪除。在無應用Pod掛載時，csi-fuse-ossfs2-xxxx Pod將自動被回收；恢複副本數後，將使用PV的新配置重新掛載，由CSI建立新的csi-fuse-ossfs2-yyyy Pod。
如果無法保證這些Pod能同時被刪除（如刪除Deployment、StatefulSet、DaemonSet管理的Pod均會立即觸發重啟），或Pod能容忍OSS讀寫失敗，執行以下命令，找到儲存卷對應的volumeattachment資源：
```
kubectl get volumeattachment | grep <pv-name> | grep cn-beijing.192.168.XX.XX
```
預期輸出：
```
csi-bd463c719189f858c2394608da7feb5af8f181704b77a46bbc219b**********   ossplugin.csi.alibabacloud.com    <pv-name>                   cn-beijing.192.168.XX.XX    true       12m
```
直接刪除該VolumeAttachment，此時應用Pod內讀寫OSS將返回disconnected error。
然後，逐個重啟業務Pod，重啟後的Pod將通過CSI建立的csi-fuse-ossfs2-yyyy Pod恢複OSS讀寫。