1.cluster-command-groups.md

# Cluster commands

OBD provides multiple-level commands. You can use the `-h/--help` option to view the help information of sub-commands. Similarly, you can also use `-v/--verbose` to view the detailed execution process of commands when the execution of sub commands reports an error.

A deployment configuration is the minimum unit for OBD cluster commands. A deployment configuration is a `yaml` file. It contains all configuration information of a deployment, including the server login information, component information, component configuration information, and component server list.

To start a cluster by using OBD, you must register the deployment configuration of your cluster to OBD. You can run the `obd cluster edit-config` command to create an empty deployment configuration or run the `obd cluster deploy -c config` command to import a deployment configuration.

## obd cluster autodeploy

When you pass a simple configuration file to OBD, OBD will automatically generate a complete configuration file with the maximum specifications based on the resources of the target server, and then deploy and start a cluster on the target server.

```shell
obd cluster autodeploy <deploy name> -c <yaml path> [-f] [-U] [-A] [-s]

# example
obd cluster autodeploy test -c all-components.yaml
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

The following table describes the corresponding options.

| Option | Required | Data type | Default value | Description |
|----|-----|-----|----|----|
| -c/--config | Yes | string | None | Specifies the yaml file used for deployment and registers the deployment configuration to OBD. <br>When the `deploy name` already exists, OBD will check the status of the existing deployment configuration. If the existing deployment configuration has not been applied, it will be overwritten. If the existing deployment configuration is in use, an error will be returned.  |
| -f/--force | No | bool | false | Specifies whether to forcibly clear the working directory. <br>When the component requires an empty working directory but this option is disabled, an error will be returned if the working directory is not empty.  |
| -C/--clean                    | No    | bool   | false | Specifies whether to clear the working directory. When the working directory (`home_path`) belongs to the current operating user and this option is true, the working directory will be cleared.    |
| -U/--ulp/--unuselibrepo | No | bool | false | Specifies whether to prevent OBD from automatically taking actions when dependencies are missing. If this option is disabled and OBD detects that some dependencies are missing, OBD will automatically search for the corresponding libs mirrors and install them. If this option is enabled, the **unuse_lib_repository: true** field will be added to the corresponding configuration file. You can also add the **unuse_lib_repository: true** field to the configuration file to enable this option.  |
| -A/--act/--auto-create-tenant | No | bool | false | Specifies whether to enable OBD to create the `test` tenant during the bootstrap by using all available resources of the cluster. If this option is enabled, the **auto_create_tenant: true** field will be added to the corresponding configuration file. You can also add the **auto_create_tenant: true** field to the configuration file to enable this option.  |
| -s/--strict-check | No | bool | false | Some components will do relevant checks before starting. It will issue an alarm when the check fails, but it will not force the process to stop. Using this option can return an error and directly exit the process when the component pre-check fails. We recommend that you enable this option to avoid startup failures due to insufficient resources.  |

## obd cluster edit-config

Modifies a deployment configuration or creates one when the specified deployment configuration does not exist.

```shell
obd cluster edit-config <deploy name>

# example
obd cluster edit-config test
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

## obd cluster deploy

Deploys a cluster based on the deployment configuration file. Based on the deployment configuration file, this command finds the matching mirror, then installs the mirror in a local repository. This process is called local installation.
Then, OBD distributes the components of the required version in the local repository to the target server. This process is called remote installation.
During both local and remote installation, OBD checks whether the server stores dependencies required for running the components.
This command allows you to deploy a cluster based on a deployment configuration that has been registered to OBD or by passing a `yaml` file.

