diff --git a/docs/en/TOC.md b/docs/en/TOC.md
index b7e18c3671e..01c8d84d7c3 100644
--- a/docs/en/TOC.md
+++ b/docs/en/TOC.md
@@ -57,6 +57,7 @@
- [API_Doc](dev/api_doc.md)
- [Develop with Kind on MacOS](dev/dev_with_kind.md)
- [Performance Analyze with pprof](dev/pprof.md)
+ - [CacheRuntime Integration Guide](dev/generic_cache_runtime_integration.md)
+ Client Usage
- [How to create and delete fluid resources using Go client](dev/use_go_create_resource.md)
- [How to use client other than Go client](dev/multiple-client-support.md)
diff --git a/docs/en/dev/generic_cache_runtime_integration.md b/docs/en/dev/generic_cache_runtime_integration.md
new file mode 100644
index 00000000000..81cf7b0dcd2
--- /dev/null
+++ b/docs/en/dev/generic_cache_runtime_integration.md
@@ -0,0 +1,318 @@
+# CacheRuntime Integration Guide
+
+# Installation
+
+* Install Fluid version that supports CacheRuntime.
+
+
+```shell
+helm repo add fluid https://fluid-cloudnative.github.io/charts
+
+helm repo update
+
+helm search repo fluid --devel
+
+helm install fluid fluid/fluid --devel --version xxx -n fluid-system
+```
+
+# Integration
+
+## Step 1. Plan Cluster Topology
+
+First, you need to plan a cluster topology:
+
+* Determine the topology type and which components are included:
+
+
+* MasterSlave: Master/Worker/Client
+
+* P2P/DHT: Worker/Client
+
+* ClientOnly: Client
+
+
+* Determine the form and configuration of each component:
+
+
+* Stateful/Stateless - Determines the workload type
+
+* Standalone/Active-Standby/Cluster
+
+
+The table below shows basic information examples for deploying several major cache topology types.
+
+* MasterSlave: CubeFS/Alluxio
+
+
+| Topology | | Settings |
+| --- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Master | | * workLoadType: apps/v1/StatefulSet
* Image configuration
* Startup command
* UFS mount command
* HeadlessService needs to be created
* Authentication keys need to be mounted |
+| Worker: Used for single worker role definition | | * workLoadType: apps/v1/StatefulSet
* Image configuration
* Startup command
* HeadlessService needs to be created
* Authentication keys do NOT need to be mounted
* TieredStore needs to be configured |
+| Client | Fuse | * Role: Posix client
* workLoadType: apps/v1/DaemonSet
* Image configuration
* Startup command
* Authentication parameters do NOT need to be mounted
* TieredStore is NOT supported |
+
+* P2P Worker: JuiceFS
+
+
+| Topology | Settings |
+| --- | --- |
+| Worker: Used for single worker role definition | * workLoadType: apps/v1/StatefulSet
* Image configuration
* Startup command
* HeadlessService
* Authentication parameters need to be mounted
* TieredStore is supported |
+| Client | * Role: Fuse client
* workLoadType: apps/v1/DaemonSet
* Image configuration
* Startup command
* Service is NOT required
* Authentication parameters need to be mounted
* TieredStore is supported |
+
+## Step 2. Prepare Cache System Template
+
+A cache system template in Fluid contains the following parts:
+
+```yaml
+├── Name # runtimeClassName is specified in CacheRuntime
+├── FileSystemType # File system type, used for mount readiness verification
+├── Topology
+│ ├── Master[component]
+│ ├── Worker[component]
+│ └── client[component]
+└── ExtraResources
+ └── ConfigMaps
+```
+
+The component in Topology mainly contains the following content:
+
+| Content | Description | Recommendation |
+| --- |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| WorkloadType | The workload type of this component | For stateful applications like Master/Worker, StatefulSet is the most common choice, as it can more easily cooperate with formatted DNS domain names provided by Headless Service for access
If Client is a Fuse client responsible for providing Posix access capability for pods on nodes, DaemonSet is generally used
If Client is an SDK proxy as a centralized stateless application, Deployment with ClusterIP type Service is generally used |
+| Options | Default options, will be overridden by user settings | |
+| Template | PodTemplateSpec native field | |
+| Service | Currently only supports Headless | |
+| Dependencies | EncryptOption | Whether this component needs Fluid to mount the access keys defined in Dataset for accessing data sources [Not supported in current version], using the keys defined in Dataset for access. |
+| | ExtraResources | Whether this component needs to mount additional ConfigMaps (the dependent ConfigMap information is defined in the ExtraResources field of CacheRuntimeClass). |
+| ExecutionEntries| MountUFS | For Master-Worker architecture, when Master is Ready, the underlying file system mount operation needs to be executed. |
+| ExecutionEntries| ReportSummary | How the cache system defines operations to obtain cache information metrics [Not supported in current version]. |
+
+### Step 2.1 Prepare K8s-adapted Native Images and Define Component workloadType and PodTemplate
+
+You can first use native images, configure component **workloadType** and **PodTemplate**, manually start a fixed cache system in the K8s cluster, manually start the cache system in the pod, and make it locally accessible. This step is mainly used to clarify what K8s resources are needed and to prepare base images.
+
+### Step 2.2 Clarify What Configurations CacheRuntime Should Provide for Components
+
+Mainly clarify the following settings:
+
+* Service
+
+* Dependencies
+
+
+### Step 2.3 Confirm Default ENV Provided by Fluid CacheRuntime for Components, Applicable by Scripts Inside Containers
+
+| ENV | Description |
+| --- |----------------------------------|
+| FLUID_DATASET_NAME | Dataset name, generally used for isolation between groups in cache group concepts |
+| FLUID_DATASET_NAMESPACE | Namespace where the dataset is located |
+| FLUID_RUNTIME_CONFIG_PATH | Runtime configuration path provided by fluid |
+| FLUID_RUNTIME_MOUNT_PATH | Often used by Client, the target path where client performs mount action |
+| FLUID_RUNTIME_COMPONENT_TYPE | Indicates whether the current component is master, worker, or client |
+| FLUID_RUNTIME_COMPONENT_SVC_NAME | If the component defines a service, this value is the service name |
+
+### Step 2.4 Create RuntimeClass Example and Field Description:
+
+```yaml
+apiVersion: data.fluid.io/v1alpha1
+kind: CacheRuntimeClass
+metadata:
+ name: demofs
+fileSystemType: $fsType
+topology:
+ master:
+ workloadType: # Create master with StatefulSet workload
+ apiVersion: apps/v1
+ kind: StatefulSet
+ service: # Need to create Headless Service for master, only supported when workloadType is StatefulSet
+ headless: {}
+ dependencies:
+ encryptOption: {} # Current not support
+ podTemplateSpec:
+ spec:
+ restartPolicy: Always
+ containers:
+ - name: master
+ image: $image
+ args:
+ - /bin/sh
+ - -c
+ - custom-endpoint.sh
+ imagePullPolicy: IfNotPresent
+ worker:
+ workloadType: # Create worker with StatefulSet workload
+ apiVersion: apps/v1
+ kind: StatefulSet
+ service:
+ headless: {} # Need to create Headless Service for worker, only supported when workloadType is StatefulSet
+ dependencies: {}
+ podTemplateSpec:
+ spec:
+ restartPolicy: Always
+ containers:
+ - name: worker
+ image: $image
+ args:
+ - /bin/sh
+ - -c
+ - custom-endpoint.sh
+ imagePullPolicy: IfNotPresent
+ client:
+ workloadType: # Create client with DaemonSet workload
+ apiVersion: apps/v1
+ kind: DaemonSet
+ dependencies:
+ encryptOption: {} # Need to provide encryptOption declared by user in dataset for client
+ podTemplateSpec:
+ spec:
+ restartPolicy: Always
+ containers:
+ - name: client
+ image: $image
+ securityContext: # Usually client needs to configure privileged for operating fuse device
+ privileged: true
+ runAsUser: 0
+ args:
+ - /bin/sh
+ - -c
+ - custom-endpoint.sh
+ imagePullPolicy: IfNotPresent
+```
+
+### Step 2.5 User Creates Runtime
+
+```yaml
+apiVersion: data.fluid.io/v1alpha1
+kind: Dataset
+metadata:
+ name: demofs
+ namespace: default
+spec:
+ placement: Shared
+ accessModes:
+ - ReadWriteMany
+ mounts:
+ - name: demo
+ mountPoint: "demofs:///"
+ options:
+ key1: value1
+ key2: value2
+ encryptOptions:
+ - name: token
+ valueFrom:
+ secretKeyRef:
+ name: jfs-secret
+ key: token
+ - name: access-key
+ valueFrom:
+ secretKeyRef:
+ name: jfs-secret
+ key: access-key
+ - name: secret-key
+ valueFrom:
+ secretKeyRef:
+ name: jfs-secret
+ key: secret-key
+---
+apiVersion: data.fluid.io/v1alpha1
+kind: CacheRuntime
+metadata:
+ name: demofs
+ namespace: default
+spec:
+ runtimeClassName: demofs
+ master:
+ options: # master option
+ key1: value1
+ key2: value2
+ replicas: 2 # master replica count
+ worker:
+ options: # worker option
+ key1: value1
+ key2: value2
+ replicas: 2 # worker
+ tieredStore:
+ levels: # worker cache configuration
+ - quota: 40Gi
+ low: "0.5"
+ high: "0.8"
+ path: "/cache-data"
+ medium:
+ emptyDir: # Use tmpfs as cache medium
+ medium: Memory
+ client:
+ options:
+ key1: value1
+ key2: value2
+ volumeMounts: # Can configure volumes and corresponding volumeMounts
+ - name: demo
+ mountPath: /mnt
+ volumes:
+ - name: demo
+ persistentVolumeClaim:
+ claimName: test
+
+```
+
+### Step 2.6 Confirm RuntimeConfig Provided by Fluid CacheRuntime for Components, Parse Parameters to Start Containers
+> You can modify the entryPoint script based on the native image, first parse RuntimeConfig, generate corresponding configuration files, and then start the container.
+> You can refer to the integration example in test/gha-e2e/curvine in the official repository.
+
+In cacheruntime, all control plane processes are handled by Fluid. However, as a data caching engine, when providing services, the entire cache system requires **topology**, **data source**, **authentication**, and **cache information**. Fluid will provide this information to components through configuration files based on different Component roles. The component's internal process is responsible for parsing this configuration to perform environment variable configuration, data engine configuration file generation, and other operations. After preparation is complete, the data engine process can be started. For specific parsing details, please refer to the table below:
+
+* Taking the above resources as an example, the Config examples mounted by Master/Worker/Client and maintained by Fluid are as follows:
+
+
+```json
+{
+ "mounts": [
+ {
+ "mountPoint": "s3://test",
+ "options": {
+ "access": "minioadmin",
+ "endpoint_url": "http://minio:9000",
+ "path_style": "true",
+ "region_name": "us-east-1",
+ "secret": "minioadmin"
+ },
+ "name": "minio",
+ "path": "/minio"
+ }
+ ],
+ "accessModes": [
+ "ReadWriteMany"
+ ],
+ "targetPath": "/runtime-mnt/cache/default/curvine-demo/cache-fuse",
+ "master": {
+ "enabled": true,
+ "name": "curvine-demo-master",
+ "options": {
+ "key1": "master-value1"
+ },
+ "replicas": 1,
+ "service": {
+ "name": "svc-curvine-demo-master"
+ }
+ },
+ "worker": {
+ "enabled": true,
+ "name": "curvine-demo-worker",
+ "options": {
+ "key1": "worker-value1"
+ },
+ "replicas": 1,
+ "service": {
+ "name": "svc-curvine-demo-worker"
+ }
+ },
+ "client": {
+ "enabled": true,
+ "name": "curvine-demo-client",
+ "options": {
+ "key1": "value1"
+ },
+ "service": {
+ "name": ""
+ }
+ }
+}
+```
diff --git a/docs/zh/TOC.md b/docs/zh/TOC.md
index 42977c21539..26c58898708 100644
--- a/docs/zh/TOC.md
+++ b/docs/zh/TOC.md
@@ -77,6 +77,7 @@
- [如何参与开发](dev/how_to_develop.md)
- [API_Doc](dev/api_doc.md)
- [如何增加新Runtime实现](dev/runtime_dev_guide.md)
+ - [CacheRuntime对接指南](dev/generic_cache_runtime_integration.md)
+ 客户端使用
- [如何使用Go客户端创建、删除fluid资源](dev/use_go_create_resource.md)
- [如何使用其他客户端（非GO语言）](dev/multiple-client-support.md)
diff --git a/docs/zh/dev/generic_cache_runtime_intergration.md b/docs/zh/dev/generic_cache_runtime_integration.md
similarity index 51%
rename from docs/zh/dev/generic_cache_runtime_intergration.md
rename to docs/zh/dev/generic_cache_runtime_integration.md
index 7b84242bc21..efa756b0874 100644
--- a/docs/zh/dev/generic_cache_runtime_intergration.md
+++ b/docs/zh/dev/generic_cache_runtime_integration.md
@@ -44,19 +44,19 @@ helm install fluid fluid/fluid --devel --version xxx -nfluid-system
* MasterSlave：CubeFS/Alluxio
-| 拓扑 | | 设置 |
-| --- | --- | --- |
-| Master | | * workLoadType：appv1/StatefulSet
* 镜像配置
* 启动命令
* 需要创建HeadlessService
* 需要挂载认证密钥 |
-| Woker：用于单一worker角色定义 | | * workLoadType：appv1/StatefulSet
* 镜像配置
* 启动命令
* 需要创建HeadlessService
* 不需要挂载认证密钥
* 需要配置TieredStore |
-| Client | Fuse | * 角色：Posix客户端
* workLoadType：appv1/Daemonset
* 镜像配置
* 启动命令
* 不需要挂载认证参数
* 不支持TieredStore |
+| 拓扑 | | 设置 |
+| --- | --- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Master | | * workLoadType：apps/v1/StatefulSet
* 镜像配置
* 启动命令
* UFS挂载命令
* 需要创建HeadlessService
* 需要挂载认证密钥 |
+| Woker：用于单一worker角色定义 | | * workLoadType：apps/v1/StatefulSet
* 镜像配置
* 启动命令
* 需要创建HeadlessService
* 不需要挂载认证密钥
* 需要配置TieredStore |
+| Client | Fuse | * 角色：Posix客户端
* workLoadType：apps/v1/Daemonset
* 镜像配置
* 启动命令
* 不需要挂载认证参数
* 不支持TieredStore |
* P2P Worker：JuiceFS
-| 拓扑 | 设置 |
-| --- | --- |
-| Woker：用于单一worker角色定义 | * workLoadType：appv1/StatefulSet
* 镜像配置
* 启动命令
* HeadlessService
* 需要挂载认证参数
* 支持TieredStore |
-| Client | * 角色：Fuse客户端
* workLoadType：appv1/Daemonset
* 镜像配置
* 启动命令
* 无需Service
* 需要挂载认证参数
* 支持TieredStore |
+| 拓扑 | 设置 |
+| --- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Woker：用于单一worker角色定义 | * workLoadType：apps/v1/StatefulSet
* 镜像配置
* 启动命令
* HeadlessService
* 需要挂载认证参数
* 支持TieredStore |
+| Client | * 角色：Fuse客户端
* workLoadType：apps/v1/Daemonset
* 镜像配置
* 启动命令
* 无需Service
* 需要挂载认证参数
* 支持TieredStore |
## 步骤 2. 准备缓存系统模板
@@ -75,14 +75,16 @@ helm install fluid fluid/fluid --devel --version xxx -nfluid-system
Topology中comopent主要包含以下内容
-| 内容 | 说明 | 建议 |
-| --- | --- | --- |
-| WorkloadType | 该组件的负载类型 | Master/Worker作为有状态应用，采取StatefulSet是最为常见的选择，好处在于可以更方便的配合Headless Service提供的格式化DNS域名进行访问
Client如果为Fuse客户端，需要负责为节点上的pod提供Posix访问能力，一般采取Daemonset
Client如果为SDK poxy，作为中心化的无状态应用，一般采用Deployment配合ClusterIP类型的Service使用 |
-| Options | 默认options，会被用户设置覆盖 | |
-| PodTemplateSpec | workload原生字段 | |
-| Service | 目前仅支持Headless | |
-| Dependencies | EncryptOption | 该组件是否需要Fluid为其挂载Dataset中定义的用于访问数据源的访问密钥 |
-| | ExtraResources | 该组件是否需要extraResources【当前版本暂未支持】 |
+| 内容 | 说明 | 建议 |
+| --- |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| WorkloadType | 该组件的负载类型 | Master/Worker作为有状态应用，采取StatefulSet是最为常见的选择，好处在于可以更方便的配合Headless Service提供的格式化DNS域名进行访问
Client如果为Fuse客户端，需要负责为节点上的pod提供Posix访问能力，一般采取DaemonSet
Client如果为SDK proxy，作为中心化的无状态应用，一般采用Deployment配合ClusterIP类型的Service使用 |
+| Options | 默认options，会被用户设置覆盖 | |
+| Template | PodTemplateSpec 原生字段 | |
+| Service | 目前仅支持Headless | |
+| Dependencies | EncryptOption | 该组件是否需要Fluid为其挂载Dataset中定义的用于访问数据源的访问密钥 【当前版本暂未支持】,使用 Dataset 的定义的密钥进行访问。 |
+| | ExtraResources | 该组件是否需要挂载额外的 ConfigMap （其依赖的ConfigMap 信息定义于 CacheRuntimeClass 的 ExtraResources 字段）。 |
+| ExecutionEntries| MountUFS | 对于Master-Worker架构，当Master Ready时，需要执行底层文件系统的挂载操作。 |
+| ExecutionEntries| ReportSummary | 缓存系统定义如何获取缓存信息指标的操作 【当前版本暂未支持】。 |
### 步骤2.1 准备K8s适配的原生镜像及明确组件workloadType和PodTemplate
@@ -99,13 +101,14 @@ Topology中comopent主要包含以下内容
### 步骤2.3 确认Fluid CacheRuntime为组件提供的默认ENV，可被容器内脚本所应用
-| ENV | 说明 |
-| --- | --- |
-| FLUID\_DATASET\_NAME | dataset名称，一般用于缓存组概念中用于group间的隔离 |
-| FLUID\_DATASET\_NAMESPACE | dataset所在ns |
-| FLUID\_RUNTIME\_CONFIG\_PATH | 由fluid提供的runtime配置路径 |
+| ENV | 说明 |
+| --- |----------------------------------|
+| FLUID\_DATASET\_NAME | dataset名称，一般用于缓存组概念中用于group间的隔离 |
+| FLUID\_DATASET\_NAMESPACE | dataset所在namespace |
+| FLUID\_RUNTIME\_CONFIG\_PATH | 由fluid提供的runtime配置路径 |
| FLUID\_RUNTIME\_MOUNT\_PATH | 常被Client所使用，client执行mount动作的目标路径 |
-| FLUID\_RUNTIME\_COMPONENT\_TYPE | 表明当前组件是master，worker，还是client |
+| FLUID\_RUNTIME\_COMPONENT\_TYPE | 表明当前组件是master，worker，还是client |
+| FLUID_RUNTIME_COMPONENT_SVC_NAME | 组件如果定义service，其值为 service 的名称 |
### 步骤2.4 创建RuntimeClass示例及字段说明：
@@ -123,7 +126,7 @@ topology:
service: #需要为master创建Headless Service，仅当workloadType为Statefulset时支持
headless: {}
dependencies:
- encryptOption: {} #需要为master提供用户在dataset中声明的encryptOption
+ encryptOption: {} # 当前暂未支持
podTemplateSpec:
spec:
restartPolicy: Always
@@ -141,7 +144,7 @@ topology:
kind: StatefulSet
service:
headless: {} #需要为worker创建Headless Service，仅当workloadType为Statefulset时支持
- dependencies: {} #此处与#14区别为fluid不会为worker提供用户在dataset中声明的encryptOption
+ dependencies: {}
podTemplateSpec:
spec:
restartPolicy: Always
@@ -250,7 +253,9 @@ spec:
```
-### 步骤2.6 确认Fluid CacheRuntime为组件提供的RuntimeConfig，基于原生镜像改造entryPoint脚本，进行参数解析
+### 步骤2.6 确认 Fluid CacheRuntime为组件提供的 RuntimeConfig，进行参数解析启动容器
+> 可以基于原生镜像改造 entryPoint 脚本，先解析 RuntimeConfig，并生成对应的配置文件，后再启动容器。
+> 可以参考官方仓库中的 test/gha-e2e/curvine 的集成示例。
在cacheruntime中，控制面的所有流程全都有Fluid来负责，但作为数据缓存引擎，提供服务时，需要整个缓存系统中的**拓扑**、**数据源、认证、缓存信息，**Fluid会根据不同的Component角色来通过配置文件的方式提供至组件内部，由组件内部进程负责解析该配置，来进行环境变量配置、数据引擎配置文件生成等操作，准备就绪后，可拉起数据引擎进程，解析过程中具体可参考下表：
@@ -261,99 +266,52 @@ spec:
{
"mounts": [
{
- "mountPoint": "demofs:///",
+ "mountPoint": "s3://test",
"options": {
- "key1": "value1",
- "key2": "value2"
+ "access": "minioadmin",
+ "endpoint_url": "http://minio:9000",
+ "path_style": "true",
+ "region_name": "us-east-1",
+ "secret": "minioadmin"
},
- "name": "demo"
+ "name": "minio",
+ "path": "/minio"
}
],
- "targetPath": "/runtime-mnt/cache/default/cachefs-demo/thin-fuse",
"accessModes": [
"ReadWriteMany"
],
+ "targetPath": "/runtime-mnt/cache/default/curvine-demo/cache-fuse",
"master": {
"enabled": true,
+ "name": "curvine-demo-master",
"options": {
- "key1": "value1",
- "key2": "value2"
+ "key1": "master-value1"
},
+ "replicas": 1,
+ "service": {
+ "name": "svc-curvine-demo-master"
+ }
},
"worker": {
"enabled": true,
+ "name": "curvine-demo-worker",
"options": {
- "key1": "value1",
- "key2": "value2"
- },
- "tieredStore": {
- "levels": [
- {
- "path": "/cache-data",
- "high": "0.8",
- "low": "0.5",
- "quota": "40Gi"
- }
- ]
+ "key1": "worker-value1"
},
+ "replicas": 1,
+ "service": {
+ "name": "svc-curvine-demo-worker"
+ }
},
"client": {
"enabled": true,
+ "name": "curvine-demo-client",
"options": {
- "key1": "value1",
- "key2": "value2"
- },
- "encryptOption": {
- "access-key": "/etc/fluid/secrets/jfs-secret/access-key",
- "secret-key": "/etc/fluid/secrets/jfs-secret/secret-key",
- "token": "/etc/fluid/secrets/jfs-secret/token"
- },
- },
- "topology": {
- "master": {
- "podConfigs": [
- {
- "podName": "cachefs-demo-master-0",
- "podIP": "10.xx.xx.xx"
- },
- {
- "podName": "cachefs-demo-master-1",
- "podIP": "10.xx.xx.xx"
- }
- ],
- "service": {
- "name": "cachefs-demo-master"
- }
- },
- "worker": {
- "podConfigs": [
- {
- "podName": "cachefs-demo-worker-0",
- "podIP": "10.xx.xx.xx"
- },
- {
- "podName": "cachefs-demo-worker-1",
- "podIP": "10.xx.xx.xx"
- }
- ],
- "service": {
- "name": ""
- }
+ "key1": "value1"
},
- "client": {
- "podConfigs": [
- {
- "podName": "cachefs-demo-client-xxxxx",
- "podIP": "10.xx.xx.xx"
- },
- {
- "podName": "cachefs-demo-client-xxxxx",
- "podIP": "10.xx.xx.xx"
- }
- ],
- "service": {
- "name": ""
- }
+ "service": {
+ "name": ""
}
}
}