Deploy OCP Express by using commands

This topic describes how to use commands to deploy OceanBase Cloud Platform (OCP) Express in three different scenarios.

Prerequisites

• The version of OceanBase Database is V4.0.0.0 or later.

• The version of OBAgent is V1.3.0 or later. If the version of OCP Express is V4.2.1 or later, that of OBAgent must be V4.2.1 or later.

• The version of OceanBase Deployer (OBD) is V2.0.0 or later. If the version of OCP Express is V4.2.1 or later, that of OBD must be V2.3.1 or later. If the OBD you are using is earlier than V2.0.0, upgrade the OBD by referring to How to update OBD? in FAQ.

• The Java environment is installed and configured on the server where you want to deploy OCP Express. Only Java Development Kit (JDK) 1.8 is supported. For more information, see How do I configure the Java environment before I deploy OCP Express? in FAQ.

• It is recommended to allocate at least 512 MB of memory for OCP Express. For long-term stable operation, it is recommended to allocate 762 MB or more.

Resource specifications of OCP Express

Configuration requirements

The OCP Express service generates high computing and storage overheads during running. Therefore, you must perform resource planning based on the specifications of managed objects. The following table lists the resource consumption of the OCP Express server based on the assumption that each cluster contains 10 tenants. You can calculate the resource consumption and properly configure resources based on the actual situation.

MetaDB resources

Meta Database (MetaDB) stores the metadata and monitoring data of OCP Express. We recommend that you create an independent tenant in the OceanBase cluster for MetaDB.

The resources required vary with the number of OBServer nodes managed in OCP Express. The following table lists the CPU, memory, and disk resources for each replica in a tenant for MetaDB based on the assumption that each cluster contains 10 tenants. You can calculate the resource consumption and properly configure resources based on the actual situation.

Configuration files

OBD provides sample configuration files for deploying OCP Express. You can modify them based on your server resources.

• If OBD is directly downloaded and installed on your server, you can view the sample configuration file provided by OBD in the /usr/obd/example directory.

• If OBD is installed by using the all-in-one package, you can view the sample configuration file provided by OBD in the ~/.oceanbase-all-in-one/obd/usr/obd/example directory.

• You can also view the sample configuration files provided by OBD at GitHub.

OBD provides the following sample configuration files for deploying OCP Express:

• Sample configuration files for distributed deployment with all components: all-components-min.yaml and all-components.yaml

• Sample configuration files for distributed deployment with ODP and OCP Express: default-components.yaml and default-components-min.yaml

• Sample configuration file for deploying OCP Express only: ocp-express-only.yaml

Scenario 1: Deploy an OceanBase cluster and OCP Express together

If you want to deploy an OceanBase cluster and OCP Express at the same time, you must configure the tenant information required by OCP Express in the oceanbase-ce component. You can directly declare in the configuration file that the configurations of the ocp-express component depend on other components such as oceanbase-ce, obproxy-ce, and obagent. In this case, you only need to configure home_path and memory_size, and other parameters are obtained from the dependent components.

The following example describes parameters of the oceanbase-ce component in the default-components.yaml configuration file:

oceanbase-ce:
  servers:
    - name: server1
      ip: 172.xx.xxx.4
  global:
    home_path: xxxx
    ...
    ocp_meta_tenant:
      tenant_name: ocp_meta
      max_cpu: 2
      memory_size: 6442450944
    ocp_meta_db: ocp_express
    ocp_meta_username: ocp_user
    ocp_meta_password:
    ...

The parameters beginning with ocp_meta_tenant are passed when the tenant is created. The preceding table shows only a few important parameters. For specific parameters, see the parameters supported in the tenant creation command. For more information, see the description of the obd cluster tenant create command in Cluster commands.

During the bootstrap of the oceanbase-ce component, if OBD detects that the preceding parameters are specified or the ocp-express component exists in the current cluster, OBD automatically creates the corresponding meta tenant and user.

Configurations of the ocp-express component are as follows:

ocp-express:
  depends:
    - oceanbase-ce
    - obproxy-ce
    - obagent
  servers:
    - name: server2
      ip: 10.10.10.4
  global:
    # The working directory for ocp-express. ocp-express is started under this directory. This is a required field.
    home_path: /home/admin/ocp-server
    # log_dir: /home/admin/ocp-server/log # The log directory of ocp express server. The default value is {home_path}/log.
    memory_size: 1G # The memory size of ocp-express server. The recommend value is 512MB + (expect node num + expect tenant num) * 60MB.
    logging_file_total_size_cap: 10GB # The total log file size of ocp-express server.

