Using Multi-tenancy for Resource Isolation

When creating a tenant, you need to bind it to a resource configuration to restrict vCPUs used by users under the tenant. This function is only available to user root.

When a tenant is created, the system checks resource constraints to ensure that the sum of the MIN_CPU values in the resource configurations of all tenants meets the resource constraints.

Resources between tenants are fully utilized. For example, there is an instance with 8 vCPUs. The MIN_CPU and MAX_CPU allocated to tenant A are 3 vCPUs and 8 vCPUs, respectively. The MIN_CPU and MAX_CPU allocated to tenant B are 5 vCPUs and 8 vCPUs, respectively. If tenant A uses 0 vCPUs, tenant B can use 8 vCPUs. If tenant A uses 1 vCPU, tenant B can use 7 vCPUs.

CREATE TENANT tenant_name RESOURCE_CONFIG config_name [COMMENT [=] 'comment_string'];

• The value of tenant_name can contain up to 10 characters. Only lowercase letters, digits, and underscores (_) are allowed.
• If a tenant is bound to shared_tenants_config, the tenant is a shared tenant. Otherwise, the tenant is a dedicated tenant. During resource contention, resources are first allocated to dedicated tenants based on the value of MIN_CPU. Any remaining resources are then contested by both shared and dedicated tenants.

ALTER TENANT tenant_name RESOURCE_CONFIG config_name [COMMENT [=] 'comment_string'];

• If the MIN_CPU value of the newly bound resource configuration is at least that of the original resource configuration, the system checks the resource constraints. Ensure that the sum of the MIN_CPU values in the resource configurations of all tenants meets the resource constraints.
• If a dedicated tenant is bound to shared_tenants_config, the tenant becomes a shared tenant and any user-level resource isolation configurations under the tenant are deleted.

DROP TENANT tenant_name;

• Before dropping a tenant, you need to ensure that the databases and users of the tenant have been dropped, or the tenant cannot be dropped.
• When a tenant is dropped, user-level resource isolation configurations associated with the tenant are also dropped.

• If the kernel version of your TaurusDB instance is 2.0.60.241200 or later, run:

  SELECT * FROM information_schema.MT_TENANT;

• If the kernel version of your TaurusDB instance is earlier than 2.0.60.241200, run:

  SELECT * FROM information_schema.DBA_RSRC_TENANT;

• Creating a database
  • Create a database for a system tenant.

    CREATE DATABASE [IF NOT EXISTS] `db_name`;

  • Create a database for a common tenant.

    CREATE DATABASE [IF NOT EXISTS] `db_name@tenant_name`; 

• Dropping a database
  • Drop a database of a system tenant.

    DROP DATABASE [IF EXISTS] `db_name`;

  • Drop a database of a common tenant.

    DROP DATABASE [IF EXISTS] `db_name@tenant_name`;

• Create a database for the current tenant.

  CREATE DATABASE [IF NOT EXISTS] 'db_name'; 

• Drop a database of the current tenant.

  DROP DATABASE [IF EXISTS] 'db_name';

To ensure compatibility after an upgrade or migration to an instance with multi-tenancy enabled, existing databases are under system tenants by default. You can allocate the existing databases to specified tenants. Additionally, after multi-tenancy is enabled, you can allocate databases that are created by system tenants and are not allocated to common tenants to specified tenants.

This function is only available to user root.

• Allocating a database
  • Allocate a database to common tenant tenant_name.

    ALTER DATABASE db_name TENANT = `tenant_name`;

  • Allocate a database back to a system tenant.

    ALTER DATABASE db_name TENANT = ``;

• Querying the mappings
  • If the kernel version of your TaurusDB instance is 2.0.60.241200 or later, run:

    SELECT * FROM information_schema.MT_TENANT_DB

  • If the kernel version of your TaurusDB instance is earlier than 2.0.60.241200, run:

    SELECT * FROM information_schema.DBA_RSRC_TENANT_DB;

• If a database is created after multi-tenancy is enabled and named in the format of db_name@tenant_name, it cannot be allocated using the database allocation statements. Otherwise, an error will be returned.
• If you specify a non-existent tenant in the statements, an error will be returned.

