Merge pull request #427 from mlycore/update-docs-en

docs/content/features/DBRE/_index.en.md

@@ -4,3 +4,32 @@ title = "Database Reliability Engineering"
 weight = 2
 chapter = true
 +++
+
+## Overview
+
+Database Reliability Engineering (DBRE) aims to improve the stability of database-related services using different technical methods, similar to Site Reliability Engineering (SRE). In cases where ShardingSphere is deployed on Kubernetes, DBRE can be further implemented with the help of Operator.
+
+## High Availability Deployment
+
+Since ShardingSphere Proxy is stateless, it serves as a computing node that processes SQL sent by the client to complete relevant data calculations. Operator abstracts and describes ShardingSphere Proxy through ComputeNode. 
+
+Currently, the Deployment mode is suitable for ShardingSphere Proxy, due to its statelessness. Deployment is a basic method provided by Kubernetes with no difference between the Pods it manages. ShardingSphere Proxy can be deployed through Deployment, which offers essential capabilities such as health checks, readiness checks, rolling upgrades, and version rollbacks.
+
+ComputeNode encompasses various attributes that are essential for deploying ShardingSphere Proxy including the number of copies, mirror repo information, version information, database driver information, health check, and readiness check probes. It also includes port mapping rules, service startup requirements server.yaml, logback.xml, and information like Agent-related configuration. During the operator tuning process, these pieces of information will be rendered through Kubernetes Deployment, Service, and ConfigMap respectively and binding and mounting actions will automatically occur. 
+
+Deployment’s capabilities result in easy multi-replicas deployment and advanced scheduling features such as affinity and taint tolerance, which in turn provide basic high availability capabilities for ShardingSphere Proxy.
+
+StorageNode includes configurations related to deploying RDS database instances on the public cloud. It specifies the corresponding public cloud resource provider through StorageProvider and enables the ability to create, automatically register and unregister, and delete database instances on the cloud, with automatic elastic expansion now supported. 
+
+## Automatic Elastic Expansion
+
+The Kubernetes community provides a Horizontal Pod Autoscaler (HPA) that automatically expands based on CPU and memory, and can also be paired with Prometheus Adapter for expansion based on custom indicators. For AWS EC2 virtual machine deployment scenarios, the community also offers the option to expand the capacity of AutoScalingGroup and through the detection mechanism of TargetGroup, only Ready instances can receive business traffic.
+
+## Observability
+
+ShardingSphere Proxy, with the assistance of ShardingSphere Agent, can effectively compile and display necessary operational information. You can get more details on ShardingSphere Agent by clicking [here](https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-proxy/observability/). Additionally, ShardingSphere on Cloud features Grafana templates that provide valuable insights into basic resource monitoring, JVM monitoring, and ShardingSphere runtime indicators. By plotting these indicators at different levels on a single Dashboard, users can easily pinpoint potential problems.
+
+## Chaos Engineering
+
+Chaos engineering allows us to verify the robustness of our system and uncover previously unknown issues. ShardingSphere Operator supports CRD Chaos that injects different types of faults such as Pod exceptions, CPU pressure, memory pressure, and network exceptions, directly into ShardingSphere Proxy. See Chaos Engineering for more details.
+

docs/content/features/EcosystemExtensions/_index.en.md

@@ -5,3 +5,120 @@ weight = 4
 chapter = true
 +++
 