The following table describes the parameters.

After you modify the configuration file, run the following commands to deploy and start the cluster:

# Deploy the cluster
obd cluster deploy <deploy name> -c config.yaml
# Start the cluster
obd cluster start <deploy name>

After the cluster is started, you can use the login address, username, and password of the ocp-express server provided in the command output to log in to OCP Express and start using it.

Scenario 2: Add OCP Express to an OceanBase cluster (with OBAgent deployed)

If you have already deployed an OceanBase cluster and OBAgent, you can refer to this section.

1. (Optional) If the version of OBAgent in the cluster is earlier than V1.3.0, run the following command to upgrade OBAgent:

   # View the hash value of OBAgent
   obd mirror list oceanbase.community.stable | grep -e " obagent "
   # Upgrade OBAgent
   obd cluster upgrade test -c obagent -V 1.3.0 --usable=<obagent_hash>
   

   You must replace obagent_hash in the command with the hash value of OBAgent of the corresponding version.

2. Create a meta tenant, a user, and a database for OCP Express, and grant the user the required privileges.

   1. Create a meta tenant.

      obd cluster tenant create <deploy name> -n <tenant_name> --max-cpu=2 --memory-size=4G --log-disk-size=3G --max-iops=10000 --iops-weight=2 --unit-num=1 --charset=utf8
      

      The specifications of the meta tenant must be configured based on the deployed cluster resources. For more information, see MetaDB resources. For more information about the obd cluster tenant create command, see the description of the obd cluster tenant create commands in Cluster commands.

      You can also log in to OceanBase Database to create a tenant for OCP Express. For more information, see Create a tenant.

   2. Create a user and grant the user the required privileges.

      create user <ocp_user> identified by '<ocp_password>';
      grant all on *.* to <ocp_user>;
      

   3. Create a database.

      create database <database_name>;
      

3. Modify the configuration file.

   The following example describes parameters of the ocp-express-only.yaml configuration file:

   ## Only need to configure when remote login is required
   # user:
   #   username: your username
   #   password: your password if need
   #   key_file: your ssh-key file path if need
   #   port: your ssh port, default 22
   #   timeout: ssh connection timeout (second), default 30
   ocp-express:
     servers:
       - name: server1
         ip: xxx.xxx.xxx.xxx
     global:
       # The working directory for ocp-express. ocp-express is started under this directory. This is a required field.
       home_path: /home/admin/ocp-server
       log_dir: /home/admin/ocp-server/log # The log directory of ocp express server. The default value is {home_path}/log.
       memory_size: 1G # The memory size of ocp-express server. The recommend value is 512MB + (expect node num + expect tenant num) * 60MB.
       jdbc_url: jdbc:oceanbase://IP:PORT/meta_db # jdbc connection string to connect to the meta db
       jdbc_username: user_name@tenant_name # username to connect to meta db
       jdbc_password: '<meta db password>' # password to connect to meta db
       port: 8180 # The http port to use.
       cluster_name: obcluster # the cluster name of oceanbase cluster. Refer to the configuration item appname of oceanbase
       ob_cluster_id: 1 # the cluster id of oceanbase cluster. Refer to the configuration item cluster_id of oceanbase
       root_sys_password: <password for root@sys>
       agent_username: <obagent> # The username of obagent
       agent_password: <password> # The password of obagent
       logging_file_total_size_cap: 10GB # The total log file size of ocp-express server.
       server_addresses: # The cluster info for oceanbase cluster
       - address: 127.0.0.1 # The address of oceanbase server
         svrPort: 2882 # The rpc port of oceanbase server
         sqlPort: 2881 # The mysql port of oceanbase server
         agentMgrPort: 8089 # The port of obagent manager process
         agentMonPort: 8088 # The port of obagent monitor process
   

   Parameter	Required?	Description
   home_path	Yes	The working directory of OCP Express. OCP Express boots from this directory.
   log_dir	No	The log directory of OCP Express. The default value is the log directory in the path specified by the home_path parameter.
   memory_size	Yes	The memory capacity of the OCP Express server. The recommended calculation formula is as follows: memory_size = 512 MB + (Expected number of nodes × Expected number of tenants) × 60 MB. The expected number of tenants should include the sys tenant and the OCP meta tenant.
   jdbc_url	Yes	The Java Database Connectivity (JDBC) connection string for connecting to the meta tenant. Make sure that the database used in the connection string has been created.
   jdbc_username	Yes	The username for connecting to the meta tenant. Make sure that this user has been created. Note The username format here is user_name@tenant_name. If user_name is specified and tenant_name is omitted, user_name@sys will be used for the connection by default. The sys tenant cannot be used as a meta tenant.
   jdbc_password	Yes	The user password for connecting to the meta tenant.
   port	No	The HTTP port for accessing OCP Express.
   cluster_name	Yes	The name of the OceanBase cluster, which must be the same as the value of the appname parameter in the oceanbase-ce component.
   ob_cluster_id	Yes	The ID of the OceanBase cluster, which must be the same as the value of the cluster_id parameter in the oceanbase-ce component.
   root_sys_password	Yes	The password of the root@sys user in the OceanBase cluster.
   agent_username	Yes	The username of OBAgent.
   agent_password	Yes	The password of OBAgent.
   logging_file_total_size_cap	Yes	The total size of log files. The default value is 1 GB. Notice: The unit of this parameter must be GB or MB. If you use the unit G or M, an error will occur, and OCP Express deployment will not be successful.
   server_addresses->address	Yes	The IP address of the OBServer node.
   server_addresses->svrPort	Yes	The remote procedure call (RPC) port of the OBServer node, which must be the same as the value of the rpc_port parameter of the corresponding node in the oceanbase-ce component.
   server_addresses->sqlPort	Yes	The MySQL port of the OBServer node, which must be the same as the value of the mysql_port parameter of the corresponding node in the oceanbase-ce component.
   server_addresses->agentMgrPort	Yes	The port for the management process of OBAgent, which must be modified according to the actual setting in the OBAgent.
   server_addresses->agentMonPort	Yes	The port for the monitoring process of OBAgent, which must be modified according to the actual setting in the OBAgent.

