Deploy an OceanBase cluster in a Kubernetes environment

This topic describes how to deploy an OceanBase cluster in a Kubernetes environment. You can use this topic as a reference for production deployment. For more information about how to customize the deployment and configuration, see OceanBase K8s O&M tool documentation.

Prerequisites

Before you start the deployment, make sure that your environment meets the following requirements.

Hardware resources

To ensure the stability and performance of the production environment, we recommend that you reserve the following resources for the Kubernetes cluster:

• CPU: More than 24 available CPU cores.

• Memory: More than 72 GB of available memory.

• Storage: SSD storage with more than 400 GB of available space.

Software dependencies

• Kubernetes cluster: The version must be v1.18 or later.

• Helm: Used to deploy ob-operator and OceanBase Dashboard. For more information, see Install Helm.

• cert-manager: ob-operator depends on cert-manager for certificate management. For more information, see Install cert-manager.

• Storage: The cluster must have an available storage class. We have tested some common storage systems. The following table lists the results. You can refer to the test results to determine whether the storage system meets your requirements. In this topic, local-path-provisioner is used as an example.

  Storage system	Tested version	Compatibility	Description
  local-path-provisioner	0.0.23	✅	Recommended for development and testing environments
  Rook CephFS	v1.6.7	❌	CephFS does not support the fallocate system call.
  Rook RBD (Block)	v1.6.7	✅
  OpenEBS (cStor)	v3.6.0	✅
  GlusterFS	v1.2.0	✅	Compatible with Linux kernel version 5.14 or later.
  Longhorn	v1.6.0	✅
  JuiceFS	v1.1.2	✅
  NFS	v5.5.0	❌	A cluster can be started when the NFS protocol is version 4.2 or later. However, tenant resources cannot be recycled.

• MySQL client or OBClient: Used to connect to the OceanBase cluster.

Procedure

Step 1: Deploy ob-operator

ob-operator is the core management component of OceanBase in Kubernetes. We recommend that you deploy ob-operator by using Helm.

1. Add the ob-operator repository.

   helm repo add ob-operator https://oceanbase.github.io/ob-operator/
   helm repo update ob-operator
   

2. Install ob-operator.

   helm install ob-operator ob-operator/ob-operator --namespace=oceanbase-system --create-namespace
   

   The --namespace parameter specifies the namespace where ob-operator is installed. You can customize the namespace as needed. We recommend that you use oceanbase-system.

3. Verify whether ob-operator is installed.

   kubectl get pod -n oceanbase-system
   

   The expected output is as follows, where the STATUS of the pod is Running.

   NAME                                            READY   STATUS    RESTARTS   AGE
   oceanbase-controller-manager-644b489fcc-6hlwf   2/2     Running   0          1m
   

Step 2: Deploy OceanBase Dashboard

OceanBase Dashboard provides visual cluster management and monitoring capabilities.

1. Install OceanBase Dashboard.

   helm install oceanbase-dashboard ob-operator/oceanbase-dashboard --namespace=oceanbase-system --set service.type=NodePort
   

   Note

   The default value of service.type is NodePort. If your environment supports LoadBalancer, you can set service.type to LoadBalancer to obtain an external IP address.

2. Obtain the access address.

   # View the service port.
   kubectl get svc -n oceanbase-system oceanbase-dashboard-oceanbase-dashboard
   

3. Log in to OceanBase Dashboard.

   You can use the service port obtained in the previous step to access OceanBase Dashboard in your browser. The default username and password are both admin. You must change the password for the first login.

   • If service.type is set to NodePort, you can access OceanBase Dashboard by using http://<IP address of any node>:<NodePort port>.

   • If service.type is set to LoadBalancer, you can access OceanBase Dashboard by using http://<External-IP>:<port>.

Step 3: Deploy an OceanBase cluster

After you log in to the OceanBase Dashboard, you can click Cluster in the left-side navigation pane and click Clusters in the upper-right corner to go to the Create Cluster page.

