Skip to content

Commit f785527

Browse files
Docs: Slightly reconstruct the "Smooth upgrade mount pod" document (#1151)
* Docs: Slightly reconstruct the "Smooth upgrade mount pod" document * Update docs * Fix lint * Update docs * Update docs * Update doc * Update docs * Apply suggestions from code review Co-authored-by: Caitin <[email protected]> * Update docs/zh_cn/administration/upgrade-juicefs-client.md Co-authored-by: Caitin <[email protected]> * Fix "Mount Pod" * Apply suggestions from code review Co-authored-by: Caitin <[email protected]> --------- Co-authored-by: Caitin <[email protected]>
1 parent 3640c9c commit f785527

27 files changed

+316
-261
lines changed

.markdownlint-cli2.jsonc

+3
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
"Badge",
2323
"TabItem",
2424
"Tabs",
25+
"VersionAdd",
2526
"br",
2627
"details",
2728
"div",
@@ -125,6 +126,8 @@
125126
"MariaDB",
126127
"Maven",
127128
"MinIO",
129+
"Mount Pod",
130+
"Mount Pods",
128131
"MySQL",
129132
"NFS",
130133
"POSIX",

docs/en/FAQs.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,14 @@ Try searching for your problems in the top right corner, using different keyword
1313

1414
## How to seamlessly remount JuiceFS file system? {#seamless-remount}
1515

16-
If you can accept downtime, simply delete mount pod and JuiceFS is remounted when mount pod is re-created (note that if [automatic mount point recovery](./guide/configurations.md#automatic-mount-point-recovery) isn't enabled, you'll need to restart or re-create application pods to bring mount point back into service). But in Kubernetes, we often wish a seamless remount. You can achieve a seamless remount by the following process:
16+
If you can accept downtime, simply delete the Mount Pod and JuiceFS is remounted when the Mount Pod is re-created (note that if [automatic mount point recovery](./guide/configurations.md#automatic-mount-point-recovery) isn't enabled, you'll need to restart or re-create application pods to bring mount point back into service). But in Kubernetes, we often wish a seamless remount. You can achieve a seamless remount by the following process:
1717

18-
* When [upgrading or downgrading CSI Driver](./administration/upgrade-csi-driver.md), if mount pod image is changed along the way, CSI Driver will create new mount pod when you perform a rolling upgrade on application pods.
19-
* Modify [mount options](./guide/configurations.md#mount-options) at PV level, and perform a rolling upgrade on application pods. Note that for dynamic provisioning, although you can modify mount options in [StorageClass](./guide/pv.md#create-storage-class), but the changes made will not be reflected on existing PVs, a rolling upgrade thereafter will not trigger mount pod re-creation.
18+
* When [upgrading or downgrading CSI Driver](./administration/upgrade-csi-driver.md), if the Mount Pod image is changed along the way, CSI Driver will create a new Mount Pod when you perform a rolling upgrade on application pods.
19+
* Modify [mount options](./guide/configurations.md#mount-options) at PV level, and perform a rolling upgrade on application pods. Note that for dynamic provisioning, although you can modify mount options in [StorageClass](./guide/pv.md#create-storage-class), but the changes made will not be reflected on existing PVs, a rolling upgrade thereafter will not trigger Mount Pod re-creation.
2020
* Modify [volume credentials](./guide/pv.md#volume-credentials), and perform a rolling upgrade on application pods.
2121
* If no configuration has been modified, but a seamless remount is still in need, you can make some trivial, ineffective changes to mount options (e.g. increase `cache-size` by 1), and then perform a rolling upgrade on application pods.
2222

23-
To learn about the CSI Driver implementation, and find out when will new mount pods are created to achieve seamless remount, see the `GenHashOfSetting()` function in [`pkg/juicefs/mount/pod_mount.go`](https://github.com/juicedata/juicefs-csi-driver/blob/master/pkg/juicefs/mount/pod_mount.go).
23+
To learn about the CSI Driver implementation and find out when new Mount Pods will be created to achieve seamless remount, see the `GenHashOfSetting()` function in [`pkg/juicefs/mount/pod_mount.go`](https://github.com/juicedata/juicefs-csi-driver/blob/master/pkg/juicefs/mount/pod_mount.go).
2424

2525
## `exec format error` {#format-error}
2626

docs/en/administration/going-production.md

+11-11
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,12 @@ sidebar_position: 1
55

66
Best practices and recommended settings when going production.
77

8-
## PV settings {#pv-settings}
8+
## Mount Pod settings {#mount-pod-settings}
99

10-
* [Configure more readable names for PV directory](../guide/configurations.md#using-path-pattern);
11-
* Enable [Automatic Mount Point Recovery](../guide/configurations.md#automatic-mount-point-recovery);
10+
* To support [smooth upgrade of Mount Pods](./upgrade-juicefs-client.md#smooth-upgrade), please configure the [CSI dashboard](./troubleshooting.md#csi-dashboard) or the [JuiceFS kubectl plugin](./troubleshooting.md#kubectl-plugin) in advance;
11+
* For dynamic PV scenarios, it is recommended to [configure a more readable PV directory name](../guide/configurations.md#using-path-pattern);
1212
* The `--writeback` option is strongly advised against, as it can easily cause data loss especially when used inside containers, if not properly managed. See ["Write Cache in Client (Community Edition)"](/docs/community/guide/cache#client-write-cache) and ["Write Cache in Client (Cloud Service)"](/docs/cloud/guide/cache#client-write-cache);
13-
* When cluster is low on resources, refer to optimization techniques in [Resource Optimization](../guide/resource-optimization.md);
13+
* When cluster resources are limited, refer to techniques in [Resource Optimization](../guide/resource-optimization.md#mount-pod-resources) for optimization;
1414
* It's recommended to set non-preempting PriorityClass for Mount Pod, see [documentation](../guide/resource-optimization.md#set-non-preempting-priorityclass-for-mount-pod) for details.
1515

1616
## Sidecar recommendations {#sidecar}
@@ -61,13 +61,13 @@ mountPodPatch:
6161
done
6262
```
6363
64-
## Configure mount pod monitoring (Community Edition) {#monitoring}
64+
## Configure Mount Pod monitoring (Community Edition) {#monitoring}
6565
6666
:::tip
6767
Content in this section is only applicable to JuiceFS Community Edition, because Enterprise Edition doesn't provide metrics via local port, instead a centralized metrics API is provided, see [enterprise docs](https://juicefs.com/docs/zh/cloud/administration/monitoring/#prometheus-api).
6868
:::
6969
70-
By default (not using `hostNetwork`), the mount pod provides a metrics API through port 9567 (you can also add [`metrics`](https://juicefs.com/docs/community/command_reference#mount) option in [`mountOptions`](../guide/configurations.md#mount-options) to customize the port number), the port name is `metrics`, so the monitoring configuration of Prometheus can be configured as follows.
70+
By default (not using `hostNetwork`), the Mount Pod provides a metrics API through port 9567 (you can also add [`metrics`](https://juicefs.com/docs/community/command_reference#mount) option in [`mountOptions`](../guide/configurations.md#mount-options) to customize the port number), the port name is `metrics`, so the monitoring configuration of Prometheus can be configured as follows.
7171

7272
### Collect data in Prometheus {#collect-metrics}
7373

@@ -182,15 +182,15 @@ Once metrics data is collected, refer to the following documents to set up Grafa
182182
* [JuiceFS Community Edition](https://juicefs.com/docs/community/administration/monitoring/#grafana)
183183
* [JuiceFS Cloud Service](https://juicefs.com/docs/cloud/administration/monitor/#prometheus-api)
184184

185-
## Collect mount pod logs using EFK {#collect-mount-pod-logs}
185+
## Collect Mount Pod logs using EFK {#collect-mount-pod-logs}
186186

187-
Troubleshooting CSI Driver usually involves reading mount pod logs, if [checking mount pod logs in real time](./troubleshooting.md#check-mount-pod) isn't enough, consider deploying an EFK (Elasticsearch + Fluentd + Kibana) stack (or other suitable systems) in Kubernetes Cluster to collect pod logs for query. Taking EFK for example:
187+
Troubleshooting CSI Driver usually involves reading Mount Pod logs, if [checking Mount Pod logs in real time](./troubleshooting.md#check-mount-pod) isn't enough, consider deploying an EFK (Elasticsearch + Fluentd + Kibana) stack (or other suitable systems) in Kubernetes Cluster to collect pod logs for query. Taking EFK for example:
188188

189189
- Elasticsearch: index logs and provide a complete full-text search engine, which can facilitate users to retrieve the required data from the log. For installation, refer to the [official documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html).
190190
- Fluentd: fetch container log files, filter and transform log data, and then deliver the data to the Elasticsearch cluster. For installation, refer to the [official documentation](https://docs.fluentd.org/installation).
191191
- Kibana: visual analysis of logs, including log search, processing, and gorgeous dashboard display, etc. For installation, refer to the [official documentation](https://www.elastic.co/guide/en/kibana/current/install.html).
192192

193-
Mount pod is labeled `app.kubernetes.io/name: juicefs-mount`. Add below config to the Fluentd configuration:
193+
The Mount Pod is labeled `app.kubernetes.io/name: juicefs-mount`. Add the configuration below to the Fluentd configuration:
194194

195195
```html
196196
<filter kubernetes.**>
@@ -383,11 +383,11 @@ Under the premise of fully understanding the risks of `--writeback`, if your sce
383383

384384
* Configure cache persistence to ensure that the cache directory will not be lost when the container is destroyed. For specific configuration methods, read [Cache settings](../guide/cache.md#cache-settings);
385385
* Choose one of the following methods (you can also adopt both) to ensure that the JuiceFS client has enough time to complete the data upload when the application container exits:
386-
* Enable [Delayed mount pod deletion](../guide/resource-optimization.md#delayed-mount-pod-deletion). Even if the application pod exits, the mount pod will wait for the specified time before being destroyed by the CSI Node. Set a reasonable delay to ensure that data is uploaded in a timely manner;
386+
* Enable [Delayed Mount Pod deletion](../guide/resource-optimization.md#delayed-mount-pod-deletion). Even if the application pod exits, the Mount Pod will wait for the specified time before being destroyed by the CSI Node. Set a reasonable delay to ensure that data is uploaded in a timely manner;
387387
* Since v0.24, the CSI Driver supports [customizing](../guide/configurations.md#customize-mount-pod) all aspects of the Mount Pod, so you can modify `terminationGracePeriodSeconds`. By using [`preStop`](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks), you can ensure that the Mount Pod waits for data uploads to finish before exiting, as demonstrated below:
388388

389389
:::warning
390-
* After `preStop` is configured, if the write cache is not uploaded successfully, the mount pod will wait for the time set by the `terminationGracePeriodSeconds` parameter and cannot exit for a long time. This will affect the normal execution of certain operations (such as upgrading mount pod). Please fully test and understand the corresponding risks;
390+
* After `preStop` is configured, if the write cache is not uploaded successfully, the Mount Pod will wait for the time set by the `terminationGracePeriodSeconds` parameter and cannot exit for a long time. This will affect the normal execution of certain operations (such as upgrading the Mount Pod). Please fully test and understand the corresponding risks;
391391
* Neither of the above two solutions can **fully guarantee** that all write cache data will be uploaded successfully.
392392
:::
393393

docs/en/administration/offline.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ An offline cluster is a Kubernetes cluster in which nodes cannot access the publ
99

1010
This section is currently only available in Chinese.
1111

12-
## Change mount pod SA to allow pull image {#mount-pod-sa}
12+
## Change Mount Pod SA to allow pull image {#mount-pod-sa}
1313

14-
Offline clusters often use private image registries, which require authentication to access. The default ServiceAccount (SA) for mount pod is `juicefs-csi-node-sa`, which probably isn't equipped to pull images from your private registry. Follow below guide to change SA for mount pod in order to pull its image normally.
14+
Offline clusters often use private image registries, which require authentication to access. The default ServiceAccount (SA) for a Mount Pod is `juicefs-csi-node-sa`, which probably isn't equipped to pull images from your private registry. Follow the guide below to change SA for the Mount Pod in order to pull its image normally.
1515

1616
A SA called `juicefs-mount-sa` is assumed to have access to your private registry, make adjustments accordingly in your environment (refer to [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account) to see how to create the SA).
1717

0 commit comments

Comments
 (0)