Deploy and use obconfigserver

1. Create a configuration file.

   When you add obconfigserver to an OceanBase cluster managed by obd, you only need to configure the information about the ob-configserver component in the created configuration file. Here is an example:

   ob-configserver:
     servers:
       - 10.10.10.1
     global:
       listen_port: 8080 # The port of ob-configserver web
       server_ip: 0.0.0.0 # Listen to the ob-configserver server IP. When you want to listen to the specified IP address,use it.
       home_path: /home/admin/ob-configserver  # The working directory for prometheus. ob-configserver is started under this directory. This is a required field.
       ## log config
       # log_level: info # Log printing level of ob-configserver. The default value is `info`
       # log_maxsize: 30 # The total size of manager ob-configserver.Log size is measured in Megabytes.The default value is 30
       # log_maxage: 7 # The days of manager expired ob-configserver.Log retention days. The default value is 7
       # log_maxbackups: 10  #The number of manager expired ob-configserver.Log. The default value is 10
       # log_localtime: true #  Switch of ob-configserver.Log naming with localtime. The default value is true
       # log_compress: true # Compress ob-configserver.Log switch. The default value is true
   
       ## vip config, configserver will generate url with vip_address and port and return it to the client
       ## do not use some random value that can't be connected
       # vip_address: "10.10.10.1"
       # vip_port:8080
       ## storage config
       # storage:
         ## database type, support sqlite3 or mysql
         # sqlite3:
         # database_type: sqlite3
         # connection_url: "/home/admin/ob-configserver/.data.db?cache=shared&_fk=1"
   
         # mysql:
         # database_type: mysql
         # connection_url: "$user:$password@tcp($IP:$PORT)/$metadb?parseTime=true"
   

   For parameters that are commented out in the configuration file, their default values are used. You can also uncomment the parameters and specify other values for them. The key parameters are described as follows:

   • server_ip: the access allowlist of obconfigserver. The default value is 0.0.0.0, which indicates that access from all IP addresses of the server where obconfigserver resides is allowed.

   • vip_address and vip_port: the IP address and port used for load balancing. If multiple nodes are configured in servers, load balancing is required. After you configure load balancing, specify the IP address and port used for load balancing in the configuration file.

   • database_type: the database type. Valid values are sqlite3 and mysql. The default value is sqlite3. The recommended value is mysql.

   • connection_url: the URL for connecting to the database. The value of connection_url is $home_path/.data.db?cache=shared&_fk=1 by default when the database type is sqlite3, and can be a URL for connecting to an OceanBase database or a MySQL database when the database type is mysql. The specified database user must have the privileges to perform DDL and DML operations on the database corresponding to the URL. If OceanBase Database is used, do not use oceanbase as the database name. Otherwise, a message prompting no privileges is displayed.

2. Run the following command to add the component:

   obd cluster component add test1 -c configserver.yaml
   

   In this example, the target OceanBase cluster is named test1 and the configuration file for adding obconfigserver is named configserver.yaml. In practice, use the actual names. You can run the obd cluster list command to query the cluster name, which is the value of the Name column in the output.

   The output is as follows:

   Connect to ob-configserver ok
   +-----------------------------------------------------------------+
   |                         ob-configserver                         |
   +---------------+------+---------------+----------+--------+------+
   | server        | port | vip_address   | vip_port | status | pid  |
   +---------------+------+---------------+----------+--------+------+
   | 10.10.10.1    | 8080 | 10.10.10.1    | 8080     | active | 2725 |
   +---------------+------+---------------+----------+--------+------+
   curl -s 'http://10.10.10.1:8080/services?Action=GetObProxyConfig'
   

   If ODP has been deployed in the target cluster, two cases exist:

   • If the version of obd is V3.2.0 or later, obd allows you to choose whether to restart the cluster in an interactive manner. You can enter restart in the output to restart ODP by using obconfigserver.

     Restart `obproxy-ce,oceanbase-ce` for test to take effect. You can do it manually later or enter `restart` now: 
     

     If you directly press Enter or enter another value instead of restart, obd will not restart the cluster. After the process ends, ODP still starts by using the RootService list.

   • If obd is of a version earlier than V3.2.0, an obd cluster restart command is provided in the output. You only need to copy and run the command. After the command is executed, ODP will restart by using obconfigserver.

     obd cluster restart demo -c obproxy-ce
     

