This is an automated email from the ASF dual-hosted git repository. duanzhengqiang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/shardingsphere-on-cloud.git
commit 80738313e1618caec3d3320a7c0a93e96b28f8e7 Author: Ghoul_Lee <[email protected]> AuthorDate: Wed Jul 20 20:21:37 2022 +0800 feat(doc): add readme ,quick start doc for fist release (#20) Signed-off-by: windghoul <[email protected]> --- README.md | 51 +++++- charts/shardingsphere-cluster/values.yaml | 6 +- charts/shardingsphere-operator/values.yaml | 4 +- doc/deploy.md | 266 +++++++++++++++++++++++++++++ doc/images/ss-operatorIA.png | Bin 0 -> 810035 bytes doc/images/ssvx.png | Bin 0 -> 28855 bytes doc/quickStart.md | 107 ------------ 7 files changed, 319 insertions(+), 115 deletions(-) diff --git a/README.md b/README.md index a6a0ecd..5caf46a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,50 @@ -# shardingsphere-operator +# shardingsphere-on-cloud +Contains various cloud solutions about ShardingSphere +## ShardingSphere Operator +Use the operator to create a ShardingSphere-Proxy cluster including the ZooKeeper cluster in the Kubernetes . +### Internal Architecture + +### Status +minimum viable product +### how to install + +[quick start](./doc/deploy.md) +## Features +* Supports the use of proxy to configure and describe the shardingsphere-proxy cluster. For detailed configuration, see the deployment documentation +* Support native shardingsphere proxy server.yaml configuration. For specific support items, please refer to the documentation +* Support automatic creation of HPA based on cpu metrics +* Support automatic download of MySQL driver + +## Deploy +### Helm +* ShardingSphere-Operator chart + * Support deploy shardingsphere operator +* ShardingSphere-Cluster chart + * Support deploy shardingsphere proxy cluster + * Support deploy Zookeeper by bitnami + * Support automatic configuration of the address of the governance center + * Use github pages to host repositories and support helm repo add to add repositories +## Prerequisites +- Kubernetes 1.18+ +## Deploy Prerequisites + +To build ShardingSphere Operator from scratch you will need to install the following tools: + +* Git +* [Golang 1.17](https://golang.org/dl/) +* make +* Kubernetes 1.20+ +* Kubebuilder 3.4.1+ +## Contributing +We welcome all kinds of contributions from the open-source community, individuals and partners. +[Contributing](./CONTRIBUTING.md) +## Community + +[Slack channel](https://join.slack.com/t/apacheshardingsphere/shared_invite/zt-sbdde7ie-SjDqo9~I4rYcR18bq0SYTg). Best for: instant communications and online meetings, sharing your applications. + + +## License +[Apache License 2.0](https://github.com/SphereEx/shardingsphere-on-cloud/blob/master/LICENSE) + -## quick start -[quick start](./doc/quickStart.md) \ No newline at end of file diff --git a/charts/shardingsphere-cluster/values.yaml b/charts/shardingsphere-cluster/values.yaml index 614d1fa..fc1a55e 100644 --- a/charts/shardingsphere-cluster/values.yaml +++ b/charts/shardingsphere-cluster/values.yaml @@ -14,7 +14,7 @@ ## limitations under the License. ## -# @section ShardingSphere-Proxy cluster parameters +## @section ShardingSphere-Proxy cluster parameters ## @param replicaCount ShardingSphere-Proxy cluster starts the number of replicas, Note: After you enable automaticScaling, this parameter will no longer take effect ## @param proxyVersion ShardingSphere-Proxy cluster version ## @@ -93,7 +93,7 @@ serverConfig: ## @param serverConfig.mode.repository.props.timeToLiveSeconds Seconds of ephemeral data live ## @param serverConfig.mode.repository.type Type of persist repository. Now only support ZooKeeper ## @param serverConfig.mode.overwrite Whether overwrite persistent configuration with local configuration - ## + ## @param serverConfig.props.proxy-frontend-database-protocol-type Default startup protocol mode: overwrite: true repository: @@ -132,4 +132,4 @@ zookeeper: storageClass: "" accessModes: - ReadWriteOnce - size: 8Gi + size: 8Gi \ No newline at end of file diff --git a/charts/shardingsphere-operator/values.yaml b/charts/shardingsphere-operator/values.yaml index b69cdba..ae6f1cb 100644 --- a/charts/shardingsphere-operator/values.yaml +++ b/charts/shardingsphere-operator/values.yaml @@ -14,8 +14,8 @@ ## limitations under the License. ## -## @section ShardingSphere-Proxy operator parameters -## @param replicaCount operator replica count +## @section ShardingSphere operator parameters +## @param replicaCount operator replica count ## replicaCount: 2 image: diff --git a/doc/deploy.md b/doc/deploy.md new file mode 100644 index 0000000..16909ac --- /dev/null +++ b/doc/deploy.md @@ -0,0 +1,266 @@ +# ShardingSphere-Operator Concise User Manual + +## install ShardingSphere-Operator + +Configuration [below](#shardingsphere-operator-parameters) configuration content, configuration file location shardingsphere-operator/values.yaml +run + +```shell +kubectl create ns shardingsphere-operator +helm install shardingsphere-operator shardingsphere-operator -n shardingsphere-operator +``` +## install ShardingSphere-Proxy cluster + +Configuration [below](#shardingsphere-proxy-cluster-parameters) configuration content, configuration file location shardingsphere-cluster/values.yaml +run + +```shell +kubectl create ns shardingsphere +helm install shardingsphere-cluster shardingsphere-cluster -n shardingsphere +``` +## Parameters +### ShardingSphere Operator parameters + +| Name | Description | Value | +| ------------------------ | ------------------------------------------- | ------------------------- | +| `replicaCount` | operator replica count | `2` | +| `image.repository` | operator image name | `sahrdingsphere-operator` | +| `image.pullPolicy` | image pull policy | `IfNotPresent` | +| `image.tag` | image tag | `0.0.1` | +| `imagePullSecrets` | image pull secret of private repository | `[]` | +| `resources` | operator Resources required by the operator | `{}` | +| `webhook.port` | operator webhook boot port | `9443` | +| `health.healthProbePort` | operator health check port | `8081` | + + +### ShardingSphere-Proxy Cluster parameters + +| Name | Description | Value | +| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `replicaCount` | ShardingSphere-Proxy cluster starts the number of replicas, Note: After you enable automaticScaling, this parameter will no longer take effect | `3` | +| `proxyVersion` | ShardingSphere-Proxy cluster version | `5.1.2` | +| `automaticScaling.enable` | ShardingSphere-Proxy Whether the ShardingSphere-Proxy cluster has auto-scaling enabled | `false` | +| `automaticScaling.scaleUpWindows` | ShardingSphere-Proxy automatically scales the stable window | `30` | +| `automaticScaling.scaleDownWindows` | ShardingSphere-Proxy automatically shrinks the stabilized window | `30` | +| `automaticScaling.target` | ShardingSphere-Proxy auto-scaling threshold, the value is a percentage, note: at this stage, only cpu is supported as a metric for scaling | `20` | +| `automaticScaling.maxInstance` | ShardingSphere-Proxy maximum number of scaled-out replicas | `4` | +| `automaticScaling.minInstance` | ShardingSphere-Proxy has a minimum number of boot replicas, and the shrinkage will not be less than this number of replicas | `1` | +| `resources` | ShardingSphere-Proxy starts the requirement resource, and after opening automaticScaling, the resource of the request multiplied by the percentage of target is used to trigger the scaling action | `{}` | +| `service.type` | ShardingSphere-Proxy external exposure mode | `ClusterIP` | +| `service.port` | ShardingSphere-Proxy exposes port | `3307` | +| `startPort` | ShardingSphere-Proxy boot port | `3307` | +| `mySQLDriver.version` | ShardingSphere-Proxy The ShardingSphere-Proxy mysql driver version will not be downloaded if it is empty | `5.1.47` | + + +### Compute-Node ShardingSphere-Proxy ServerConfiguration authority parameters + +| Name | Description | Value | +| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | +| `serverConfig.authority.privilege.type` | authority provider for storage node, the default value is ALL_PERMITTED | `ALL_PRIVILEGES_PERMITTED` | +| `serverConfig.authority.users[0].password` | Password for compute node. | `root` | +| `serverConfig.authority.users[0].user` | Username,authorized host for compute node. Format: <username>@<hostname> hostname is % or empty string means do not care about authorized host | `root@%` | + + +### Compute-Node ShardingSphere-Proxy ServerConfiguration mode Configuration parameters + +| Name | Description | Value | +| ----------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| `serverConfig.mode.type` | Type of mode configuration. Now only support Cluster mode | `Cluster` | +| `serverConfig.mode.repository.props.namespace` | Namespace of registry center | `governance_ds` | +| `serverConfig.mode.repository.props.server-lists` | Server lists of registry center | `{{ printf "%s-zookeeper.%s:2181" .Release.Name .Release.Namespace }}` | +| `serverConfig.mode.repository.props.maxRetries` | Max retries of client connection | `3` | +| `serverConfig.mode.repository.props.operationTimeoutMilliseconds` | Milliseconds of operation timeout | `5000` | +| `serverConfig.mode.repository.props.retryIntervalMilliseconds` | Milliseconds of retry interval | `500` | +| `serverConfig.mode.repository.props.timeToLiveSeconds` | Seconds of ephemeral data live | `600` | +| `serverConfig.mode.repository.type` | Type of persist repository. Now only support ZooKeeper | `ZooKeeper` | +| `serverConfig.mode.overwrite` | Whether overwrite persistent configuration with local configuration | `true` | +| `serverConfig.props.proxy-frontend-database-protocol-type` | Default startup protocol | `MySQL` | + + +### ZooKeeper chart parameters + +| Name | Description | Value | +| ------------------------------------ | ---------------------------------------------------- | ------------------- | +| `zookeeper.enabled` | Switch to enable or disable the ZooKeeper helm chart | `true` | +| `zookeeper.replicaCount` | Number of ZooKeeper nodes | `1` | +| `zookeeper.persistence.enabled` | Enable persistence on ZooKeeper using PVC(s) | `false` | +| `zookeeper.persistence.storageClass` | Persistent Volume storage class | `""` | +| `zookeeper.persistence.accessModes` | Persistent Volume access modes | `["ReadWriteOnce"]` | +| `zookeeper.persistence.size` | Persistent Volume size | `8Gi` | + + +## Configuration example + +shardingsphere-operator/values.yaml + +```yaml +## @section ShardingSphere-Proxy operator parameters +## @param replicaCount operator replica count +## +replicaCount: 2 +image: + ## @param image.repository operator image name + ## + repository: "sahrdingsphere-operator" + ## @param image.pullPolicy image pull policy + ## + pullPolicy: IfNotPresent + ## @param image.tag image tag + ## + tag: "0.0.1" +## @param imagePullSecrets image pull secret of private repository +## e.g: +## imagePullSecrets: +## - name: mysecret +## +imagePullSecrets: [] +## @param resources operator Resources required by the operator +## e.g: +## resources: +## limits: +## cpu: 2 +## limits: +## cpu: 2 +## +resources: {} +## @param webhook.port operator webhook boot port +## +webhook: + port: 9443 +## @param health.healthProbePort operator health check port +## +health: + healthProbePort: 8081 +``` + +shardingsphere-cluster/values.yaml + +```yaml +# @section ShardingSphere-Proxy cluster parameters +## @param replicaCount ShardingSphere-Proxy cluster starts the number of replicas, Note: After you enable automaticScaling, this parameter will no longer take effect +## @param proxyVersion ShardingSphere-Proxy cluster version +## +replicaCount: "3" +proxyVersion: "5.1.2" +## @param automaticScaling.enable ShardingSphere-Proxy Whether the ShardingSphere-Proxy cluster has auto-scaling enabled +## @param automaticScaling.scaleUpWindows ShardingSphere-Proxy automatically scales the stable window +## @param automaticScaling.scaleDownWindows ShardingSphere-Proxy automatically shrinks the stabilized window +## @param automaticScaling.target ShardingSphere-Proxy auto-scaling threshold, the value is a percentage, note: at this stage, only cpu is supported as a metric for scaling +## @param automaticScaling.maxInstance ShardingSphere-Proxy maximum number of scaled-out replicas +## @param automaticScaling.minInstance ShardingSphere-Proxy has a minimum number of boot replicas, and the shrinkage will not be less than this number of replicas +## +automaticScaling: + enable: false + scaleUpWindows: 30 + scaleDownWindows: 30 + target: 20 + maxInstance: 4 + minInstance: 1 +## @param resources ShardingSphere-Proxy starts the requirement resource, and after opening automaticScaling, the resource of the request multiplied by the percentage of target is used to trigger the scaling action +## e.g: +## resources: +## limits: +## cpu: 2 +## requests: +## cpu: 2 +## +resources: + limits: + cpu: '2' + requests: + cpu: '1' +## @param service.type ShardingSphere-Proxy external exposure mode +## @param service.port ShardingSphere-Proxy exposes port +## +service: + type: ClusterIP + port: 3307 +## @param startPort ShardingSphere-Proxy boot port +## +startPort: 3307 +## @param mySQLDriver.version ShardingSphere-Proxy The ShardingSphere-Proxy mysql driver version will not be downloaded if it is empty +## +mySQLDriver: + version: "5.1.47" +## @section ShardingSphere-Proxy ServerConfiguration parameters +## NOTE: If you use the sub-charts to deploy Zookeeper, the server-lists field must be "{{ printf \"%s-zookeeper.%s:2181\" .Release.Name .Release.Namespace }}", +## otherwise please fill in the correct zookeeper address +## The server.yaml is auto-generated based on this parameter. +## If it is empty, the server.yaml is also empty. +## ref: https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-jdbc/yaml-config/mode/ +## ref: https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-jdbc/builtin-algorithm/metadata-repository/ +## +serverConfig: + ## @section Compute-Node ShardingSphere-Proxy ServerConfiguration authority parameters + ## NOTE: It is used to set up initial user to login compute node, and authority data of storage node. + ## @param serverConfig.authority.privilege.type authority provider for storage node, the default value is ALL_PERMITTED + ## @param serverConfig.authority.users[0].password Password for compute node. + ## @param serverConfig.authority.users[0].user Username,authorized host for compute node. Format: <username>@<hostname> hostname is % or empty string means do not care about authorized host + ## + authority: + privilege: + type: ALL_PRIVILEGES_PERMITTED + users: + - password: root + user: root@% + ## @section Compute-Node ShardingSphere-Proxy ServerConfiguration mode Configuration parameters + ## @param serverConfig.mode.type Type of mode configuration. Now only support Cluster mode + ## @param serverConfig.mode.repository.props.namespace Namespace of registry center + ## @param serverConfig.mode.repository.props.server-lists Server lists of registry center + ## @param serverConfig.mode.repository.props.maxRetries Max retries of client connection + ## @param serverConfig.mode.repository.props.operationTimeoutMilliseconds Milliseconds of operation timeout + ## @param serverConfig.mode.repository.props.retryIntervalMilliseconds Milliseconds of retry interval + ## @param serverConfig.mode.repository.props.timeToLiveSeconds Seconds of ephemeral data live + ## @param serverConfig.mode.repository.type Type of persist repository. Now only support ZooKeeper + ## @param serverConfig.mode.overwrite Whether overwrite persistent configuration with local configuration + ## + mode: + overwrite: true + repository: + props: + maxRetries: 3 + namespace: governance_ds + operationTimeoutMilliseconds: 5000 + retryIntervalMilliseconds: 500 + server-lists: "{{ printf \"%s-zookeeper.%s:2181\" .Release.Name .Release.Namespace }}" + timeToLiveSeconds: 600 + type: ZooKeeper + type: Cluster + props: + proxy-frontend-database-protocol-type: MySQL +## @section ZooKeeper chart parameters + +## ZooKeeper chart configuration +## https://github.com/bitnami/charts/blob/master/bitnami/zookeeper/values.yaml +## +zookeeper: + ## @param zookeeper.enabled Switch to enable or disable the ZooKeeper helm chart + ## + enabled: true + ## @param zookeeper.replicaCount Number of ZooKeeper nodes + ## + replicaCount: 3 + ## ZooKeeper Persistence parameters + ## ref: https://kubernetes.io/docs/user-guide/persistent-volumes/ + ## @param zookeeper.persistence.enabled Enable persistence on ZooKeeper using PVC(s) + ## @param zookeeper.persistence.storageClass Persistent Volume storage class + ## @param zookeeper.persistence.accessModes Persistent Volume access modes + ## @param zookeeper.persistence.size Persistent Volume size + ## + persistence: + enabled: false + storageClass: "" + accessModes: + - ReadWriteOnce + size: 8Gi +``` + + + +## clean + +```shell +helm uninstall shardingsphere-cluster -n shardingsphere +helm uninstall shardingsphere-operator -n shardingsphere-operator +kubectl delete crd proxies.shardingsphere.sphere-ex.com proxyconfigs.shardingsphere.sphere-ex.com +``` diff --git a/doc/images/ss-operatorIA.png b/doc/images/ss-operatorIA.png new file mode 100644 index 0000000..4484ca4 Binary files /dev/null and b/doc/images/ss-operatorIA.png differ diff --git a/doc/images/ssvx.png b/doc/images/ssvx.png new file mode 100644 index 0000000..1fdcbe4 Binary files /dev/null and b/doc/images/ssvx.png differ diff --git a/doc/quickStart.md b/doc/quickStart.md deleted file mode 100644 index f29f309..0000000 --- a/doc/quickStart.md +++ /dev/null @@ -1,107 +0,0 @@ -# ShardingSphere-Operator 简明使用手册 - -## 配置 - -**Proxy.shardingsphere.sphere-ex.com/v1alpha1** - -```yaml -apiVersion: shardingsphere.sphere-ex.com/v1alpha1 -kind: Proxy -metadata: - name: proxy-sample -spec: - version: "5.1.2" - serviceType: - type: ClusterIP - replicas: 1 - proxyConfigName: "sharding-proxy" - port: 3307 - mySQLDriver: - version: "5.1.47" - resources: - limits: - cpu: "2" - memory: "2Gi" - requests: - cpu: "0.2" - memory: "1.6Gi" -``` - -**ProxyConfig.shardingsphere.sphere-ex.com/v1alpha1** - -```yaml -apiVersion: shardingsphere.sphere-ex.com/v1alpha1 -kind: ProxyConfig -metadata: - name: proxyconfig-sample -spec: - authority: - users: - - user: root@% - password: root - - user: sphere - password: sphere - privilege: - type: ALL_PRIVILEGES_PERMITTED - mode: - type: Cluster - repository: - type: ZooKeeper - props: - namespace: "governance_ds" - server-lists: "<your zkAddr>" - retryIntervalMilliseconds: 500 - timeToLiveSeconds: 600 - maxRetries: 3 - operationTimeoutMilliseconds: 5000 - overwrite: true -``` - -<span id="001">**values.yaml**</span> - -```yaml -# Default values for proxy-operator. -# This is a YAML-formatted file. -# Declare variables to be passed into your templates. - -replicaCount: 2 - -image: - repository: "shardingsphere-operator" - pullPolicy: IfNotPresent - # Overrides the image tag whose default is the chart appVersion. - tag: "0.0.1" -imagePullSecrets: [ ] -service: - type: ClusterIP - port: 80 -resources: - requests: - cpu: 100m - memory: 128Mi -webhook: - serviceName: shardingsphere-operator-admission-webhook - port: 9443 -health: - healthProbePort: 8081 -serviceAccount: - name: shardingsphere-operator -``` - -## 安装 ShardingSphere-Operator - -按照[values.yaml](#001)中的配置完成对 charts/shardingsphere-operator/values.yaml - -执行 - -```shell -kubectl create ns shardingsphere-operator -helm install shardingsphere-operator shardingsphere-operator -n shardingsphere-operator -``` - -## 安装 ShardingSphere-Proxy - -```shell -kubectl apply -f shardingsphere-operator/deploy/samples/shardingsphere_v1alpha1_proxy.yaml -kubectl apply -f shardingsphere-operator/deploy/samples/shardingsphere_v1alpha1_proxyconfig.yaml -```
