Как использовать S3-хранилище в Kubernetes с помощью CSI

Дек 12, 2025 / Статьи

Когда в кластере перестает хватать дисков, в дело идет объектное хранилище. S3 масштабируется, стоит дешевле блочных дисков и хорошо подходит для логов, архивов и артефактов. Напрямую подключить S3 к поду нельзя. Kubernetes-хранилище ожидает volume (далее том) и не знает как воспользоваться S3 по HTTP API, поэтому приходится использовать CSI S3.

В статье разберем, как использовать объектное хранилище S3 в Kubernetes с помощью CSI. Поясним, как работает CSI S3 driver, что такое Kubernetes S3 Storage Class, как подготовить бакет и кластер, настроить PVC, а затем подключить S3 бакет как том к приложению.

Что такое S3 и как его использовать в Kubernetes

S3 — это объектное хранилище, а не классическая файловая система. Данные лежат в бакете как объекты с ключами и метаданными. Доступ идет по протоколу HTTP, операции — это запросы к API. Это не POSIX и не сетевой диск.

Использовать Kubernetes объектное хранилище в таком виде не может. Pod работает с файловой системой, которая монтируется с помощью kubelet. Kubernetes-хранилище использует следующие ресурсы для управления монтируемых файловых систем:

PersistentVolume, PersistentVolumeClaim,
StorageClass,
VolumeAttachment,
CSI Driver.

Чтобы связать эти миры, в дело вступает CSI Kubernetes. CSI (Container Storage Interface) описывает стандартный интерфейс между Kubernetes и конкретным драйвером. Сторонний CSI-драйвер реализует этот интерфейс и превращает S3 в том, который можно смонтировать в под.

Для каких задач подходит S3-хранилище в Kubernetes

S3 не заменяет диски узлов. Зато оно хорошо закрывает сценарии, где важны объем и надежность, а не минимальная задержка.

Чаще всего S3-хранилище в Kubernetes используют так:

Логи приложений и инфраструктуры. Поды пишут логи в примонтированный каталог, а через K8S CSI S3 они попадают в бакет и могут лежать там годами.
Архивы и резервные копии. Бэкапы баз данных, дампы и архивы конфигураций удобно складывать в объектное хранилище, где можно настроить срок хранения и классы хранения.
Данные для аналитики и машинного обучения. Датасеты, результаты расчетов, модельные артефакты. Jobs внутри кластера читают и пишут объекты напрямую, а S3 становится общим слоем для разных сервисов.
Статический контент. Изображения, CSS и JS, загруженные пользователями файлы. Под может отдавать их сам или использовать S3 как источник для дальнейшей раздачи.

Для транзакционных нагрузок, реляционных баз и сценариев с тысячами мелких записей в секунду S3 подходит плохо. Там все еще нужны блочные диски и привычное Kubernetes-хранилище.

Что такое CSI и как работает CSI S3 driver

CSI Kubernetes — это спецификация. Она описывает, какие операции должен поддерживать драйвер, чтобы Kubernetes умел:

создавать и удалять тома,
монтировать и размонтировать тома на узлах,
узнавать параметры хранилища.

Сами драйверы реализуют разные поставщики. Для S3 популярны варианты csi-s3 (s3-csi), а также их форки под конкретные облака. Часто в документации можно встретить формулировки kubernetes s3 csi driver или просто CSI S3.

Типичный k8s CSI S3 устроен так:

На каждом узле работает компонент CSI Node. Он отвечает за фактическое монтирование тома и работу с FUSE или другой файловой системой поверх S3.
В кластере есть CSI Controller. Он создает и удаляет тома, обрабатывает запросы на выделение хранилища и следит за жизненным циклом томов.
CSI Identity — содержит информацию о CSI драйвере.
CSI Volume — том, который может быть примонтирован к подам.
Kubernetes общается с драйвером через стандартный CSI Kubernetes API. Для него это просто еще один тип хранилища.

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

Объектное S3-хранилище Servercore

AWS S3 API совместимость, тройная репликация данных и SLA 99,99% для надежного хранения любых объемов данных

Узнать больше

Ограничения и особенности работы S3 через CSI

У такого подхода есть важные особенности, о которых нужно помнить до запуска в продакшн:

