FAQ volume persisten ossfs 2.0 - Container Service for Kubernetes

Atasi kegagalan mount, konfigurasikan akses lintas akun, dan kelola volume ossfs 2.0 di ACK.

Diagnosis masalah pod ossfs 2.0

Sebelum melakukan troubleshooting, periksa status dan event pod ossfs 2.0:

# Periksa event pod untuk error mount
kubectl describe pod <pod-name> -n <namespace>

# Periksa apakah pod ossfs 2.0 ada dan sedang Berjalan
kubectl -n ack-csi-fuse get pod -l csi.alibabacloud.com/volume-id=<pv-name> -owide

Cocokkan error dalam event pod dengan bagian relevan di bawah ini.

Kegagalan mount

Pod gagal memulai dengan FailedMount karena izin AccessKey

Pod melaporkan FailedMount karena AccessKey tidak memiliki izin yang diperlukan.

Untuk mengatasi hal ini:

Verifikasi bahwa kebijakan akses Pengguna RAM memenuhi persyaratan mounting OSS. Lihat Gunakan volume ossfs 2.0 yang disediakan secara statis.
Konfirmasi bahwa AccessKey tidak dinonaktifkan atau diganti.

Penting

Perubahan AccessKey dalam Secret yang ditentukan oleh nodePublishSecretRef tidak berlaku pada proses ossfs 2.0 yang sedang berjalan. Restart pod ossfs 2.0 untuk menerapkan kredensial baru. Lihat Restart proses ossfs 2.0.

Pod pada node virtual gagal dengan "secrets is forbidden"

Event pod berisi:

failed to get secret secrets "xxx" is forbidden: User "serverless-xxx" cannot get resource "secrets" in API group "" in the namespace "xxx"

Pada node virtual (pod Container Compute Service), Secret yang dirujuk oleh nodePublishSecretRef harus berada dalam namespace yang sama dengan PersistentVolumeClaim (PVC).

Buat Secret di namespace PVC tersebut. Di PV, atur nodePublishSecretRef untuk merujuk Secret ini. Lihat Autentikasi menggunakan AccessKey Pengguna RAM.

Pod gagal dengan "mounter.sock: connect: no such file or directory"

Event pod berisi:

FailedMount /run/fuse.ossfs/xxxxxx/mounter.sock: connect: no such file or directory

Pod ossfs 2.0 tidak dimulai dengan benar atau dihapus secara tak terduga.

Periksa apakah pod ossfs 2.0 ada di node tempat pod aplikasi dijadwalkan:
- Jika pod ada tetapi tidak dalam status Running, lakukan troubleshooting. Setelah mencapai status Running, restart pod aplikasi untuk memicu remount.
- Jika pod tidak ada, lanjutkan ke langkah berikutnya.
```
   kubectl -n ack-csi-fuse get pod -l csi.alibabacloud.com/volume-id=<PV_NAME> -owide | grep <NODE_NAME>
```
(Opsional) Periksa log audit untuk penghapusan pod yang tidak terduga. Penyebab umum: skrip pembersihan, drain node, dan auto-healing. Sesuaikan konfigurasi untuk mencegah pengulangan.

Periksa sisa resource VolumeAttachment:

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

Restart pod aplikasi untuk memicu remount dan verifikasi bahwa pod ossfs 2.0 baru dibuat.

Mount gagal karena bucket menggunakan mirroring-based back-to-origin

Jika bucket OSS menggunakan mirroring-based back-to-origin dan direktori mount belum disinkronkan dari origin, mount akan gagal.

Sinkronkan data dari origin sebelum melakukan mount. Lihat Ikhtisar back-to-origin.

Mount gagal karena bucket memiliki static website hosting yang diaktifkan

Dengan static website hosting diaktifkan, pemeriksaan direktori ossfs 2.0 akan dialihkan ke file seperti index.html, sehingga menyebabkan kegagalan mount.

Nonaktifkan atau sesuaikan static website hosting sebelum melakukan mount. Lihat Static website hosting.

