Modify unit_config|V4.1.0| docs|Distributed Database

Modify unit_config

Last Updated：2023-08-01 06:02:28 Updated

You can increase and decrease the resources of a tenant by modifying the unit_config parameter. The parameter specifies the resource unit configurations.

Prerequisites

Before you perform a scale-in or scale-out operation on a tenant, you must perform the following steps:

If the tenant is deleted, delete the resource pool of the tenant to release resources. Resources in an idle resource pool are also considered occupied resources.

For more information about how to delete a resource pool, see Delete a resource pool.
Perform a round of minor compaction to release the occupied memory resources.

For more information about how to manually trigger a minor compaction, see Manually trigger a minor compaction.
View the allocation of resources in the cluster to understand resource usage.

For more information about how to view the total amount of resources and the resource allocation on OBServer nodes, see View the resource information about a cluster.

Modify the resource unit configs of a tenant by using SQL statements

The modifications on resource unit configs involve the following two scenarios:

If the current tenant uses independent resource unit configs, you can directly modify the resource unit configs.
If the tenant uses the same resource unit configuration as other tenants do, you must create a resource unit for the tenant.

Perform the following steps to confirm whether the tenant uses independent resource unit configs:

Log on to the sys tenant of the cluster as the root user.

Execute the following statement to obtain the unit config ID of the tenant:

obclient> SELECT a.TENANT_NAME, b.UNIT_CONFIG_ID  FROM oceanbase.DBA_OB_TENANTS a,oceanbase.DBA_OB_RESOURCE_POOLS b WHERE b.TENANT_ID=a.TENANT_ID;
+-------------+----------------+
| TENANT_NAME | UNIT_CONFIG_ID |
+-------------+----------------+
| sys         |              1 |
| MySQL       |           1002 |
| Oracle      |           1004 |
+-------------+----------------+
3 rows in set

If UNIT_CONFIG_ID of the current tenant is the same as other tenants, multiple tenants use the same resource unit configs. If UNIT_CONFIG_ID of the current tenant is different from that of any other tenant, the current tenant uses independent resource unit configs.

The following content describes the detailed information.

Considerations

If you want to upgrade the unit configs, the total amount of resources after adjustment must meet the following requirements:

Sum(min_cpu) <= CPU_CAPACITY;
Sum(max_cpu) <= CPU_CAPACITY * resource_hard_limit;
Sum(memory_size) <= MEM_CAPACITY;
Sum(log_disk_size) <= LOG_DISK_CAPACITY;

Otherwise, the system returns an error, indicating that the scale-out fails.

Parameters:

CPU_CAPACITY: the total CPU capacity.
MEM_CAPACITY: the total memory capacity.
LOG_DISK_CAPACITY: the total capacity of the log disk. The total capacity of the log disk is jointly controlled by the log_disk_size and log_disk_percentage parameters. log_disk_size specifies the size of the disk where REDO logs are stored, and the default value is 0. log_disk_percentage specifies the percentage of the disk space occupied by REDO logs, and the default value is 0. The rules for using the two parameters are described in the following list:
- If the value of log_disk_size is 0 but the value of log_disk_percentage is not 0, the system allocates log disk space based on the value of log_disk_percentage.
- If the value of log_disk_size is not 0, the system allocates log disk space based on the value of log_disk_size, regardless of whether the value of log_disk_percentage is 0.
- If the values of both log_disk_size and log_disk_percentage are 0, the system automatically calculates the percentage of the disk space occupied by REDO logs. The percentage depends on whether the disk is shared by REDO logs and data.
  - If the disk is shared, the percentage of the disk space occupied by REDO logs is 30%.
  - If the disk is exclusive for REDO logs, the percentage of the disk space occupied by REDO logs is 90%.
For more information about the log_disk_size parameter, see log_disk_size.

For more information about the log_disk_percentage parameter, see log_disk_percentage.
resource_hard_limit: a specific system parameter.