Это не полноценная POSIX файловая система. Не всегда корректно работают изменение прав и владельцев, частичная перезапись, жесткие ссылки и другие сложные операции с файлами.
Задержки зависят от сети и S3-сервиса. Каждый доступ к файлу — это, по сути, обращение к объекту. Поэтому многое зависит от класса хранения. Например, для логов и статики холодное хранение — это нормально. Для чата в реальном времени или OLTP уже нет, но для некоторых даже более загруженных задач может помочь комбинация расположения региона S3 и класса хранения.
Консистентность обычно eventual. Если один под записал файл, другой может увидеть старое состояние каталога с небольшой задержкой.

Поэтому Kubernetes S3 CSI идеально в использовать для логов, архивов, статики и статичных артефактов любого размера, но не для баз данных и критичных транзакций.

Подготовка хранилища: бакет, ключи, права

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

Создайте бакет в нужном регионе. Продумайте схему именования ключей и префиксов, например logs/, backup/, ml/.
Настройте пользователя и ключи доступа. Сгенерируйте access key и secret key, которые потом попадут в Secret для CSI S3.
Ограничьте права. Используйте bucket policy для ограничения действия в этом бакете, например, чтобы CSI S3 не мог случайно удалить чужие данные.
Включите шифрование и политику хранения. Настройте шифрование объектов, lifecycle для горячих и старых данных и, при необходимости, версионирование.

Эти шаги удобнее описать в Terraform. Один модуль создает бакет, второй — пользователя и ключ, третий — политики доступа. Тогда Kubernetes объектное хранилище будет подчиняться тем же правилам IaC, что и остальная инфраструктура.

Подготовка Kubernetes-кластера

Дальше готовим кластер, чтобы Kubernetes S3 CSI заработал без сюрпризов:

Убедитесь в поддержке CSI. Нужна версия Kubernetes с поддержкой CSI Kubernetes v1 API, обычно поддерживается с версии k8s сервера 1.10 и выше.
Настройте сеть узлов до S3-сервиса. Узлы должны иметь сетевой доступ до объектного хранилища по DNS и порту 443, а правила безопасности не должны резать трафик.
Подготовьте права в самом кластере. CSI S3 будет создавать и обновлять PersistentVolume (далее PV), работать с PersistentVolumeClaim (далее PVC) и StorageClass, поэтому нужны соответствующие роли и привязки.

В managed-сервисах часть настроек уже есть, но ограничения может накладывать политика безопасности. Если драйвер требует привилегированного доступа или доступ к hostPath, на эти места стоит обратить внимание.

Managed Kubernetes Servercore

Готовые кластеры с автообновлением, автомасштабированием и SLA по доступности Control Plane для быстрого развертывания

Узнать больше

Установка и настройка CSI для S3

Выбор и подготовка CSI S3 driver

Для S3 обычно используют один из форков csi-s3 или готовый модуль от облачного провайдера. При выборе Kubernetes S3 CSI driver проверьте несколько вещей:

Совместимость с вашей версией кластера. Старый драйвер может не поддерживать новые версии Kubernetes.
Наличие инструкций по StorageClass и PVC. Вменяемая документация экономит часы отладки.
Поддерживаемый mounter (монтировщик). GeeseFS или другой FUSE-слой напрямую влияет на производительность. Например, s3fs обеспечивает большой набор POSIX-функций, но goofys оптимизирован под производительность с потерей некоторых возможностей POSIX.

Установка через helm или manifest

Проще всего поставить модуль через helm. Часто он так и называется csi-s3 или s3-csi. Пример установки может выглядеть так:

helm repo add s3-csi-driver https://example.com/helm/s3-csi
helm repo update
helm install csi-s3 s3-csi-driver/csi-s3 \
  --namespace kube-system \
  --create-namespace \
  --set secret.accessKey=<ACCESS_KEY> \
  --set secret.secretKey=<SECRET_KEY> \
  --set secret.region=<REGION> \
  --set secret.endpoint=https://s3.example.com

Так helm берет на себя развертывание всех нужных компонентов. Если helm использовать нельзя, подойдет установка через обычные Kubernetes manifest-файлы с Deployment, DaemonSet и CRD.

Секреты и учетные данные

Доступ к S3 на стороне кластера оформляем через Secret и ServiceAccount:

apiVersion: v1
kind: Secret
metadata:
  name: csi-s3-secret
  namespace: kube-system
type: Opaque
data:
  accessKey: <base64-access-key>
  secretKey: <base64-secret-key>
  endpoint: <base64-endpoint-url>
  region: <base64-region>