• Creating a tablespace
  • Create a tablespace for a system tenant.

    CREATE TABLESPACE `tablespace_name`;

    CREATE TABLESPACE `tablespace_name` add datafile `tablespace_file_name.ibd`;

  • Create a tablespace for a common tenant.

    CREATE TABLESPACE `tablespace_name@tenant_name`;

    CREATE TABLESPACE `tablespace_name@tenant_name` add datafile `tablespace_file_name.ibd`;

• Dropping a tablespace
  • Drop a tablespace of a system tenant.

    DROP TABLESPACE `tablespace_name`;

  • Drop a tablespace of a common tenant.

    DROP TABLESPACE `tablespace_name@tenant_name`;

• Renaming a tablespace
  • Rename a tablespace of a system tenant.

    ALTER TABLESPACE `tablespace_name` RENAME TO `tablespace_name`;

  • Rename a tablespace of a common tenant.

    ALTER TABLESPACE ` tablespace_name@tenant_name ` RENAME TO `new_tablespace_name@tenant_name`;

• Associating a table with a tablespace
  • Create a table for a system tenant and associate it with a specified tablespace.

    CREATE TABLE table_name ... TABLESPACE [=] `tablespace_name`;

  • Create a table for a common tenant and associate it with a specified tablespace.

    CREATE TABLE table_name ... TABLESPACE [=] `tablespace_name@tenant_name`;

  • Associate an existing table of a system tenant with a specified tablespace.

    ALTER TABLE table_name TABLESPACE `tablespace_name`;

  • Associate an existing table of a common tenant with a specified tablespace.

    ALTER TABLE table_name TABLESPACE `tablespace_name@tenant_name`;

If you plan to associate a common tenant's table with a common tenant's tablespace as a system tenant, the table and tablespace must belong to the same tenant.

• Creating a tablespace for the current tenant

  If a tenant attempts to create a tablespace with the same datafile name as one created by themselves or another tenant, the tablespace will fail to be created.

  CREATE TABLESPACE tablespace_name;

  After multi-tenancy is enabled, the maximum length of a tablespace name allowed is reduced from 64 characters to 50 characters, and the tablespace name cannot contain any at signs (@).

  Special tablespaces, for example, tablespaces starting with innodb_, cannot be created.

• Dropping a tablespace of the current tenant

  DROP TABLESPACE tablespace_name;

• Renaming a tablespace of the current tenant

  ALTER TABLESPACE old_tablespace_name RENAME TO new_tablespace_name ;

• Creating a table for the current tenant and associating it with a specified tablespace

  CREATE TABLE table_name … TABLESPACE [=] tablespace_name;

• Associating an existing table of the current tenant with a specified tablespace

  ALTER TABLE table_name TABLESPACE tablespace_name;

  If you plan to associate a common tenant's table with a tablespace starting with innodb_ (a system tablespace) as a system tenant, you can omit @tenant_name after tablespace_name in the command.

• Creating a user
  • Create a user for a system tenant.

    CREATE user [IF NOT EXISTS] user_name@'host' IDENTIFIED BY 'password';

  • Create a user for a common tenant.

    CREATE user [IF NOT EXISTS] 'user_name@tenant_name'@'host' IDENTIFIED BY 'password'; 

• Renaming a user
  • Rename a user under a system tenant.

    RENAME USER user_from@host1 TO user_to@'host'; 

  • Rename a user under a common tenant.

    RENAME USER 'user_from@tenant_name'@host1 TO 'user_to@tenant_name'@'host'; 

• Dropping a user
  • Drop a user under a system tenant.

    DROP USER [IF EXISTS] user_name@'host'; 

  • Drop a user under a common tenant.

    DROP USER [IF EXISTS] 'user_name@tenant_name'@'host';

• Authorizing a user
  • Grant the priv_type permissions of tenant_1 to 'user_1@tenant_1'@'%'.

    GRANT priv_type ON *.* to 'user_1@tenant_1'@'%' with grant option;

  • Check permissions.

    SHOW grants for 'user_1@tenant_1'@'%';

• Creating a user

  Create a user for the current tenant.

  CREATE user [IF NOT EXISTS] user_name@'host' IDENTIFIED BY 'password'; 

• Renaming a user

  RENAME USER user_from@host1 TO user_to@'host';

• Dropping a user

  DROP USER [IF EXISTS] user_name@'host';

