Deploy an OceanBase cluster in a Kubernetes environment

This topic describes how to deploy an OceanBase cluster in a Kubernetes environment, which can serve as a reference for production deployment. For more information on custom deployment and configuration methods, see OceanBase Kubernetes O&M Tool Documentation.

Prerequisites

Before you begin the deployment, ensure your environment meets the following requirements.

Hardware resources

To ensure the stability and performance of the production environment, it is recommended that the remaining Kubernetes resources meet the following suggested configurations:

• CPU: More than 24 available CPUs.

• Memory: More than 72 GB of available memory.

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

Software dependencies

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

• helm: Used to deploy ob-operator and OceanBase Dashboard. Refer to the helm installation documentation to complete the installation.

• cert-manager: ob-operator depends on cert-manager for certificate management. Refer to the cert-manager installation documentation to complete the installation.

• Storage: The cluster must have an available storage class. We have tested some common storage systems, as shown in the following table. You can refer to the test results in the storage compatibility section to determine whether your needs are met. In this topic, local-path-provisioner is used as an example.

  Storage solution	Test version	Compatibility	Description
  local-path-provisioner	0.0.23	✅	Recommended for development and test 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 when the kernel version is not earlier than 5.14
  Longhorn	v1.6.0	✅
  JuiceFS	v1.1.2	✅
  NFS	v5.5.0	❌	The cluster can be started when the NFS protocol version is >= 4.2, but tenant resources cannot be reclaimed

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

Procedure

Step 1: Deploy ob-operator

ob-operator is the core management and control component of OceanBase in Kubernetes. It is recommended to deploy it 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
   

   --namespace is used to set the installation namespace, which can be customized as needed. It is recommended to use oceanbase-system.

3. Verify successful installation

   kubectl get pod -n oceanbase-system
   

   The expected output is as follows, with the pod's STATUS being 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.

2. Obtain the access address

   # View 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 through a browser. The default account and password are both admin. You must change the password upon first login.

   • If service.type is specified as NodePort, you can access it via http://<any-node-ip>:<NodePort-port>.

   • If service.type is specified as LoadBalancer, you can access it via http://<External-IP>:<port>.

Step 3: Deploy an OceanBase cluster

After logging in to the OceanBase Dashboard, you can click Cluster in the left navigation bar. On the cluster page, click Create Cluster in the upper-right corner of the Clusters section to go to the Create Cluster page.

