[docs] Add examples (#8)

Signed-off-by: Aleksandr Zimin <[email protected]>
deckhouse · May 15, 2024 · e4d9f58 · e4d9f58
1 parent a81dead
commit e4d9f58
Show file tree

Hide file tree

Showing 12 changed files with 283 additions and 14 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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, 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 `/<namespace>/<PVC name>` 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
@@ -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.
+Нет, данные для подключения к 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
@@ -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
-```
+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 - <<EOF
+apiVersion: storage.deckhouse.io/v1alpha1
+kind: NFSStorageClass
+metadata:
+  name: nfs-storage-class
+spec:
+  connection:
+    host: 10.223.187.3
+    share: /
+    nfsVersion: "4.1"
+  reclaimPolicy: Delete
+  volumeBindingMode: WaitForFirstConsumer
+EOF
+```
+
+In this example, `subDir` is not specified, so a directory `<directory from share>/<PV name>` will be created for each PV.
+
+### Checking module health
+
+You can check the module health [here](./faq.html#how-to-check-module-health)