Skip to content

update doc #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 20, 2023
Merged

update doc #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 2 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,29 +19,11 @@ The design architecture of this project is based on [openkruise/controllermesh](
<p align="center"><img width="800" src="./docs/img/mesh-arch-2.png"/></p>

## 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.
Expand Down
Empty file added docs/circuitbreaker.md
View file
Open in desktop
Empty file.
2 changes: 0 additions & 2 deletions docs/demo.md
View file
Open in desktop

This file was deleted.

104 changes: 92 additions & 12 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Binary file added docs/img/sharding.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
38 changes: 35 additions & 3 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:`<br>`ctrlmesh.kusionstack.io/v1alpha1:`<br>`- '*'`<br>` v1:`<br>`- Pod`<br>`- PersistentVolumeClaim`<br>`- Service`<br>`- ConfigMap`<br>`- Endpoint`<br>` apps/v1:`<br>`- StatefulSet`<br>`- ReplicaSet`<br>`- ControllerRevision` |

Specify each parameter using the `--set key=value` argument to `helm install` or `helm upgrade`.


2 changes: 1 addition & 1 deletion docs/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**.

<p align="center"><img width="800" src="../docs/img/mesh-arch-2.png"/></p>