4. After you modify the configuration file, run the following commands to deploy and start the cluster:

   # Deploy the cluster
   obd cluster deploy <deploy name> -c config.yaml
   # Start the cluster
   obd cluster start <deploy name>
   

5. After the cluster is started, you can use the login address, username, and password of the ocp-express server provided in the command output to log in to OCP Express and start using it.

Scenario 3: Add OCP Express to an OceanBase cluster (without deploying OBAgent)

If you have already deployed an OceanBase cluster but have not deployed OBAgent, you can refer to this section.

Step 1: Create a meta tenant

Create a meta tenant, a user, and a database for OCP Express, and grant the user the required privileges.

1. Create a meta tenant.

   obd cluster tenant create <deploy name> -n <tenant_name> --max-cpu=2 --memory-size=4G --log-disk-size=3G --max-iops=10000 --iops-weight=2 --unit-num=1 --charset=utf8
   

   The specifications of the meta tenant must be configured according to the specific cluster deployment. For detailed information, see MetaDB resources. For detailed instructions on the obd cluster tenant create command, see the description of the obd cluster tenant create command in Cluster commands.

   You can also log in to OceanBase Database to create a tenant for OCP Express. For detailed instructions, see Create a tenant.

2. Create a user and grant the user the required privileges.

   create user <ocp_user> identified by '<ocp_password>';
   grant all on *.* to <ocp_user>;
   

3. Create a database.

   create database <database_name>;
   

Step 2: Modify the configuration file

You can refer to this section to configure OBAgent and OCP Express.

1. Configure the user.

   ## 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
   

   Here, username specifies the username for logging in to the target server. Make sure that your username has the write privilege on home_path. Generally, you can specify either password or key_file because both of them are used for user authentication.