1. Configure basic information

   On this page, you can configure the cluster's Namespace, Cluster Name, Cluster Mode, and root Password.

   

   Parameter	Description
   Namespace	Select a namespace for creating the OceanBase cluster from the drop-down list. You can also click + Add Namespace in the list to create a new one. When adding a namespace, it must start with a lowercase letter and end with a lowercase letter or number, can contain lowercase letters, numbers, and -, and be no longer than 63 characters long.
   Resource Name	The custom resource name for the OceanBase cluster in Kubernetes, which must not duplicate existing resource names in the same namespace. The custom resource name must start with a lowercase letter and end with a lowercase letter or number, can contain lowercase letters, numbers, and -, and be no longer than 63 characters long.
   Cluster Name	Set the OceanBase cluster name. It 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.
   Cluster Mode	Select the cluster deployment mode from the drop-down list. Different modes have version requirements for OceanBase Database and affect the recovery strategy in case of failure. Choose carefully based on your actual environment and cluster version. Normal Mode: No special handling is done; the pod IP address is used directly for bootstrapping. Currently recognizes calico and kube-ovn plugins, using the pre-failure IP address when rebuilding a pod after a failure. It is recommended to allocate a dedicated IP range for the OceanBase cluster to avoid being occupied by other pods. If the Kubernetes cluster uses other network plugins, it will employ an expansion-then-contraction failure recovery strategy, which often requires longer time to replicate large amounts of data and cannot recover from a majority node failure. Standalone Mode: Uses 127.0.0.1 for bootstrapping, limited to single-node cluster deployments. Since 127.0.0.1 is specified as the OBServer service address, original data can be reused for quick recovery when the pod is rebuilt. Service Mode: Creates a separate service for each OBServer service and uses the service's cluster IP address for bootstrapping. Original data can also be reused for quick recovery when the pod is rebuilt. This mode is generally recommended.
   Optimization Scenario	Provides parameter templates for common OceanBase cluster usage scenarios. Selecting a scenario automatically configures the parameters. For detailed introductions to optimization scenarios, see Configuration Best Practices.
   root Password	The root user password for the sys tenant. You can click Randomly generated to let the Dashboard automatically generate a random string, or set it manually. When setting a custom password, it must meet the following requirements: Be 8 to 32 characters long Contain only letters, numbers, and special characters (~!@#%^&*_-+=|()[]:;,.?/) Include at least 2 uppercase letters, 2 lowercase letters, and 2 special characters After configuration, you can click Copy Password to save the configured password.
   Deletion Protection	Enable or disable deletion protection by checking the box. If enabled, deleting this OceanBase cluster will be intercepted by a webhook. You need to disable it before deleting the cluster.
   Advanced Configuration	Click the expand icon next to Advanced Configuration to configure the proxyro password. If Advanced Configuration is not enabled, the Dashboard automatically generates a random string as the proxyro password. The proxyro password is for the sys tenant's proxyro user. ODP can access the corresponding OceanBase cluster only if its proxyro password matches that in ODP. You can click Randomly generated to let the Dashboard generate a random string, or set it manually. When setting a custom password, it must meet the following requirements: Be 8 to 32 characters long Contain only letters, numbers, and special characters (~!@#%^&*_-+=|()[]:;,.?/) Include at least 2 uppercase letters, 2 lowercase letters, and 2 special characters After configuration, you can click Copy Password to save the configured password.

2. Configure the cluster topology

   The cluster topology primarily configures all Zone information for the cluster. Generally, at least three Zones are required. You can click + Add Zone or the delete icon next to a Zone to add or remove a Zone.

   

   Parameter	Description
   Zone Name	Configure the Zone name in OceanBase Database. It can be customized. The Zone 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.
   Server Count	Set how many OBServer services are included in the current Zone.
   K8s Cluster	This parameter applies only to multi-Kubernetes-cluster deployment scenarios. It specifies which K8s cluster this Zone will be deployed into. For single-Kubernetes-cluster deployment, you can leave it empty. For more information on multi-Kubernetes-cluster deployment, see Multi-Kubernetes-Cluster Deployment.
   Topology	Click the expand button before Topology to configure affinity settings. Supports configuration for node selector, pod affinity, and toleration. The configuration only takes effect for the pods of the OBServer services in the current Zone.

3. Configure OBServer resources

   

   Parameter	Description
   Image	Configure the image used to deploy the OceanBase cluster. You can click Image List to view all images. The image tag corresponds to the OceanBase Database version number. It is recommended to use an LTS version image. The image should be written in full as registry/image:tag, for example, oceanbase/oceanbase-cloud-native:4.2.0.0-101000032023091319.
   Resources	Includes CPU, memory, and storage resources. For storage, three independent PVCs will be created to hold data, runtime logs, and redo logs. The configurations for data, runtime logs, and redo logs must be at least three times the value configured for Memory. Supports enabling independent lifecycles for PVCs. After selecting PVC Independent Lifecycle, deleting the OBServer resource will not cascade delete the PVC; you need to delete it manually. You can click the Minimum Specification Configuration button in the upper-right corner of the OBserver module, and the Dashboard will automatically fill in the resources according to the minimum specification.

4. Optional configurations

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

   

   Module	Parameter	Note
   Monitoring	Image	After enabling monitoring, you can configure ObAgent as a sidecar container to provide monitoring capabilities. This parameter specifies the image used to deploy ObAgent. You can click Image list to view all images. The image tag corresponds to the ObAgent version number. The image should be written in the full registry/image:tag format, for example, oceanbase/obagent:4.2.0-100000062023080210.
   	Resources	Specify the number of CPU cores and memory required for deploying ObAgent. Enter positive integers.
   Parameter settings	Parameter name	Enter the parameters for the OceanBase cluster.
   	Parameter value	Set a reasonable value for the corresponding parameter. The set parameter values apply to all OBServer services.
   	Action	You can click the Delete field to delete the corresponding parameter. Note You can click + Add Parameter to add a new row for configuring parameters.
   Mount NFS backup volume	Address	If you need to use NSF for backup and recovery, you can configure the address of the NFS service here.
   	Path	Enter the backup path. The NFS path will be mounted into the container of the OBServer service.

5. Submit and wait for successful creation

   After completing the above configuration, click Submit. Wait until the Status in the Clusters changes to Running to indicate that the cluster has been successfully created.

   Note

   Under normal circumstances, the cluster is expected to be created within two to three minutes.

   

Step 4: Create a tenant

After the cluster is deployed, it is recommended to create a business tenant for application use. You can click Tenant in the left navigation bar, and on the Tenants page, click Create Tenant in the upper-right corner of the Tenants section to go to the Create Tenant page.

1. Fill in the tenant basic information

   

   Parameter	Description
   OB Cluster	Select the OceanBase cluster where the tenant will be created from the drop-down list.
   Resource Name	The name of the custom resource for the tenant in Kubernetes. The tenant will be created under the same namespace as the cluster.
   Tenant Name	The name of the tenant to be created.
   Password	The password for the tenant's root account. You can click Randomly generated to have the dashboard automatically generate a random string, or you can set it manually. When setting a custom password, the password must meet the following requirements: 8 to 32 characters in length Can only contain letters, numbers, and special characters (~!@#%^&*_-+=|()[]:;,.?/) Must contain at least 2 uppercase letters, 2 lowercase letters, 2 numbers, and 2 special characters After configuration, you can click Copy Password to save the configured password.
   Optimization Scenario	Provides parameter templates for common OceanBase Database usage scenarios. Selecting a scenario automatically configures the parameters. For detailed introductions to optimization scenarios, see Configuration Best Practices.
   Connection Allowlist	The allowlist of addresses that can connect to the tenant. By default, % represents any address.
   Deletion Protection	You can enable or disable deletion protection by checking the box. If enabled, deleting the tenant will be intercepted by a webhook, and the tenant can only be deleted after the protection is disabled.

2. Configure the tenant resource pool

   

   Parameter	Description
   Replica Distribution	You can configure which Zones the tenant will be distributed to by clicking the checkbox before each Zone, and set the priority, replica type, and number of units in the corresponding Zone.
   Unit Specification	Configure the resources for each unit of the tenant. It is recommended to configure based on the Available resources displayed in the Replica Distribution section.

3. Submit and wait for successful creation

   After configuration, click Submit, and wait for the Status in the Tenants to change to Running. This indicates the tenant has been successfully created.

   

Step 5: Deploy ODP

ODP (also known as OBProxy) is a necessary component for applications to connect to distributed OceanBase clusters, as it routes requests to the correct OBServer node. You can click OBProxy in the left navigation bar, and on the OBProxy page, click Create OBProxy Cluster in the upper-right corner of the Clusters section 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 configured name must start with a lowercase letter and end with a lowercase letter or number, can contain lowercase letters, numbers, and -, and must not exceed 63 characters in length.
   OBProxy Cluster Name	The application name for ODP.
   Connect to OB Cluster	Select the OceanBase cluster to connect 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 selecting an OceanBase cluster, the namespace of the selected OceanBase cluster is automatically filled in by default.
   OBProxy root Password	The root user password for the ODP management tenant (proxysys). You can click Randomly generated to have the dashboard automatically generate a random string, or you can set it manually. When setting a custom password, the password must meet the following requirements: 8 to 32 characters in length Can only contain letters, numbers, and special characters (~!@#%^&*_-+=|()[]:;,.?/) Must contain at least 2 uppercase letters, 2 lowercase letters, 2 numbers, and 2 special characters After configuration, you can click Copy Password to save the configured password.

2. More configurations

   

   Parameter	Description
   Image	Configure the image used to deploy ODP. You can click Image list to view all images. It is recommended to deploy the latest version. The image tag corresponds to the ODP version number. The image should be written in full registry/image:tag format, for example, oceanbase/obproxy-ce:4.3.3.0-5.
   Service type	Select the service type for the ODP deployment from the drop-down list. If access is only required within the Kubernetes cluster, you can choose to use ClusterIP; if access outside the cluster is needed, you can select NodePort or LoadBalancer based on your situation.
   Number of replicas	Configure the number of ODP replicas.
   CPU cores	Configure the number of CPU cores allocated to ODP.
   Memory size	Configure the memory resources allocated to ODP.
   Parameter settings	You can click Add to configure ODP parameters in KV format.

3. Submit and wait for successful creation

   After completing the above configuration, click Submit. Wait for the Clusters to show that the Status has changed to Running, indicating that ODP has been successfully created.

   

Step 6: Connection verification

After deployment is complete, you can view the Service address on the OBProxy details page and use this address to connect to the cluster.

Run the following command to connect to the obtenant2 tenant in the obcluster cluster through ODP. For detailed information about connecting to a tenant, see Overview of connection methods.

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, OceanBase and/or its affiliates. All rights reserved.

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 high-availability requirements. You can explore these features further on the Dashboard page or refer to the links below.

• GitHub ob-operator documentation

• GitHub ob-operator code repository

• OceanBase Kubernetes O&M tool documentation