The system allocates CPU resources based on the value of the resource_hard_limit parameter. Value range: [1,10000]. The default value is 100, indicating that over-allocation is not allowed.

For more information about the resource_hard_limit parameter, see resource_hard_limit.

Background

Assume that you have a cluster that has three zones, which are z1, z2, and z3, and each zone has three OBServer nodes. The cluster has a user tenant named tenant1. The following code shows the resource distribution of the tenant:

obclient> CREATE RESOURCE UNIT unit1 MAX_CPU 6, MIN_CPU 6, MEMORY_SIZE '36G', MAX_IOPS 1024, MIN_IOPS 1024, IOPS_WEIGHT=0, LOG_DISK_SIZE = '4G';

obclient> CREATE RESOURCE POOL pool1 UNIT 'unit1', UNIT_NUM 2, ZONE_LIST ('z1','z2','z3');

obclient>CREATE TENANT tenant1 resource_pool_list=('pool1');

Scenario 1: The current tenant uses independent resource unit configs

If the current tenant uses independent resource unit configs, you can directly modify the unit_config parameter to scale out or scale in the tenant.

Perform the following steps:

Log on to the sys tenant of the cluster as the root user.
Execute the following statement to go to the database named oceanbase:
```
obclient>USE oceanbase;
```

Execute the following statement to obtain the unit config ID of the tenant:

obclient> SELECT a.TENANT_NAME, b.UNIT_CONFIG_ID  FROM oceanbase.DBA_OB_TENANTS a,oceanbase.DBA_OB_RESOURCE_POOLS b WHERE b.TENANT_ID=a.TENANT_ID;
+-------------+----------------+
| TENANT_NAME | UNIT_CONFIG_ID |
+-------------+----------------+
| sys         |              1 |
| MySQL       |           1001 |
| Oracle      |           1002 |
+-------------+----------------+
3 rows in set

Execute the following statement to query the resource configurations of the current tenant.

obclient> SELECT * FROM oceanbase.DBA_OB_UNIT_CONFIGS WHERE UNIT_CONFIG_ID='1001';
+----------------+-------+---------+---------+-------------+---------------+----------+----------+-------------+
| UNIT_CONFIG_ID | NAME  | MAX_CPU | MIN_CPU | MEMORY_SIZE | LOG_DISK_SIZE | MAX_IOPS | MIN_IOPS | IOPS_WEIGHT |
+----------------+-------+---------+---------+-------------+---------------+----------+----------+-------------+
|           1001 | unit1 |       6 |       6 | 38654705664 |    4294967296 |     1024 |     1024 |           0 |
+----------------+-------+---------+---------+-------------+---------------+----------+----------+-------------+
1 row in set

Modify the specifications of the unit1 resource unit based on the obtained information.

Upgrade the specifications of unit1

obclient> ALTER RESOURCE UNIT unit1 MAX_CPU 8, MIN_CPU 8, MEMORY_SIZE '40G', MAX_IOPS 1024, MIN_IOPS 1024, IOPS_WEIGHT 0, LOG_DISK_SIZE '6G';

Downgrade the specifications of unit1

obclient> ALTER RESOURCE UNIT unit1 MAX_CPU 5, MIN_CPU 5, MEMORY_SIZE '5G', MAX_IOPS 1024, MIN_IOPS 1024, IOPS_WEIGHT 0, LOG_DISK_SIZE '2G';

Scenario 2: The current tenant uses the same resource unit configs as other tenants

If the current tenant uses the same resource unit configs as that of other tenants, you cannot simply upgrade or downgrade the specifications to increase or decrease tenant resources. If you modify the resource unit configs for a tenant, the modification applies to all tenants that use the same resource unit configs.

In this scenario, you must create an independent resource unit and replace the original resource unit with the new one.

For example, tenant1 requires scaling, and both tenant1 and tenant2 use the same resource unit unit1. In this case, you need to create a new resource unit for tenant1.

