Skip to content

Commit

Permalink
docs: merge cn api docs and update descriptions for termination policy (
Browse files Browse the repository at this point in the history 
#8414)
  • Loading branch information
@michelle-0808
michelle-0808 authored Nov 11, 2024
1 parent 21fa706 commit a94a08e
Show file tree
Hide file tree
Showing 86 changed files with 5,454 additions and 723 deletions.
6 changes: 3 additions & 3 deletions ...ecloud-mysql/cluster-management/create-and-connect-an-apecloud-mysql-cluster.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,7 @@ KubeBlocks supports creating two types of ApeCloud MySQL clusters: Standalone an
|---------------------------------------|--------------------------------------|
| `spec.clusterDefinitionRef` | It specifies the name of the ClusterDefinition for creating a specific type of cluster. |
| `spec.clusterVersionRef` | It is the name of the cluster version CRD that defines the cluster version. |
| `spec.terminationPolicy` | It is the policy of cluster termination. The default value is `Delete`. Valid values are `DoNotTerminate`, `Halt`, `Delete`, `WipeOut`. <p> - `DoNotTerminate` blocks deletion operation. </p><p> - `Halt` deletes workload resources such as statefulset and deployment workloads but keep PVCs. </p><p> - `Delete` is based on Halt and deletes PVCs. </p><p> - `WipeOut` is based on Delete and wipe out all volume snapshots and snapshot data from a backup storage location. </p>|
| `spec.terminationPolicy` | It is the policy of cluster termination. The default value is `Delete`. Valid values are `DoNotTerminate`, `Delete`, `WipeOut`. For the detailed definition, you can refer to [Termination Policy](./delete-mysql-cluster.md#termination-policy). |
| `spec.affinity` | It defines a set of node affinity scheduling rules for the cluster's Pods. This field helps control the placement of Pods on nodes within the cluster. |
| `spec.affinity.podAntiAffinity` | It specifies the anti-affinity level of Pods within a component. It determines how pods should spread across nodes to improve availability and performance. |
| `spec.affinity.topologyKeys` | It represents the key of node labels used to define the topology domain for Pod anti-affinity and Pod spread constraints. |
Expand Down Expand Up @@ -264,11 +264,11 @@ KubeBlocks operator creates a new Secret called `mycluster-conn-credential` to s
1. Run the command below to get the `username` and `password` for the `kubectl exec` command.
```bash
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\username}' | base64 -d
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.username}' | base64 -d
>
root
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\password}' | base64 -d
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.password}' | base64 -d
>
2gvztbvz
```
Expand Down
8 changes: 4 additions & 4 deletions ...r_docs/kubeblocks-for-apecloud-mysql/cluster-management/delete-mysql-cluster.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ The termination policy determines how a cluster is deleted.
| **terminationPolicy** | **Deleting Operation** |
|:----------------------|:-------------------------------------------------|
| `DoNotTerminate` | `DoNotTerminate` blocks delete operation. |
| `Halt` | `Halt` deletes workload resources such as statefulset, deployment workloads but keep PVCs. |
| `Delete` | `Delete` deletes workload resources and PVCs but keep backups. |
| `WipeOut` | `WipeOut` deletes workload resources, PVCs and all relevant resources included backups. |
| `Halt` | `Halt` deletes Cluster resources like Pods and Services but retains Persistent Volume Claims (PVCs), allowing for data preservation while stopping other operations. Halt policy is deprecated in v0.9.1 and will have same meaning as DoNotTerminate. |
| `Delete` | `Delete` extends the Halt policy by also removing PVCs, leading to a thorough cleanup while removing all persistent data. |
| `WipeOut` | `WipeOut` deletes all Cluster resources, including volume snapshots and backups in external storage. This results in complete data removal and should be used cautiously, especially in non-production environments, to avoid irreversible data loss. |

To check the termination policy, execute the following command.

Expand Down Expand Up @@ -63,7 +63,7 @@ Run the command below to delete a specified cluster.
<TabItem value="kbcli" label="kbcli" default>

```bash
kbcli cluster delete mycluster
kbcli cluster delete mycluster -n demo
```

</TabItem>
Expand Down
4 changes: 2 additions & 2 deletions ..._docs/kubeblocks-for-apecloud-mysql/cluster-management/restart-mysql-cluster.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ You can restart all pods of the cluster. When an exception occurs in a database,
Configure the values of `components` and `ttlSecondsAfterSucceed` and run the command below to restart a specified cluster.

```bash
kbcli cluster restart <name> --components="mysql" --ttlSecondsAfterSucceed=30
kbcli cluster restart mycluster --components="mysql" --ttlSecondsAfterSucceed=30 -n demo
```

- `components` describes the component name that needs to be restarted.
Expand All @@ -33,7 +33,7 @@ You can restart all pods of the cluster. When an exception occurs in a database,
2. Check the cluster status to validate the restarting.

```bash
kbcli cluster list mycluster
kbcli cluster list mycluster -n demo
>
NAME NAMESPACE CLUSTER-DEFINITION VERSION TERMINATION-POLICY STATUS CREATED-TIME
mycluster demo apecloud-mysql ac-mysql-8.0.30 Delete Running Sep 19,2024 16:01 UTC+0800
Expand Down
2 changes: 1 addition & 1 deletion ...cs/kubeblocks-for-apecloud-mysql/cluster-management/scale-for-apecloud-mysql.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@ mycluster apecloud-mysql ac-mysql-8.0.30 Delete Running
Horizontal scaling changes the amount of pods. For example, you can scale out replicas from three to five. The scaling process includes the backup and restore of data.
From v0.9.0, besides replicas, KubeBlocks also supports scaling in and out instances, refer to [Horizontal Scale](./../../../api_docs/maintenance/scale/horizontal-scale.md) in API docs for more details and examples.
From v0.9.0, besides replicas, KubeBlocks also supports scaling in and out instances, refer to the [Horizontal Scale tutorial](./../../maintenance/scale/horizontal-scale.md) for more details and examples.
### Before you start
Expand Down
79 changes: 16 additions & 63 deletions docs/user_docs/kubeblocks-for-apecloud-mysql/configuration/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -175,10 +175,10 @@ The example below takes configuring `max_connections` and `innodb_buffer_pool_si
4. Connect to the database to verify whether the parameters are configured as expected.
The whole searching process has a 30-second delay since it takes some time for kubelet to synchronize modifications to the volume of the pod.
It takes about 30 seconds for the configuration to take effect because the kubelet requires some time to sync changes in the ConfigMap to the Pod's volume.
```bash
kbcli cluster connect mycluster
kbcli cluster connect mycluster -n demo
```
```bash
Expand Down Expand Up @@ -219,7 +219,7 @@ The following steps take configuring MySQL Standalone as an example.
:::note
* Since ApeCloud MySQL currently supports multiple templates, it is required to use `--config-spec` to specify a configuration template. You can run `kbcli cluster describe-config mycluster` to view all template names.
* Since ApeCloud MySQL currently supports multiple templates, it is required to use `--config-spec` to specify a configuration template. You can run `kbcli cluster describe-config mycluster -n demo` to view all template names.
* If there are multiple components in a cluster, use `--components` to specify a component.
:::
Expand All @@ -233,7 +233,7 @@ The following steps take configuring MySQL Standalone as an example.
3. Connect to the database to verify whether the parameters are configured as expected.
```bash
kbcli cluster connect mycluster
kbcli cluster connect mycluster -n demo
```
:::note
Expand Down Expand Up @@ -319,11 +319,11 @@ KubeBlocks supports configuring cluster parameters by editing the configuration
1. Get the username and password.
```bash
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\username}' | base64 -d
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.username}' | base64 -d
>
root
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\password}' | base64 -d
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.password}' | base64 -d
>
2gvztbvz
```
Expand All @@ -344,6 +344,12 @@ KubeBlocks supports configuring cluster parameters by editing the configuration
1 row in set (0.00 sec)
```
:::note
Just in case you cannot find the configuration file of your cluster, you can switch to the `kbcli` tab and use relevant commands to view the current configuration file of a cluster.
:::
</TabItem>
<TabItem value="OpsRequest" label="OpsRequest">
Expand Down Expand Up @@ -399,11 +405,11 @@ KubeBlocks supports configuring cluster parameters with an OpsRequest.
1. Get the username and password.
```bash
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\username}' | base64 -d
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.username}' | base64 -d
>
root
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\password}' | base64 -d
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.password}' | base64 -d
>
2gvztbvz
```
Expand All @@ -426,63 +432,10 @@ KubeBlocks supports configuring cluster parameters with an OpsRequest.
:::note
Just in case you cannot find the configuration file of your cluster, you can use `kbcli` to view the current configuration file of a cluster.
```bash
kbcli cluster describe-config mycluster -n demo
```
From the meta information, the cluster `mycluster` has a configuration file named `my.cnf`.
You can also view the details of this configuration file and parameters.
* View the details of the current configuration file.
```bash
kbcli cluster describe-config mycluster --show-detail -n demo
```
* View the parameter description.
```bash
kbcli cluster explain-config mycluster -n demo | head -n 20
```
* View the user guide of a specified parameter.
```bash
kbcli cluster explain-config mycluster --param=innodb_buffer_pool_size --config-specs=mysql-consensusset-config -n demo
```
`--config-specs` is required to specify a configuration template since ApeCloud MySQL currently supports multiple templates. You can run `kbcli cluster describe-config mycluster` to view the all template names.
<details>
<summary>Output</summary>
```bash
template meta:
ConfigSpec: mysql-consensusset-config ComponentName: mysql ClusterName: mycluster
Configure Constraint:
Parameter Name: innodb_buffer_pool_size
Allowed Values: [5242880-18446744073709552000]
Scope: Global
Dynamic: false
Type: integer
Description: The size in bytes of the memory buffer innodb uses to cache data and indexes of its tables
```
</details>
* Allowed Values: It defines the valid value range of this parameter.
* Dynamic: The value of `Dynamic` in `Configure Constraint` defines how the parameter configuration takes effect. There are two different configuration strategies based on the effectiveness type of modified parameters, i.e. **dynamic** and **static**.
* When `Dynamic` is `true`, it means the effectiveness type of parameters is **dynamic** and can be configured online.
* When `Dynamic` is `false`, it means the effectiveness type of parameters is **static** and a pod restarting is required to make the configuration effective.
* Description: It describes the parameter definition.
Just in case you cannot find the configuration file of your cluster, you can switch to the `kbcli` tab and use relevant commands to view the current configuration file of a cluster.
:::
</TabItem>
</Tabs>
</Tabs>
4 changes: 2 additions & 2 deletions .../user_docs/kubeblocks-for-apecloud-mysql/high-availability/high-availability.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,11 +112,11 @@ After the leader pod is deleted, the ApeCloud MySQL RaftGroup Cluster elects a n
Connect to this cluster to check the pod roles and status. This cluster can be connected within seconds.

