diff --git a/README.md b/README.md index fc1288c5..41bdc302 100644 --- a/README.md +++ b/README.md @@ -19,29 +19,11 @@ The design architecture of this project is based on [openkruise/controllermesh](

## Quick Start -Visit [Quick Start](). +Visit [Quick Start](docs/getting-started.md). ## Installation -**Install by helm** -```shell -# Firstly add charts repository if you haven't do this. -$ helm repo add kusionstack https://kusionstack.io/charts - -# [Optional] -$ helm repo update - -# Install the latest version. -$ helm install ctrlmesh kusionstack/ctrlmesh --version v0.1.0 - -# Uninstall -$ helm uninstall ctrlmesh -``` -**Proxy** -1. Apply your [ShardingConfig](). -2. Add label `ctrlmesh.kusionstack.io/enable-proxy=true` on pod template. - - +Visit [Installation](docs/installation.md). ## Principles Generally, a `ctrlmesh-proxy` container will be injected into each operator Pod that has configured in ShardingConfigs. diff --git a/docs/circuitbreaker.md b/docs/circuitbreaker.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/demo.md b/docs/demo.md deleted file mode 100644 index 796e048a..00000000 --- a/docs/demo.md +++ /dev/null @@ -1,2 +0,0 @@ -# Demo - diff --git a/docs/getting-started.md b/docs/getting-started.md index 5009dcda..6952be2d 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,30 +2,110 @@ This guide lets you quickly evaluate KusionStack Controller Mesh. -## Installation -Controller-Mesh requires **Kubernetes version >= 1.18** +## Install Controller Mesh Manager +Controller Mesh requires **Kubernetes version >= 1.18** **Install with helm** -```shell +```bash # Firstly add KusionStack charts repository if you haven't do this. $ helm repo add kusionstack https://kusionstack.io/charts -# [Optional] -$ helm repo update +# To update the kusionstack repo. +$ helm repo update kusionstack # Install the latest version. $ helm install ctrlmesh kusionstack/ctrlmesh --version v0.1.0 -# Uninstall -$ helm uninstall ctrlmesh +# Wait manager ready +$ kubectl -n ctrlmesh get po +NAME READY STATUS RESTARTS AGE +ctrlmesh-57d6b4df57-mdslc 1/1 Running 0 40s +ctrlmesh-57d6b4df57-mtv2s 1/1 Running 0 40s ``` +[Install manager with more options](installation.md) +## Enable Custom Operator Sharding -## Deploy the sample operator application + 1. Deploy the sample operator application: - 1. Deploy the sample operator application +```bash +$ helm install sample kusionstack/sample-operator --version v0.1.1 -```shell -# -$ helm install ctrlmesh kusionstack/demo-operator --version v0.1.0 +$ kubeconfig kubectl -n ctrlmesh get sts +NAME READY AGE +demo-operator 2/2 10s +$ kubectl -n ctrlmesh get po +NAME READY STATUS RESTARTS AGE +ctrlmesh-57d6b4df57-mdslc 1/1 Running 0 1m +ctrlmesh-57d6b4df57-mtv2s 1/1 Running 0 1m +demo-operator-0 1/1 Running 0 17s +demo-operator-1 1/1 Running 0 16s +``` + + 2. Config and apply shardingconfig: + +```bash +# Show demo shardingconfig +$ helm template sample kusionstack/sample-operator --version v0.1.1 --set sharding.enable=true --show-only templates/shardingconfig.yaml > shardingconfig.yaml +$ cat shardingconfig.yaml +``` +```yaml +--- +# Source: sample-operator/templates/shardingconfig.yaml +apiVersion: ctrlmesh.kusionstack.io/v1alpha1 +kind: ShardingConfig +metadata: + name: sharding-root + namespace: ctrlmesh +spec: + # auto sharding config + root: + prefix: sample-demo + targetStatefulSet: sample-operator + canary: + replicas: 1 + inNamespaces: + - demo-0a + auto: + everyShardReplicas: 2 + shardingSize: 2 + resourceSelector: + - relateResources: + - apiGroups: + - '*' + resources: + - configmaps + selector: + matchLabels: + control-by: demo + controller: + leaderElectionName: demo-manager +``` +```bash +# You can configure the ShardingConfig according to your requirements. +# Apply shardingconfig +$ kubectl apply shardingconfig.yaml + +# Waiting for pods to be recreate and ready. +# The mesh-proxy container will be automatically injected into the pod. +$ kubectl -n ctrlmesh get po +NAME READY STATUS RESTARTS AGE +ctrlmesh-57d6b4df57-mdslc 1/1 Running 0 6m +ctrlmesh-57d6b4df57-mtv2s 1/1 Running 0 6m +sample-operator-0 2/2 Running 0 22s +sample-operator-1 2/2 Running 0 17s +sample-operator-2 2/2 Running 0 13s +sample-operator-3 2/2 Running 0 9s +sample-operator-4 2/2 Running 0 5s + +# Now we have three shards with three lease. +# sample-demo-0-canary -> [sample-operator-0] +# sample-demo-1-normal -> [sample-operator-1, sample-operator-2] +# sample-demo-2-normal -> [sample-operator-3, sample-operator-4] +$ kubectl -n ctrlmesh get lease +NAME HOLDER AGE +ctrlmesh-manager ctrlmesh-57d6b4df57-mdslc_a804c1cc-4bca-4acc-a0c3-54762b459cb3 6m +demo-manager---sample-demo-0-canary sample-operator-0_55a0909a-a72b-469b-86c6-cbabccee1269 85s +demo-manager---sample-demo-1-normal sample-operator-1_45efc2fa-4928-4073-81c4-9b0892a7398d 81s +demo-manager---sample-demo-2-normal sample-operator-3_55914401-a735-445b-84d2-17120dca0e05 73s ``` \ No newline at end of file diff --git a/docs/img/sharding.png b/docs/img/sharding.png new file mode 100644 index 00000000..decbec69 Binary files /dev/null and b/docs/img/sharding.png differ diff --git a/docs/installation.md b/docs/installation.md index e000b8d4..9edb0803 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,18 +1,50 @@ ## Installation -**Helm** +### Install with helm +Controller Mesh requires **Kubernetes version >= 1.18** ```shell # Firstly add charts repository if you haven't do this. $ helm repo add kusionstack https://kusionstack.io/charts -# [Optional] -$ helm repo update +# To update the kusionstack repo. +$ helm repo update kusionstack # Install the latest version. $ helm install ctrlmesh kusionstack/ctrlmesh --version v0.1.0 +# Upgrade to the latest version +$ helm upgrade ctrlmesh kusionstack/ctrlmesh + # Uninstall $ helm uninstall ctrlmesh ``` +[Helm](https://github.com/helm/helm) is a tool for managing packages of pre-configured Kubernetes resources. +### Optional: chart parameters + +The following table lists the configurable parameters of the chart and their default values. + +| Parameter | Description | Default | +|-------------------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `namespace` | namespace for controller mesh installation | `ctrlmesh` | +| `namespaceEnabled` | Whether to create the installation.namespace | `true` | +| `manager.replicas` | Replicas of ctrlmesh-manager deployment | `2` | +| `manager.image.repo` | Repository for ctrlmesh-manager image | `kusionstack/ctrlmesh-manager` | +| `manager.image.pullPolicy` | Image pull policy for ctrlmesh-manager | `IfNotPresent` | +| `manager.image.tag` | Tag for ctrlmesh-manager | `v0.1.0` | +| `manager.resources.limits.cpu` | CPU resource limit of ctrlmesh-manager container | `500m` | +| `manager.resources.limits.memory` | Memory resource limit of ctrlmesh-manager container | `512Mi` | +| `manager.resources.requests.cpu` | CPU resource request of ctrlmesh-manager container | `10m` | +| `manager.resources.requests.memory` | Memory resource request of ctrlmesh-manager container | `64Mi` | +| `proxy.image.repo` | Repository for ctrlmesh-proxy image | `kusionstack/ctrlmesh-proxy` | +| `proxy.image.pullPolicy` | Image pull policy for ctrlmesh-proxy | `IfNotPresent` | +| `proxy.image.tag` | Tag for ctrlmesh-proxy | `v0.1.0` | +| `proxy.resources.limits.cpu` | CPU resource requests of ctrlmesh-proxy container | `100m` | +| `proxy.resources.limits.memory` | Memory resource requests of ctrlmesh-proxy container | `100Mi` | +| `init.image.repo` | Repository for ctrlmesh-init image | `kusionstack/ctrlmesh-init` | +| `init.image.tag` | Tag for ctrlmesh-init | `v0.1.0` | +| `shardingGroupVersionKinds` | Sharding resource lists（yaml） | `groupVersionKinds:`
`ctrlmesh.kusionstack.io/v1alpha1:`
`- '*'`
` v1:`
`- Pod`
`- PersistentVolumeClaim`
`- Service`
`- ConfigMap`
`- Endpoint`
` apps/v1:`
`- StatefulSet`
`- ReplicaSet`
`- ControllerRevision` | + +Specify each parameter using the `--set key=value` argument to `helm install` or `helm upgrade`. + diff --git a/docs/intro.md b/docs/intro.md index bb70a14c..e2cdca9c 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -11,6 +11,6 @@ The design architecture of this project is based on [openkruise/controllermesh]( 1. **Sharding**: Through relevant configurations, Kubernetes single-point deployed operator applications can be flexibly shard deployed. 2. **Canary upgrade**: Depends on sharding, the controllers can be updated in canary progress instead of one time replace. 3. **Circuit breaker and rate limiter**: Not only Kubernetes operation requests, but also other external operation requests. -4. **Multicluster routing and sharding**: This feature is supported by [kusionstack/kaera(karbour)]() +4. **Multicluster routing and sharding**.

\ No newline at end of file