diff --git a/.github/workflows/deploy_dev.yml b/.github/workflows/deploy_dev.yml index ba1a5bd..defc7ae 100644 --- a/.github/workflows/deploy_dev.yml +++ b/.github/workflows/deploy_dev.yml @@ -9,6 +9,9 @@ env: MODULES_REGISTRY_PASSWORD: ${{ secrets.DEV_MODULES_REGISTRY_PASSWORD }} RELEASE_CHANNEL: ${{ github.event.inputs.channel }} MODULES_MODULE_TAG: ${{ github.event.inputs.tag }} + GOLANG_VERSION: ${{ vars.GOLANG_VERSION }} + GOPROXY: ${{ secrets.GOPROXY }} + SOURCE_REPO: ${{ secrets.SOURCE_REPO }} on: workflow_dispatch: diff --git a/crds/doc-ru-crd-csi-snapshot.yaml b/crds/doc-ru-crd-csi-snapshot.yaml new file mode 100644 index 0000000..a38dbdd --- /dev/null +++ b/crds/doc-ru-crd-csi-snapshot.yaml @@ -0,0 +1,60 @@ +spec: + versions: + - name: v1 + schema: + openAPIV3Schema: + description: | + VolumeSnapshot — это запрос пользователя на создание снимка состояния постоянного тома на определенный момент времени или на привязку к существующему снимку. + properties: + apiVersion: + description: | + APIVersion определяет версионированную схему этого представления объекта. Серверы должны конвертировать распознанные схемы в последнее внутреннее значение и могут отклонить нераспознанные значения. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + kind: + description: | + Kind — это строковое значение, представляющее ресурс REST, который представляет этот объект. Серверы могут выводить его из конечной точки, к которой клиент отправляет запросы. Не может быть обновлено. Используется в CamelCase. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + spec: + description: | + spec определяет желаемые характеристики снимка, запрашиваемого пользователем. Подробнее: https://kubernetes.io/docs/concepts/storage/volume-snapshots#volumesnapshots Обязательный параметр. + properties: + source: + description: | + source указывает, откуда будет создан снимок. Это поле неизменно после создания. Обязательный параметр. + properties: + persistentVolumeClaimName: + description: | + persistentVolumeClaimName указывает имя объекта PersistentVolumeClaim, представляющего том, из которого должен быть создан снимок. Предполагается, что этот PVC находится в том же пространстве имен, что и объект VolumeSnapshot. Это поле должно быть установлено, если снимок не существует и его нужно создать. Это поле неизменно. + volumeSnapshotContentName: + description: | + volumeSnapshotContentName указывает имя существующего объекта VolumeSnapshotContent, представляющего существующий снимок тома. Это поле должно быть установлено, если снимок уже существует и нужно только его представление в Kubernetes. Это поле неизменно. + volumeSnapshotClassName: + description: | + VolumeSnapshotClassName — это имя класса VolumeSnapshot, запрашиваемого VolumeSnapshot. VolumeSnapshotClassName может быть оставлено пустым (nil), чтобы указать, что должен использоваться класс SnapshotClass по умолчанию. В данном кластере может быть несколько классов Volume Snapshot по умолчанию: один по умолчанию для каждого драйвера CSI. Если VolumeSnapshot не указывает SnapshotClass, будет проверено VolumeSnapshotSource для определения связанного драйвера CSI, и будет использован класс VolumeSnapshotClass по умолчанию, связанный с этим драйвером CSI. Если для данного драйвера CSI существует более одного VolumeSnapshotClass и более одного из них помечены как по умолчанию, создание снимка (CreateSnapshot) завершится неудачей и будет сгенерировано событие. Пустая строка для этого поля не допускается. + - name: v1beta1 + schema: + openAPIV3Schema: + description: | + VolumeSnapshot — это запрос пользователя на создание снимка состояния постоянного тома на определенный момент времени или на привязку к существующему снимку. + properties: + apiVersion: + description: | + APIVersion определяет версионированную схему этого представления объекта. Серверы должны конвертировать распознанные схемы в последнее внутреннее значение и могут отклонить нераспознанные значения. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + kind: + description: | + Kind — это строковое значение, представляющее ресурс REST, который представляет этот объект. Серверы могут выводить его из конечной точки, к которой клиент отправляет запросы. Не может быть обновлено. Используется в CamelCase. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + spec: + description: | + spec определяет желаемые характеристики снимка, запрашиваемого пользователем. Подробнее: https://kubernetes.io/docs/concepts/storage/volume-snapshots#volumesnapshots Обязательный параметр. + properties: + source: + description: | + source указывает, откуда будет создан снимок. Это поле неизменно после создания. Обязательный параметр. + properties: + persistentVolumeClaimName: + description: | + persistentVolumeClaimName указывает имя объекта PersistentVolumeClaim, представляющего том, из которого должен быть создан снимок. Предполагается, что этот PVC находится в том же пространстве имен, что и объект VolumeSnapshot. Это поле должно быть установлено, если снимок не существует и его нужно создать. Это поле неизменно. + volumeSnapshotContentName: + description: | + volumeSnapshotContentName указывает имя существующего объекта VolumeSnapshotContent, представляющего существующий снимок тома. Это поле должно быть установлено, если снимок уже существует и нужно только его представление в Kubernetes. Это поле неизменно. + volumeSnapshotClassName: + description: | + VolumeSnapshotClassName — это имя класса VolumeSnapshot, запрашиваемого VolumeSnapshot. VolumeSnapshotClassName может быть оставлено пустым (nil), чтобы указать, что должен использоваться класс SnapshotClass по умолчанию. В данном кластере может быть несколько классов Volume Snapshot по умолчанию: один по умолчанию для каждого драйвера CSI. Если VolumeSnapshot не указывает SnapshotClass, будет проверено VolumeSnapshotSource для определения связанного драйвера CSI, и будет использован класс VolumeSnapshotClass по умолчанию, связанный с этим драйвером CSI. Если для данного драйвера CSI существует более одного VolumeSnapshotClass и более одного из них помечены как по умолчанию, создание снимка (CreateSnapshot) завершится неудачей и будет сгенерировано событие. Пустая строка для этого поля не допускается. diff --git a/crds/doc-ru-nfsstorageclass.yaml b/crds/doc-ru-nfsstorageclass.yaml index db1a64c..e0d2e49 100644 --- a/crds/doc-ru-nfsstorageclass.yaml +++ b/crds/doc-ru-nfsstorageclass.yaml @@ -7,6 +7,8 @@ spec: Интерфейс управления StorageСlass для CSI-драйвера nfs.csi.k8s.io. Ручное создание StorageClass для данного драйвера запрещено. properties: spec: + description: | + Определяет конфигурацию StorageClass. properties: connection: description: | diff --git a/crds/nfsstorageclass.yaml b/crds/nfsstorageclass.yaml index 87832b7..3eb937a 100644 --- a/crds/nfsstorageclass.yaml +++ b/crds/nfsstorageclass.yaml @@ -33,6 +33,8 @@ spec: Defines a Kubernetes Storage class configuration. required: - connection + - reclaimPolicy + - volumeBindingMode properties: connection: type: object diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..e4af1d4 --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,5 @@ +--- +title: "The csi-nfs module: configuration" +force_searchable: true +description: The csi-nfs Deckhouse Kubernetes Platform module's configuration. +--- diff --git a/docs/CONFIGURATION.ru.md b/docs/CONFIGURATION.ru.md new file mode 100644 index 0000000..b1828e4 --- /dev/null +++ b/docs/CONFIGURATION.ru.md @@ -0,0 +1,5 @@ +--- +title: "Модуль csi-nfs: настройки" +force_searchable: true +description: Параметры настройки модуля csi-nfs Deckhouse Kubernetes Platform. +--- diff --git a/docs/CR.md b/docs/CR.md new file mode 100644 index 0000000..0a7c5ea --- /dev/null +++ b/docs/CR.md @@ -0,0 +1,4 @@ +--- +title: "The csi-nfs module: Custom Resources" +description: "The csi-nfs module Custom Resources: LocalStorageClass." +--- diff --git a/docs/CR.ru.md b/docs/CR.ru.md new file mode 100644 index 0000000..02b103c --- /dev/null +++ b/docs/CR.ru.md @@ -0,0 +1,4 @@ +--- +title: "Модуль csi-nfs: Custom Resources" +description: "Модуль csi-nfs Custom Resources: LocalStorageClass." +--- diff --git a/docs/FAQ.md b/docs/FAQ.md index 45fd711..7181766 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -3,6 +3,71 @@ title: "The csi-nfs module: FAQ" description: CSI NFS module FAQ --- +## How to check module health? + +To do this, you need to check the status of the pods in the `d8-csi-nfs` namespace. All pods should be in the `Running` or `Completed` state and should be running on all nodes. + +```shell +kubectl -n d8-csi-nfs get pod -owide -w +``` + ## Is it possible to change the parameters of an NFS server for already created PVs? -No, the connection data to the NFS server is stored directly in the PV manifest and cannot be changed. Changing the Storage Class also does not affect the connection settings in already existing PVs. \ No newline at end of file +No, the connection data to the NFS server is stored directly in the PV manifest and cannot be changed. Changing the Storage Class also does not affect the connection settings in already existing PVs. + +## How to use the `subDir` parameter? + +The `subDir` parameter allows you to specify a subdirectory for each PV. + +### Example with templates + +You can use 3 templates: + +- `${pvc.metadata.name}` +- `${pvc.metadata.namespace}` +- `${pv.metadata.name}` + +```yaml +kubectl apply -f - <<'EOF' +apiVersion: storage.deckhouse.io/v1alpha1 +kind: NFSStorageClass +metadata: + name: nfs-storage-class +spec: + connection: + host: 10.223.187.3 + share: / + subDir: "${pvc.metadata.namespace}/${pvc.metadata.name}" + nfsVersion: "4.1" + reclaimPolicy: Delete + volumeBindingMode: WaitForFirstConsumer +EOF +``` + +In this example, a directory `//` will be created on the NFS server for each volume. + +> **Caution!** The PVC name is set by the user. Such `subDir` settings may lead to a situation where the directory name for a newly created volume matches the directory name of a previously deleted volume. If `reclaimPolicy` is set to `Retain`, the data from the previously allocated volumes with the same PVC name will be available in the new volume. + +### Example without templates + +In addition to templates, you can specify a regular string as the subdirectory name. + +```yaml +kubectl apply -f - <<'EOF' +apiVersion: storage.deckhouse.io/v1alpha1 +kind: NFSStorageClass +metadata: + name: nfs-storage-class +spec: + connection: + host: 10.223.187.3 + share: / + subDir: "shared-folder" + nfsVersion: "4.1" + reclaimPolicy: Retain + volumeBindingMode: WaitForFirstConsumer +``` + +In this example, all PVs of this StorageClass will use the same directory on the server: `/shared-folder`. + +> **Caution!** If `reclaimPolicy` is set to `Delete`, deleting any PVC of this StorageClass will result in the deletion of the entire `/shared-folder` directory. diff --git a/docs/FAQ_RU.md b/docs/FAQ_RU.md index 22c8d66..bfc0f4e 100644 --- a/docs/FAQ_RU.md +++ b/docs/FAQ_RU.md @@ -3,6 +3,72 @@ title: "Модуль csi-nfs: FAQ" description: FAQ по модулю CSI NFS --- +## Как проверить работоспособность модуля? + +Для этого необходимо проверить состояние подов в namespace `d8-csi-nfs`. Все поды должны быть в состоянии `Running` или `Completed` и запущены на всех узлах. + +```shell +kubectl -n d8-csi-nfs get pod -owide -w +``` + ## Возможно ли изменение параметров NFS-сервера уже созданных PV? -Нет, данные для подключения к NFS-серверу сохраняются непосредственно в манифесте PV, и не подлежат изменению. Изменение Storage Class также не повлечет изменений настроек подключения в уже существующих PV. \ No newline at end of file +Нет, данные для подключения к NFS-серверу сохраняются непосредственно в манифесте PV, и не подлежат изменению. Изменение Storage Class также не повлечет изменений настроек подключения в уже существующих PV. + +## Как использовать параметр `subDir`? + +`subDir` позволяет задавать подпапку для каждого PV. + +### Пример с шаблонами + +Можно использовать 3 шаблона: + +- `${pvc.metadata.name}` +- `${pvc.metadata.namespace}` +- `${pv.metadata.name}` + +```yaml +kubectl apply -f - <<'EOF' +apiVersion: storage.deckhouse.io/v1alpha1 +kind: NFSStorageClass +metadata: + name: nfs-storage-class +spec: + connection: + host: 10.223.187.3 + share: / + subDir: "${pvc.metadata.namespace}/${pvc.metadata.name}" + nfsVersion: "4.1" + reclaimPolicy: Delete + volumeBindingMode: WaitForFirstConsumer +EOF +``` + +В данном примере на NFS-сервере для каждого тома будет создаваться каталог `/<название namespace>/<название PVC>`. + +> **Внимание!** Имя PVC задается пользователем. Такие настройки `subDir` могут привести к ситуации, когда имя каталога для вновь создаваемого тома совпадет с именем каталога ранее удаленного тома. Если `reclaimPolicy` установлен в значение `Retain`, то в новом томе будут доступны данные томов, выделенных ранее для PVC с таким же именем. + +### Пример без шаблонов + +Помимо шаблонов, можно указывать обычную строку - имя подпапки. + +```yaml +kubectl apply -f - <<'EOF' +apiVersion: storage.deckhouse.io/v1alpha1 +kind: NFSStorageClass +metadata: + name: nfs-storage-class +spec: + connection: + host: 10.223.187.3 + share: / + subDir: "shared-folder" + nfsVersion: "4.1" + reclaimPolicy: Retain + volumeBindingMode: WaitForFirstConsumer +EOF +``` + +В данном примере все PV такого StorageClass будут использовать один и тот же каталог на сервере: `/shared-folder`. + +> **Внимание!** Если `reclaimPolicy` выставлен в `Delete`, то удаление любой PVC такого StorageClass приведет к удалению всего каталога `/shared-folder`. diff --git a/docs/README.md b/docs/README.md index 583c647..382b2ee 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,15 +4,21 @@ description: "The csi-nfs module: General Concepts and Principles." moduleStatus: experimental --- -This module provides CSI that manages volumes based on `NFS`. +This module provides CSI that manages volumes based on `NFS`. The module allows you to create a `StorageClass` in `Kubernetes` by creating [Kubernetes custom resources](./cr.html#nfsstorageclass) `NFSStorageClass`. > **Caution!** The user is not allowed to create a `StorageClass` for the `nfs.csi.k8s.io` CSI driver. +## System requirements and recommendations + +### Requirements +- Stock kernels shipped with the [supported distributions](https://deckhouse.io/documentation/v1/supported_versions.html#linux). +- Presence of a deployed and configured NFS server. + ## Quickstart guide Note that all commands must be run on a machine that has administrator access to the Kubernetes API. -### Enabling modules +### Enabling module - Enable the `csi-nfs` module. This will result in the following actions across all cluster nodes: - registration of the CSI driver; @@ -36,8 +42,28 @@ EOF kubectl get mc csi-nfs -w ``` -- Make sure that all pods in `d8-csi-nfs` namespaces are `Running` or `Completed` and are running on all nodes. +### Creating a StorageClass -```shell -kubectl -n d8-csi-nfs get pod -owide -w -``` \ No newline at end of file +To create a StorageClass, you need to use the [NFSStorageClass](./cr.html#nfsstorageclass) resource. Here is an example command to create such a resource: + +```yaml +kubectl apply -f - </` will be created for each PV. + +### Checking module health + +You can check the module health [here](./faq.html#how-to-check-module-health) diff --git a/docs/README_RU.md b/docs/README_RU.md index 639b104..e235085 100644 --- a/docs/README_RU.md +++ b/docs/README_RU.md @@ -4,15 +4,22 @@ description: "Модуль csi-nfs: общие концепции и полож moduleStatus: experimental --- -Модуль предоставляет CSI для управления томамим на основе `NFS`. +Модуль предоставляет CSI для управления томамим на основе `NFS`. Модуль позволяет создавать `StorageClass` в `Kubernetes` через создание [пользовательских ресурсов Kubernetes](./cr.html#nfsstorageclass) `NFSStorageClass`. > **Внимание!** Создание `StorageClass` для CSI-драйвера `nfs.csi.k8s.io` пользователем запрещено. +## Системные требования и рекомендации + +### Требования + +- Использование стоковых ядер, поставляемых вместе с [поддерживаемыми дистрибутивами](https://deckhouse.ru/documentation/v1/supported_versions.html#linux); +- Наличие развернутого и настроенного `NFS` сервера. + ## Быстрый старт Все команды следует выполнять на машине, имеющей доступ к API Kubernetes с правами администратора. -### Включение модулей +### Включение модуля - Включить модуль `csi-nfs`. Это приведет к тому, что на всех узлах кластера будет: - зарегистрирован CSI драйвер; @@ -36,8 +43,28 @@ EOF kubectl get mc csi-nfs -w ``` -- Проверить, что в namespace `d8-csi-nfs` все поды в состоянии `Running` или `Completed` и запущены на всех узлах. +### Создание StorageClass -```shell -kubectl -n d8-csi-nfs get pod -owide -w -``` \ No newline at end of file +Для создания StorageClass необходимо использовать ресурс [NFSStorageClass](./cr.html#nfsstorageclass). Пример команды для создания такого ресурса: + +```yaml +kubectl apply -f -</<имя PV>`. + +### Проверка работоспособности модуля. + +Проверить работоспособность модуля можно [так](./faq.html#как-проверить-работоспособность-модуля)