Create a configuration file named config-only.yaml. The parameters for the components in the configuration file are described as follows:

1. Configure user information.

   ## Only need to configure when remote login is required
   user:
     username: admin
   #   password: your password if need
     key_file: /home/admin/.ssh/id_rsa
   #   port: your ssh port, default 22
   #   timeout: ssh connection timeout (second), default 30
   

   username specifies the username of the account used to log in to the target server. Make sure that this account has the write permission on home_path. password and key_file are used for user verification. Generally, you need to specify only one of them.

   Notice

   After you specify the path of the key, comment out or delete the password parameter if your key does not require a password. Otherwise, the value of the password parameter will be taken as the password of the key and used for login, leading to a login verification failure.

2. Configure the ob-configserver component.

   ob-configserver:
     servers:
       - 10.10.10.1
     global:
       listen_port: 8080 # The port of ob-configserver web
       server_ip: 0.0.0.0 # Listen to the ob-configserver server IP. When you want to listen to the specified IP address,use it.
       home_path: /home/admin/ob-configserver  # The working directory for prometheus. ob-configserver is started under this directory. This is a required field.
       ## log config
       # log_level: info # Log printing level of ob-configserver. The default value is `info`
       # log_maxsize: 30 # The total size of manager ob-configserver.Log size is measured in Megabytes.The default value is 30
       # log_maxage: 7 # The days of manager expired ob-configserver.Log retention days. The default value is 7
       # log_maxbackups: 10  #The number of manager expired ob-configserver.Log. The default value is 10
       # log_localtime: true #  Switch of ob-configserver.Log naming with localtime. The default value is true
       # log_compress: true # Compress ob-configserver.Log switch. The default value is true
   
       ## vip config, configserver will generate url with vip_address and port and return it to the client
       ## do not use some random value that can't be connected
       # vip_address: "10.10.10.1"
       # vip_port:8080
       ## storage config
       # storage:
         ## database type, support sqlite3 or mysql
         # sqlite3:
         # database_type: sqlite3
         # connection_url: "/home/admin/ob-configserver/.data.db?cache=shared&_fk=1"
   
         # mysql:
         # database_type: mysql
         # connection_url: "$user:$password@tcp($IP:$PORT)/$metadb?parseTime=true"
   

   For parameters that are commented out in the configuration file, their default values are used. You can also uncomment the parameters and specify other values for them. The key parameters are described as follows:

   • server_ip: the access allowlist of obconfigserver. The default value is 0.0.0.0, which indicates that access from all IP addresses of the server where obconfigserver resides is allowed.

   • vip_address and vip_port: the IP address and port used for load balancing. If multiple nodes are configured in servers, load balancing is required. After you configure load balancing, specify the IP address and port used for load balancing in the configuration file.

   • database_type: the database type. Valid values are sqlite3 and mysql. The default value is sqlite3. The recommended value is mysql.

   • connection_url: the URL for connecting to the database. The value of connection_url is $home_path/.data.db?cache=shared&_fk=1 by default when the database type is sqlite3, and can be a URL for connecting to an OceanBase database or a MySQL database when the database type is mysql. The specified database user must have the privileges to perform DDL and DML operations on the database corresponding to the URL. If OceanBase Database is used, do not use oceanbase as the database name. Otherwise, a message prompting no privileges is displayed.

3. Deploy obconfigserver.

   [admin@obtest ~]$ obd cluster deploy config-only -c config-only.yaml
   

   Here is an example of deploying the config-only cluster by using the config-only.yaml configuration file. In practice, use the actual cluster names and configuration file names.

