Deploy an OceanBase cluster in a Kubernetes environment

This topic introduces how to deploy an OceanBase cluster in a Kubernetes environment and can be used as a reference for production deployment. For more information on custom deployment and configuration methods, refer to the Kubernetes operator for OceanBase (ob-operator) documentation.

Prerequisites

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

Hardware resources

To ensure stability and performance in production, we recommend that the remaining Kubernetes resources meet the following configuration:

• CPU: 24 or more available CPUs.

• Memory: 72 GB or more available memory.

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

Software dependencies

• Kubernetes cluster: Version v1.18 or later is required.

• helm: Used to deploy ob-operator and OceanBase Dashboard. For installation, see Installing Helm.

• cert-manager: ob-operator depends on cert-manager for certificate management. For installation, see the cert-manager installation documentation.

• Storage: The cluster must have an available storage class. We have tested some common storage systems. The following table shows the test results. You can refer to the storage compatibility test results to determine whether your environment meets the requirements. This topic uses local-path-provisioner as an example.

  Storage solution	Tested version	Compatible?	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 machine kernel version is 5.14 or later
  Longhorn	v1.6.0	✅
  JuiceFS	v1.1.2	✅
  NFS	v5.5.0	❌	Cluster can start when NFS protocol >= 4.2, but 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 control component of OceanBase in Kubernetes. We recommend deploying it 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
   

   --namespace is used to set the installation namespace. You can customize it as needed. We recommend using oceanbase-system.

3. Verify that the installation is successful

   kubectl get pod -n oceanbase-system
   

   The expected output is as follows. The pod STATUS should be 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 the service port
   kubectl get svc -n oceanbase-system oceanbase-dashboard-oceanbase-dashboard
   

3. Log in to OceanBase Dashboard

   Use the service port obtained in the previous step to access OceanBase Dashboard through a browser. The default username and password are both admin. You must change the password upon the first login.

   • If service.type is NodePort, access via http://<any-node-IP>:<NodePort>.

   • If service.type is LoadBalancer, access via http://<External-IP>:<port>.

Step 3: Deploy an OceanBase cluster

After you log in to OceanBase Dashboard, click Clusters in the left-side navigation pane. On the Clusters page, click Create a cluster in the upper-right corner of Cluster list to open the Create a cluster page.