Konfigurasi mount

Mount satu file dari bucket OSS

ossfs 2.0 melakukan mount path bucket OSS sebagai sistem file — tidak dapat melakukan mount satu file saja. Untuk mengakses file tertentu, mount direktori induknya dan gunakan subPath dalam volumeMounts.

Sebagai contoh, untuk melakukan mount a.txt dan b.txt dari bucket:/subpath ke pod berbeda di /path/to/file/:

Konfigurasi PV — mount direktori induk:

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              # Path induk yang berisi a.txt dan b.txt
      url: "oss-cn-hangzhou.aliyuncs.com"
      fuseType: ossfs2

volumeMounts Pod — gunakan subPath untuk memilih file:

  volumeMounts:
    - mountPath: /path/to/file   # Memetakan ke bucket:/subpath
      name: oss-pvc              # Harus sesuai dengan nama volume
      subPath: a.txt             # Path relatif di dalam bucket:/subpath

Setelah mount, /path/to/file/a.txt di dalam pod memetakan ke bucket:/subpath/a.txt.

Lihat Gunakan volume ossfs 2.0 yang disediakan secara statis.

Mount bucket OSS dari akun berbeda

Gunakan RRSA (RAM Roles for Service Accounts) untuk melakukan mount bucket lintas akun.

Verifikasi bahwa versi kluster dan komponen CSI Anda memenuhi persyaratan RRSA.

Prosedur berikut melakukan mount bucket di Akun B ke kluster di Akun A.

Di Akun B (tempat bucket berada):

Buat peran RAM bernama roleB yang mempercayai Akun A. Lihat Buat peran RAM untuk akun Alibaba Cloud tepercaya.
Berikan izin kepada roleB untuk mengakses bucket OSS target.
Di Konsol RAM, buka halaman detail roleB dan salin ARN-nya. Contoh: acs:ram::130xxxxxxxx:role/roleB.

Di Akun A (tempat kluster berada):

Buat peran RAM bernama roleA untuk RRSA. Atur tipe entitas tepercaya ke OIDC IdP.
Berikan izin kepada roleA untuk mengasumsikan roleB. roleA tidak memerlukan kebijakan akses OSS — lampirkan kebijakan dengan aksi sts:AssumeRole, seperti AliyunSTSAssumeRoleAccess. Lihat Aktifkan RRSA di kluster (volume statis) atau Gunakan volume ossfs 1.0 yang disediakan secara dinamis (volume dinamis).

Konfigurasi volume — atur assumeRoleArn ke ARN dari roleB:

Volume yang disediakan secara statis (PV): Tambahkan ke volumeAttributes:
```
  assumeRoleArn: <ARN of roleB>
```
Volume yang disediakan secara dinamis (StorageClass): Tambahkan ke parameters:
```
  assumeRoleArn: <ARN of roleB>
```

Gunakan CoreDNS untuk menyelesaikan titik akhir akses OSS

Untuk menyelesaikan titik akhir OSS melalui domain internal kluster, konfigurasikan kebijakan DNS untuk pod ossfs agar memprioritaskan CoreDNS selama proses mount.

Memerlukan komponen CSI versi v1.34.2 atau lebih baru. Untuk upgrade, lihat Kelola komponen CSI.

Volume statis (PV): Tambahkan dnsPolicy ke spec.csi.volumeAttributes.
```
dnsPolicy: ClusterFirstWithHostNet
```
Volume dinamis (StorageClass): Tambahkan dnsPolicy ke parameters.
```
dnsPolicy: ClusterFirstWithHostNet
```

Gunakan ARN atau ServiceAccount kustom untuk RRSA

Secara default, menyetel roleName di PV memungkinkan CSI secara otomatis mengambil ARN Role dan ARN Penyedia OIDC. Untuk kontrol lebih lanjut — seperti menggunakan OIDC IdP pihak ketiga atau ServiceAccount non-default — tentukan langsung roleArn dan oidcProviderArn.