```shell
obd cluster deploy <deploy name> [-c <yaml path>] [-f] [-U] [-A]

# example
obd cluster deploy test -c all-components-min.yaml
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

The following table describes the corresponding options.

| Option | Required | Data type | Default value | Description |
|----|-----|-----|----|----|
| -c/--config | No | string | None | Specifies the yaml file used for deployment and registers the deployment configuration to OBD. <br>If this option is enabled and a deployment configuration of the specified `deploy name` already exists, the existing deployment configuration will be overwritten. <br>If this option is not enabled, OBD will search for the registered deployment configuration of the specified `deploy name`.  |
| -f/--force | No | bool | false | Specifies whether to forcibly clear the working directory. <br>When the component requires an empty working directory but this option is disabled, an error will be returned if the working directory is not empty.  |
| -C/--clean                    | No    | bool   | false | Specifies whether to clear the working directory. When the working directory (`home_path`) belongs to the current operating user and this option is true, the working directory will be cleared.    |
| -U/--ulp/--unuselibrepo | No | bool | false | Specifies whether to prevent OBD from automatically taking actions when dependencies are missing. If this option is disabled and OBD detects that some dependencies are missing, OBD will automatically search for the corresponding libs mirrors and install them. If this option is enabled, the **unuse_lib_repository: true** field will be added to the corresponding configuration file. You can also add the **unuse_lib_repository: true** field to the configuration file to enable this option.  |
| -A/--act/--auto-create-tenant | No | bool | false | Specifies whether to enable OBD to create the `test` tenant during the bootstrap by using all available resources of the cluster. If this option is enabled, the **auto_create_tenant: true** field will be added to the corresponding configuration file. You can also add the **auto_create_tenant: true** field to the configuration file to enable this option.  |

## obd cluster start

Starts a deployed cluster. If the cluster is started, OBD will return its status.

```shell
obd cluster start <deploy name> [flags]

# example
obd cluster start test -S
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

This table describes the corresponding options.

| Option | Required | Data type | Default value | Description |
|----|-----|-----|----|----|
| -s/--servers | No | string | Empty  | A list of machines, followed by the `name` value corresponding to `servers` in the `yaml` file, separated by `,`. If the `name` value is not configured after `servers`, the `ip` value is used. Be used for specifying the machines need to be started. If this option is disabled, all machines under the component will start without executing bootstrap.  |
| -c/--components | No | string | Empty  | A list of components, separated by `,`. Be used for specifying the components need to be started. If this option is disabled, all machines under the component will start without entering the running state.  |
| --wop/--without-parameter | No | bool | false | Start without parameters. The node does not respond to this option when this node is starting for the first time.  |
| -S/--strict-check | No | bool | false | Some components will do relevant checks before starting. OBD will throw an error when the check fails, but OBD will not force the process to stop. Using this option can return an error and directly exit the process when the component pre-check fails. We recommend that you enable this option to avoid startup failures due to insufficient resources.  |

## obd cluster list

Shows the status of all clusters that have been registered to OBD. The cluster names are specified by the deploy name parameter.

```shell
obd cluster list
```

## obd cluster display

Shows the status of the specified cluster.

```shell
obd cluster display <deploy name>

# example
obd cluster display test
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

## obd cluster reload

Reloads a running cluster. After you modify the configuration information of a running cluster by using the `edit-config` command, you can run the `reload` command to let your modification take effect.

> **NOTE:**
>
> Some configuration items may not take effect after you run the `reload` command. You need to restart or even redeploy the cluster for these configuration items to take effect. Do operations based on the result returned by the `edit-config` command.

```shell
obd cluster reload <deploy name>

# example
obd cluster reload test
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

## obd cluster restart

Restarts a running cluster. By default, OBD restarts without any parameters. After you run the edit-config command to modify the configuration information of a running cluster, you can run the `restart` command for the modification to take effect.

> **NOTE:**
>
> Some configuration items may not take effect after you run the `restart` command. You even need to redeploy the cluster for some configuration items to take effect. Perform operations based on the result returned by the edit-config command.

```shell
obd cluster restart <deploy name>

# example
obd cluster restart test -c obproxy-ce --wp
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

This table describes the corresponding options.

| Option | Required | Data type | Default value | Description |
|----|-----|-----|----|----|
| -s/--servers | No | string | Empty  | A list of machines, followed by the `name` value corresponding to `servers` in the `yaml` file, separated by `,`. If the `name` value is not configured after `servers`, the `ip` value is used. Be used to specify the machines need to be restarted. |
| -c/--components | No | string | Empty  | A list of components, separated by `,`. Be used to specify the components need to be restarted. If this option is disabled, all machines under the component will start without entering the running state.  |
| --wp/--with-parameter | No | bool | false | Restarts OBD with parameters. This option makes the parameters valid when you restart OBD.   |

## obd cluster redeploy

Redeploys a running cluster. After you run the `edit-config` command to modify the configuration information of a running cluster, you can run the `redeploy` command to let your modification take effect.

> **NOTE:**
>
> This command destroys the cluster and redeploys it. Data in the cluster will be lost. Please back up the data before you run this command.

```shell
obd cluster redeploy <deploy name> [-f]