2. Configure OBAgent.

   obagent:
     servers:
       # Do not use the hostname. Only IP address is supported.
       - 10.10.10.1
       - 10.10.10.2
       - 10.10.10.3
     global:
       # The working directory for obagent. obagent is started under this directory. This is a required field.
       home_path: /home/admin/obagent
       # The port of monitor agent. The default port number is 8088.
       monagent_http_port: 8088
       # The port of manager agent. The default port number is 8089.
       mgragent_http_port: 8089
       # The log path. The default value is log/monagent.log.
       log_path: log/monagent.log
       # The log level of manager agent.
       mgragent_log_level: info
       # The total size of manager agent.Log size is measured in Megabytes. The default value is 30M.
       mgragent_log_max_size: 30
       # Expiration time for manager agent logs. The default value is 30 days.
       mgragent_log_max_days: 30
       # The maximum number for manager agent log files. The default value is 15.
       mgragent_log_max_backups: 15
       # The log level of monitor agent.
       monagent_log_level: info
       # The total size of monitor agent.Log size is measured in Megabytes. The default value is 200M.
       monagent_log_max_size: 200
       # Expiration time for monitor agent logs. The default value is 30 days.
       monagent_log_max_days: 30
       # The maximum number for monitor agent log files. The default value is 15.
       monagent_log_max_backups: 15
       # The username for HTTP authentication. The default value is admin.
       http_basic_auth_user: admin
       # Password for HTTP authentication.
       http_basic_auth_password: ******
       # Monitor password for OceanBase Database. The default value is empty. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the ocp_agent_monitor_password in oceanbase-ce.
       monitor_password: ******
       # The SQL port for observer. The default value is 2881. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the mysql_port in oceanbase-ce.
       sql_port: 2881
       # The RPC port for observer. The default value is 2882. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the rpc_port in oceanbase-ce.
       rpc_port: 2882
       # Cluster name for OceanBase Database. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the appname in oceanbase-ce.
       cluster_name: obcluster
       # Cluster ID for OceanBase Database. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the cluster_id in oceanbase-ce.
       cluster_id: 1
       # The redo dir for Oceanbase Database. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the redo_dir in oceanbase-ce.
       ob_log_path: /home/admin/observer/store
       # The data dir for Oceanbase Database. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the data_dir in oceanbase-ce.
       ob_data_path: /home/admin/observer/store
       # The work directory for Oceanbase Database. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the home_path in oceanbase-ce.
       ob_install_path: /home/admin/observer
       # The log path for Oceanbase Database. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the {home_path}/log in oceanbase-ce.
       observer_log_path: /home/admin/observer/log
       # Monitor status for OceanBase Database. Active is to enable. Inactive is to disable. The default value is active. When you deploy a cluster automatically, OBD decides whether to enable this parameter based on depends.
       ob_monitor_status: active
     10.10.10.1:
       # Zone name for your observer. The default value is zone1. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the zone name in oceanbase-ce.
       zone_name: zone1
     10.10.10.2:
       # Zone name for your observer. The default value is zone1. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the zone name in oceanbase-ce.
       zone_name: zone2
     10.10.10.3:
       # Zone name for your observer. The default value is zone1. When a depends exists, OBD gets this value from the oceanbase-ce of the depends. The value is the same as the zone name in oceanbase-ce.
       zone_name: zone3
   

   Parameter	Required?	Default value	Description
   servers	Yes	None	You must specify each server with - name: server ID (line break) ip: server IP address. The server ID must be unique. If the server IP addresses are unique, you can also use the - <ip> (line break)- <ip> format to specify them. In this case, - <ip> is equivalent to - name: server ID (line break) ip: server IP address.
   home_path	Yes	None	The working directory of the component. We recommend that you create this directory under the common user admin.
   monagent_http_port	Yes	8088	The port for the monitoring service of OBAgent.
   mgragent_http_port	Yes	8089	The port for the management service of OBAgent.
   log_path	Yes	log/monagent.log	The log path.
   mgragent_log_level	No	None	The log level for the management service of OBAgent.
   mgragent_log_max_size	No	30	The log file size for the management service of OBAgent, in MB.
   mgragent_log_max_days	No	30	The maximum retention days for log files of the management service of OBAgent.
   mgragent_log_max_backups	No	15	The maximum number of backups for log files of the management service of OBAgent.
   monagent_log_level	No	info	The log level for the monitoring service of OBAgent.
   monagent_log_max_size	No	200	The log file size for the monitoring service of OBAgent, in MB.
   monagent_log_max_days	No	30	The maximum retention days for log files of the monitoring service of OBAgent.
   monagent_log_max_backups	No	15	The maximum number of backups for log files of the monitoring service of OBAgent.
   http_basic_auth_user	Yes	admin	The username for HTTP service authentication.
   http_basic_auth_password	Yes	root	The password for HTTP service authentication.
   monitor_password	No	Empty	The password for collecting monitoring data of OceanBase Database. The value must be the same as that of the ocp_agent_monitor_password parameter in OceanBase Database.
   sql_port	No	2881	The SQL port of the OBServer node. The value must be the same as that of the mysql_port parameter in OceanBase Database.
   rpc_port	No	2882	The RPC port of the OBServer node. The value must be the same as that of the rpc_port parameter in OceanBase Database.
   cluster_name	No	obcluster	The name of the OceanBase cluster. The value must be the same as that of the appname parameter in the oceanbase-ce component.
   cluster_id	No	1	The ID of the OceanBase cluster. The value must be the same as that of the cluster_id parameter in the oceanbase-ce component.
   ob_log_path	No	None	The log disk path of the OBServer node. The value must be the same as that of the redo_dir parameter in the oceanbase-ce component.
   ob_data_path	No	None	The data disk path of the OBServer node. The value must be the same as that of the data_dir parameter in the oceanbase-ce component.
   ob_install_path	No	None	The installation directory of the OBServer node. The value must be the same as that of the home_path parameter in the oceanbase-ce component.
   observer_log_path	No	None	The log path in the installation directory of the OBServer node. The value must be the same as that of the {home_path}/log parameter in the oceanbase-ce component.
   ob_monitor_status	Yes	active	The metric collection status of OceanBase Database. The value active indicates that metric collection is enabled. The value inactive indicates that metric collection is disabled.
   zone_name	No	zone1	The name of the zone to which the OBServer node belongs.