1. Configure the basic information

   On this page, you can configure the Namespace, Cluster Name, Cluster Mode, and root password of the cluster.

   Parameter	Description
   Namespace	You can select a namespace from the drop-down list to create an OceanBase cluster. You can also click + Add Namespace in the drop-down list to create a new namespace. When you create a namespace, the namespace name must start with a lowercase letter and end with a lowercase letter or a digit. It can contain lowercase letters, digits, and hyphens (-), and must be no longer than 63 characters.
   Resource Name	The custom resource name of the OceanBase cluster in Kubernetes. It must be unique in the same namespace. When you create a custom resource name, it must start with a lowercase letter and end with a lowercase letter or a digit. It can contain lowercase letters, digits, and hyphens (-), and must be no longer than 63 characters.
   Cluster Name	The name of the OceanBase cluster. It must start with an English letter and end with an English letter or a digit. It can contain English letters, digits, and underscores (_), and must be 2 to 32 characters in length.
   Cluster Mode	You can select a cluster deployment mode from the drop-down list. Different cluster deployment modes have different requirements on the version of OceanBase Database. The cluster deployment mode also affects the strategy for data recovery when a failure occurs. You must select a deployment mode based on your actual environment and the version of the cluster. General Mode: In this mode, no special processing is performed. The pod IP address is directly used for bootstrap. At present, this mode can identify the calico and kube-ovn plugins. When a pod is rebuilt, the IP address before the failure is used. We recommend that you allocate a separate network segment for the OceanBase cluster to avoid being occupied by other pods. If your Kubernetes cluster uses other network plugins, the failure recovery strategy will be to expand and then shrink the cluster, which often takes a long time to copy a large amount of data and cannot recover from a failure of a majority node. Single Node Mode: In this mode, the 127.0.0.1 address is used for bootstrap. This mode is only applicable for deploying a single-node cluster. Since the 127.0.0.1 address is specified as the OBServer service address, the original data can be reused for quick recovery when a pod is rebuilt. Service Mode: In this mode, a service is created for each OBServer service. The cluster IP address of the service is used for bootstrap. When a pod is rebuilt, the original data can be reused for quick recovery. We recommend that you use this mode.
   Optimization Scenario	You can select an optimization scenario from the drop-down list. The Dashboard automatically sets the parameters based on the selected scenario. For more information, see Best Practices.
   Root Password	The password of the root user of the sys tenant. You can click Randomly generated to let the Dashboard generate a random string, or you can set a custom password. When you set a custom password, it must meet the following requirements: It must be 8 to 32 characters in length. It can contain only letters, digits, and special characters (~!@#%^&*_-+=|()[]:;,.?/). It must contain at least two uppercase letters, two lowercase letters, two digits, and two special characters. After you set the password, you can click Copy Password to copy the password.
   Delete Protection	You can enable or disable delete protection. If you enable delete protection, the operation to delete the OceanBase cluster will be intercepted by a webhook. You must disable delete protection before you can delete the cluster.
   Advanced Configuration	You can click the expand icon next to Advanced Configuration to configure the proxyro Password. If you do not enable Advanced Configuration, the Dashboard automatically generates a random string as the proxyro password. The proxyro password is the password of the proxyro user of the sys tenant. When the proxyro password of the OceanBase cluster is consistent with that of the ODP, the ODP can access the OceanBase cluster. You can click Randomly generated to let the Dashboard generate a random string, or you can set a custom password. When you set a custom password, it must meet the following requirements: It must be 8 to 32 characters in length. It can contain only letters, digits, and special characters (~!@#%^&*_-+=|()[]:;,.?/). It must contain at least two uppercase letters, two lowercase letters, two digits, and two special characters. After you set the password, you can click Copy Password to copy the password.

2. Configure the cluster topology

   The cluster topology mainly specifies the information of all zones. Generally, you must specify at least three zones. You can click + Add Zone or the delete icon next to a zone to add or delete a zone.

   Parameter	Description
   Zone name	The name of the zone in OceanBase Database. You can customize the name. The zone name must start with an English letter and end with an English letter or a digit. It can contain English letters, digits, and underscores. The length of the zone name must be between 2 and 32 characters.
   Number of servers	The number of OBServer nodes in the zone.
   K8s cluster	This parameter is applicable only to a multi-K8s cluster deployment. Specify the K8s cluster in which the zone is deployed. This parameter can be left empty in a single-K8s cluster deployment. For more information about a multi-K8s cluster deployment, see Deploy an OceanBase cluster in a multi-K8s cluster.
   Topology	You can click the expand icon before Topology to configure affinity. You can configure node selector, pod affinity, and toleration. The configuration takes effect only on the OBServer pods in the zone.

3. Configure the resources of an OBServer node

   Parameter	Description
   Image	The image to be used for deploying the OceanBase cluster. You can click Image List to view all images. The image tag corresponds to the version of OceanBase Database. We recommend that you use the LTS image. The image must be in the registry/image:tag format, for example, oceanbase/oceanbase-cloud-native:4.2.0.0-101000032023091319.
   Resources	The CPU, memory, and storage resources. The storage resources create three independent PVCs for storing data, running logs, and redo logs. The data, running logs, and redo logs must be configured with at least three times the Memory resources. You can enable the independent lifecycle for PVCs. If you enable PVC Independent Lifecycle, PVCs will not be automatically deleted when the OBServer resources are deleted. You must manually delete PVCs. Click Minimum Specification in the upper-right corner of the OBServer section to automatically fill in the resources based on the minimum specifications.

4. Optional configurations

   You can click the buttons after Monitoring, Parameter Settings, and Mount NFS Backup Volume to configure the corresponding parameters.

   Module	Parameter	Description
   Monitoring	Image	After monitoring is enabled, you can configure obagent as a sidecar container to provide monitoring capabilities. This parameter is used to configure the image for deploying obagent. You can click Image List to view all images. The image tag corresponds to the version of obagent. The image must be in the registry/image:tag format, for example, oceanbase/obagent:4.2.0-100000062023080210.
   	Resources	Configure the number of CPU cores and memory for deploying obagent. Enter a positive integer.
   Parameter Settings	Parameter Name	Enter the parameters of the OceanBase cluster.
   	Parameter Value	Enter a reasonable value for the parameter. The parameter value takes effect on all OBServer nodes.
   	Action	Click Delete to delete the corresponding parameter. Note Click + Add Parameter to add a row for configuring parameters.
   Mount NFS Backup Volume	Address	If you want to use NFS for backup and restore, you can configure the address of the NFS service here.
   	Path	Enter the backup path. The NFS path will be mounted to the container of the OBServer node.

5. Submit and wait for the cluster to be created

   After you complete the preceding configurations, click Submit. When the Running status appears in the Status column of the Clusters section, the cluster is created.

   Note

   Usually, the cluster is created within a few minutes.

Step 4: Create a tenant

After the cluster is deployed, we recommend that you create a business tenant for application use. You can click Tenant in the left-side navigation pane, and click Create Tenant in the upper-right corner of the Tenants section to go to the Create Tenant page.

1. Specify the basic information of the tenant

   Parameter	Description
   OceanBase Cluster	Select the OceanBase cluster where the tenant will be created from the drop-down list.
   Resource Name	The name of the tenant custom resource in Kubernetes. The tenant will be created in the same namespace as the cluster.
   Tenant Name	The name of the tenant to be created.
   Password	The password of the root account of the tenant. You can click Randomly generated to let the Dashboard generate a random string, or you can set a custom password. The custom password must meet the following requirements: It must be 8 to 32 characters in length. It can contain only letters, digits, and special characters (~!@#%^&*_-+=|()[]:;,.?/). It must contain at least two uppercase letters, two lowercase letters, and two digits or special characters. After you set the password, you can click Copy Password to copy the password.
   Optimization Scenario	You can select a template for a common OceanBase Database usage scenario to automatically configure the parameters. For more information, see Best Practices.
   Allowlist	The allowlist of IP addresses that can connect to the tenant. The default value is %, which indicates any IP address.
   Delete Protection	You can enable or disable delete protection by selecting this option. If you enable delete protection, the deletion of the tenant will be intercepted by a webhook. You need to disable delete protection before you can delete the tenant.

2. Specify the resource pool configuration of the tenant

   Parameter	Description
   Replica Distribution	You can click the check box before each zone to specify the zones where the tenant will be distributed, and set the priority, replica type, and number of units in each zone.
   Resource Unit Specification	Specify the resources of each unit of the tenant. We recommend that you configure the resources based on the Available resources displayed in the Replica Distribution section.

3. Submit the configuration

   After you configure the parameters, click Submit. When the Status in the Tenants section changes to Running, the tenant is created.

Step 5: Deploy ODP

ODP (also known as OBProxy) is a necessary component for applications to connect to a distributed OceanBase cluster. It routes requests to the correct OBServer node. You can click OBProxy in the left-side navigation pane, and then click Clusters in the upper-right corner of the OBProxy page to go to the Create OBProxy Cluster page.

1. Configure the basic information.

   Parameter	Description
   Resource Name	The name of the deployment created in Kubernetes. The name must start with a lowercase letter and end with a lowercase letter or a digit. It can contain lowercase letters, digits, and hyphens (-), and must be no longer than 63 characters.
   OBProxy Cluster Name	The application name of ODP.
   Connect to OB Cluster	You can select an OceanBase cluster from the drop-down list. By default, the selected OceanBase cluster is connected using the rs_list method.
   Namespace	The namespace in Kubernetes where ODP is deployed. After you select an OceanBase cluster, the namespace of the selected OceanBase cluster is automatically filled in.
   OBProxy Root Password	The root password of the proxysys tenant of ODP. You can click Randomly generated to let the Dashboard generate a random string, or you can set a custom password. If you set a custom password, it must meet the following requirements: Length: 8 to 32 characters Contains only letters, digits, and special characters (~!@#%^&*_-+=|()[]:;,.?/) At least two uppercase letters, two lowercase letters, and two digits or special characters After you configure the password, you can click Copy Password to copy the password.

2. Configure more parameters.

   Parameter	Description
   Image	The image to be used for deploying ODP. You can click Image List to view all images. We recommend that you deploy the latest version. The image tag corresponds to the ODP version number. The image should be in the registry/image:tag format, for example, oceanbase/obproxy-ce:4.3.3.0-5.
   Service Type	The type of the service to be created for ODP. If you need to access ODP only within the Kubernetes cluster, you can select ClusterIP. If you need to access ODP from outside the cluster, you can select NodePort or LoadBalancer.
   Replicas	The number of replicas of ODP.
   CPU Cores	The number of CPU cores allocated to ODP.
   Memory Size	The size of memory allocated to ODP.
   Parameter Settings	You can click + Add to configure ODP parameters in key-value pairs.

3. Submit the configuration.

   After you configure the parameters, click Submit. Wait until the Status column in the Clusters list changes to Running, which indicates that ODP is created.

Step 6: Verify the connection

After ODP is deployed, you can view the Service Address on the ODP details page. You can use this address to connect to the cluster.

Execute the following command to connect to the obtenant2 tenant of the obcluster cluster through ODP. For more information about how to connect to a tenant, see Overview.

mysql -h10.10.10.1 -P2883 -uroot@obtenant2#obcluster -p****** oceanbase

The output is as follows:

Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MySQL connection id is 7
Server version: 5.6.25 OceanBase_CE 4.3.5.3 (r103000092025080818-e8da5f0afb288ed0add0613740c6ccf2a3c6830b) (Built Aug  8 2025 18:43:02)

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MySQL [oceanbase]>

References

This topic describes only the basic deployment method, which is suitable for initial environment setup. We also support comprehensive O&M and monitoring features, as well as deployment modes in multi-Kubernetes clusters for higher availability requirements. You can explore these features on the Dashboard page or refer to the following links:

• GitHub ob-operator documentation

• GitHub ob-operator code repository

• OceanBase K8s O&M tool documentation