# example
obd cluster redeploy test -f
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

Before OBD redeploys the cluster, it will check for running processes. These processes may result from the failure of the `obd cluster start` command. They may also belong to other clusters when configurations of this cluster overlap with those of other clusters. If an ongoing process is found in the working directory, OBD will stop the `obd cluster redeploy` command.

`-f` is `--force-kill`. This option specifies whether to forcibly stop running processes in the working directory. If this option is enabled, OBD will forcibly stop the ongoing processes and run the `obd cluster redeploy` command. `-f` is optional. Its data type is `bool`. This option is disabled by default.

## obd cluster stop

Stops a running cluster.

```shell
obd cluster stop <deploy name>

# example
obd cluster stop test -s server1
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

This table describes the corresponding options.

| Option | Required | Data type | Default value | Description |
|----|-----|-----|----|----|
| -s/--servers | No | string | Empty  | A list of machines, followed by the `name` value corresponding to `servers` in the `yaml` file, separated by `,`. If the `name` value is not configured after `servers`, the `ip` value is used. Be used to specify the machines need to be stopped  |
| -c/--components | No | string | Empty  | A list of components, separated by `,`. Be used to specify the components need to be stopped. If not all components under the configuration start, this configuration will not enter the stopped state.  |

## obd cluster destroy

Destroys a deployed cluster. If the cluster is running state, this command will first try to execute `stop` and then `destroy` after success.

```shell
obd cluster destroy <deploy name> [-f]

# example
obd cluster destroy test -f
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

Before OBD destroys the cluster, it will check for running processes. These processes may result from the failure of the `obd cluster start` command. They may also belong to other clusters when configurations of this cluster overlap with those of other clusters. If an ongoing process is found in the working directory, OBD will stop the `obd cluster destroy` command.

`-f` is `--force-kill`. This option specifies whether to forcibly stop running processes in the working directory. If this option is enabled, OBD will forcibly stop the ongoing processes and run the `obd cluster destroy` command. `-f` is optional. Its data type is `bool`. This option is disabled by default.

## obd cluster upgrade

Update a running component.

```shell
obd cluster upgrade <deploy_name> -c <component_name> -V <version> [tags]

# example
obd cluster upgrade test -c oceanbase-ce -V 4.0.0.0 --usable=c63bb73384b17d74299b34fe3aceb0ae310fd319d2ccdb1acd39f31ba6673198 
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

| Option | Required | Data type | Default value | Description |
|----|-----|-----|----|----|
| -c/--component | Yes | string | Empty | The component name you want to upgrade. |
| -V/--version | Yes | string |  Empty |  The target upgrade version number. |
| --skip-check | No | bool | false | Skip check. |
| --usable | No | string | Empty | The hash list for the mirrors that you use during upgrade. Separated with `,`. |
| --disable | No | string | Empty | The hash list for the mirrors that you disable during upgrade. Separated with `,`. |
| -e/--executer-path | No | string | /usr/obd/lib/executer | The executer path for the upgrade script. |

## obd cluster reinstall

You can run this command to reinstall the repository of a deployed component. The new repository must have the same version number as the previous repository. If this command is used to replace the repository when the deployment status is 'running', the component is restarted after the replacement without loading parameters.

```bash
obd cluster reinstall <deploy name> -c <component name> --hash <hash> [-f/--force]