Log on to the sys tenant of the cluster as the root user.
Execute the following statement to go to the database named oceanbase:
Create an independent resource unit.

Specify a name for the new resource unit, such as unit2. Resource unit names must be globally unique.
- Create unit2 with higher specifications than those of the current resource unit
```
obclient> CREATE RESOURCE UNIT unit2 MAX_CPU 8, MIN_CPU 8, MEMORY_SIZE '20G', MAX_IOPS 1024, MIN_IOPS 1024, IOPS_WEIGHT 0, LOG_DISK_SIZE '6G';
```
- Create unit3 with lower specifications than those of the current resource unit
```
obclient> CREATE RESOURCE UNIT unit3 MAX_CPU 5, MIN_CPU 5, MEMORY_SIZE '5G', MAX_IOPS 1024, MIN_IOPS 1024, IOPS_WEIGHT 0, LOG_DISK_SIZE '2G';
```
Replace the current resource unit of the resource pool with the newly created resource unit.

In this example, unit2 and unit3 are newly created resource units.
```
obclient> ALTER RESOURCE POOL pool1 unit='unit2';

obclient> ALTER RESOURCE POOL pool1 unit='unit3';
```

What to do next

You can query the oceanbase.DBA_OB_UNIT_CONFIGS view to confirm whether the unit_config parameter is successfully modified for the current tenant.

obclient> SELECT * FROM oceanbase.DBA_OB_UNIT_CONFIGS;

For more information about the DBA_OB_UNIT_CONFIGS view, see DBA_OB_UNIT_CONFIGS.

More information

During the scaling of a tenant, you can query resource information about the tenant in the following views:

oceanbase.DBA_OB_UNIT_CONFIGS

The DBA_OB_UNIT_CONFIGS view displays the unit_config information of all tenants in the current cluster.

Example:

obclient> SELECT * FROM oceanbase.DBA_OB_UNIT_CONFIGS;
+----------------+-----------------+---------+---------+-------------+---------------+----------+----------+-------------+
| UNIT_CONFIG_ID | NAME            | MAX_CPU | MIN_CPU | MEMORY_SIZE | LOG_DISK_SIZE | MAX_IOPS | MIN_IOPS | IOPS_WEIGHT |
+----------------+-----------------+---------+---------+-------------+---------------+----------+----------+-------------+
|              1 | sys_unit_config |     2.5 |     2.5 | 17179869184 |   17179869184 |    25000 |    25000 |           2 |
|           1001 | unit001         |       1 |       1 |  6442450944 |   19327352832 |    10000 |    10000 |           1 |
|           1002 | unit002         |       1 |       1 |  6442450944 |   19327352832 |    10000 |    10000 |           1 |
|           1003 | unit003         |       1 |       1 |  6442450944 |   19327352832 |    10000 |    10000 |           1 |
|           1004 | unit004         |       1 |       1 |  6442450944 |   19327352832 |    10000 |    10000 |           1 |
|           1005 | unit1           |       6 |       6 | 38654705664 |    2147483648 |     1024 |     1024 |           0 |
+----------------+-----------------+---------+---------+-------------+---------------+----------+----------+-------------+
6 rows in set

oceanbase.GV$OB_UNITS

The GV$OB_UNITS view displays the resource allocation information of all tenants in the cluster.

Sample statement:

obclient> SELECT * FROM oceanbase.GV$OB_UNITS\G
*************************** 1. row ***************************
         SVR_IP: xx.xx.xx.xx
      SVR_PORT: 2882
         UNIT_ID: 1
      TENANT_ID: 1
            ZONE: zone1
         MAX_CPU: 2.5
         MIN_CPU: 2.5
   MEMORY_SIZE: 17179869184
      MAX_IOPS: 25000
      MIN_IOPS: 25000
   IOPS_WEIGHT: 2
   LOG_DISK_SIZE: 17179869184
LOG_DISK_IN_USE: 191441460
DATA_DISK_IN_USE: 406847488
         STATUS: NORMAL
   CREATE_TIME: 2022-07-19 11:04:39.226231