4. Start obconfigserver.

   [admin@obtest ~]$ obd cluster start config-only
   

   The output is as follows, where you can see the access address of obconfigserver.

   +-----------------------------------------------------------+
   |                      ob-configserver                      |
   +---------+------+---------------+----------+--------+------+
   | server  | port | vip_address   | vip_port | status | pid  |
   +---------+------+---------------+----------+--------+------+
   | 0.0.0.0 | 8080 | 10.10.10.1    | 8080     | active | 6270 |
   +---------+------+---------------+----------+--------+------+
   curl -s 'http://10.10.10.1:8080/services?Action=GetObProxyConfig'
   

1. Log in as the root user to the sys tenant of the cluster to be registered.

   obclient -h<IP> -P<PORT> -uroot@sys -p -c -A
   #example
   obclient -h10.10.10.4 -P4883 -uroot@sys -p -c -A
   

   Here, IP specifies the IP address for connecting to OceanBase Database. PORT specifies the port for connecting to OceanBase Database, which takes the value of the mysql_port parameter in the case of direct connection, or the value of the listen_port parameter in the case of connection through ODP.

   For more information about how to use OBClient to connect to an OceanBase cluster, see Connect to an OceanBase Database tenant by using OBClient.

2. View the value of the obconfig_url parameter.

   obclient> SHOW PARAMETERS LIKE 'obconfig_url';
   

   The output is as follows, indicating that obconfig_url is not configured for the cluster.

   +-------+----------+---------------+----------+--------------+-----------+-------+--------------------------+----------+---------+---------+-------------------+---------------+-----------+
   | zone  | svr_type | svr_ip        | svr_port | name         | data_type | value | info                     | section  | scope   | source  | edit_level        | default_value | isdefault |
   +-------+----------+---------------+----------+--------------+-----------+-------+--------------------------+----------+---------+---------+-------------------+---------------+-----------+
   | zone3 | observer | 10.10.10.4   |     2882  | obconfig_url | STRING    |       | URL for OBConfig service | OBSERVER | CLUSTER | DEFAULT | DYNAMIC_EFFECTIVE |               |         1 |
   | zone1 | observer | 10.10.10.2   |     2882  | obconfig_url | STRING    |       | URL for OBConfig service | OBSERVER | CLUSTER | DEFAULT | DYNAMIC_EFFECTIVE |               |         1 |
   | zone2 | observer | 10.10.10.3   |     2882  | obconfig_url | STRING    |       | URL for OBConfig service | OBSERVER | CLUSTER | DEFAULT | DYNAMIC_EFFECTIVE |               |         1 |
   +-------+----------+---------------+----------+--------------+-----------+-------+--------------------------+----------+---------+---------+-------------------+---------------+-----------+
   

3. Configure obconfig_url.

   alter system set obconfig_url = 'http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=test1';
   

   10.10.10.1:8080 is the access address of obconfigserver. test1 is the appname value of the OceanBase cluster to be registered, which you can obtain by executing the SHOW PARAMETERS LIKE 'cluster'; statement after connecting to the cluster. The value provided here is only for reference. You must change it based on the actual situation.

4. Log out of the OceanBase cluster and verify whether obconfigserver can parse the information about the cluster.

   curl -s 'http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=test1' |jq .
   

   Note

   After you register an OceanBase cluster with obconfigserver, you can query related information in obconfigserver after a few minutes.

The output is as follows, showing that the IP addresses and ports of OBServer nodes in the cluster are successfully parsed.

{
  "Code": 200,
  "Message": "successful",
  "Success": true,
  "Data": {
    "ObClusterId": 1,
    "ObRegionId": 1,
    "ObCluster": "test1",
    "ObRegion": "test1",
    "ReadonlyRsList": [],
    "RsList": [
      {
        "address": "10.10.10.4:4882",
        "role": "LEADER",
        "sql_port": 4881
      }
    ],
    "Type": "PRIMARY",
    "timestamp": 1692699586370950
  },
  "Trace": "362172a2d5de734c",
  "Server": "10.10.10.1",
  "Cost": 1
}