# example
[admin@test ~]$ obd mirror list
+------------------------------------------------------------------+
|                      Mirror Repository List                      |
+----------------------------+--------+---------+------------------+
| SectionName                | Type   | Enabled | Update Time      |
+----------------------------+--------+---------+------------------+
| oceanbase.community.stable | remote | True    | 2022-12-16 10:41 |
| oceanbase.development-kit  | remote | True    | 2022-12-16 10:41 |
| local                      | local  | -       | 2022-12-16 10:52 |
+----------------------------+--------+---------+------------------+
Use `obd mirror list <section name>` for more details
[admin@test ~]$ obd mirror list oceanbase.community.stable | grep -e " oceanbase-ce " | grep -e " 4.0.0.0 "
| oceanbase-ce                      | 4.0.0.0 | 100000272022110114.el7 | x86_64 | 759074414c7b7b723013855353f62a7ba0aae0f493216ef2511825850ce77b51 |
| oceanbase-ce                      | 4.0.0.0 | 100000282022112511.el7 | x86_64 | debb18ab3c0b3d16f145c41cd21c30686863580b721d45ddaa068e6309e03b64 |
| oceanbase-ce                      | 4.0.0.0 | 102000032022120718.el7 | x86_64 | c63bb73384b17d74299b34fe3aceb0ae310fd319d2ccdb1acd39f31ba6673198 |

[admin@test ~]$ obd cluster reinstall test -c oceanbase-ce --hash=c63bb73384b17d74299b34fe3aceb0ae310fd319d2ccdb1acd39f31ba6673198
```

The `deploy name` parameter indicates the name of the deployed cluster, which is also the alias of the configuration file.

| Option name  | Required | Data type  | Default value   |    Description   |
|---------|----------|-------------|-------------|--------------|
| -c/--component | Yes | string | Null | The name of the component whose repository is to be replaced. |
|--hash | Yes | string | Null | The hash value of the target repository. The target repository must be of the same version as the current repository. |
| -f/--force | No | Bool | false | Specifies whether to enable forced replacement even if the restart fails. |

## obd cluster tenant create

Creates a tenant. This command applies only to an OceanBase cluster. This command automatically creates resource units and resource pools.

```shell
obd cluster tenant create <deploy name> [-n <tenant name>] [flags]

# example
obd cluster tenant create test -n obmysql --max-cpu=2 --memory-size=2G --log-disk-size=3G --max-iops=10000 --iops-weight=2 --unit-num=1 --charset=utf8
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

This table describes the corresponding options.