+
+## WebAssembly (Wasm) Extensions
+
+WebAssembly (abbreviated as Wasm) has now expanded its application beyond web browsers, despite its initial intention of improving JavaScript performance on webpages. 
+
+With WebAssembly System Interface (WASI), Wasm can now run in various scenarios including trusted computing and edge computing. The majority of popular programming languages are compatible with Wasm, while ShardingSphere plugins (SPIs) currently only support the Java ecosystem. Introducing Wasm into ShardingSphere, can significantly enhance ShardingShphere's pluggable ecosystem with better flexibility, and attract more developers to the community.
+
+### Using Wasm for Custom Sharding
+
+Apache ShardingSphere currently uses Service Provider Interface (SPIs) to expand its pluggable architecture. For more information, please refer to the [ShardingSphere Developer Manual](https://shardingsphere.apache.org/document/current/en/dev-manual/). 
+
+We have implemented a custom sharding demo using Wasm for sharding scenarios. The demo below shows the custom sharding logic when `sharding_count` is `3`:
+
+1. Extract the sharding SPI logic from Apache ShardingSphere, for example, the auto-create sharding algorithm `MOD` from the [document](https://shardingsphere.apache.org/document/current/en/dev-manual/sharding/). Organize it into a separate [directory](https://github.com/apache/shardingsphere-on-cloud/tree/main/wasm/wasm-sharding-java/src/main/java/org/apache/shardingsphere):
+
+```shell
+├── pom.xml
+├── src
+│   └── main
+│       └── java
+│           └── org
+│               └── apache
+│                   └── shardingsphere
+│                       ├── infra 
+│                       ├── sharding 
+```
+
+2. Add [demo.java](https://github.com/apache/shardingsphere-on-cloud/blob/main/wasm/wasm-sharding-java/src/main/java/org/apache/shardingsphere/demo.java) to the above directory. Instantiate `StandardShardingAlgorithm` using `WasmShardingAlgorithm` provided by Wasm for sharding. Run the custom sharding logic and view the output. 
+
+```java
+// ...
+        StandardShardingAlgorithm<?> shardingAlgorithm = new WasmShardingAlgorithm();
+// ...
+```
+
+3. Write [custom sharding logic](https://github.com/apache/shardingsphere-on-cloud/tree/main/wasm/wasm-sharding-java/wasm-sharding) in Rust, and compile to Wasm module.
+
+```rust
+#[link(wasm_import_module = "sharding")]
+extern "C" {
+    fn poll_table(addr: i64, len: i32) -> i32;
+}
+
+// The value of sharding_count must be consistent with the value of the AvaliableTargetNames
+const SHARDING_COUNT: u8 = 3;
+
+#[no_mangle]
+pub unsafe extern "C" fn do_work() -> i64 {
+// ...
+    let sharding =  column_value % SHARDING_COUNT;
+// ...
+    std::ptr::copy_nonoverlapping(table_name.as_mut_ptr() as *const _, buf.as_mut_ptr().add(len as usize), table_name.len());
+    buf_ptr
+}
+```
+
+4. Create [WasmShardingAlgorithm.java](https://github.com/apache/shardingsphere-on-cloud/blob/main/wasm/wasm-sharding-java/src/main/java/org/apache/shardingsphere/sharding/WasmShardingAlgorithm.java) under `src/main/java/org/apache/shardingsphere/sharding/`, to communicate with the custom sharding logic in Wasm:
+
+```java
+//...
+public final class WasmShardingAlgorithm implements StandardShardingAlgorithm<Comparable<?>> {
+// ...
+    private static final String WASM_PATH = "./wasm-sharding/target/wasm32-wasi/debug/wasm_sharding.wasm";
+    private String wasmDoSharding(final Collection<String> availableTargetNames, final PreciseShardingValue<Comparable<?>> shardingValue) {
+// ...
+    }
+
+    @Override
+    public String getType() {
+        return "WASM";
+    }
+}
+
+```
+
+### Extend Custom Sharding Expressions with Wasm
+
+ShardingSphere only supports Groovy for defining sharding rules within the Java ecosystem. With Wasm, you can now define sharding logic using your preferred language. `WASM-sharding-js` demonstrates how to define the CRC32MOD sharding algorithm using JavaScript. 
+
+To make sharding easier, Wasm allows you to use your familiar language, which makes the extension of sharding algorithms even more effortless. [wasm-sharding-js](https://github.com/apache/shardingsphere-on-cloud/tree/main/wasm/wasm-sharding-js) provides an example of how to compile the sharding algorithms in JavaScript into Wasm extensions. 
+
+The directory structure is as follows:
+```shell
+├── Cargo.lock
+├── Cargo.toml
+├── README.md
+├── build.rs
+├── lib
+│   └── binding.rs
+├── package-lock.json
+├── package.json
+├── sharding
+│   ├── config.js
+│   ├── crc32.js
+│   ├── sharding.js
+│   └── strgen.js
+└── src
+```
+In the file `sharding/config.js`, two sharding resources are defined: `t_order_00${0..2}` and `ms_ds00${crc32(field_id)}`. For `t_order_00${0..2}`, it's expected to generate three sharded tables: `t_order_000`, `t_order_001`, and `t_order_002` after parsing. For `ms_ds00${crc32(field_id)}`, we expect the `field_id` to be hashed with `crc32` before sharding: 
+
+```javascript
+export let cc = "t_order_00${0..2}"
+export let cc_crc32 = "ms_ds00${crc32(field_id)}"
+```
+
+Furthermore, the `pisa_crc32` function declared in the file `sharding/sharding.js` shows the parsing of the above two expressions using JavaScript:
+
+```javascript
+//...
+function pisa_crc32(str, mod) {
+    let c2 = crc32_str(str)
+    let m = c2 % mod
+    return m < 256 ? 0 : m < 512 ? 1: m<768 ? 2 : 3
+}
+//...
+```
+Thanks to Wasm, not only you can enhance the functionality of ShardingSphere, but also extend their technical capabilities to a wider range of stacks.

docs/content/features/QuickDeployment/_index.en.md

@@ -4,3 +4,35 @@ title = "Deployment on Cloud"
 weight = 1
 chapter = true
 +++
+
+## Overview
+
+Cloud computing has evolved over the years from IaaS to PaaS, and then to SaaS. It not only changed infrastructure compositions but also upgraded software development concepts. 
+With Kubernetes leading the cloud-native wave, an increasing number of applications, including ShardingSphere, are being deployed using cloud-native technology stacks. To deploy ShardingSphere in a cloud environment, we recommend adopting Infrastructure as Code (IaC).
+
+### AWS One-Click Deployment
+
+To deploy ShardingSphere on AWS, you should first familiarize yourself with various AWS resources and services such as VPC, subnet, security group, elastic load balancer, domain name, EC2, RDS, and CloudWatch. You can adopt IaC, like AWS's CloudFormation, to quickly describe and deploy a complete set of ShardingSphere structures. 
+
+CloudFormation uses json or yaml templates to describe and combine various resources required for abstract deployment. It's interpreted and executed by related services. You only need to write relevant descriptions using version control tools, such as Git, to manage and maintain the deployed code. 
+
+Currently, Apache ShardingSphere's CloudFormation is hosted in the ShardingSphere on Cloud repo. You can get the corresponding AMI information on the AWS Marketplace by clicking [HERE](https://us-east-1.console.aws.amazon.com/marketplace/home?region=ap-southeast-1#/subscriptions/ef146e06-20ca-4da4-8954-78a7c51b3c5a).
+
+See [Quick Start](https://shardingsphere.apache.org/document/current/en/quick-start/) to learn how to start a ShardingSphere Proxy cluster on AWS with CloudFormation's minimal configuration. If you want to learn more about CloudFormation parameters or are familiar with Terraform, please refer to [User Manual](https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-jdbc/).
+
+### Kubernetes One-Click Deployment
+
+Deploying ShardingSphere on Kubernetes has never been easier, thanks to our one-click deployment feature that utilizes the Helm package manager. This tool enables users to describe the deployment structure using a set of templates and Charts comprised of variable declarations. 
+
+Resource objects involved in the deployment include Kubernetes workloads such as Deployment, Service, and ConfigMap. You can produce Charts packages for each version release and submit them to public product repos like ArtifactHub. 
+
+Currently, we offer this feature with the relevant source code hosted on the ShardingSphere on Cloud repo.
+
+See [Quick Start](https://shardingsphere.apache.org/document/current/en/quick-start/) to learn how to start a ShardingSphere Proxy cluster on Kubernetes with Helm Charts's minimal configuration. If you want to know more about Charts parameters or are familiar with Operator, please refer to [User Manual](https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-jdbc/).
+
+## Applicable Scenarios
+
+You can use the one-click deployment mode for testing purposes. If you plan to use ShardingSphere Proxy in a production environment, please refer to [User Manual](https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-jdbc/). It is crucial to learn relevant parameters before configuring and deploying. 
+
+
+

docs/content/features/ShardingSphereChaos/_index.en.md

@@ -4,3 +4,54 @@ title = "ShardingSphere Chaos"
 weight = 3
 chapter = true
 +++
+
+
+## Overview
+
+System availability is a critical metric for evaluating service reliability. There are numerous techniques to ensure availability, such as engineering resilience, anti-fragility, and others. 
+
+However, disruptions in hardware and software can still occur, resulting in potential damage to the availability and robustness of the system. 
+
+Chaos Engineering is a practice that aims to enhance system robustness by detecting the weaknesses in software systems, ultimately optimizing the ability to react to stresses and failures. According to the definition from [principleofchaos.org](https://principleofchaos.org/): 
+> *Chaos Engineering is the discipline of experimenting on a system in order to build confidence in the system’s capability to withstand turbulent conditions in production.*
+
+## General Principle
+
+Chaos engineering generally involves five steps, which can be repeated if necessary: 
+- defining a steady-state
+- formulating hypotheses about the steady-state
+- running chaos experiments
+- verifying the results
+- fixing the issue if necessary
+
+To save time and increase teams' productivity, we suggest using Continuous Verification (CV) in chaos experiments, similar to Continuous Integration (CI). 
+
+We also recommend introducing a diverse range of real-world events into the chaos experiments. While conducting experiments, minimize the blast radius to contain negative impact on a larger group of customers. 
+
+## CustomResourceDefinitions (CRD) Chaos
+
+ShardingSphere Operator supports `CustomResourceDefinitions` (CRD) chaos. The Operator supports multiple types of fault injection, for example, PodChaos including experiment actions like Pod Kill, Pod Failure, CPU Stress and Memory Stress, and NetworkChaos including network delay and loss. Once the basic parameters have been defined, Operator converts them into corresponding chaos experiments. For example:
+
+```yaml
+apiVersion: shardingsphere.apache.org/v1alpha1
+kind: Chaos
+metadata:
+  name: cpu-chaos
+  annotations:
+    selector.chaos-mesh.org/mode: one
+spec:
+  podChaos:
+    selector:
+      labelSelectors:
+        app: foo
+      namespaces: 
+      - foo-chaos
+    params:
+      cpuStress:
+        duration: 1m
+        cores: 2
+        load: 50
+    action: "CPUStress"
+```
+
+If you are using Chaos Mesh as the Chaos Engineering platform, you will need to deploy it in Kubernetes as the test environment prior to creating and submitting ShardingSphere Chaos configuration files. For further information, please refer to the user manual.

docs/content/user-manual/cn-sn-operator/_index.cn.md

@@ -147,7 +147,7 @@ metadata:
   name: shardingsphere-cluster-shardingsphere-proxy
   namespace: shardingsphere-operator
 spec:
-  version: 5.3.1
+  version: 5.4.0
   serviceType:
     type: ClusterIP
   replicas: 3
@@ -270,7 +270,7 @@ spec:
   storageNodeConnector:
     type: mysql
     version: 5.1.47
-  serverVersion: 5.3.1
+  serverVersion: 5.4.0
   replicas: 3
   selector:
     matchLabels:
@@ -318,7 +318,7 @@ StorageNode 是 Operator 对于数据源的描述，提供对数据源的生命
 目前 Operator 想要使用 StorageNode 需要打开相应的 FeatureGate：
 
 ```shell
-helm install [RELEASE_NAME] shardingsphere/apache-shardingsphere-operator-charts --set operator.featureGates.storageNode=true
+helm install [RELEASE_NAME] shardingsphere/apache-shardingsphere-operator-charts --set operator.featureGates.storageNode=true --set operator.storageNodeProviders.aws.region='' --set operator.storageNodeProviders.aws.accessKeyId='' --set operator.storageNodeProviders.aws.secretAccessKey='' --set operator.storageNodeProviders.aws.enabled=true
 ```
 
 #### 字段说明