```bash
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\username}' | base64 -d
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.username}' | base64 -d
>
root
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\password}' | base64 -d
kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.password}' | base64 -d
>
pt2mmdlp4
Expand Down
12 changes: 5 additions & 7 deletions docs/user_docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ It is recommended to use kbcli to create an ApeCloud MySQL Proxy Cluster.

:::note

If you only have one node for deploying a RaftGroup Cluster, set the `extra.availability-policy` as `none` when creating a RaftGroup Cluster.
If you only have one node for deploying a RaftGroup Cluster, set the `extra.availabilityPolicy` as `none` when creating a RaftGroup Cluster.

```bash
helm install myproxy kubeblocks/apecloud-mysql-cluster --version=v0.9.0 --set mode=raftGroup,proxyEnabled=true,etcd.serviceReference.endpoint="etcd-cluster-etcd.default.svc.cluster.local:2379" --set extra.availabilityPolicy=none
Expand Down Expand Up @@ -422,11 +422,7 @@ VTGate, VTConsensus, and VTTablet support parameter configuration. You can confi

</TabItem>

<TabItem value="kubectl" label="kubectl">

VTGate, VTConsensus, and VTTablet support parameter configuration. You can configure the proxy cluster by editing the configuration file or by performing an OpsRequest.

### Option 1. Edit the config file
<TabItem value="Edit Config File" label="Edit Config File">

