Deckhouse поддерживает работу с объектным хранилищем на основе S3, обеспечивая возможность использования его в Kubernetes для хранения данных в виде томов. В качестве файловой системы применяется GeeseFS, работающая через FUSE поверх S3, что позволяет монтировать S3-хранилища как стандартные файловые системы.

На этой странице представлены инструкции по настройке S3-хранилища в Deckhouse, включая подключение, создание StorageClass, а также проверку работоспособности системы.

Системные требования

  • Kubernetes версии 1.17+ с поддержкой привилегированных контейнеров.
  • Настроенное S3-хранилище с доступными ключами.
  • Достаточный объем памяти на узлах. GeeseFS использует кэш для работы с файлами, загружаемыми из S3. Размер кэша задается параметром maxCacheSize в S3StorageClass. Результаты стресс-теста: 7 узлов, 600 подов и PVC, maxCacheSize = 500 МБ, каждый под записывает 300 МБ, читает их и завершает работу.

Результаты теста

Настройка

Обратите внимание, что все команды должны выполняться на машине с административными правами в Kubernetes API.

Необходимые шаги:

Включение модуля

Для поддержки работы с S3-хранилищем включите модуль csi-s3, который позволяет создавать StorageClass и Secret в Kubernetes с помощью пользовательских ресурсов S3StorageClass. После включения модуля на узлах кластера произойдёт:

  • регистрация CSI-драйвера;
  • запуск сервисных подов csi-s3 и создание необходимых компонентов.
d8 k apply -f - <<EOF
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: csi-s3
spec:
  enabled: true
  version: 1
EOF

Дождитесь, пока модуль не перейдет в состояние Ready.

d8 k get module csi-s3 -w

Создание StorageClass

Модуль настраивается с помощью манифеста S3StorageClass. Пример конфигурации:

apiVersion: storage.deckhouse.io/v1alpha1
kind: S3StorageClass
metadata:
  name: example-s3
spec:
  bucketName: example-bucket
  endpoint: https://s3.example.com
  region: us-east-1
  accessKey: <your-access-key>
  secretKey: <your-secret-key>
  maxCacheSize: 500
  insecure: false

Если bucketName не указан, для каждого PersistentVolume будет создан отдельный bucket. Если bucketName задан, в нем будут создаваться папки под каждый PersistentVolume. Если такого bucket нет, он будет создан автоматически.

Проверка работоспособности модуля

Для проверки работоспособности модуля убедитесь, что все поды в пространстве имён d8-csi-s3находятся в статусе Running или Completed и запущены на каждом узле кластера:

d8 k -n d8-csi-s3 get pod -owide -w

Ограничения

S3 не является полноценной файловой системой, поэтому существуют определенные ограничения. Совместимость с POSIX зависит от используемого монтирующего модуля и провайдера S3. Некоторые хранилища могут не гарантировать консистентность данных (подробнее).

ОБратите внимание на таблицу совместимости с POSIX.

Основные ограничения:

  • Разрешения файловой системы, символические ссылки, пользовательские mtimes и специальные файлы (блочные/символьные устройства, именованные каналы, сокеты UNIX) не поддерживаются, поскольку стандарт S3 не возвращает метаданные пользователя в списках и не читает все эти метаданные в стандарте S3. Потребуется дополнительный запрос HEAD для каждого файла в листинге, что сделает листинги слишком медленными.
  • Поддержка специальных файлов включена по умолчанию для Яндекс S3 и отключена для других.
  • Разрешения файловой системы отключены по умолчанию.
  • Пользовательское время модификации также отключено по умолчанию: ctime, atime и mtime всегда одинаковы.
  • Время изменения файла не может быть установлено пользователем (например, с помощью cp --preserve, rsync -a или utimes(2))
  • Не поддерживаются жесткие ссылки.
  • Не поддерживается блокировка.
  • Не поддерживаются «невидимые» удаленные файлы. Если приложение сохраняет открытый файловый дескриптор после удаления файла, оно получит ошибки ENOENT от операций FS.
  • Ограничение размера файла по умолчанию составляет 1,03 ТБ и достигается путем разделения файла на 1000 частей по 5 МБ, 1000 частей по 25 МБ и 8000 частей по 125 МБ. Вы можете изменить размеры частей, но собственный лимит AWS в любом случае составляет 5 ТБ.

Известные ошибки и проблемы

  • Запрос размера тома в PVC никак не отражается на создаваемых bucket.
  • df -h показывает размер смонтированного хранилища в 1 ПБ, used никак не меняется во время использования.
  • CSI не проверяет корректность ключей для доступа к хранилищу, статус пода будет Running, а PersistentVolume и PersistentVolumeClaim будут Bound даже если ключи неправильные. Попытка доступа к смонтированной директории в поде приведёт к перезапуску пода.

Изменение параметров подключения для существующих PV

Параметры подключения к хранилищу изменить нельзя. Изменение StorageClass не обновляет настройки подключения в уже созданных PV.

Особенность отображения размера монтированной директории

Команда df -h показывает размер смонтированного тома как 1 ПБ, а значение Used остаётся неизменным в процессе работы. Это особенность модуля монтирования GeeseFS.

Обработка превышения квоты bucket или пользователя

Превышение квоты — нештатная ситуация, которой следует избегать. Поведение при этом зависит от используемого бэкенда:

  • файлы можно копировать и редактировать в подах, но изменения не отражаются в хранилище;
  • под может выйти из строя и перезапуститься.

Получение информации об используемом пространстве

Для получения информации об используемом пространстве воспользуйтесь веб-интерфейсом хранилища или командной строкой.

Использование нескольких S3-хранилищ в одном модуле

Чтобы использовать несколько S3-хранилищ, создайте дополнительный S3StorageClass и соответствующий PVC, а затем смонтируйте их в поде следующим образом:

d8 k apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: csi-s3-test-nginx
  namespace: default
spec:
  containers:
   - name: csi-s3-test-nginx
     image: nginx
     volumeMounts:
       - mountPath: /usr/share/nginx/html/s3
         name: webroot
       - mountPath: /opt/homedir
         name: homedir
  volumes:
   - name: webroot
     persistentVolumeClaim:
       claimName: csi-s3-pvc # PVC name
       readOnly: false
   - name: homedir
     persistentVolumeClaim:
       claimName: csi-s3-pvc2 # PVC-2 name
       readOnly: false
EOF

Использование одного bucket для нескольких подов

При указании параметра bucketName в S3StorageClass в одном bucket для каждого PV создаются отдельные каталоги, что позволяет использовать один bucket для нескольких подов.

Диагностика неисправностей

Проблемы при создании PVC

При возникновении проблем при создании PVC проверьте логи provisioner:

d8 k -n d8-csi-s3 logs -l app=csi-provisioner-s3 -c csi-s3

Проблемы с запуском контейнеров

Убедитесь, что для MountPropagation не установлено значение false, и проверьте логи S3-драйвера:

d8 k -n d8-csi-s3 logs -l app=csi-s3 -c csi-s3