Этот Secret будет использовать CSI S3 driver. Важно ограничить к нему доступ и не хранить закрытые ключи в config map.

Определение S3 StorageClass

Теперь нужно описать, как именно будет выглядеть S3-том с точки зрения кластера. Для этого создаем S3 StorageClass Kubernetes. Иногда его называют просто storage class s3.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: csi-s3
provisioner: csi.s3.example.com
parameters:
  bucket: my-app-bucket
  prefix: kubernetes/
  mounter: geesefs
reclaimPolicy: Retain
volumeBindingMode: WaitForFirstConsumer

Здесь мы описали kubernetes s3 storage class. Он знает, с каким бакетом работать, какой префикс использовать для чтения и записи объектов, и как вести себя с томом после удаления PVC.

Создание PVC и проверка монтирования S3-бакета

Дальше создаем PVC и проверяем, что бакет действительно монтируется как том:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-s3-pvc
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: csi-s3
  resources:
    requests:
      storage: 50Gi

Такой pvc запрашивает том в классе csi-s3. Для Kubernetes это обычный запрос к хранилищу. Для драйвера — команда подготовить область в S3.

Чтобы убедиться, что все работает, поднимаем тестовый под и монтируем туда PVC:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: s3-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: s3-app
  template:
    metadata:
      labels:
        app: s3-app
    spec:
      containers:
        - name: s3-app-container
          image: nginx
          volumeMounts:
            - name: s3-storage
              mountPath: /usr/share/nginx/html
      volumes:
        - name: s3-storage
          persistentVolumeClaim:
            claimName: csi-s3-pvc

В таком виде приложение s3 app видит каталог /usr/share/nginx/html как файловую систему. Фактически за ней стоит S3-бакет, подключенный через S3 CSI.

Использование S3 в приложении Kubernetes

С точки зрения разработчика все выглядит просто. В манифесте Deployment появляется том, а в контейнере — каталог, с которым можно работать.

Важно учитывать несколько моментов:

Режимы доступа. Обычно используется ReadWriteMany, чтобы несколько подов могли читать и писать в один и тот же том.
Паттерны записи. Лучше писать данные крупными блоками, а не тысячи мелких файлов. Для логов удобен режим дозаписи в большой файл, который хранится как объект, но важно учитывать что при больших объемах запись не должна быть частой.
Особенности совместного доступа. При одновременной записи из нескольких подов возможны гонки. Если приложение не готово к этому, стоит продумать, как сериализовать доступ или разделить поды по префиксам.

Если учесть эти моменты, Kubernetes S3 CSI можно использовать без переделки кода приложения. Оно просто пишет в файловую систему, а CSI S3 driver берет на себя остальное.

Автоматизация и эксплуатация

Чтобы решение не превращалось в ручную сборку, все стоит описывать как код:

Управляйте хранилищем и кластером через terraform. Бакет, ключи, политики, кластер и helm-релиз с CSI S3 можно описать в одном наборе модулей.
Мониторьте сам драйвер и объектное хранилище. Смотрите на состояние pod с CSI, ошибки монтирования, тайм-ауты и ограничение по квотам.
Продумывайте масштабирование заранее. Если нагрузка растет, важно понимать, насколько быстро S3 и FUSE-слой выдержат дополнительный поток запросов.
Настройте admission webhook для инъекции PV. Для изменения применяемых манифестов на лету можно рассмотреть к реализации Kubernetes admission webhook.

При таком подходе Kubernetes-хранилище на базе S3 становится управляемой частью инфраструктуры, а не набором ручных настроек.

Работа с данными: чтение, запись, совместимость, латентность

При чтении через Kubernetes S3 CSI Driver каждая операция в примонтированном каталоге превращается в запрос к Object Storage. Последовательное чтение крупных файлов и кэширование часто запрашиваемых объектов дают предсказуемое время отклика, а произвольный доступ к тысячам мелких файлов увеличивает латентность и нагрузку на сеть.

Для чтения критичных данных лучше держать горячий слой на блочном хранилище, а Kubernetes Object Storage через CSI использовать как более медленный, но емкий уровень.

Запись тоже требует аккуратного проектирования. Лучше ориентироваться на модели append-only и запись батчами, чем на частичную перезапись файлов: так драйверу проще сопоставлять файловые операции с объектами в бакете. Также стоит иметь в виду, что большие файлы монтировщик может отправлять с помощью multipart загрузки, поэтому операций на запись на большие объекты стоит минимизировать.