• Authorizing a user
  • Grant the priv_type permissions of the current tenant to user1.

    GRANT priv_type ON *.* to 'user_1'@'%' with grant option;

  • Check permissions.

    SHOW grants for 'user_1';

Multiple users can belong to a given resource consumer group and they share the resources associated with the resource consumer group. Users under a tenant can connect to a database to manage resource consumer groups.

• Creating a consumer group

  dbms_resource_manager.create_consumer_group (
     consumer_group     CHAR(128),
     comment            CHAR(2000));

  Parameter description:

  • consumer_group: name of the resource consumer group. Only uppercase letters, lowercase letters, digits, and underscores (_) are allowed.
  • comment: description of the resource consumer group. The value can be ''.
• Adding a user to a resource consumer group/Removing a user from a resource consumer group

  dbms_resource_manager.set_consumer_group_mapping ( 
     attribute        CHAR(128),  
     value            varbinary(128),  
     consumer_group   CHAR(128));

  Parameter description:

  • attribute: mapping attribute to be added or modified. The current version supports only USER.
  • value: mapping attribute to be added or modified. The current version supports only usernames.
  • consumer_group: name of the resource consumer group. If this parameter is not empty, users are added to the resource consumer group. If this parameter is empty (''), users are removed from the resource consumer group.
• Deleting a consumer group

  dbms_resource_manager.delete_consumer_group (
      consumer_group   CHAR(128));

  Parameter description:

  consumer_group: name of the resource consumer group.

  • When a resource consumer group is deleted, the resource plan directive and resource consumer group mapping corresponding to the resource consumer group are also deleted.
  • If multi-tenancy is enabled, deleted users will be automatically removed from their associated resource consumer groups. If multi-tenancy is disabled, deleted users will remain in their associated resource consumer groups. However, if multi-tenancy is later enabled, the system will remove these deleted users from their resource consumer groups.
  • If multi-tenancy is enabled, the mapping between a user and a resource consumer group is not affected when the user is renamed. If you delete a user and create a user with the same name after multi-tenancy is disabled, the user still belongs to the original resource consumer group after the multi-tenancy is enabled.
• Viewing resource consumer groups

  The DBA_RSRC_CONSUMER_GROUPS view records information about resource consumer groups. If you are under a system tenant, you can view the resource consumer groups of all tenants. If you are under a common tenant, you can only view the resource consumer groups of the current tenant.

  • If the kernel version of your TaurusDB instance is 2.0.60.241200 or later, run:

    SELECT * FROM information_schema.MT_CONSUMER_GROUP;

  • If the kernel version of your TaurusDB instance is earlier than 2.0.60.241200, run:

    SELECT * FROM information_schema.DBA_RSRC_CONSUMER_GROUPS;

• Viewing the mappings between users and resource consumer groups

  The DBA_RSRC_GROUP_MAPPINGS view records the mappings between users and resource consumer groups. If you are under a system tenant, you can view the mappings between users and resource consumer groups of all tenants. If you are under a common tenant, you can only view the mappings between users and resource consumer groups of the current tenant.

  • If the kernel version of your TaurusDB instance is 2.0.60.241200 or later, run:

    SELECT * FROM information_schema.MT_GROUP_MAPPING_RULE;

  • If the kernel version of your TaurusDB instance is earlier than 2.0.60.241200, run:

    SELECT * FROM information_schema.DBA_RSRC_GROUP_MAPPINGS;

A resource plan is used to enable or disable resource plan directives. Each resource plan is associated with one or more resource plan directives. Enabling or disabling a resource plan will activate or deactivate the resource plan directives. Only one resource plan can be enabled per tenant.

• Creating a resource plan

  dbms_resource_manager.create_plan (
     plan_name         VARCHAR(128), 
     comment           VARCHAR(2000));

  • If you delete an enabled resource plan, the resource plan configuration will be cleared and any associated resource plan directives will also be deleted.
  • mt_resource_plan_num: number of plans. By default, there are up to 128 plans.

  Parameter description:

  • plan_name: resource plan name. Only uppercase letters, lowercase letters, digits, and underscores (_) are allowed.
  • comment: description of the resource plan. The value can be ''.

• Enabling or disabling a resource plan

  dbms_resource_manager.set_resource_manager_plan( 
      plan_name     VARCHAR(128));

  Parameter description:

  plan_name: resource plan name. If the value is empty (''), the resource plan is disabled.

