Связаться с намиПодключиться

Интеграция с Object Storage

Статья создана
Улучшена
Обновлена 6 августа 2025 г.

Container Storage Interface позволяет динамически резервировать бакеты Yandex Object Storage и монтировать их к подам кластера Managed Service for Kubernetes. При этом можно монтировать уже существующие бакеты или создавать новые.

Чтобы воспользоваться возможностями Container Storage Interface:

  1. Подготовьте рабочее окружение.
  2. Настройте Container Storage Interface.

См. также:

Подготовка рабочего окружения

  1. Создайте сервисный аккаунт с ролью storage.editor.
  2. Создайте статический ключ доступа для сервисного аккаунта. Сохраните идентификатор ключа и секретный ключ — они понадобятся при установке Container Storage Interface.
  3. Создайте бакет Object Storage, который будет смонтирован к PersistentVolume. Сохраните имя бакета — оно понадобится при установке Container Storage Interface.

  4. Установите kubectl и настройте его на работу с созданным кластером.

Настройка Container Storage Interface

  1. Создайте файл secret.yaml, в котором укажите настройки доступа для Container Storage Interface:

    ---
apiVersion: v1
kind: Secret
metadata:
  namespace: kube-system
  name: csi-s3-secret
stringData:
  accessKeyID: <идентификатор_ключа_доступа>
  secretAccessKey: <секретный_ключ>
  endpoint: https://storage.yandexcloud.kz

    В полях accessKeyID и secretAccessKey укажите полученные ранее идентификатор и значение секретного ключа.

  2. Создайте файл с описанием класса хранилища storageclass.yaml:

    ---
kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: csi-s3
provisioner: ru.yandex.s3.csi
parameters:
  mounter: geesefs
  options: "--memory-limit=1000 --dir-mode=0777 --file-mode=0666"
  bucket: <имя_существующего_бакета>
  csi.storage.k8s.io/provisioner-secret-name: csi-s3-secret
  csi.storage.k8s.io/provisioner-secret-namespace: kube-system
  csi.storage.k8s.io/controller-publish-secret-name: csi-s3-secret
  csi.storage.k8s.io/controller-publish-secret-namespace: kube-system
  csi.storage.k8s.io/node-stage-secret-name: csi-s3-secret
  csi.storage.k8s.io/node-stage-secret-namespace: kube-system
  csi.storage.k8s.io/node-publish-secret-name: csi-s3-secret
  csi.storage.k8s.io/node-publish-secret-namespace: kube-system

    Параметр bucket опциональный. Задайте его, чтобы использовать существующий бакет. Эта настройка актуальна только для динамических PersistentVolume.

  3. Клонируйте GitHub-репозиторий, содержащий актуальный драйвер Container Storage Interface:

    git clone https://github.com/yandex-cloud/k8s-csi-s3.git

  4. Создайте ресурсы для Container Storage Interface и класс хранилища:

    kubectl create -f secret.yaml && \
kubectl create -f k8s-csi-s3/deploy/kubernetes/provisioner.yaml && \
kubectl create -f k8s-csi-s3/deploy/kubernetes/driver.yaml && \
kubectl create -f k8s-csi-s3/deploy/kubernetes/csi-s3.yaml && \
kubectl create -f storageclass.yaml

    После установки драйвера Container Storage Interface и настройки класса хранилища можно создавать статические и динамические PersistentVolume, которые будут использовать бакеты Object Storage.

Использование Container Storage Interface

При настроенном Container Storage Interface создание статических и динамических PersistentVolumes имеет свои особенности.

Динамический PersistentVolume

При работе с динамическим PersistentVolume:

  • Укажите имя нужного класса хранилища в параметре spec.storageClassName при создании PersistentVolumeClaim.
  • При необходимости укажите имя бакета в параметре bucket (в настройках приложения Yandex Cloud Marketplace — поле Общий бакет S3 для томов) при создании класса хранилища. Это влияет на поведение Container Storage Interface:

    • Если при настройке класса хранилища было указано имя бакета, Container Storage Interface создаст отдельный каталог внутри этого бакета на каждый созданный PersistentVolume.

      Примечание

      Такая настройка может быть полезна, если в облаке действуют строгие квоты на количество бакетов Object Storage.

    • Если при настройке класса хранилища не было указано имя бакета, то Container Storage Interface создаст отдельный бакет на каждый созданный PersistentVolume.