3. Configure OCP Express.

   ocp-express:
     depends:
       - obagent
     servers:
       - name: server1
         ip: 10.10.10.4
     global:
       # The working directory for ocp-express. ocp-express is started under this directory. This is a required field.
       home_path: /home/admin/ocp-server
       log_dir: /home/admin/ocp-server/log # The log directory of ocp express server. The default value is {home_path}/log.
       memory_size: 1G # The memory size of ocp-express server. The recommend value is 512MB + (expect node num + expect tenant num) * 60MB.
       jdbc_url: jdbc:oceanbase://IP:PORT/meta_db # jdbc connection string to connect to the meta db
       jdbc_username: user_name@tenant_name # username to connect to meta db
       jdbc_password: '<meta db password>' # password to connect to meta db
       port: 8180 # The http port to use.
       cluster_name: obcluster # the cluster name of oceanbase cluster. Refer to the configuration item appname of oceanbase
       ob_cluster_id: 1 # the cluster id of oceanbase cluster. Refer to the configuration item cluster_id of oceanbase
       root_sys_password: <password for root@sys>
       logging_file_total_size_cap: 10GB # The total log file size of ocp-express server.
       server_addresses: # The cluster info for oceanbase cluster
       - address: 127.0.0.1 # The address of oceanbase server
         svrPort: 2882 # The rpc port of oceanbase server
         sqlPort: 2881 # The mysql port of oceanbase server
   

   Parameter	Required?	Description
   home_path	Yes	The working directory of OCP Express. OCP Express boots from this directory.
   log_dir	No	The log directory of OCP Express. The default value is the log directory in the path specified by the home_path parameter.
   memory_size	Yes	The memory capacity of the OCP Express server. The recommended calculation formula is as follows: memory_size = 512 MB + (Expected number of nodes × Expected number of tenants) × 60 MB. The expected number of tenants should include the sys tenant and the OCP meta tenant.
   jdbc_url	Yes	The JDBC connection string for connecting to the meta tenant. Make sure that the database used in the connection string has been created.
   jdbc_username	Yes	The username for connecting to the meta tenant. Make sure that this user has been created. Note The username format here is user_name@tenant_name. If user_name is specified and tenant_name is omitted, user_name@sys will be used for the connection by default. The sys tenant cannot be used as a meta tenant.
   jdbc_password	Yes	The user password for connecting to the meta tenant.
   port	No	The HTTP port for accessing OCP Express.
   cluster_name	Yes	The name of the OceanBase cluster, which must be the same as the value of the appname parameter in the oceanbase-ce component.
   ob_cluster_id	Yes	The ID of the OceanBase cluster, which must be the same as the value of the cluster_id parameter in the oceanbase-ce component.
   root_sys_password	Yes	The password of the root@sys user in the OceanBase cluster.
   logging_file_total_size_cap	Yes	The total size of log files. The default value is 1 GB. Notice: The unit of this parameter must be GB or MB. If you use the unit G or M, an error will occur, and OCP Express deployment will not be successful.
   server_addresses->address	Yes	The IP address of the OBServer node.
   server_addresses->svrPort	Yes	The RPC port of the OBServer node, which must be the same as the value of the rpc_port parameter of the corresponding node in the oceanbase-ce component.
   server_addresses->sqlPort	Yes	The MySQL port of the OBServer node, which must be the same as the value of the mysql_port parameter of the corresponding node in the oceanbase-ce component.

Step 3: Deploy OCP Express

After you modify the configuration file, run the following commands to deploy and start OCP Express:

# Deploy the cluster
obd cluster deploy <deploy name> -c config.yaml
# Start the cluster
obd cluster start <deploy name>

After the cluster is started, you can use the login address, username, and password of the ocp-express server provided in the command output to log in to OCP Express and start using it.