1. Get the configuration file of this cluster.

Expand Down Expand Up @@ -478,7 +474,9 @@ VTGate, VTConsensus, and VTTablet support parameter configuration. You can confi
1 row in set (0.00 sec)
```

### Option 2. Apply an OpsRequest
</TabItem>

<TabItem value="OpsRequest" label="OpsRequest">

Apply an OpsRequest to the specified cluster. Configure the parameters according to your needs.

Expand Down
77 changes: 75 additions & 2 deletions docs/user_docs/kubeblocks-for-elasticsearch/manage-elasticsearch.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ EOF

| Field | Definition |
|---------------------------------------|--------------------------------------|
| `spec.terminationPolicy` | It is the policy of cluster termination. The default value is `Delete`. Valid values are `DoNotTerminate`, `Halt`, `Delete`, `WipeOut`. <p> - `DoNotTerminate` blocks deletion operation. </p><p> - `Halt` deletes workload resources such as statefulset and deployment workloads but keep PVCs. </p><p> - `Delete` is based on Halt and deletes PVCs. </p> - `WipeOut` is based on Delete and wipe out all volume snapshots and snapshot data from a backup storage location. |
| `spec.terminationPolicy` | It is the policy of cluster termination. The default value is `Delete`. Valid values are `DoNotTerminate`, `Delete`, `WipeOut`. For the detailed definition, you can refer to [Termination Policy](#termination-policy). |
| `spec.affinity` | It defines a set of node affinity scheduling rules for the cluster's Pods. This field helps control the placement of Pods on nodes within the cluster. |
| `spec.affinity.podAntiAffinity` | It specifies the anti-affinity level of Pods within a component. It determines how pods should spread across nodes to improve availability and performance. |
| `spec.affinity.topologyKeys` | It represents the key of node labels used to define the topology domain for Pod anti-affinity and Pod spread constraints. |
Expand Down Expand Up @@ -199,7 +199,7 @@ mycluster Delete R

Horizontal scaling changes the amount of pods. For example, you can scale out replicas from three to five.

From v0.9.0, besides replicas, KubeBlocks also supports scaling in and out instances, refer to [Horizontal Scale](./../../api_docs/maintenance/scale/horizontal-scale.md) in API docs for more details and examples.
From v0.9.0, besides replicas, KubeBlocks also supports scaling in and out instances, refer to the [Horizontal Scale tutorial](./../maintenance/scale/horizontal-scale.md) for more details and examples.

<Tabs>

Expand Down Expand Up @@ -893,3 +893,76 @@ You can stop/start a cluster to save computing resources. When a cluster is stop
</TabItem>
</Tabs>
## Delete a cluster
### Termination policy
:::note
The termination policy determines how a cluster is deleted.
:::
| **terminationPolicy** | **Deleting Operation** |
|:----------------------|:-------------------------------------------------|
| `DoNotTerminate` | `DoNotTerminate` blocks delete operation. |
| `Halt` | `Halt` deletes Cluster resources like Pods and Services but retains Persistent Volume Claims (PVCs), allowing for data preservation while stopping other operations. Halt policy is deprecated in v0.9.1 and will have same meaning as DoNotTerminate. |
| `Delete` | `Delete` extends the Halt policy by also removing PVCs, leading to a thorough cleanup while removing all persistent data. |
| `WipeOut` | `WipeOut` deletes all Cluster resources, including volume snapshots and backups in external storage. This results in complete data removal and should be used cautiously, especially in non-production environments, to avoid irreversible data loss. |
To check the termination policy, execute the following command.
<Tabs>
<TabItem value="kbcli" label="kbcli" default>
```bash
kbcli cluster list mycluster -n demo
>
NAME NAMESPACE CLUSTER-DEFINITION VERSION TERMINATION-POLICY STATUS CREATED-TIME
mycluster demo Delete Running Sep 27,2024 11:42 UTC+0800
```
</TabItem>
<TabItem value="kubectl" label="kubectl">
```bash
kubectl get cluster mycluster -n demo
>
NAME CLUSTER-DEFINITION VERSION TERMINATION-POLICY STATUS AGE
mydemo Delete Creating 27m
```
</TabItem>
</Tabs>
### Steps
Run the command below to delete a specified cluster.
<Tabs>
<TabItem value="kbcli" label="kbcli" default>
```bash
kbcli cluster delete mycluster -n demo
```
</TabItem>
<TabItem value="kubectl" label="kubectl">
If you want to delete a cluster and its all related resources, you can modify the termination policy to `WipeOut`, then delete the cluster.
```bash
kubectl patch -n demo cluster mycluster -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge"
kubectl delete -n demo cluster mycluster
```
</TabItem>
</Tabs>
Loading

0 comments on commit a94a08e

Please sign in to comment.