См. также пример создания динамического PersistentVolume.

Статический PersistentVolume

При работе со статическим PersistentVolume:

  • Укажите пустое значение параметра spec.storageClassName при создании PersistentVolumeClaim.

  • Укажите имя нужного бакета или директории бакета в параметре spec.csi.volumeHandle при создании PersistentVolume. Если такого бакета не существует — создайте его.

    Примечание

    При удалении такого PersistentVolume соответствующий ему бакет не будет удален автоматически.

  • Если вам нужно изменить опции клиента GeeseFS для работы с бакетом, укажите их в параметре spec.csi.volumeAttributes.options при создании PersistentVolume. Например, в опции --uid можно указать идентификатор пользователя-владельца всех файлов в хранилище. Список опций GeeseFS см. с помощью команды geesefs -h или в репозитории на GitHub.

    Опции GeeseFS, указанные в параметре parameters.options (в настройках приложения Yandex Cloud Marketplace — поле Опции монтирования GeeseFS) класса хранилища (StorageClass), для статических PersistentVolume игнорируются. Подробнее см. в документации Kubernetes.

См. также пример создания статического PersistentVolume.

Примеры использования

Динамический PersistentVolume

Чтобы использовать Container Storage Interface совместно с динамическим PersistentVolume:

  1. Настройте Container Storage Interface.

  2. Создайте PersistentVolumeClaim:

    1. Создайте файл pvc-dynamic.yaml, содержащий описание PersistentVolumeClaim:

      pvc-dynamic.yaml
      ---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-s3-pvc-dynamic
  namespace: default
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  storageClassName: csi-s3

      При необходимости измените размер запрашиваемого хранилища в значении параметра spec.resources.requests.storage.

    2. Создайте PersistentVolumeClaim:

      kubectl create -f pvc-dynamic.yaml

    3. Убедитесь, что PersistentVolumeClaim перешел в состояние Bound:

      kubectl get pvc csi-s3-pvc-dynamic

      Результат:

      NAME                STATUS  VOLUME                    CAPACITY  ACCESS MODES  STORAGECLASS  AGE
csi-s3-pvc-dynamic  Bound   pvc-<имя_dynamic-бакета>  5Gi       RWX           csi-s3        73m

  3. Создайте под для проверки динамического PersistentVolume.

    1. Создайте файл pod-dynamic.yaml, содержащий описание пода:

      pod-dynamic.yaml
      ---
apiVersion: v1
kind: Pod
metadata:
  name: csi-s3-test-nginx-dynamic
  namespace: default
spec:
  containers:
  - name: csi-s3-test-nginx
    image: nginx
    volumeMounts:
      - mountPath: /usr/share/nginx/html/s3
        name: webroot
  volumes:
    - name: webroot
      persistentVolumeClaim:
        claimName: csi-s3-pvc-dynamic
        readOnly: false

    2. Создайте под, на котором будет смонтирован бакет для динамического PersistentVolume:

      kubectl create -f pod-dynamic.yaml

    3. Убедитесь, что под перешел в состояние Running:

      kubectl get pods

  4. Создайте в контейнере файл /usr/share/nginx/html/s3/hello_world. Для этого выполните команду на поде:

    kubectl exec -ti csi-s3-test-nginx-dynamic -- touch /usr/share/nginx/html/s3/hello_world

  5. Убедитесь, что файл попал в бакет:

    1. Перейдите на страницу каталога и выберите сервис Object Storage.
    2. Нажмите на бакет pvc-<имя_dynamic-бакета>. Если при настройке класса хранилища было указано имя бакета, то откройте указанный бакет и каталог pvc-<имя_dynamic-бакета> внутри него.

