Container Service for Kubernetes：ossfs 1.0儲存卷FAQ

OSS儲存卷掛載時間延長

問題現象

OSS儲存卷掛載時間延長。

問題原因

同時滿足以下配置，kubelet在儲存卷掛載過程中將執行chmod或chown操作，導致掛載時間延長。

• PV及PVC中配置AccessModes為ReadWriteOnce。

• 應用模板中配置了securityContext.fsgroup。

解決方案

• ossfs掛載工具支援通過參數修改其掛載點下檔案所屬的UID、GID以及檔案的mode。

  參數	說明
  uid	指定掛載目錄下子目錄及檔案歸屬使用者的使用者UID。
  gid	指定掛載目錄下子目錄及檔案歸屬使用者的使用者GID。
  umask	用於設定掛載目錄下子目錄及檔案的許可權掩碼。使用方式與mp_umask類似，但無需依賴allow_other配置項。

  配置後，請刪除securityContext下的fsgroup參數。

• 對於1.20及之後版本的Kubernetes叢集，除了上述解決方案外，也可將fsGroupChangePolicy配置為OnRootMismatch，實現僅在初次開機時才會執行chmod或chown操作，後續掛載時間將恢複正常。關於fsGroupChangePolicy的更多資訊，請參見為Pod或容器配置資訊安全內容。

OSS儲存掛載許可權問題

當您在以下幾種情境中進行操作時，出現錯誤提示Permission Denied或Operation not permitted。

OSS儲存卷掛載失敗，業務Pod Event提示FailedMount

問題現象

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

問題原因