roleArn dan oidcProviderArn harus dikonfigurasi bersamaan. Jika diatur, nilai-nilai ini menggantikan 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               # Harus sesuai dengan nama PV
    volumeAttributes:
      bucket: "oss"
      url: "oss-cn-hangzhou.aliyuncs.com"
      authType: "rrsa"
      fuseType: "ossfs2"
      oidcProviderArn: "<oidc-provider-arn>"
      roleArn: "<role-arn>"
      # roleName: "<role-name>"        # Diabaikan saat roleArn dan oidcProviderArn diatur
      serviceAccountName: "csi-fuse-<service-account-name>"

Parameter	Deskripsi
`oidcProviderArn`	ARN dari OIDC IdP. Lihat Kelola penyedia identitas OIDC.
`roleArn`	ARN dari peran RAM yang mempercayai OIDC IdP. Lihat Contoh SSO berbasis peran yang menggunakan OIDC.
`serviceAccountName`	Opsional. Nama ServiceAccount untuk pod kontainer ossfs. Harus diawali dengan `csi-fuse-` dan telah dibuat sebelumnya. Jika tidak diatur, CSI menggunakan ServiceAccount default-nya.

Kapasitas

Melebihi kapasitas volume yang dikonfigurasi

OSS tidak memberlakukan batas kapasitas pada bucket atau subdirektori. Nilai .spec.capacity (PV) dan .spec.resources.requests.storage (PVC) diabaikan — pastikan nilainya sesuai antara PV dan PVC yang terikat.

Jika penggunaan aktual melebihi kapasitas yang dikonfigurasi, volume tetap beroperasi normal. Tidak diperlukan scaling.

Operasi

Restart proses ossfs 2.0

Setelah memodifikasi kredensial atau versi ossfs 2.0, proses yang sedang berjalan tidak secara otomatis menerapkan perubahan tersebut. Menerapkan perubahan memerlukan restart baik pod ossfs 2.0 (csi-fuse-ossfs2-* di ack-csi-fuse) maupun semua pod aplikasi yang menggunakan volume tersebut, yang menyebabkan gangguan layanan.

Penting

Jangan hapus pod ossfs 2.0 secara manual. CSI tidak dapat memulihkan atau membuat ulang pod yang dihapus di luar manajemen siklus hidupnya.

Prosedur:

Identifikasi pod ossfs 2.0 target. Ganti <pv-name> dan <node-name>:

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

Identifikasi semua pod aplikasi yang menggunakan volume ini. Ganti <ns> dan <pvc-name>. Bidang Used By mencantumkan pod tersebut:

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

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

Temukan pod aplikasi pada node yang sama dengan pod ossfs 2.0:
```
   kubectl -n <ns> get pod -owide | grep <node-name>
```
Hapus semua pod aplikasi secara simultan. Gunakan kubectl scale atau setara. Saat tidak ada pod yang mereferensikan mount tersebut, CSI akan mereklaim pod csi-fuse-ossfs2-*. Setelah replika dipulihkan, volume akan dimount ulang dengan konfigurasi yang diperbarui.

Pendekatan alternatif — jika penghapusan simultan tidak memungkinkan (misalnya, Deployment, StatefulSet, atau DaemonSet segera membuat ulang pod yang dihapus), atau aplikasi dapat mentoleransi kegagalan baca/tulis OSS sementara:

Temukan VolumeAttachment untuk volume tersebut. Output yang diharapkan:

   kubectl get volumeattachment | grep <pv-name> | grep <node-name>

   csi-bd463c719189f858c2394608da7feb5af8f181704b77a46bbc219b**********   ossplugin.csi.alibabacloud.com   <pv-name>   <node-name>   true   12m

Hapus VolumeAttachment tersebut. Pod aplikasi akan mengembalikan disconnected error pada operasi OSS.
Restart pod aplikasi satu per satu. Masing-masing akan terhubung ke pod csi-fuse-ossfs2-* baru dengan konfigurasi yang diperbarui.