*************************** 2. row ***************************
         SVR_IP: xx.xx.xx.xx
      SVR_PORT: 2882
         UNIT_ID: 1001
      TENANT_ID: 1001
            ZONE: zone1
         MAX_CPU: NULL
         MIN_CPU: NULL
   MEMORY_SIZE: 644245094
      MAX_IOPS: NULL
      MIN_IOPS: NULL
   IOPS_WEIGHT: NULL
   LOG_DISK_SIZE: 1932735283
LOG_DISK_IN_USE: 155042605
DATA_DISK_IN_USE: 211812352
         STATUS: NORMAL
   CREATE_TIME: 2022-07-19 13:48:36.308843
*************************** 3. row ***************************
         SVR_IP: xx.xx.xx.xx
      SVR_PORT: 2882
         UNIT_ID: 1001
      TENANT_ID: 1002
            ZONE: zone1
         MAX_CPU: 1
         MIN_CPU: 1
   MEMORY_SIZE: 5798205850
      MAX_IOPS: 10000
      MIN_IOPS: 10000
   IOPS_WEIGHT: 1
   LOG_DISK_SIZE: 17394617549
LOG_DISK_IN_USE: 154632504
DATA_DISK_IN_USE: 121634816
         STATUS: NORMAL
   CREATE_TIME: 2022-07-19 13:48:36.308843
*************************** 4. row ***************************
         SVR_IP: xx.xx.xx.xx
      SVR_PORT: 2882
         UNIT_ID: 1002
      TENANT_ID: 1005
            ZONE: zone1
         MAX_CPU: NULL
         MIN_CPU: NULL
   MEMORY_SIZE: 644245094
      MAX_IOPS: NULL
      MIN_IOPS: NULL
   IOPS_WEIGHT: NULL
   LOG_DISK_SIZE: 1932735283
LOG_DISK_IN_USE: 152132563
DATA_DISK_IN_USE: 211812352
         STATUS: NORMAL
   CREATE_TIME: 2022-07-19 13:51:56.627867
*************************** 5. row ***************************
         SVR_IP: xx.xx.xx.xx
      SVR_PORT: 2882
         UNIT_ID: 1002
      TENANT_ID: 1006
            ZONE: zone1
         MAX_CPU: 1
         MIN_CPU: 1
   MEMORY_SIZE: 5798205850
      MAX_IOPS: 10000
      MIN_IOPS: 10000
   IOPS_WEIGHT: 1
   LOG_DISK_SIZE: 17394617549
LOG_DISK_IN_USE: 158023991
DATA_DISK_IN_USE: 134217728
         STATUS: NORMAL
   CREATE_TIME: 2022-07-19 13:51:56.627867
5 rows in set

oceanbase.DBA_OB_RESOURCE_POOLS

The DBA_OB_RESOURCE_POOLS view displays the resource configurations of all resource pools in the current cluster. unit_count indicates the number of resource units in the resource pool.

Sample statement:

obclient> SELECT * FROM oceanbase.DBA_OB_RESOURCE_POOLS;
+------------------+----------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
| RESOURCE_POOL_ID | NAME     | TENANT_ID | CREATE_TIME                | MODIFY_TIME                | UNIT_COUNT | UNIT_CONFIG_ID | ZONE_LIST | REPLICA_TYPE |
+------------------+----------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
|                1 | sys_pool |         1 | 2022-07-19 11:05:18.168896 | 2022-07-19 11:05:18.175708 |          1 |              1 | zone1     | FULL         |
|             1001 | pool001  |      1002 | 2022-07-19 13:47:55.854548 | 2022-07-19 13:48:36.307978 |          1 |           1001 | zone1     | FULL         |
|             1002 | pool002  |      1006 | 2022-07-19 13:49:53.869792 | 2022-07-19 13:51:56.626742 |          1 |           1001 | zone1     | FULL         |
+------------------+----------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
3 rows in set