Skip to content

Commit

Permalink
update the installing doc (fluid-cloudnative#630)
Browse files Browse the repository at this point in the history 
* update the installing doc

* update doc of upgrading fluid

* update the faq doc

Co-authored-by: 仇伶玮 <[email protected]>
  • Loading branch information
@yangyuliufeng
yangyuliufeng and 仇伶玮 authored Mar 15, 2021
1 parent fda5a62 commit 3096325
Show file tree
Hide file tree
Showing 4 changed files with 100 additions and 24 deletions.
11 changes: 10 additions & 1 deletion docs/en/userguide/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,4 +95,13 @@ If the csidriver object exists, please check if the csi registered node contains
```
kubectl get csinode | grep <node_name>
```
If the above command has no output, check whether the kubelet configuration of the node which the task is scheduled on is the default value `/var/lib/kubelet`. Because Fluid's CSI component is registered to kubelet through a fixed address socket, the default value is `--csi-address=/var/lib/kubelet/csi-plugins/fuse.csi.fluid.io/csi.sock --kubelet-registration-path=/var/lib/kubelet/csi-plugins/fuse.csi.fluid.io/csi.sock`.
If the above command has no output, check whether the kubelet configuration of the node which the task is scheduled on is the default value `/var/lib/kubelet`. Because Fluid's CSI component is registered to kubelet through a fixed address socket, the default value is `--csi-address=/var/lib/kubelet/csi-plugins/fuse.csi.fluid.io/csi.sock --kubelet-registration-path=/var/lib/kubelet/csi-plugins/fuse.csi.fluid.io/csi.sock`.

## 5. After upgrading fluid，why does the dataset created in older version miss some fields compared to a newly created dataset, when querying them via `kubectl get` command？

**Answer**: During the upgrading, we perhaps have upgraded the CRDs. The dataset created in older version，will set the new fields in the CRDs to null
For example, if you upgrade from v0.4 or before, the dataset did not have a 'FileNum' field at that time
After upgrading fluid, if you use the `kubectl get` command, you cannot query the FileNum of the dataset

You can recreate the dataset, and the new dataset will display these fields normally

52 changes: 41 additions & 11 deletions docs/en/userguide/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,10 @@ TEST SUITE: None
> The general format of the `helm install` command is like: `helm install <RELEASE_NAME> <SOURCE>`. In the above command, the first `fluid` means the release name, and the second `fluid` specified the path to the helm chart, i.e. the directory just unpacked.

### Upgrade Fluid with Helm
### Upgrade Fluid to the latest version with Helm

Before updating, it is recommended to ensure that all components in the AlluxioRuntime resource object have been started completely, which is similar to the following state:
If you have installed an older version of Fluid before, you can use Helm to upgrade it.
Before upgrading, it is recommended to ensure that all components in the AlluxioRuntime resource object have been started completely, which is similar to the following state:

```shell
$ kubectl get pod
Expand All @@ -61,19 +62,44 @@ hbase-master-0 2/2 Running 0 9h
hbase-worker-bdbjg 2/2 Running 0 9h
hbase-worker-rznd5 2/2 Running 0 9h
```
If you have installed an older version of Fluid before, you can use Helm to update it.

The command "helm upgrade" will not upgrade CRDs，we need to upgrade them manually：

```shell
$ helm upgrade fluid fluid-0.4.0.tgz
$ tar zxvf fluid-0.5.0.tgz ./
$ kubectl apply -f fluid/crds/.
```

upgrade fluid：
```shell
$ helm upgrade fluid fluid/
Release "fluid" has been upgraded. Happy Helming!
NAME: fluid
LAST DEPLOYED: Wed Nov 4 09:19:58 2020
LAST DEPLOYED: Fri Mar 12 09:22:32 2021
NAMESPACE: default
STATUS: deployed
REVISION: 2
TEST SUITE: None
```
> We have only tried to update from v0.3 to v0.4. If you upgrade directly to v0.4 from an older version, unknown types of errors may occur.

The old version of controller will not terminate automatically, the new version will stay in the Pending status：
```shell
$ kubectl -n fluid-system get pods
NAME READY STATUS RESTARTS AGE
alluxioruntime-controller-56687869f6-g9l9n 0/1 Pending 0 96s
alluxioruntime-controller-5b64fdbbb-j9h6r 1/1 Running 0 3m55s
csi-nodeplugin-fluid-r6crn 2/2 Running 0 94s
csi-nodeplugin-fluid-wvhdn 2/2 Running 0 87s
dataset-controller-5b7848dbbb-rjkl9 1/1 Running 0 3m55s
dataset-controller-64bf45c497-w8ncb 0/1 Pending 0 96s
```
delete them manually：
```shell
$ kubectl -n fluid-system delete pod alluxioruntime-controller-5b64fdbbb-j9h6r
$ kubectl -n fluid-system delete pod dataset-controller-5b7848dbbb-rjkl9
```

> We recommend you to update from v0.3 and v0.4. If you have an older version, you'd better to reinstall it.
### Check Status of Component

Expand All @@ -84,16 +110,20 @@ $ kubectl get crd | grep data.fluid.io
alluxiodataloads.data.fluid.io 2020-07-24T06:54:50Z
alluxioruntimes.data.fluid.io 2020-07-24T06:54:50Z
datasets.data.fluid.io 2020-07-24T06:54:50Z
dataloads.data.fluid.io 2021-03-12T00:00:47Z
datasets.data.fluid.io 2021-03-12T00:00:47Z
jindoruntimes.data.fluid.io 2021-03-12T00:03:45Z
```

**Check the status of pods:**

```shell
$ kubectl get pod -n fluid-system
NAME READY STATUS RESTARTS AGE
controller-manager-7f99c884dd-894g9 1/1 Running 0 5m28s
csi-nodeplugin-fluid-dm9b8 2/2 Running 0 5m28s
csi-nodeplugin-fluid-hwtvh 2/2 Running 0 5m28s
alluxioruntime-controller-5dfb5c7966-mkgzb 1/1 Running 0 2d1h
csi-nodeplugin-fluid-64h69 2/2 Running 0 2d1h
csi-nodeplugin-fluid-tc7fx 2/2 Running 0 2d1h
dataset-controller-7c4bc68b96-26mcb 1/1 Running 0 2d1h
```

If the Pod status is as shown above, then Fluid is installed on your Kubernetes cluster successfully!
Expand Down Expand Up @@ -143,8 +173,8 @@ $ kubectl delete ns fluid-system

### Advanced Configuration

In some cloud vendors, the default mount root directory `/alluxio-mnt` is not writable, so you have to modify the directory location
In some cloud vendors, the default mount root directory `/runtime-mnt` is not writable, so you have to modify the directory location

```
helm install fluid --set runtime.mountRoot=/var/lib/docker/alluxio-mnt fluid
helm install fluid --set runtime.mountRoot=/var/lib/docker/runtime-mnt fluid
```
11 changes: 10 additions & 1 deletion docs/zh/userguide/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,4 +98,13 @@ kubectl get csidriver
```
kubectl get csinode | grep <node_name>
```
如果上述命令无输出，查看任务被调度节点所在的 kubelet 配置是否为默认`/var/lib/kubelet`。因为Fluid的CSI组件通过固定地址的socket注册到kubelet，默认为`--csi-address=/var/lib/kubelet/csi-plugins/fuse.csi.fluid.io/csi.sock --kubelet-registration-path=/var/lib/kubelet/csi-plugins/fuse.csi.fluid.io/csi.sock`。
如果上述命令无输出，查看任务被调度节点所在的 kubelet 配置是否为默认`/var/lib/kubelet`。因为Fluid的CSI组件通过固定地址的socket注册到kubelet，默认为`--csi-address=/var/lib/kubelet/csi-plugins/fuse.csi.fluid.io/csi.sock --kubelet-registration-path=/var/lib/kubelet/csi-plugins/fuse.csi.fluid.io/csi.sock`。


## 5. 为什么更新了fluid后，使用 `kubectl get` 查询更新前创建的dataset，发现相比新建的dataset缺少了某些字段？

**回答**:由于我们在fluid的升级过程中可能更新了CRD，你在旧版本创建的dataset，会将CRD中新增的字段设置为空
例如，如果你从v0.4或更早版本升级，那时候的dataset没有FileNum字段
更新fluid后，如果你使用 `kubectl get` 命令，无法查询到该dataset的FileNum

你可以重建dataset，新建的dataset会正常显示这些字段
50 changes: 39 additions & 11 deletions docs/zh/userguide/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,10 @@ TEST SUITE: None

> `helm install`命令的一般格式是`helm install <RELEASE_NAME> <SOURCE>`，在上面的命令中，第一个`fluid`指定了安装的release名字，这可以自行更改，第二个`fluid.tgz`指定了helm chart所在路径。
### 使用Helm更新Fluid
### 使用Helm将Fluid更新到最新版本

更新前，建议确保AlluxioRuntime资源对象中的各个组件得以顺利启动，也就是类似以下状态：
如果您此前已经安装过旧版本的Fluid，可以使用Helm进行更新。
更新前，建议确保AlluxioRuntime资源对象中的各个组件已经顺利启动完成，也就是类似以下状态：

```shell
$ kubectl get pod
Expand All @@ -55,29 +56,56 @@ hbase-master-0 2/2 Running 0 9h
hbase-worker-bdbjg 2/2 Running 0 9h
hbase-worker-rznd5 2/2 Running 0 9h
```
如果您此前已经安装过旧版本的Fluid，可以使用Helm进行更新。

由于helm upgrade不会更新CRD，需要先对其手动进行更新：

```shell
$ tar zxvf fluid-0.5.0.tgz ./
$ kubectl apply -f fluid/crds/.
```

更新：
```shell
$ helm upgrade fluid fluid-0.4.0.tgz
$ helm upgrade fluid fluid/
Release "fluid" has been upgraded. Happy Helming!
NAME: fluid
LAST DEPLOYED: Wed Nov 4 09:19:58 2020
LAST DEPLOYED: Fri Mar 12 09:22:32 2021
NAMESPACE: default
STATUS: deployed
REVISION: 2
TEST SUITE: None
```
> 我们目前只尝试过从v0.3更新到v0.4，如果您从更旧的版本直接升级到v0.4，可能会出现未知类型的错误。
此时，旧版本的controller不会自动结束，新版本的controller会停留在Pending状态：
```shell
$ kubectl -n fluid-system get pods
NAME READY STATUS RESTARTS AGE
alluxioruntime-controller-56687869f6-g9l9n 0/1 Pending 0 96s
alluxioruntime-controller-5b64fdbbb-j9h6r 1/1 Running 0 3m55s
csi-nodeplugin-fluid-r6crn 2/2 Running 0 94s
csi-nodeplugin-fluid-wvhdn 2/2 Running 0 87s
dataset-controller-5b7848dbbb-rjkl9 1/1 Running 0 3m55s
dataset-controller-64bf45c497-w8ncb 0/1 Pending 0 96s
```
手动进行删除：
```shell
$ kubectl -n fluid-system delete pod alluxioruntime-controller-5b64fdbbb-j9h6r
$ kubectl -n fluid-system delete pod dataset-controller-5b7848dbbb-rjkl9
```

> 建议您从v0.3和v0.4升级。如果您安装的是更旧版本的Fluid，建议重新进行安装。
### 检查各组件状态

**查看Fluid使用的CRD:**

```shell
$ kubectl get crd | grep data.fluid.io
alluxiodataloads.data.fluid.io 2020-07-24T06:54:50Z
alluxioruntimes.data.fluid.io 2020-07-24T06:54:50Z
datasets.data.fluid.io 2020-07-24T06:54:50Z
alluxiodataloads.data.fluid.io 2021-03-12T00:00:47Z
alluxioruntimes.data.fluid.io 2021-03-12T00:00:47Z
databackups.data.fluid.io 2021-03-12T00:03:45Z
dataloads.data.fluid.io 2021-03-12T00:00:47Z
datasets.data.fluid.io 2021-03-12T00:00:47Z
jindoruntimes.data.fluid.io 2021-03-12T00:03:45Z
```

**查看各Pod的状态:**
Expand Down Expand Up @@ -139,9 +167,9 @@ $ kubectl delete ns fluid-system

### 高级配置

在一些特定的云厂商实现下， 默认mount根目录`/alluxio-mnt`是不可写的,因此需要修改目录位置
在一些特定的云厂商实现下， 默认mount根目录`/runtime-mnt`是不可写的,因此需要修改目录位置

```
helm install fluid --set runtime.mountRoot=/var/lib/docker/alluxio-mnt fluid
helm install fluid --set runtime.mountRoot=/var/lib/docker/runtime-mnt fluid
```

0 comments on commit 3096325

Please sign in to comment.