| Option | Required | Data type | Default value | Description |
|----|-----|-----|----|----|
| -t/-n/--tenant-name | No | string | test | The tenant name. OBD will automatically generate resource units and resource pools with unique names based on the tenant name.  |
| --max-cpu | No | float | 0 | The maximum number of CPU cores available for the tenant. When this option is set to 0, all available CPU cores of the cluster can be used by the tenant.    |
| --min-cpu | No | float | 0 | The minimum number of CPU cores available for the tenant. When this option is set to 0, the minimum number of CPU cores is the same as the maximum number of CPU cores.   |
| --max-memory | No | int | 0 | The maximum memory capacity available for the tenant. When this option is set to 0, all available memory capacity of the cluster can be used by the tenant. When the actual value is less than 1 GB, an error is returned. <blockquote> Not supported after the OceanBase database V4.0.0.0. You can use `--memory-size` instead.   </blockquote>  |
| --min-memory | No | int | 0 | The minimum memory capacity available for the tenant. When this option is set to 0, the minimum memory capacity is the same as the maximum memory capacity.<blockquote> Not supported after the OceanBase database V4.0.0.0. You can use `--memory-size` instead.   </blockquote>  |
| --memory-size         | No    | int    | 0                        | The available memory unit size of the tenant. Supported since the OceanBase database V4.0.0.0.           |
| --max-disk-size | No | int | 0 | The maximum disk space available for the tenant. When this option is set to 0, all available disk space of the cluster can be used by the tenant. If the actual value is less than 512 MB, an error is returned. <blockquote> Not supported after the OceanBase database V4.0.0.0.   </blockquote>  |
| --log-disk-size       | No    | int    | 0                        | Specifies the tenant's Unit log disk size. The default value is 3 times the memory specification value. The minimum value is `2G`.           |
| --max-iops | No | int | <ul><li> The default value is 128 when the OceanBase database version is lower than V4.0.0.0. </li><li> The default value is 1024 after the OceanBase database V4.0.0.0. </li></ul> | The maximum IOPS for the tenant. The value range of this parameter can be divided into the following two cases according to the OceanBase version. <ul><li>Value range is [128,+∞) when the OceanBase database version is lower than V4.0.0.0. </li><li>   Value range is [1024,+∞) after the OceanBase database V4.0.0.0. </li></ul>    |
| --min-iops | No | int | 0 | The minimum IOPS for the tenant. The value range is the same as `--max-iops`. When this option is set to 0, the minimum IOPS is the same as the maximum IOPS.  |
| --iops-weight         | No    | int    | 0   | Specifies the weight of the tenant's IOPS. Supported since the OceanBase database V4.0.0.0.   |
| --max-session-num | No | int | 64 | The maximum number of sessions allowed for the tenant. Value range: [64, +∞). <blockquote> Not supported after the OceanBase database V4.0.0.0.   </blockquote>  |
| --unit-num | No | int | 0 | The number of units to be created in a zone. It must be less than the number of OBServers in the zone. When this option is set to 0, the maximum value is used.  |
| -z/--zone-list | No | string | Empty  | Specifies the list of zones of the tenant. Separate multiple zones with commas (,). If this option is not specified, all zones of the cluster are included.  |
| --primary-zone | No | string | RANDOM | The primary zone of the tenant.  |
| --charset | No | string | Empty  | The character set of the tenant.  |
| --collate | No | string | Empty  | The collation of the tenant.  |
| --replica-num | No | int | 0 | The number of replicas of the tenant. When this option is set to 0, the number of replicas is the same as that of zones.  |
| --logonly-replica-num | No | string | 0 | The number of log replicas of the tenant. When this option is set to 0, the number of log replicas is the same as that of replicas.  |
| --tablegroup | No | string | Empty  | The default table group of the tenant. |
| --locality | No | string | Empty  | The distribution status of replicas across zones. For example, F@z1,F@z2,F@z3,R@z4 means that z1, z2, and z3 are full-featured replicas and z4 is a read-only replica.  |
| -s/--variables | No | string | ob_tcp_invited_nodes='%' | The system variables of the tenant.  |

## obd cluster tenant drop

Deletes a tenant. This command applies only to an OceanBase cluster. This command automatically deletes the corresponding resource units and resource pools.

```shell
obd cluster tenant drop <deploy name> [-n <tenant name>]

# example
obd cluster tenant drop test -n obmysql
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

`-n` is `--tenant-name`. This option specifies the name of the tenant to be deleted. This option is required.

## obd cluster chst

You can run this command to change the configuration style.

```shell
obd cluster chst <deploy name> --style <STYLE> [-c/--components]

# example
obd cluster chst test -c oceanbase-ce --style cluster
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

The following table describes details about the available options.

|          Option          | Required |  Data type  |           Default value            |                                   Description                                   |
|-----------------------|------|--------|--------------------------|------------------------------------------------------------------------|
| --style      | Yes    | string | N/A                     | The preferred configuration style. Valid values: default and cluster.                                       |
| -c/--components             | No    | string  |  Empty                       | The components whose configuration style need to be changed. Separate multiple components with commas `,`.                                    |

## obd cluster check4ocp

You can run this command to check whether the current configurations can be taken over by OceanBase Cloud Platform (OCP).

```shell
obd cluster check4ocp <deploy name> [-c/--components] [-V/--version]

# example
obd cluster check4ocp test -V 4.0.0
```

The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.

can be understood as an alias for the configuration file

The following table describes details about the available options.

|          Option          | Required |  Data type  |           Default value            |                                   Description                                   |
|-----------------------|------|--------|--------------------------|------------------------------------------------------------------------|
| -c/--components             | No    | string  |  Empty                       | The components whose configuration style need to be changed. Separate multiple components with commas `,`.                                    |
| -V/--version      | Yes    | string | 3.1.0                    | The OCP version.                                       |