1. Configure basic information

   On this page, you can configure the namespace, cluster name, cluster mode, root password, and other information.

   Parameter	Description
   Namespace	Select the namespace for creating the OceanBase cluster from the drop-down list. You can also click + Add namespace in the drop-down list to create a new namespace. When adding a namespace, the name must start with a lowercase letter and end with a lowercase letter or digit. It can contain lowercase letters, digits, and -, and must not exceed 63 characters.
   Resource Name	The OceanBase cluster custom resource in Kubernetes. It cannot be the same as an existing OceanBase cluster resource name in the same namespace. When customizing, the name must start with a lowercase letter and end with a lowercase letter or digit. It can contain lowercase letters, digits, and -, and must not exceed 63 characters.
   Cluster name	The OceanBase cluster name. It must start with a letter and end with a letter or digit. It can contain letters, digits, and underscores, and must be 2 to 32 characters in length.
   Cluster mode	Select the cluster deployment mode from the drop-down list. Different cluster modes have different requirements for the OceanBase Database version and affect the recovery strategy when failures occur. Select based on your environment and cluster version. Regular mode: No special processing. Bootstrap is performed directly using pod IP addresses. Currently supports calico and kube-ovn plugins. When rebuilding a failed pod, the previous IP address is used. We recommend allocating a separate network segment for the OceanBase cluster to avoid occupation by other pods. If the K8s cluster uses other network plugins, a scale-out-then-scale-in recovery strategy is used, which often takes longer to replicate large amounts of data and cannot recover from majority-node failure scenarios. Standalone mode: Uses 127.0.0.1 for bootstrap. Only for single-node cluster deployment. Since 127.0.0.1 is specified as the OBServer service address, data can be reused for quick recovery when a pod is rebuilt. Service mode: Creates a service for each OBServer service and uses the service cluster IP address for bootstrap. Data can also be reused for quick recovery when a pod is rebuilt. We recommend this mode in general.
   Optimization Scenarios	Provides parameter templates for common OceanBase cluster usage scenarios. Selecting a scenario automatically configures parameters. For more information, see Recommended configurations.
   root password	The root user password of the sys tenant. You can click Randomly generated to have Dashboard automatically generate a random string, or set a custom password. For custom passwords: Length: 8-32 characters Can only contain letters, digits, and special characters (~!@#%^&*_-+=|()[]:;,.?/) Must contain at least 2 of each: uppercase letters, lowercase letters, digits, and special characters After configuration, you can click Copy password to copy and save the configured password.
   Deletion protection	Select to enable or disable deletion protection. When enabled, deletion of the OceanBase cluster will be intercepted by the webhook. You must disable it before the cluster can be deleted.
   Advanced Configuration	Click the expand icon after Advanced configuration to configure proxyro password. When Advanced configuration is not opened, Dashboard automatically generates a random string as the proxyro password. The proxyro password is the proxyro user password of the sys tenant. OceanBase Database Proxy (ODP) can access the corresponding OceanBase cluster only when the proxyro password in the OceanBase cluster matches that in ODP. You can click Randomly generated to have Dashboard generate a random string, or set a custom password. For custom passwords, the same requirements as root password apply.

2. Configure cluster topology

   Cluster topology mainly configures all zone information for the cluster. Generally, at least 3 zones need to be configured. You can click Add Zone or the delete icon after a zone to add or remove zones.

   Parameter	Description
   Zone name	The zone name in OceanBase Database. The zone name can be customized. It must start with a letter, end with a letter or number, can contain letters, numbers, and underscores, and must be between 2 and 32 characters long.
   Servers	The number of OBServer services in the current zone.
   K8s cluster	This parameter applies only to multi-K8s cluster deployment. Used to set which K8s cluster this zone is deployed to. Can be left empty for single-K8s cluster deployment.
   Topology	Click the expand button before Topology to configure affinity (node selector, pod affinity, and toleration). The configuration applies only to OBServer service pods in the current zone.

3. Configure OBServer resources

   Parameter	Description
   Image	The image for deploying the OceanBase cluster. You can click Image list to view all images. The image tag corresponds to the OceanBase Database version. We recommend using LTS version images. Use the full format registry/image:tag, for example oceanbase/oceanbase-cloud-native:4.2.0.0-101000032023091319.
   Resources	Includes CPU, memory, and storage resources. Three separate PVCs will be created for storing data, running logs, and redo logs. The configuration for data, running logs, and redo logs must each be at least three times the memory configuration. It is supported to enable independent lifecycle for PVCs. When PVC independent life cycle is checked, deleting OBServer resources will not cascade-delete the PVCs, and manual deletion is required. You can click the Minimum specification configuration button at the top right of the OBServer section, and the Dashboard will automatically fill in the resources according to the minimum specifications.

4. Optional configuration

   Click the buttons after Monitoring, Parameter settings, and Mount NFS resources to configure the corresponding content.

   Module	Parameter	Description
   Monitoring	Image	When monitoring is enabled, obagent can be configured as a sidecar container to provide monitoring. This field configures the image for deploying obagent. You can click Image list to view all images. The image tag corresponds to the obagent version. Use the full format registry/image:tag, for example oceanbase/obagent:4.2.0-100000062023080210.
   	Resources	The CPU and memory required for deploying obagent. Enter positive integers.
   Parameter settings	Parameter name	The OceanBase cluster parameter name.
   	Parameter value	Set a reasonable value for the corresponding parameter. The set value applies to all OBServer services.
   	Operation	Click Delete to remove the corresponding parameter. Note Click + Add parameter to add a row for configuring parameters.
   Mount NFS backup volume	Address	To use NFS for backup and recovery, configure the NFS service address here.
   	Path	The backup path. The NFS path will be mounted to the OBServer service container.

   5. Submit and wait for creation to succeed

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

      Note

      Normally, the creation takes about two to three minutes.

   Step 4: Create a tenant

   After the cluster is deployed, we recommend creating a business tenant for application use. Click Tenants in the left-side navigation pane. On the Tenant List page, click Create a tenant in the upper-right corner of Tenant List to open the Create a tenant page.

   1. Enter basic tenant information

      Parameter	Description
      OB cluster	Select the OceanBase cluster for the tenant from the drop-down list.
      Resource Name	The tenant custom resource name in Kubernetes. The tenant is created in the same namespace as the cluster.
      Tenant name	The name of the tenant to be created.
      Password	The root account password of the tenant. You can click Randomly generated or set a custom password. For custom passwords, the same requirements as root password apply.
      Optimization Scenarios	Provides parameter templates for common OceanBase Database usage scenarios. Selecting a scenario automatically configures parameters. For more information, see Recommended configurations.
      Connection whitelist	The allowlist addresses that can connect to the tenant. Default % indicates any address.
      Deletion protection	Select to enable or disable deletion protection. When enabled, deletion of the tenant will be intercepted by the webhook.

   2. Configure tenant resource pool

      Parameter	Description
      Replica distribution	Click the checkboxes before each zone to configure which zones the tenant is distributed in, and set the priority, replica type, and unit count for each zone.
      Resource unit specification	Configure the resources for each unit of the tenant. We recommend configuring based on the Available resources displayed in the Replica distribution module.

   3. Submit and wait for creation to succeed

      After configuration, click Submit. Wait until Status in Tenant List changes to Running to indicate that the tenant has been created successfully.

   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 nodes. Click OBProxy in the left-side navigation pane. On the OBProxy page, click Create an OBProxy cluster in the upper-right corner of Cluster List to open the Create an OBProxy cluster page.

   1. Configure basic information

      Parameter	Description
      Resource Name	The deployment name created in Kubernetes. Must start with a lowercase letter and end with a lowercase letter or digit. Can contain lowercase letters, digits, and -. Length must not exceed 63 characters.
      OBProxy cluster name	The ODP application name.
      Connect to the OB cluster	Select the OceanBase cluster to connect to from the drop-down list. By default, rs_list is used to connect to the selected OceanBase cluster.
      Namespace	The Kubernetes namespace for deploying ODP. After selecting an OceanBase cluster, the namespace of the selected OceanBase cluster is automatically filled.
      OBProxy root password	The root user password of the ODP management tenant (proxysys). You can click Randomly generated or set a custom password. For custom passwords, the same requirements as root password apply.

   2. More configuration

      Parameter	Description
      Image	The image for deploying ODP. You can click Image list to view all images. We recommend deploying the latest version. The image tag corresponds to the ODP version. Use the full format registry/image:tag, for example oceanbase/obproxy-ce:4.3.3.0-5.
      Service Type	Select the service type for ODP from the drop-down list. For access only within the Kubernetes cluster, use ClusterIP. For access from outside the cluster, choose NodePort or LoadBalancer as appropriate.
      Number of replicas	The number of ODP replicas.
      Number of CPU cores	The CPU cores allocated to ODP.
      Memory size	The memory resources allocated to ODP.
      Parameter setting	Click + Add to configure ODP parameters in key-value format.

   3. Submit and wait for creation to succeed

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

   Step 6: Connection verification

   After deployment, you can view the Service address on the OBProxy details page to connect to the cluster.

   Run the following command to connect to the obtenant2 tenant of the obcluster cluster through ODP. For detailed information about connecting to tenants, see Connection methods 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 document covers only the most basic deployment method, which applies to initial environment setup. We also support comprehensive O&M and monitoring features, as well as deployment modes in multi-K8s clusters for higher high availability requirements. You can explore these features further on the Dashboard page or refer to the following links for more information.

   • GitHub documentation for ob-operator

   • GitHub code repository for ob-operator

   • ob-operator documentation