• Deleting a resource plan

  dbms_resource_manager.delete_plan (
      plan_name    VARCHAR(128));

  If you delete an enabled resource plan, the resource plan configuration will be cleared and any associated resource plan directives will also be deleted.

  Parameter description:

  plan_name: resource plan name.

• Querying a resource plan

  The DBA_RSRC_PLANS view records details about resource plans. If you are under a system tenant, you can view the resource plans of all tenants. If you are under a common tenant, you can only view the resource plans of the current tenant.

  • If the kernel version of your TaurusDB instance is 2.0.60.241200 or later, run:

    SELECT * FROM information_schema.MT_RESOURCE_PLAN;

  • If the kernel version of your TaurusDB instance is earlier than 2.0.60.241200, run:

    SELECT * FROM information_schema.DBA_RSRC_PLANS;

A resource plan directive corresponds to only one resource consumer group and describes the specific resource configuration of the resource consumer group. A resource consumer group can be associated with multiple resource plan directives, but only one can be enabled at a time. As mentioned earlier, you can enable a resource plan directive by enabling a resource plan.

• Updating a resource plan directive

  dbms_resource_manager.update_plan_directive (
     plan                    CHAR(128), 
     group_or_subplan        CHAR(128), 
     new_comment             VARCHAR(2000), 
     new_mgmt_p1             bigint(20),
     new_utilization_limit   bigint(20));

  Users in a resource consumer group share the resources configured by the enabled resource plan directive. For example, if user1 and user2 of a tenant are added to consumer_group1, the utilization_limit value of the enabled resource plan directive for consumer_group1 is 70, and the mgmt_p1 value is 10, then user1 and user2 can use up to 70% vCPUs of the tenant. During vCPU contention, the total vCPUs that are committed to user1 and user2 are 10% vCPUs of the tenant.

  Table 3 Parameter description

  Parameter	Description
  plan	Name of the resource plan.
  group_or_subplan	Name of the resource consumer group.
  comment	Description of the resource plan directive. The value can be ''.
  mgmt_p1	Percentage of total vCPUs of a tenant that is vCPUs committed to the resource consumer group in the case of vCPU contention. The value range is [0, 100] (100: 100% vCPUs of the tenant are used). The sum of mgmt_p1 of all resource plan directives associated with a resource plan of a tenant cannot exceed 100. In the event of vCPU contention among resource consumer groups of a tenant, the vCPUs committed to each resource consumer group are preferentially allocated based on an on-demand allocation policy, and the remaining vCPUs are contested by each resource consumer group. For example, if 20% of vCPUs are committed to a resource consumer group but only 5% of vCPUs are required due to small workloads, the remaining 15% of vCPUs will be allocated to other resource consumer groups as needed.
  utilization_limit	Upper limit on vCPU utilization for a resource consumer group. The value range is [1, 100]. The value 100 indicates that a group can use all vCPUs of the tenant. The value 70 indicates that it can only use 70% vCPUs of the tenant.

• Deleting a resource plan directive

  If you delete a resource plan directive that has been enabled, the resource configuration of the corresponding user will become invalid.

  dbms_resource_manager.delete_plan_directive (
      plan                   CHAR(128), 
      group_or_subplan       VARCHAR(128));

  Table 4 Parameter description

  Parameter	Description
  plan	Name of the resource plan.
  group_or_subplan	Name of the resource consumer group.

• Querying a resource plan directive

  The DBA_RSRC_PLAN_DIRECTIVES view records details about resource plan directives. If you are under a system tenant, you can view the resource plan directives of all tenants. If you are under a common tenant, you can only view the resource plan directives of the current tenant.

  • If the kernel version of your TaurusDB instance is 2.0.60.241200 or later, run:

    SELECT * FROM information_schema.MT_PLAN_DIRECTIVE;

  • If the kernel version of your TaurusDB instance is earlier than 2.0.60.241200, run:

    SELECT * FROM information_schema.DBA_RSRC_PLAN_DIRECTIVES;

You can clear all user-level resource configurations of a tenant, including resource consumer groups, resource plans, and resource plan directives. If you execute this statement under a system tenant, only the user-level resource configurations of the system tenant are cleared.

dbms_resource_manager.clear_all_configs();