Create a distributed cluster|V4.5.1|OceanBase Cloud Platform|docs|OceanBase Documentations

A distributed cluster is an enterprise-level native distributed database architecture of OceanBase. It features financial-grade high availability and smooth scaling, and is highly compatible with Oracle/MySQL modes. It is suitable for core business systems with high data security requirements.

You can create a distributed primary cluster to be managed based on your business needs.

Applicability

OCP Community Edition only supports creating primary clusters.

Background information

When the cluster Deployment Mode is set to Single Zone Multi-host, only the computing capability of the OceanBase service is scaled out. This configuration does not provide high availability through multiple replicas and is suitable for development and test environments.
When the cluster Deployment Mode has an even number of zones, it cannot meet high availability requirements and poses data security risks. We recommend that you adjust the configuration to maintain an odd number of zones or enable the arbitration service for the cluster or tenant.

Prerequisites

The current user logged in to OCP has the ADMIN or ORG_ADMIN role.
(Optional) If you are creating a multi-replica OceanBase cluster, an available OBProxy cluster must already exist in the current OCP. You can refer to the following links to add an OBProxy cluster.
- Create an OBProxy cluster
- Take over OBProxy

Procedure

Step 1: Go to the cluster creation page

After logging in to OCP, click Cluster in the left navigation bar to go to the Cluster overview page. Locate the entry for creating a new cluster based on your actual business scenario.
1. If you have no manageable clusters, the system will prompt you to create a new cluster on the Clusters tab. Click Create Cluster directly in the prompt.
2. If you already have manageable clusters, click Create Cluster in the upper-right corner of the Clusters tab.
On the Create Cluster page, select the Distributed Cluster mode.

Step 2: Configure basic cluster information

The following basic information is required when creating a distributed cluster:

Configuration	Description
Cluster Type	Select Primary Cluster.
Cluster Name	The name of the cluster to be managed. The cluster name must start with a letter and end with a letter or number, can contain letters, numbers, and underscores, and be 2 to 32 characters long.
root@sys password	Supports custom or randomly generated passwords. The password must meet the following complexity requirements: 8 to 32 characters in length Must contain at least three of the four character types: digits (0-9), uppercase letters (A-Z), lowercase letters (a-z), and special characters. Supported special characters are `~!@#%^&*_-+=\`	(){}[]:;,.?/.
OceanBase Version	You can select an existing OceanBase cluster version from the list, or click Add Version at the bottom of the list to upload a new OceanBase version.
Associate OBProxy Cluster	If you have created an OceanBase cluster with multiple replicas, it is recommended that you enable the Associated OBProxy Cluster switch and associate this OceanBase cluster with an OBProxy cluster. After association, SQL requests related to your business will be accurately forwarded to the corresponding replicas, enabling access to OceanBase Database with performance comparable to accessing a standalone database. 1. By default, the proxyro user is used for association; you do not need to enter a username and password. 2. Select the OBProxy cluster you want to associate from the drop-down list. If no OBProxy cluster is available in the drop-down list, refer to the description in the Prerequisites section of this topic to add an OBProxy cluster. The following limitations apply to the OBProxy cluster to be associated: You can only select an OBProxy cluster that has the same network as the OceanBase cluster and is not empty. When the OceanBase cluster version is V4.0 or later, only OBProxy clusters of version V4.0.0 or later are supported for association.
Load Type	You can select a workload type for a cluster. The workload type primarily affects the time taken to judge SQL queries (parameter: large_query_threshold) and may significantly impact the response time of OLTP workloads. Choose carefully. OCP supports five cluster workload types, described as follows. Express OLTP: Suitable for workloads such as trading, core payment systems, and high-throughput Internet applications. No foreign keys or other restrictions, no stored procedures, no long or large transactions, no complex joins, and no complex subqueries. Version requirement: OceanBase Database V4.2.5 or later. HTAP: Suitable for mixed OLAP and OLTP workloads. Typically used to gain instant insights from active operational data, fraud detection, and personalized recommendations. Version requirement: OceanBase Database V4.2.5 or later. OLAP: Used for real-time data warehouse analytics scenarios. Version requirement: OceanBase Database V4.3.0 or later. Complex OLTP: Suitable for workloads such as banking and insurance systems. These typically involve complex joins, complex correlated subqueries, batch processing jobs written in PL, and long and large transactions. Sometimes uses parallel execution for short-running queries. Version requirement: OceanBase Database V4.2.5 or later. OBKV: Used for key-value workloads and HBase-like wide-column workloads. These workloads usually have very high throughput and are latency-sensitive. Version requirement: OceanBase Database V4.2.5 or later.

Step 3: Configure the cluster's deployment mode

By default, information for 3 Zones is added. If you want to deploy a cluster with more than 3 Zones, you can click the Add button below to add Zone information. If you want to deploy a cluster with fewer than 3 Zones, you can click the delete icon next to a Zone.

The information that needs to be set for each Zone and its description are shown in the following table.

Configuration	Description
Zone Name	You can keep the default value or customize it. The zone name must start with a letter, support uppercase and lowercase letters, numbers, and underscores, and be 2 to 32 characters in length. For an OceanBase cluster deployed across multiple zones, one zone must have the same region as the primary zone.
Data Center	The IDC where the zone is located. A zone can exist only in one IDC.
Instance Type	Optional. If you select a host type, the host list will be filtered accordingly.
CPU Architecture	When multiple installation packages of different architectures exist for the selected OceanBase version, you need to select the host hardware architecture that matches this software package. Notice The default architecture type is that of the first installation package and can be switched. After switching to a specified architecture, hosts of that architecture are displayed in the Hosts list. If different architectures are set for different zones, a mixed-architecture deployment mode may result in stability and performance issues. Proceed with caution.
Host	You can select multiple hosts or add a host.
Root Service Location	You need to select an IP address for the server hosting the RootService. In a multi-replica OceanBase cluster, you must specify a RootService for each zone.
Zone Priority Sorting	Specify whether to prioritize the distribution of primary replicas for the cluster's sys tenant. If specified, the zone with the highest priority will be considered the primary zone, and there can only be one. The sorting method is as follows: 1. Select one or more zones from the left list box. This list shows all available zones in the current cluster. 2. Click the > button in the middle. The selected zones will then be moved to the Zone Priority Sorting list. Multiple selected zones have the same priority. 3. Repeat steps a and b to add zones with lower priorities. 4. To adjust priorities, drag zones within the Zone Priority Sorting list. In the list, priorities decrease from top to bottom. If not specified, the default is primary_zone=RANDOM (random distribution).
Add Arbitration Service	Choose whether to add an arbitration service for the cluster. You can select a service from the drop-down list, or click Create Service to create a new arbitration service for the cluster. For more information, see Add an arbitration service. Note Arbitration services are supported only for primary clusters of version V4.1.0 and later.

Step 4: Configure Cgroup

Cgroup is mainly used for CPU resource isolation between tenants and within tenants in an OceanBase cluster. You can choose whether to enable Cgroup for the cluster based on your actual business type to achieve stronger CPU/IOPS isolation. When you create an OceanBase cluster of version V4.0 or later, Cgroup is enabled by default.

Enabling Cgroup will result in a performance drop of about 7%. If your business scenario involves single tenants, small specifications (<14C), and requires higher database performance, it is recommended to disable Cgroup.
If the host's operating system kernel version is lower than 5.1.0, it is recommended to disable Cgroup for the cluster, as this may cause system performance degradation or instability.
If the host's operating system kernel version is lower than 4.1.9, the cluster will not be able to create tenants. In this case, Cgroup is disabled by default and the Cgroup switch is not displayed.

Step 5: Configure CPU overprovisioning

When loads from different business scenarios overlap, an OceanBase cluster may experience overload during operation, leading to thread competition for CPU resources among different tenants and consequently slowing down the actual business scenarios. To ensure that the loads of different tenants in the system can run in an orderly manner, you can configure CPU overprovisioning when configuring CPU resources to improve resource utilization.

Note

Only OceanBase V4.0 and later support CPU overprovisioning. With proper configuration, you can fully utilize hardware resources.
The CPU overprovisioning feature depends on Cgroup. Before configuring the CPU overprovisioning ratio, please enable Cgroup for the cluster.

In the CPU Oversubscription Settings section, you can configure the overprovisioning ratio using the slider or the input box. The default value is 120%, with a range of 101% to 200%.

Step 6: Configure the JVM environment dependency service

Enable JVM Environment Dependency Service so that OBServer can interface with external tables, Java UDFs, ODPS remote access, and other features through the JNI (Java Native Interface) framework.

Notice

Only OceanBase Database V4.3.5.1 and later support configuring the JVM environment dependency service.
Refer to Deploy the OceanBase Database Java SDK environment. Use the Upload a software package feature to upload the JAR package library required by the service dependency in advance, ensuring that OBServer can load and use it properly.

This service depends on the Java environment. If any machines in the cluster have not yet been configured with a Java environment, configure it yourself:

If the host is an x86_64 architecture, ensure OpenJDK is version 15 or later.
If the host is of another architecture, ensure OpenJDK is version 11 or later.

Configure the service type.

OCP supports five service types: ODPS external table, HDFS external table, Java UDF, ODPS Catalog, and MySQL external table plugin. Different services have different requirements for the OceanBase cluster version. For details, see the following table.

Service type	OceanBase version requirement
ODPS external table	[V4.3.5.1, +∞)
HDFS external table	[V4.3.5.1, +∞)
Java UDF	[V4.3.5.1, +∞)
ODPS Catalog	[V4.4.0, +∞)
MySQL external table plugin	[V4.4.1, +∞)

Note

When configuring the service type, the first four service types—ODPS external table, HDFS external table, Java UDF, and ODPS Catalog—are enabled by default and cannot be disabled.

Configure JVM memory.

Proper JVM memory configuration directly affects the stability and performance of Java applications. By setting the JVM memory, you can ensure the basic operational needs of Java applications in the OceanBase cluster. The following table provides predefined JVM memory configuration options based on the different memory specifications of OBServer nodes:

OBServer memory node	-Xmx/-Xms	-Dio.netty.maxDirectMemory	Total JVM memory
16 GiB	512 MiB	512 MiB	1 GiB
32 GiB	1 GiB	1 GiB	2 GiB
70 GiB	3 GiB	3 GiB	6 GiB

Configure the JAVA_HOME path.

After enabling the JVM environment dependency service, you need to manually specify the JAVA_HOME path. Ensure that the JAVA_HOME paths for all OBServer nodes in the cluster are identical.

Step 7: Configure cluster parameters

Open the Parameter Settings module to customize cluster parameters.

If you have configured a workload type in Basic Settings, the system will automatically select the corresponding parameter template by default.
You can add startup parameters one by one and configure values for them as shown in position ① in the figure.

Alternatively, as shown in position ② in the figure, click Select Parameter Template and then select a parameter template. The system will automatically fill in the parameters and configurations from the template here. If no cluster parameter template has been created, you can click Create Cluster Template to create one for the cluster. For details, see Manage cluster parameter templates.

The system provides the following six built-in templates, which contain common parameter settings. You can directly apply these templates for initial cluster configuration. The specific descriptions of the built-in templates are as follows.

Template	Description
COMPLEX_OLTP Default Parameter Template	Corresponds to the Complex OLTP workload type. This template is only applicable to OceanBase Database V4.2.5 and later.
HTAP Default Parameter Template	Corresponds to the HTAP workload type. This template is only applicable to OceanBase Database V4.2.5 and later.
KV Default Parameter Template	Corresponds to the OBKV workload type. This template is only applicable to OceanBase Database V4.2.5 and later.
EXPRESS_OLAP Default Parameter Template	Corresponds to the Express OLAP workload type. This template is only applicable to OceanBase Database V4.2.5 and later.
OLAP Default Parameter Template	Corresponds to the OLAP workload type. This template is only applicable to OceanBase Database V4.3.0 and later.
2.2.77 Default Parameter Template	Recommended parameter settings for OceanBase clusters of version V2.2.77, intended for production environments.

Note

If you have customized requirements for CPU, memory, data disk, and log disk usage at the cluster level, set the parameters: cpu_count, memory_limit_percentage, system_memory, data_disk_usage_limit_percentage, datafile_size, clog_disk_usage_limit_percentage, and log_disk_size. For specific parameter descriptions, refer to the OceanBase official website Cluster Parameters Overview.

Step 8: Configure users, paths, and ports

In the Custom Settings module, you can perform cluster-level user configuration (such as the operating system owner user), path configuration (such as software installation paths, data disk paths, and log disk paths), and port configuration (such as SQL ports and RPC ports).

Configure the operating system owner user:

This user is the operating system user used for installing and running OBServer and cannot be edited. You can modify this user by adjusting the default configuration of the ocp.operation.default.os.user parameter. This parameter modification only affects the creation of distributed clusters, standalone clusters, OBProxy clusters, and arbitration service clusters. It does not affect other configurations of existing clusters.

Configure related paths:

Configuration	Description
Software Path	When the Operating System Owner User is admin, the Software Path defaults to `/home/admin/oceanbase` and supports customization. When the Operating System Owner User is non-admin, the Software Path defaults to `/opt/oceanbase/oceanbase` and supports customization.
Data Disk Path	Defaults to `/data/1` and supports customization.
Log Disk Path	Defaults to `/data/log1` and supports custom paths. In a production environment, it is recommended that the log disk space be at least three times the host's memory space. Additionally, to avoid disk usage collection issues, it is recommended to mount the data directory, installation directory, and log directory on different disks. Note Starting from OCP 4.3.0 BP1, when creating an OceanBase cluster of the following versions, the slog directory will be placed on the log disk and will no longer be bound to the data disk. If `log_disk_size=0` is configured at this time, it will be interpreted as exclusive for clogs, meaning the default `log_disk_percentage` is 90%. If the size of the disk where slog and clog reside is less than 40 GiB, the reserved space for slog will be less than 4 GiB, which may affect slog writing. V4.2.4.0 ≤ OceanBase < V4.3.0.0 OceanBase ≥ V4.3.1.0 For more information about slog, see OBServer Node Installation Directory Structure.

Configure ports:

Configuration	Description
SQL Port	Defaults to 2881 and supports customization.
RPC Port	Defaults to 2882 and supports customization.

After configuration, click Test to verify that the specified path and port are available.
- If the test passes, click Create.
- If the test fails, troubleshoot the issue as prompted.

Step 9: Confirm the configuration information

In the right-side panel, confirm that the configured cluster information is correct, and click Next.
Perform a pre-check before creation. The system verifies whether your environment meets the minimum requirements for creating a distributed primary cluster. If a check item fails, you can perform the following operations as prompted:
- Upload: Displayed only when a specific check item fails. Follow the prompts and click Upload to manually upload the required software package.
- Skip: This operation skips the current check item (designed for special scenarios). Ensure the related check item meets product specification requirements; otherwise, subsequent process execution may fail. After skipping, the status of that check item changes to Warning.
- Retry: Troubleshoot and fix the issue based on the failure cause and optimization suggestions. After fixing it, click Retry to rerun the failed check item.
- Retry All: After all issues are troubleshooted and fixed, click Retry All to rerun all failed check items.
Once there are no failed check items, click Create.

After submitting the new cluster task, you can view its execution progress in Task Center.