• 原因1：ossfs早期版本不支援掛載到Bucket中不存在的目錄中，原掛載目錄不存在導致掛載失敗。

  重要

  OSS控制台中可見的子路徑在Server端不一定真實存在，以ossutil或OSS API的返回為準。例如，直接建立/a/b/c/目錄，/a/b/c/為單獨的目錄對象，而/a/或/a/b/目錄對象實際並不存在。同理，如上傳/a/*檔案，/a/b、/a/c等為單獨的檔案對象，/a/目錄對象不存在。

• 原因2：AccessKey或RRSA使用的角色資訊填寫錯誤或許可權不足導致掛載失敗。

• 原因3：掛載業務的運行環境被OSSBucket的授權策略攔截。

• 原因4：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位於同一個命名空間。

• 原因5：CSI版本在1.30.4及以上時，OSSFS所在的Pod運行在ack-csi-fuse命名空間中。掛載時CSI將先拉起OSSFS所在的Pod，再通過RPC請求實際啟動Pod中的OSSFS進程。若Event的內容中包含FailedMount /run/fuse.ossfs/xxxxxx/mounter.sock: connect: no such file or directory，原因為OSSFS所在Pod未正常拉起或被意外刪除。

• 原因6：Event的內容中包含Failed to find executable /usr/local/bin/ossfs: No such file or directory，原因為OSSFS在節點上安裝失敗。

• 原因7：Event的內容中包含error while loading shared libraries: xxxxx: cannot open shared object file: No such file or directory，掛載失敗的原因為當前CSI版本ossfs直接運行在節點上，且作業系統缺乏部分ossfs運行所需的動態庫。以下情況都可能導致該報錯：

  • 手動在節點安裝過其他版本的ossfs工具，且適配的作業系統與當前節點不一致。

  • 節點作業系統版本升級導致OpenSSL預設版本變更，例如Alibaba Cloud Linux 2升級至Alibaba Cloud Linux 3。

  • ossfs運行在節點上時，不支援CentOS、Alibaba Cloud Linux、ContainerOS和龍蜥以外的作業系統。

  • 在符合作業系統要求的節點上刪除過預設的FUSE、cURL、xml2等ossfs運行需要的動態庫，或變更過OpenSSL的預設版本。

• 原因8：掛載OSS Bucket的子目錄時，AccessKey或RRSA使用的角色僅授權了子目錄範圍的許可權，掛載失敗。ossfs Pod日誌中同時包含403 AccessDenied 和404 NoSuchKey報錯。

  ossfs在啟動時將自動對OSS Bucket進行許可權校正與連通性檢測。掛載目標為OSS子目錄時，1.91.5以下版本的ossfs將先嘗試訪問Bucket根目錄；若訪問失敗，則重新嘗試訪問子目錄。對Bucket有完整隻讀許可權時，新版本ossfs允許掛載OSS Bucket中不存在的子目錄。

  因此，對若AccessKey或RRSA使用的角色僅授權了子目錄範圍的許可權，將在初次驗證時報403 AccessDenied錯誤；若該子目錄不存在，則繼續報404 NoSuchKey錯誤並異常退出，導致掛載失敗。

• 原因9：Bucket配置了鏡像回源，掛載目錄未從來源站點同步。

• 原因10：Bucket配置了靜態網站託管，ossfs檢查OSS端掛載目錄時，請求轉寄到index.html等檔案中。

解決方案

• 原因1解決方案：

  檢查子路徑在OSS Server端是否存在。

  假設PV的掛載路徑為sub/path/，您可以使用stat（查看Bucket和Object資訊）查詢objectname為sub/path/的對象，或使用openapi HeadObject查詢key為sub/path/的對象。若返回為404，確認Server端不存在該子路徑。

  • 您可以通過ossutil、SDK、OSS控制台等工具手動建立缺失的Bucket或子目錄，然後重新掛載。

  • ossfs1.91+版本不強制要求掛載目錄存在，您也可以通過升級ossfs版本解決該問題。更多資訊，請參見ossfs 1.0新版本功能介紹及效能壓測。若升級後掛載仍出現問題，請參見本問題原因6。

• 原因2解決方案：

  • 確認掛載使用的RAM使用者或RAM角色的策略許可權包括2. 建立RAM角色並授權中列舉的許可權。

  • 確認掛載點根路徑及subpath路徑的檔案系統許可權，詳情請參考OSS儲存掛載許可權問題中的情境2和情境7。

  • 對於通過RAM使用者AccessKey鑒權方式掛載的儲存卷，確認掛載時使用的AccessKey是否被禁用或已輪轉，詳情請參考OSS儲存掛載許可權問題中的情境5.

  • 對於通過RRSA鑒權方式掛載的儲存卷，確認是否為RAM角色配置正確的信任策略。信任策略的配置請參考1. 在叢集中啟用RRSA。預設情況下，信任的ServiceAccount為ack-csi-fuse命名空間下的csi-fuse-ossfs，而非業務使用的ServiceAccount。

    重要

    RRSA鑒權方式掛載僅支援1.26及以上版本的叢集，且叢集使用的CSI組件為1.30.4及以上版本。若在1.30.4之前的版本中使用了RRSA功能，請及時參見【產品變更】CSI ossfs版本升級與掛載流程最佳化增加RAM角色授權配置。

• 原因3解決方案：

  檢查並修正OSS Bucket授權策略，詳情請參考OSS儲存掛載許可權問題中的情境1。

• 原因4解決方案：

  請在PVC所在的命名空間下建立所需的Secret，建立PV時，將nodePublishSecretRef指向該Secret。具體操作，請參見OSS唯讀權限原則。

• 原因5解決方案：

  1. 執行以下命令，確認OSSFS所在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. 確認CSI provisioner與CSI plugin均升級到1.30.4及以上後：

     1. 執行以下步驟，確認是否殘留VolumeAttachment資源

        kubectl get volumeattachment | grep <PV_NAME> | grep <NODE_NAME>

        若有，請刪除該VolumeAttachment資源。

     2. 重啟業務Pod觸發重新掛載，並確認OSSFS Pod有正常建立流程。

• 原因6解決方案：

  1. 建議您將csi-plugin版本升級到v1.26.2或以上版本，該版本修複了剛擴容出的節點初始化時，ossfs安裝失敗的問題。

  2. 執行以下命令，嘗試重啟對應節點上的csi-plugin後，查看Pod是否能正常啟動。

     以下代碼中csi-plugin-****為節點所在csi-plugin的Pod名稱。

     kubectl -n kube-system delete pod csi-plugin-****

  3. 若升級或重啟組件後，問題仍無法解決，請登入節點，執行以下命令。

     ls /etc/csi-tool

     部分預期輸出：

     ... ossfs_<ossfsVer>_<ossfsArch>_x86_64.rpm ...

     • 若輸出中存在OSSFS的RPM包，則執行以下命令，查看Pod是否能正常啟動。

       rpm -i /etc/csi-tool/ossfs_<ossfsVer>_<ossfsArch>_x86_64.rpm

     • 若輸出中不存在OSSFS的RPM包，請參見安裝ossfs 1.0下載最新版本。

• 原因7解決方案：

  • 若您手動安裝過ossfs工具，請檢查適配的作業系統與節點是否一致。

  • 若您升級過叢集的節點作業系統，可以執行以下指令重啟csi-plugin，更新ossfs版本後再嘗試掛載。

    kubectl -n kube-system delete pod -l app=csi-plugin

  • 建議您升級CSI至1.28或以上版本，掛載OSS儲存卷時ossfs以容器的方式運行在叢集中，對節點作業系統無要求。

  • 若您的叢集無法升級CSI版本，可以切換至符合要求的OS或手動安裝缺少的動態庫，以Ubuntu節點為例：

    • 使用which指令，查詢當前ossfs的安裝位置（預設安裝路徑為/usr/local/bin/ossfs）。

      which ossfs

    • 使用ldd指令，查詢ossfs缺失的動態庫檔案。

      ldd /usr/local/bin/ossfs

    • 使用apt-file指令，查詢缺失的動態庫檔案（如libcrypto.so.10）所屬的Package。

      apt-get install apt-file
      apt-file update
      apt-file search libcrypto.so.10

    • 使用apt-get指令安裝對應Package（如libssl.1.0.0）。

      apt-get install libssl1.0.0

• 原因8解決方案：

  • 推薦方案：升級CSI版本至v1.32.1-35c87ee-aliyun以上。

  • 其他方案1：參考本問題原因1，確認子目錄是否存在。

  • 其他方案2：若業務長期需要掛載子目錄，建議將許可權範圍擴大到整個Bucket。

• 原因9解決方案：

  您需要同步來源站點資料後，再進行掛載。更多資訊，請參見回源配置概述。

• 原因10解決方案：

  您需要關閉或調整靜態網站託管的配置，再進行掛載。更多資訊，請參見靜態網站託管。

OSS儲存卷掛載失敗，業務Pod Event提示FailedAttachVolume

問題現象

OSS儲存卷掛載失敗，Pod無法啟動，Event提示FailedAttachVolume。

問題原因

Event中包含AttachVolume.Attach failed for volume "xxxxx" : attaching volumes from the kubelet is not supported。此錯誤表明，節點的kubelet未開啟enable-controller-attach-detach配置。

這通常發生在從FlexVolume遷移至CSI的情境中：v1.30.4及以上版本的CSI組件依賴此參數來執行AttachVolume操作，但在遷移過程中節點的kubelet配置未能正確更新。

，

解決方案

1. 檢查節點kubelet配置

   登入節點，確認kubelet的enable-controller-attach-detach參數配置。

   其中，/etc/systemd/system/kubelet.service.d/10-kubeadm.conf為叢集kubelet預設的設定檔路徑。請替換為實際路徑。

   cat /etc/systemd/system/kubelet.service.d/10-kubeadm.conf | grep enable-controller-attach-detach

   正常情況下，預期輸出為true。

   …… --enable-controller-attach-detach=true ……

2. 更新節點配置

   若kubelet未正確開啟enable-controller-attach-detach配置，請先確認叢集已經完成所有FlexVolume儲存卷的遷移，並參見將無儲存叢集的Flexvolume遷移至CSI中的步驟三：修改叢集中所有節點池的配置和步驟四：修改現有節點配置，完成對節點池及存量節點的配置變更。

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

OSS儲存卷通過ossfs工具將OSS的某個路徑以檔案系統的形式掛載到Pod中，ossfs本身並不支援掛載檔案。若您希望在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"

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

  volumeMounts:
    - mountPath: /path/to/file/a.txt # 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。

OSS儲存卷的基本使用說明請參考使用ossfs 1.0靜態儲存卷。

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

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

此時，您只需要在PV中通過roleName配置項指定RAM角色名稱，即可由CSI儲存外掛程式擷取預設的Role ARN及OIDC Provider ARN。若您需要實現定製化的RRSA鑒權，則需要更改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 # 需要和PV名字一致。
    volumeAttributes:
      bucket: "oss"
      url: "oss-cn-hangzhou.aliyuncs.com"
      otherOpts: "-o umask=022 -o max_stat_cache_size=0 -o allow_other"
      authType: "rrsa"
      oidcProviderArn: "<oidc-provider-arn>"
      roleArn: "<role-arn>"
      #roleName: "<role-name>" #配置roleArn和oidcProviderArn後，roleName失效。
      serviceAccountName: "csi-fuse-<service-account-name>" 

如何跨帳號掛載OSS Bucket？

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

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

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

1. 在帳號B中的操作：

   1. 在帳號B中建立可信實體為帳號A的RAM角色roleB，詳情請參見建立可信實體為阿里雲帳號的RAM角色。

   2. 為roleB授權需要掛載的OSS Bucket許可權。

   3. 在RAM控制台，訪問roleB的角色詳情頁，複製其ARN，如acs:ram::130xxxxxxxx:role/roleB。

2. 在帳號A中的操作：

   1. 為應用建立一個用於 RRSA 鑒權的 RAM 角色roleA，信任主體類型為OIDC身份供應商。

   2. 為 roleA 授予代入 roleB 的許可權。具體操作請參見1. 在叢集中啟用RRSA（靜態卷）或使用ossfs 1.0動態儲存裝置卷（動態磁碟區）。

      roleA無需再授權OSS相關權限原則，但需要授權包含sts:AssumeRoleAPI的權限原則，如系統策略AliyunSTSAssumeRoleAccess。

3. 在叢集中配置儲存卷：

   在建立儲存卷時，將 roleB的 ARN 配置到 assumeRoleArn參數中：

   • 靜態卷 (PV)：在 spec.csi.volumeAttributes欄位中添加 assumeRoleArn。

     assumeRoleArn: <roleB的ARN>

   • 動態磁碟區 (StorageClass)：StorageClass 的 parameters欄位中添加 assumeRoleArn。

     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

ossfs容器化後如何開啟獨享掛載模式？

問題現象

同一節點上掛載了相同OSS儲存卷的多個Pod共用掛載點。

問題原因

ossfs容器化前，預設使用獨享方式掛載，即每個掛載OSS儲存卷的Pod，都將在對應節點上為該儲存卷拉起ossfs進程。不同ossfs進程對應的掛載點之間完全獨立，即對於掛載了同一OSS儲存卷的不同Pod在讀寫時互不影響。

ossfs容器化後，ossfs進程將以容器的方式運行在Pod中，具體為kube-system或ack-csi-fuse命名空間下名為csi-fuse-ossfs-*的 Pod。在多掛載情境下，獨享方式掛載將在叢集中拉起大量Pod，進而導致彈性網卡不足等問題。因此，容器化後將預設使用共用方式掛載，即同一節點上掛載了相同OSS儲存卷的多個Pod共用掛載點，均對應同一個csi-fuse-ossfs-* Pod，實際由同一ossfs進程實現掛載。

解決方案

如果您期望恢複到容器化前的獨享掛載，請在建立OSS儲存卷時增加useSharedPath配置項，並將其設為"false"。樣本如下：

apiVersion: v1
kind: PersistentVolume
metadata:
  name: oss-pv
spec:
  accessModes:
  - ReadOnlyMany
  capacity:
    storage: 5Gi
  csi:
    driver: ossplugin.csi.alibabacloud.com
    nodePublishSecretRef:
      name: oss-secret
      namespace: default
    volumeAttributes:
      bucket: bucket-name
      otherOpts: -o max_stat_cache_size=0 -o allow_other
      url: oss-cn-zhangjiakou.aliyuncs.com
      useSharedPath: "false" 
    volumeHandle: oss-pv
  persistentVolumeReclaimPolicy: Delete
  volumeMode: Filesystem

使用subpath或subpathExpr方式掛載OSS儲存卷異常

問題現象

使用subpath或subpathExpr方式掛載OSS儲存卷時，出現以下異常：

• 掛載失敗：掛載OSS儲存卷的Pod建立後，一直處於CreateContainerConfigError狀態，並且出現如下類似Event。

  Warning  Failed          10s (x8 over 97s)  kubelet            Error: failed to create subPath directory for volumeMount "pvc-oss" of container "nginx"

• 讀寫異常：掛載OSS儲存卷進行OSS讀寫操作時，出現許可權不足的報錯提示Operation not permitted或Permission denied。

• 卸載失敗：刪除掛載了OSS儲存卷的Pod時，Pod一直處於Terminating狀態。

問題原因

為方便闡述原因及解決方案，假設PV的相關配置為：

...
    volumeAttributes:
      bucket: bucket-name
      path: /path
      ...

Pod的相關配置為：

...
       volumeMounts:
      - mountPath: /path/in/container
        name: oss-pvc
        subPath: subpath/in/oss
      ...

則OSS服務端subpath掛載目錄為Bucket中的/path/subpath/in/oss/。

• 掛載失敗原因：

  • 原因1：OSS服務端不存在掛載目錄/path/subpath/in/oss/，且OSS儲存卷使用的使用者或角色未被授權PutObject許可權（例如唯讀情境中僅配置了OSS ReadOnly許可權）。

    kubelet嘗試在OSS服務端建立/path/subpath/in/oss/目錄時因許可權不足失敗。

  • 原因2：OSS服務端的掛載目錄/path/subpath/in/oss/中某一層的目錄對象（以"/"結尾的key，如path/、path/subpath/等）在檔案系統中被解析為檔案，導致Kubelet無法正常確認subpath路徑狀態。

• 讀寫異常原因：非root使用者啟動並執行業務容器沒有/path/subpath/in/oss/目錄下檔案的許可權（預設為640）。subpath方式掛載OSS儲存卷時，ossfs在OSS服務端實際的掛載目錄為PV中定義的path目錄，即上述樣本中的/path，而非/path/subpath/in/oss/。配置allow_other或mp_umask掛載項僅對/path目錄生效，/path/subpath/in/oss/目錄作為子目錄仍預設為640。

• 卸載失敗原因：OSS服務端中/path/subpath/in/oss/掛載目錄被刪除，阻塞kubelet回收subpath路徑，導致卸載失敗。

解決方案

• 掛載失敗解決方案：

  • 原因1：

    1. 在OSS服務端預先建立/path/subpath/in/oss/目錄，提供kubelet掛載subpath路徑。

    2. 若需要建立的目錄較多（例如通過subpathExpr方式掛載OSS儲存卷），無法全部預先建立時，可為OSS儲存卷使用的使用者或角色增加putObject許可權授權。

  • 原因2：

    1. 參考問題檔案目錄掛載後，顯示為檔案對象的原因1解決方案，確認OSS服務端中各目錄對象（key為path/、path/subpath/等，查詢時請勿以"/"開頭）是否存在，及content-type和content-length欄位。符合以下條件時，該目錄對象將在檔案系統中被異常識別為檔案：

       目錄對象存在（API返回碼為20X，否則content-type和content-length欄位無意義）且目錄對象的content-type非plain、octet-stream或x-directory（如json、tar等）、content-length長度非0.

    2. 如符合以上條件，參考問題檔案目錄掛載後，顯示為檔案對象的原因1解決方案清除異常的目錄對象。

• 讀寫異常解決方案：通過umask配置項修改子目錄預設許可權，例如-o umask=000將預設許可權修改為777。

• 卸載失敗解決方案：請參見OSS靜態卷卸載失敗，Pod一直處於Terminating狀態中的原因2解決方案。

OSS儲存卷訪問Bucket過慢

問題現象

OSS儲存卷訪問Bucket過慢。

問題原因

• 原因1：OSS開啟版本控制後，當Bucket中存在大量刪除標記時，listObjectsV1效能下降。

• 原因2：OSS服務端設定儲存類型為標準儲存（Standard）以外的儲存，其他儲存類型將不同程度地降低資料訪問的效能。

解決方案

• 原因1解決方案：

  1. 升級CSI plugin組件至v1.26.6，ossfs支援通過listObjectsV2訪問Bucket。

  2. 在OSS靜態卷PV的otherOpts欄位中增加-o listobjectsv2來解決。

• 原因2解決方案：修改儲存類型或者解凍檔案。

OSS控制台看到檔案大小為0

問題現象

容器內掛載OSS資料卷時，在檔案中寫入資料，但在OSS控制台看到檔案大小為0。

問題原因

容器使用ossfs掛載OSS，即基於FUSE方式掛載OSS Bucket，只有在檔案執行close或者flush時，檔案內容才會上傳至OSS服務端。

解決方案

使用lsof+檔案名稱的方式，查看檔案是否被其他進程佔用，關閉相應進程，釋放檔案fd。更多資訊，請參見lsof。

業務訪問掛載點報錯"Transport endpoint is not connected"

問題現象

容器內掛載OSS資料卷後，突然訪問掛載點失敗，報錯：Transport endpoint is not connected。

問題原因

容器使用ossfs掛載OSS，業務訪問OSS資料期間，ossfs進程異常退出，導致掛載點處於斷聯狀態。

其中，ossfs進程異常退出的原因主要有：

• 資源不足退出，如OOM Killed。

• ossfs在訪問資料期間因段錯誤退出。

解決方案

1. 確認ossfs進程異常退出原因。

   重要

   若您的線上業務因掛載點斷聯受損，且該異常為偶發現象，您可以先通過重新部署業務容器重新掛載OSS儲存卷進行修複。

   重新掛載OSS儲存卷將導致下述排查流程中所需的部分資訊丟失，相關步驟已註明。

   1. 確認是否因資源不足退出。

      1. Pod維度資源不足：若CSI版本在1.28及以上，確認ossfs所在Pod是否有重啟次數，且上一次異常退出的原因是否為OOM Killed等原因。擷取ossfs所在Pod的方式請參考ossfs 1.0異常問題排查。

      2. 節點維度資源不足：若異常Pod已因重新掛載被刪除，或CSI版本在1.28以下，可通過ACK或ECS監控大盤中確認在掛載儲存卷期間節點是否處於資源高水位狀態。

   2. 確認是否因段錯誤退出。

      1. 若CSI版本在1.28以下，ossfs以進程方式運行在節點上，需登入節點查詢系統日誌。查詢是否有與段錯誤退出相關的資訊。

         journalctl -u ossfs | grep segfault

      2. 若CSI版本在1.28及以上，直接查詢ossfs所在Pod的日誌，確認是否有"signal: segmentation fault"等與段錯誤退出相關的資訊。

         說明

         以下情況會導致無法擷取相關日誌，若已確認ossfs進程非資源不足原因退出，建議您可以先按段錯誤退出進行進一步排查。

         • 若段錯誤發生時間較久，節點或Pod的日誌均可能已因輪轉而丟失。

         • 若已重新掛載業務容器，日誌因被Pod刪除而丟失。

2. 若ossfs因資源不足退出，請適當調整ossfs所在Pod的資源限制，或將掛載OSS儲存卷的業務Pod調度到資源更充裕的節點中。

   若確認是ossfs自身佔用較多記憶體，其原因可能是業務或三方掃描軟體對掛載點的readdir操作觸發ossfs向OSS服務端發送大量的HeadObject請求，您可以考慮開啟readdir最佳化功能，具體請參考新增readdir最佳化功能。

3. 絕大部分低版本ossfs的段錯誤問題均已在1.91及以上版本中修複，若ossfs因段錯誤退出，應優先考慮將ossfs的版本升級至1.91及以上，即升級CSI版本至1.30.4及以上。ossfs版本詳情請參考ossfs 1.0版本說明。

   若您的CSI版本已滿足，請根據以下步驟進一步收集段錯誤coredump檔案並提交工單。

   • 若節點作業系統為Alibaba Cloud Linux 3，節點預設已配置好吐核參數，ossfs段錯誤發生後可登入節點後在/var/lib/systemd/coredump/路徑下找到打包的coredump檔案core.ossfs.xxx.lz4。

   • 對作業系統非Alibaba Cloud Linux 3的節點，需要確認節點允許進程產生coredump檔案。如對於Alibaba Cloud Linux 2節點，可登入節點並執行以下操作：

     echo "|/usr/lib/systemd/systemd-coredump %P %u %g %s %t %c %h %e" > /proc/sys/kernel/core_pattern

     配置後，與Alibaba Cloud Linux 3作業系統類似，ossfs段錯誤發生後可登入節點後在/var/lib/systemd/coredump/路徑下找到打包的coredump檔案core.ossfs.xxx.xz。

業務訪問掛載點報錯"Input/output error"

問題現象

業務訪問掛載點報錯"Input/output error"

問題原因

• 原因1：OSS掛載路徑下的對象名稱包含特殊字元，導致服務端的返回無法解析。

• 原因2：FUSE檔案系統不支援對根掛載點進行chmod、chown等操作。

• 原因3：RAM權限原則的Resource為單個Bucket或其中某目錄許可權時，授權不完整。

解決方案

• 原因1解決方案：

  參考ossfs 1.0異常問題排查，擷取ossfs用戶端日誌，包含類似如下的錯誤記錄檔：

  parser error : xmlParseCharRef: invalid xmlChar value 16
      <Prefix>xxx&#16;xxxx/</Prefix>

  其中，表示某無法解析的Unicode字元；xxxxxxx/表示該對象的完整名稱（樣本為目錄對象）。通過API、控制台等方式確認該對象在OSS服務端存在。OSS控制台該字元可能顯示為空白格。

  參考重新命名檔案，重新命名OSS服務端的對象。若該對象為目錄，建議參考常用操作，使用ossbrowser 2.0的方式重新命名整個目錄。

• 原因2解決方案：

  使用-o allow_other、-o mp_umask掛載參數對掛載路徑實作類別似chmod的效果：

  參數	說明
  allow_other	設定掛載目錄的許可權為777。
  mp_umask	用於設定掛載目錄的許可權掩碼，只有當allow_other選項設定後，該選項才生效。預設值為000。例如： 需設定掛載目錄的許可權為770，則增加-o allow_other -o mp_umask=007。 需設定掛載目錄的許可權為700，則增加-o allow_other -o mp_umask=077。

  使用-o gid、-o uid掛載參數對掛載路徑實作類別似chown的效果：

  參數	說明
  uid	指定掛載目錄下子目錄及檔案歸屬使用者的使用者UID。
  gid	指定掛載目錄下子目錄及檔案歸屬使用者的使用者GID。

• 原因3解決方案：

  若需要僅為某個Bucket或Bucket中的某個路徑授權，請參考2. 建立RAM角色並授權中的授權策略，需要同時為mybucket及mybucket/*（授權某Bucket），或mybucket/subpath及mybucket/subpath/*授權（授權某路徑）。

檔案目錄掛載後，顯示為檔案對象

問題現象

容器內掛載OSS資料卷時，檔案原本是目錄，掛載後顯示為檔案對象。

問題原因

• 原因1：目錄對象在OSS服務端content-type類型是非預設的application/octet-stream類型（例如text/html、image/jpeg等），或目錄對象的大小非0，ossfs根據其元資訊將其視為檔案對象。

• 原因2：非原因1的情況，但目錄對象缺少元資訊x-oss-meta-mode。

解決方案

• 原因1解決方案：

  通過HeadObject或stat（查看Bucket和Object資訊）擷取目錄對象元資訊，目錄對象需要以"/"結尾（例如a/b/），以API返回為例。

  {
    "server": "AliyunOSS",
    "date": "Wed, 06 Mar 2024 02:48:16 GMT",
    "content-type": "application/octet-stream",
    "content-length": "0",
    "connection": "keep-alive",
    "x-oss-request-id": "65E7D970946A0030334xxxxx",
    "accept-ranges": "bytes",
    "etag": "\"D41D8CD98F00B204E9800998ECFxxxxx\"",
    "last-modified": "Wed, 06 Mar 2024 02:39:19 GMT",
    "x-oss-object-type": "Normal",
    "x-oss-hash-crc6xxxxx": "0",
    "x-oss-storage-class": "Standard",
    "content-md5": "1B2M2Y8AsgTpgAmY7Phxxxxx",
    "x-oss-server-time": "17"
  }

  以上返回樣本中：

  • content-type：為application/octet-stream，即目錄對象為application/octet-stream類型。

  • content-length：為0，即目錄對象大小為0。

  若不滿足以上條件，您可以通過以下方式修複：

  1. 通過GetObject或命令列工具ossutil快速入門擷取該對象，確認資料是否有用。若資料有用或不能確定，建議對其進行備份，例如變更名稱（對xx/目錄對象，請勿使用xx作為新的名稱）後上傳至OSS。

  2. 通過DeleteObject或rm（刪除）刪除有問題的目錄對象，然後確認ossfs是否正常顯示目錄。

• 原因2解決方案：

  若通過原因1的解決方案未修複問題，您可以在容器內掛載OSS資料卷時，在OSS靜態卷PV的otherOpts欄位中增加-o complement_stat來解決。

  說明

  CSI plugin組件版本為v1.26.6及以上版本時，配置項已預設開啟，您可以將儲存群組件升級至v1.26.6或以上版本，重啟業務Pod並重新掛載OSS靜態卷解決問題。

OSS服務端監控到大量異常請求流量

問題現象

容器內掛載OSS資料卷時，OSS服務端監控到請求數量遠超預期。

問題原因

ossfs掛載OSSObject Storage Service時，將在節點上產生掛載路徑，ECS上的其他進程對掛載點的掃描也會轉換為向OSS的請求。請求次數過多會產生費用。

解決方案

通過審計追蹤請求進程並修複。您可以在節點上進行如下操作。

1. 安裝auditd並啟動。

   sudo yum install auditd
   sudo service auditd start

2. 將ossfs掛載路徑設為監測目錄。

   • 如需添加所有掛載路徑，請執行以下命令。

     for i in $(mount | grep -i ossfs | awk '{print $3}');do auditctl -w ${i};done

   • 如需添加某個PV的掛載路徑，請執行以下命令。

     <pv-name>為指定的PV名稱。

     for i in $(mount | grep -i ossfs | grep -i <pv-name> | awk '{print $3}');do auditctl -w ${i};done

3. 在auditlog中查看哪些進程訪問了OSS Bucket中的路徑。

   ausearch -i 

   審計日誌分析樣本如下。以下樣本中，---分隔字元間的審計日誌為一組，記錄對監控掛載點的單次操作。該樣本表示updatedb進程對掛載點中的子目錄進行了open的操作，進程PID為1636611。

   ---
   type=PROCTITLE msg=audit(2023年09月22日 15:09:26.244:291) : proctitle=updatedb
   type=PATH msg=audit(2023年09月22日 15:09:26.244:291) : item=0 name=. inode=14 dev=00:153 mode=dir,755 ouid=root ogid=root rdev=00:00 nametype=NORMAL cap_fp=none cap_fi=none cap_fe=0 cap_fver=0
   type=CWD msg=audit(2023年09月22日 15:09:26.244:291) : cwd=/subdir1/subdir2
   type=SYSCALL msg=audit(2023年09月22日 15:09:26.244:291) : arch=x86_64 syscall=open success=yes exit=9 a0=0x55f9f59da74e a1=O_RDONLY|O_DIRECTORY|O_NOATIME a2=0x7fff78c34f40 a3=0x0 items=1 ppid=1581119 pid=1636611 auid=root uid=root gid=root euid=root suid=root fsuid=root egid=root sgid=root fsgid=root tty=pts1 ses=1355 comm=updatedb exe=/usr/bin/updatedb key=(null)
   ---

4. 藉助日誌進一步確認是否存在非業務的進程調用，並進行修複。

   例如，通過auditlog查到updatedb掃描了所掛載的目錄，可以通過修改/etc/updatedb.conf讓它跳過。具體操作如下。

   1. 在RUNEFS =後面加上fuse.ossfs。

   2. 在PRUNEPATHS =後面加上掛載的目錄。

通過OSS儲存卷寫入的檔案對象的中繼資料Content-Type全為application/octet-stream類型

問題現象

通過OSS儲存卷寫入的檔案對象的中繼資料Content-Type全為application/octet-stream類型，導致瀏覽器或其他用戶端未能正確識別和處理這些檔案。

問題原因

• 未指定Content-Type類型，ossfs預設將檔案對象視為二進位流檔案。

• 通過/etc/mime.types設定檔指定Content-Type類型，但未生效。

解決方案

1. 確認CSI組件版本，1.26.6和1.28.1版本的組件對Content-Type配置存在相容性問題。若使用了相關版本，請升級CSI至最新版本。更多資訊，請參見【組件公告】關於1.26.6和1.28.1版本的csi-plugin和csi-provisioner組件相容性問題。

2. 若您已經通過使用mailcap、mime-support在節點上產生/etc/mime.types的方式指定Content-Type類型，升級CSI版本後，重新掛載對應OSS儲存卷即可。

3. 若您未指定Content-Type類型，可通過以下兩種方式指定：

   • 節點層級配置：在節點上產生/etc/mime.types設定檔，對所有新掛載到該節點上的OSS儲存卷生效。更多資訊，請參見常見問題。

   • 叢集層級配置：該方式對叢集所有新掛載的OSS儲存卷生效，/etc/mime.types內容與mailcap預設產生的內容一致。

     1. 檢查csi-plugin設定檔是否存在。

        kubectl -n kube-system get cm csi-plugin

        若不存在，使用以下內容建立csi-plugin同名ConfigMap；若不存在，則需要在原ConfigMap中增加data.fuse-ossfs中的內容mime-support="true"。

        apiVersion: v1
        kind: ConfigMap
        metadata:
          name: csi-plugin
          namespace: kube-system
        data:
          fuse-ossfs: |
            mime-support=true

     2. 重啟csi-plugin，使配置生效。

        重啟csi-plugin不會影響當前已經成功掛載的儲存卷的使用。

        kubectl -n kube-system delete pod -l app=csi-plugin

4. 重新掛載對應的OSS儲存卷。

建立永久連結時返回錯誤Operation not supported或Operation not permitted

問題現象

建立永久連結時返回錯誤Operation not supported或Operation not permitted。

問題原因

OSS儲存卷不支援永久連結操作，將返回Operation not supported錯誤。在早期的CSI版本中，永久連結操作返回的報錯為Operation not permitted。

解決方案

改造業務，在使用OSS儲存卷時，應避免永久連結操作。若您的業務必須使用永久連結操作，建議您更換儲存。

如何查看通過OSS儲存卷訪問OSS的記錄？

您可以在OSS管理主控台查看OSS的操作記錄。請確保已開通即時日誌查詢。

1. 登入OSS管理主控台。

2. 單擊Bucket 列表，然後單擊目標Bucket名稱。

3. 在左側導覽列，選擇日誌管理 > 即時查詢。

4. 在即時查詢頁簽下，根據查詢文法和分析文法，輸入查詢和分析語句，對OSS日誌進行分析。您可以通過user_agent和client_ip欄位定位日誌是否來源於ACK。

   1. 定位由ACK發送的OSS操作請求時，您需要選擇user_agent欄位，展開後看到user_agent裡包含ossfs的都可以選擇。

      重要

      • user-agent欄位的值與ossfs版本有關，ossfs版本不同，user-agent欄位的值也不一樣，但均以aliyun-sdk-http/1.0()/ossfs開頭。

      • 如果您在ECS上也通過ossfs掛載，相關日誌也會被耦合到這裡。

   2. 如需定位到某個ECS執行個體或叢集，您可以選擇client_ip欄位，然後選擇對應的IP。

   結合以上兩個欄位選擇，查詢到的日誌樣本如下圖所示。

   日誌查詢部分欄位說明

   欄位	說明
   operation	對OSS操作的類型。例如GetObject、GetBucketStat等。更多資訊，請參見API概覽。
   object	對象名稱，OSS中的目錄、檔案。
   request_id	請求的唯一標識，如果有請求ID，您可以精確查詢某個請求。
   http_status、error_code	針對請求結果的查詢。更多資訊，請參見HTTP錯誤碼。

共用掛載方式下，如何重啟ossfs進程？

問題現象

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

問題原因

• ossfs運行後無法變更鑒權資訊等配置，變更配置後，需要重啟ossfs進程（容器化版本後，即為kube-system或ack-csi-fuse命名空間下的csi-fuse-ossfs-* Pod）與對應的應用Pod，造成業務中斷。因此，預設情況下CSI不會對已經啟動並執行ossfs進行變更。

• 正常使用流程中，ossfs的部署與刪除均由CSI完成。手動刪除ossfs進程所在的Pod後，無法觸發CSI的重新部署與相關資源（如VolumeAttachment）的刪除。

解決方案

若您使用的是非容器化的CSI版本，或開啟了獨享掛載，可以直接重啟對應的應用Pod。容器化版本後，預設使用共用掛載方式，即每個節點上掛載同一OSS儲存卷的所有應用Pod共用ossfs進程實現掛載。

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

   1. 執行以下命令，確認需要變更的csi-fuse-ossfs-* Pod。

      其中<pv-name>為PV名稱，<node-name>為節點名稱。

      CSI版本小於1.30.4時，執行以下操作：

      kubectl -n kube-system get pod -lcsi.alibabacloud.com/volume-id=<pv-name> -owide | grep <node-name>

      CSI版本大於等於1.30.4時，執行以下操作

      kubectl -n ack-csi-fuse get pod -lcsi.alibabacloud.com/volume-id=<pv-name> -owide | grep <node-name>

      預期輸出：

      csi-fuse-ossfs-xxxx   1/1     Running   0          10d     192.168.128.244   cn-beijing.192.168.XX.XX   <none>           <none>

   2. 執行以下命令，確認正在掛載該OSS儲存卷的所有Pod。

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

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

      預期輸出（包含User By）：

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

   4. 執行以下命令，擷取通過csi-fuse-ossfs-xxxx掛載的Pod，即與csi-fuse-ossfs-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.100.11   cn-beijing.192.168.100.3     <none>           <none>
      oss-static-94849f647-6****   1/1     Running   0          7m36s   192.168.100.18   cn-beijing.192.168.100.3     <none>           <none>

2. 重啟業務與ossfs進程。

   將應用Pod（上述樣本中為oss-static-94849f647-4****和oss-static-94849f647-6****）通過kubectl scale等方式同時刪除。在無應用Pod掛載時，csi-fuse-ossfs-xxxx Pod將自動被回收；恢複副本數後，將使用PV的新配置重新掛載，由CSI建立新的csi-fuse-ossfs-yyyy Pod。

   如果無法保證這些Pod能同時被刪除（如刪除Deployment、StatefulSet、DaemonSet管理的Pod均會立即觸發重啟），或Pod能容忍OSS讀寫失敗：

   • CSI版本小於1.30.4時，您可以直接刪除csi-fuse-ossfs-xxxx Pod，此時應用Pod內讀寫OSS將返回disconnected error。

   • CSI版本大於等於1.30.4時，您可以執行以下操作：

     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-ossfs-yyyy Pod恢複OSS讀寫。

如何查看掛載OSS儲存卷時使用的ossfs版本？

ossfs的版本隨CSI版本迭代，ACK使用的ossfs版本基於OSS公開版本，版本表達方式為1.91.1.ack.1，詳情請參考版本說明。公開版本查詢請參考安裝ossfs 1.0、安裝ossfs 2.0。

• 不同的CSI組件版本對應掛載OSS儲存卷時預設使用的ossfs版本。可查詢csi-provisioner。

  說明

  CSI版本小於1.28且不包含1.26.6時，ossfs 1.0運行在節點上，使用的ossfs版本以節點實際安裝版本為準。需參考以下方式查詢ossfs版本。

• 對於已經掛載的OSS儲存卷，可參考查看ossfs版本。

CSI 組件的版本決定了其預設使用的 ossfs 版本。ACK 使用的 ossfs 版本在其社區版號後增加了 .ack.x尾碼（如 1.91.1.ack.1），詳見版本說明。

社區公開版本資訊，請參見安裝ossfs 1.0、安裝ossfs 2.0。

可通過以下方式查詢版本資訊：

• 版本對應關係：瞭解不同 CSI 版本對應的 ossfs 版本，請查閱csi-provisioner。

  對於較老的 CSI 版本（v1.28 之前且非 v1.26.6），ossfs 1.0直接運行在節點上，其版本由節點上安裝的版本決定，不受 CSI 控制，請直接通過實際版本查詢。

• 驗證實際版本：確認當前已掛載儲存卷正在啟動並執行 ossfs 確切版本，請參見查看ossfs版本。

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

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

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

OSS靜態卷卸載失敗，Pod一直處於Terminating狀態

問題現象

OSS靜態卷卸載失敗，Pod一直處於Terminating狀態。

問題原因

Pod刪除時卡在Terminating的原因較多，可先藉助kubelet日誌定位。導致OSS儲存卷卸載失敗的常見原因如下：

• 原因1：對應掛載點在節點上被佔用，CSI儲存外掛程式無法正常unmount掛載點。

• 原因2：PV中指定的OSS bucket或目錄（path）被刪除，無法判斷當前掛載點狀態。

解決方案

• 原因1解決方案

  1. 在叢集中執行以下命令，擷取Pod的UID。

     替換以下<ns-name>和<pod-name>為您的業務實際值。

     kubectl -n <ns-name> get pod <pod-name> -ogo-template --template='{{.metadata.uid}}'

     預期輸出：

     5fe0408b-e34a-497f-a302-f77049****

  2. 登入Terminating的Pod所在的節點。

  3. 在節點上執行以下命令，查詢當前是否有進程佔用掛載點。

     lsof /var/lib/kubelet/pods/<pod-uid>/volumes/kubernetes.io~csi/<pv-name>/mount/

     若有輸出，請確認並清理相關進程。

• 原因2解決方案

  1. 登入OSS管理主控台。

  2. 查詢Bucket或目錄是否被刪除，若您使用了subpath方式掛載OSS儲存卷，還需要確認subpath掛載目錄是否被刪除。

  3. 確認由於刪除目錄導致的卸載失敗，請參考以下操作處理。

     1. 在叢集中執行以下命令，擷取Pod的UID。

        替換以下<ns-name>和<pod-name>為您的業務實際值。

        kubectl -n <ns-name> get pod <pod-name> -ogo-template --template='{{.metadata.uid}}'

        預期輸出：

        5fe0408b-e34a-497f-a302-f77049****

     2. 登入Terminating的Pod所在的節點，在節點上執行以下命令，查詢Pod相關的掛載點。

        mount | grep <pod-uid> | grep fuse.ossfs

        預期輸出：

        ossfs on /var/lib/kubelet/pods/<pod-uid>/volumes/kubernetes.io~csi/<pv-name>/mount type fuse.ossfs (ro,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other)
        ossfs on /var/lib/kubelet/pods/<pod-uid>/volume-subpaths/<pv-name>/<container-name>/0 type fuse.ossfs (ro,relatime,user_id=0,group_id=0,allow_other)

        其中ossfs on與type之間路徑為節點上的實際掛載點。

     3. 手動umount掛載點。

        umount /var/lib/kubelet/pods/<pod-uid>/volumes/kubernetes.io~csi/<pv-name>/mount
        umount /var/lib/kubelet/pods/<pod-uid>/volume-subpaths/<pv-name>/<container-name>/0

     4. 等待kubelet重試時正常回收，或者直接通過--force刪除Pod。