Совместимость с POSIX ограничена: блокировки, fsync и сложные сценарии совместного доступа могут работать не так, как ожидает приложение. Это стоит явно учитывать в описании Deployment и PVC, где том из S3 StorageClass Kubernetes используется несколькими подами.

Латентность работы с данными через CSI S3 зависит от расстояния до региона S3 и настроек кэша, класса хранения и квот. Для эксплуатационной практики важно мерить не только среднее время чтения и записи, но и p95–p99 задержек, количество повторных запросов и ошибок.

Если приложения чувствительны к этим параметрам, их лучше отделить в отдельный PVC и StorageClass, а K8s CSI S3 использовать в первую очередь для менее чувствительных к задержкам задач.

Сценарии применения: журналы, архивы, данные машинного обучения

Для журналов и технических логов S3 лучше всего подходит как дешевый и практически безразмерный слой хранения. Приложения последовательно дописывают записи в файлы, а Kubernetes S3 CSI Driver прозрачно складывает их в бакет. В S3 StorageClass Kubernetes можно описать отдельный класс для логов с агрессивной политикой lifecycle и отдельными префиксами для сервисов, а в Helm и Deployment зашить единообразные PVC под логирование.

Архивы и бэкапы — второй естественный сценарий для Kubernetes Object Storage. Сюда попадают редкие, но ценные данные: SQL-дампы, архивы конфигураций, экспортные наборы. Для таких PVC можно настроить менее дорогой класс хранения и более длинный срок жизни объектов, а сами задачи архивирования запускать как Job, которые используют тот же K8s CSI S3, но пишут в свои префиксы бакета.

Данные машинного обучения удобно держать в отдельных бакетах и PVC, чтобы разделить тренировочные датасеты, сырые выгрузки и артефакты моделей. Через Terraform можно описать модуль, который создает бакет, политику доступа и PVC под конкретный ML-проект, а в Helm Chart монтировать этот том в Job и Deployment для обучения и инференса. Так Kubernetes S3 CSI Driver становится стандартным способом раздавать датасеты внутри кластера без жесткой привязки к локальным дискам.

Устранение проблем и типичные ошибки

Большинство сбоев при работе CSI S3 укладываются в несколько сценариев:

Неверные ключи или права доступа. Драйвер не может авторизоваться в S3, PVC застревает в состоянии Pending, а в логах видно AccessDenied.
Недоступный endpoint. Ошибки подключения и тайм-ауты при монтировании. Проверяем DNS, правила маршрутизации и адрес сервиса.
Ошибки в RBAC. CSI-драйвер не может создавать PV или читать StorageClass, kubernetes s3 csi driver падает с ошибками доступа к API.
Несовместимость версий. Старый модуль csi-s3 не понимает новые версии Kubernetes и падает при старте.
Проблемы с доступом в S3. Аккаунт, который используется может быть read-only, или на бакете, куда происходит запись, могут быть особые правила для префиксов.

Диагностика стандартная. Смотрим kubectl get pods, kubectl describe и kubectl logs для подов с CSI и для приложений, которые используют PVC. Часто одного взгляда в логи достаточно, чтобы понять, в чем именно проблема.

Облачные серверы Servercore

Гибкое масштабирование ресурсов и оплата по факту потребления для размещения узлов Kubernetes-кластера

Узнать больше

Выводы

S3 в Kubernetes через CSI — удобный способ подключить объектное хранилище как том. Kubernetes хранилище продолжает работать с томами и PVC, а csi s3 driver берет на себя интеграцию с S3.

Правильная схема выглядит так: мы настраиваем бакет и права доступа, готовим кластер, устанавливаем s3-csi или другой модуль через helm, создаем S3 StorageClass Kubernetes и PVC, а затем монтируем том в приложение.

Для разработчиков это выглядит как обычное подключение каталога, а для администраторов — как еще один управляемый тип хранилища, а ПО даже не догадывается что работает с S3.

Главное — помнить, какой у вас профиль нагрузки и про ограничения вашего s3 провайдера, не пытаться перенести на него все подряд и держать конфигурацию под контролем через terraform и мониторинг. Тогда Kubernetes S3 CSI будет не источником отказов, а надежным и понятным инструментом.

Была ли эта статья полезной для вас?

Начните пользоваться продуктами Servercore сейчас

Регистрация в панели управления займет несколько минут.

Уже есть аккаунт? Авторизуйтесь.