Статический PersistentVolume

Чтобы использовать Container Storage Interface совместно со статическим PersistentVolume:

  1. Настройте Container Storage Interface.

  2. Создайте PersistentVolumeClaim:

    1. Создайте файл pvc-static.yaml, содержащий описание PersistentVolumeClaim:

      pvc-static.yaml
      ---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-s3-pvc-static
  namespace: default
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi
  storageClassName: ""

      Для статического PersistentVolume имя класса хранилища в параметре spec.storageClassName не указывается. При необходимости измените размер запрашиваемого хранилища в значении параметра spec.resources.requests.storage.

    2. Создайте файл pv-static.yaml, содержащий описание статического PersistentVolume, и укажите в нем значение параметра volumeHandle:

      pv-static.yaml
      ---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: s3-volume
spec:
  storageClassName: csi-s3
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteMany
  claimRef:
    namespace: default
    name: csi-s3-pvc-static
  csi:
    driver: ru.yandex.s3.csi
    volumeHandle: "<имя_static-бакета>/<путь_к_каталогу_в_бакете>"
    controllerPublishSecretRef:
      name: csi-s3-secret
      namespace: kube-system
    nodePublishSecretRef:
      name: csi-s3-secret
      namespace: kube-system
    nodeStageSecretRef:
      name: csi-s3-secret
      namespace: kube-system
    volumeAttributes:
      capacity: 10Gi
      mounter: geesefs
      options: "--memory-limit=1000 --dir-mode=0777 --file-mode=0666 --uid=1001"

      В этом примере настройки GeeseFS для работы с бакетом изменены по сравнению со StorageClass. В них добавлена опция --uid, в которой указан идентификатор пользователя-владельца всех файлов в хранилище — 1001. Подробнее о настройке GeeseFS для статического PersistentVolume см. выше.

      В параметре volumeHandle путь к каталогу в бакете задается опционально.

    3. Создайте PersistentVolumeClaim:

      kubectl create -f pvc-static.yaml

    4. Создайте статический PersistentVolume:

      kubectl create -f pv-static.yaml

    5. Убедитесь, что PersistentVolumeClaim перешел в состояние Bound:

      kubectl get pvc csi-s3-pvc-static

      Результат:

      NAME               STATUS  VOLUME                  CAPACITY  ACCESS MODES  STORAGECLASS  AGE
csi-s3-pvc-static  Bound   <имя_PersistentVolume>  10Gi      RWX           csi-s3        73m

  3. Создайте под для проверки статического PersistentVolume.

    1. Создайте файл pod-static.yaml, содержащий описание пода:

      pod-static.yaml
      ---
apiVersion: v1
kind: Pod
metadata:
  name: csi-s3-test-nginx-static
  namespace: default
spec:
  containers:
  - name: csi-s3-test-nginx-static
    image: nginx
    volumeMounts:
      - mountPath: /usr/share/nginx/html/s3
        name: s3-volume
  volumes:
    - name: s3-volume
      persistentVolumeClaim:
        claimName: csi-s3-pvc-static
        readOnly: false

    2. Создайте под, на котором будет смонтирован бакет для статического PersistentVolume:

      kubectl create -f pod-static.yaml

    3. Убедитесь, что под перешел в состояние Running:

      kubectl get pods

  4. Создайте в контейнере файл /usr/share/nginx/html/s3/hello_world_static. Для этого выполните команду на поде:

    kubectl exec -ti csi-s3-test-nginx-static -- touch /usr/share/nginx/html/s3/hello_world_static

  5. Убедитесь, что файл попал в бакет:

    1. Перейдите на страницу каталога и выберите сервис Object Storage.
    2. Нажмите на бакет <имя_static-бакета>. Если вы указали путь к каталогу в бакете в описании статического PersistentVolume, то сначала откройте указанный каталог.
Предыдущая
Подключение тома в блочном режиме
Следующая
Получение информации о кластере Kubernetes