Why OceanBase Driver Throws Access Denied in Kubernetes and How to Resolve

1. Problem Background

In a customer environment, after migrating the application database from MySQL to OceanBase, new application servers encounter errors when connecting with the OceanBase driver. Although the whitelist and network settings are correct, the driver reports Access denied, while the MySQL driver connects successfully.

The application requires the OceanBase driver’s LoadBalance mode for load balancing, so the root cause must be identified.

Driver Versions

MySQL driver : mysql-connector-java-8.0.33

OceanBase driver : oceanbase-client-2.4.12

2. Reproduction and Analysis

1. Problem Thinking

In OceanBase’s MySQL mode, the Access denied error usually occurs during authentication or authorization.

Possible causes to focus on:

Whitelist or permission control : the client IP may not be in the allowed list; the OceanBase driver might use a different IP (e.g., after proxy) than the MySQL driver.

Driver compatibility (low probability) : the OceanBase driver could use protocol extensions that are incompatible with the server version, while the MySQL driver follows the standard MySQL protocol.

Following this checklist resolves about 95% of Access denied errors.

2. Problem Reproduction

Network topology in the application side (image):

Kubernetes pod information (image):

The tenant obmysql whitelist contains the Kubernetes node IP (image):

When using the MySQL driver, the application starts without errors and the database session source is the physical server IP (Node IP) (image):

When using the OceanBase driver, the application logs show many Access denied errors (image):

3. Error Log Analysis

OBProxy_error Log

The obproxy_error.log records all request errors, including those returned by OceanBase. The log contains Access denied messages.

To obtain richer error information, enable the cluster‑level parameter enable_rich_error_msg=true (default false). No restart is required; the observer will apply the change immediately.

# Use root@sys to execute
alter system set enable_rich_error_msg = True;

After enabling, both obproxy_error.log and the application logs include a trace_id for detailed debugging (image):

The log shows that the client IP recorded is the pod IP (e.g., 10.245.2.30), not the node IP, and this IP is not in the whitelist, causing the Access denied error.

Therefore, the whitelist must include the actual pod IP range (e.g., 10.245.0.0/24) to allow connections.

3. Problem Extension

1. Spoofing Client IP

OceanBase’s whitelist checks the client_ip attribute in the connection. By modifying the driver code (classes AbstractQueryProtocol#changeUser and AbstractConnectProtocol#authenticationHandler) you can inject a custom IP via the environment variable OB_CLIENT_IP. Setting OB_CLIENT_IP=10.186.63.80 (an IP already in the whitelist) bypasses the whitelist check.

After redeploying the modified driver, the application runs without errors and the database session source shows the forged node IP (image):

2. OBProxy Parameter Transmission

OBProxy has a parameter enable_client_ip_checkout that controls whether the client IP is validated.

Default value: True – client IP is checked and sent to ODP.

Set to False – client IP is not checked; the session source becomes the OBProxy IP.

When the parameter remains True, pod IPs are rejected (image):

Setting enable_client_ip_checkout=false disables the check, allowing the application to connect, but the session source changes to the OBProxy IP (image):

4. Solutions and Preventive Measures

Solution 1: Whitelist Configuration Best Practices

Whitelist must cover all actual client pod IPs. Because pod IPs are dynamic in Kubernetes, add the entire pod network segment (e.g., 10.245.0.0/24) to the whitelist and regularly audit the list.

Solution 2: Modify Driver Code (Not Recommended)

Security risk: disabling IP whitelist may expose the database to unauthorized access.

Maintainability: driver changes require ongoing maintenance and violate security best practices.

Solution 3: Adjust OBProxy Parameters (Not Recommended)

Disabling client IP verification via enable_client_ip_checkout works but changes the session source to the OBProxy IP and may affect multi‑tenant or shared‑proxy scenarios.

5. Summary

Enable enable_rich_error_msg=true to obtain trace_id and detailed error messages for faster troubleshooting.

The OceanBase driver forwards the real client IP, while the MySQL driver does not.

In Kubernetes, even if the node IP is whitelisted, the pod IP is the one checked; therefore, whitelist the pod IP range.

Adjust network and whitelist configurations according to the actual client IPs to ensure normal database access.

Further Considerations

Modifying the driver to bypass whitelist verification constitutes a security vulnerability and may lead to unauthorized database access. Changing OBProxy’s enable_client_ip_checkout also carries similar risks and should be used with caution.

References

[1] obproxy_error.log: https://www.oceanbase.com/docs/common-odp-doc-cn-1000000002839678

[2] enable_rich_error_msg: https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000003381759

[3] "Tenant Whitelist and OceanBase JDBC Driver Configuration Relationship": https://www.oceanbase.com/knowledge-base/oceanbase-connector-j-1000000000217903

[4] obconnector-j source code: https://github.com/oceanbase/obconnector-j.git

[5] enable_client_ip_checkout: https://www.oceanbase.com/docs/common-odp-doc-cn-1000000002839895