[Yandex Cloud documentation](../../index.md) > [Yandex Managed Service for MySQL®](../index.md) > [Step-by-step guides](index.md) > Clusters > Creating a cluster # Creating a MySQL® cluster A MySQL® cluster consists of one or more database hosts. In multi-host clusters, [semi-synchronous replication](../concepts/replication.md) is configured automatically. For more information on the Managed Service for MySQL® cluster structure, see [Resource relationships](../concepts/index.md). {% note info %} * The number of hosts you can create together with a MySQL® cluster depends on the selected [disk type](../concepts/storage.md#storage-type-selection) and [host class](../concepts/instance-types.md#available-flavors). * The available disk types [depend](../concepts/storage.md) on the selected [host class](../concepts/instance-types.md#available-flavors). {% endnote %} ## Creating a cluster {#create-cluster} To create a Managed Service for MySQL® cluster, you need the [vpc.user](../../vpc/security/index.md#vpc-user) role along with the [managed-mysql.editor role or higher](../security/index.md#roles-list). For more information on assigning roles, see [this Identity and Access Management guide](../../iam/operations/roles/grant.md). Cluster DB connections are managed by Connection Manager. Creating a cluster automatically creates: * [Connection Manager connection](../../metadata-hub/concepts/connection-manager.md) with information about the database connection. * [Yandex Lockbox secret](../../metadata-hub/concepts/secret.md) that stores the DB owner's user password. Storing passwords in Yandex Lockbox ensures their security. The connection and secret will be created for each new database user. To view all connections, select the **Connections** tab on the cluster page. You need the `connection-manager.viewer` role to view connection info. You can [use Connection Manager](../../metadata-hub/operations/connection-access.md) to configure access to connections. You can use Connection Manager and secrets you create there free of charge. {% list tabs group=instructions %} - Management console {#console} To create a Managed Service for MySQL® cluster: 1. In the [management console](https://console.yandex.cloud), select the [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) where you want to create your database cluster. 1. Navigate to **Managed Service for MySQL**. 1. Click **Create cluster**. 1. Enter a name for the Managed Service for MySQL® cluster in the **Cluster name** field. The cluster name must be unique within the folder. 1. Select the environment where you want to create your Managed Service for MySQL® cluster (you cannot change the environment once the cluster is created): * `PRODUCTION`: For stable versions of your applications. * `PRESTABLE`: For testing purposes. The prestable environment is similar to the production environment and likewise covered by an SLA, but it is the first to get new features, improvements, and bug fixes. In the prestable environment, you can test new versions for compatibility with your application. 1. Select the DBMS version. 1. Select the host class, which will determine the technical specifications of the [VMs](../../compute/concepts/vm-platforms.md) for deploying your database hosts. All available options are listed under [Host classes](../concepts/instance-types.md). Changing the host class of a Managed Service for MySQL® cluster updates the specifications for all of its existing hosts. 1. Under **Storage size**: * Select the [disk type](../concepts/storage.md). The type you select determines the increments for changing the disk size: * Network HDDs and SSDs: In increments of 1 GB. * Local SSDs: * For **Intel Broadwell** and **Intel Cascade Lake**: In 100 GB increments. * For **Intel Ice Lake** and **AMD Zen 4**: In 368 GB increments. * Non-replicated SSDs and ultra high-speed network SSDs with three replicas: In increments of 93 GB. * Select the storage size for data and backups. For more information on how backups take up storage space, see [Backups](../concepts/backup.md). {% note info %} If the database storage reaches 95% capacity, the Managed Service for MySQL® cluster will switch to read-only mode. Make sure to expand the storage in advance. {% endnote %} * Optionally, select **Encrypted disk** to encrypt the disk with a [custom KMS key](../../kms/concepts/key.md). * To [create](../../kms/operations/key.md#create) a new key, click **Create**. * To use a previously created key, select it in the **KMS key** field. To learn more about disk encryption, see [Storage](../concepts/storage.md#disk-encryption). 1. Optionally, under **Automatic increase of storage size**: * Select **In the maintenance window when full at more than** and specify the **of the current size is full** percentage at which the storage will be expanded in the next [maintenance window](../concepts/maintenance.md#maintenance-window). * Select **Immediately when full at more than** and specify the **of the current size is full** percentage at which the storage will be expanded immediately. * In the **Maximum storage size** field, specify the maximum storage size that can be set during autoscaling. {% note warning %} * Automatic storage expansion is not supported on dedicated hosts. * If you have configured storage scaling during a maintenance window, set the [maintenance window](../concepts/maintenance.md#maintenance-window) schedule. {% endnote %} Learn more about storage autoscaling [here](../concepts/storage.md#disk-size-autoscaling). 1. Under **Database**, specify the database details: * Database name. The name must be unique within the folder. The database name may contain Latin letters, numbers, hyphens, and underscores. It may be up to 63 characters long. Such names as `mysql`, `sys`, `information_schema`, and `performance_schema` are reserved for internal use by Managed Service for MySQL®. You cannot create databases with these names. * Database owner username. The username may contain Latin letters, numbers, hyphens, and underscores, and must start with a letter, number, or underscore. It must be from 1 to 32 characters long. * User password: * **Enter manually**: Select this option to set your own password. It must be from 8 to 128 characters long. * **Generate**: Select this option to generate a password using Connection Manager. To view the password after creating a cluster, select the **Users** tab and click **View password** for the relevant user. This will open the page of the Yandex Lockbox secret containing the password. To view passwords, you need the `lockbox.payloadViewer` role. 1. Under **Network settings**, select: * [Cloud network](../../vpc/concepts/network.md#network) for the cluster. * [Security groups](../../vpc/concepts/security-groups.md) for the cluster network traffic. You may also need to [configure security groups](connect/index.md#configure-security-groups) to connect to the Managed Service for MySQL® cluster. 1. Under **Hosts**, click ![image](../../_assets/console-icons/pencil.svg) and specify the settings for the database hosts created together with the Managed Service for MySQL® cluster: * Availability zone. * Host [subnet](../../vpc/concepts/network.md#subnet): By default, each host is created in a separate subnet. * **Public access** to make the host accessible from outside Yandex Cloud, if required. * [Host priority for promotion to master](../concepts/replication.md#master-failover). * [Host priority as a MySQL® replica](../concepts/backup.md#size) for creating backups. The minimum number of hosts per cluster depends on the selected [disk type](../concepts/storage.md). The default cluster configuration offered in the management console includes: * Two hosts if the selected disk type is `network-ssd`, `network-hdd`, or `network-ssd-io-m3`. * Three hosts if the selected disk type is `local-ssd` or `network-ssd-nonreplicated`. {% note warning %} We do not recommend creating a single-host cluster. While being cheaper, it will not ensure [high availability](../concepts/high-availability.md#host-configuration). {% endnote %} After creating a Managed Service for MySQL® cluster, you can add more hosts to it if your [folder resource](../concepts/limits.md) quotas allow. 1. Specify additional Managed Service for MySQL® cluster settings, if required: - **Backup start time (UTC)**: Time interval during which the cluster backup starts. Time is specified in 24-hour UTC format. The default time is `22:00 - 23:00` UTC. - **Retention period for automatic backups, days** Automatic backups will be stored for this many days. - **Maintenance**: [Maintenance window](../concepts/maintenance.md) settings: * To enable maintenance at any time, select **At any time** (default). * To specify the preferred maintenance start time, select **By schedule** and specify the day of the week and the UTC time interval. For example, you can choose a time when the cluster is least loaded. Both active and stopped clusters are subject to maintenance. Maintenance operations include DBMS updates, patches, etc. - **DataLens access**: Enables you to analyze cluster data in [Yandex DataLens](../../datalens/concepts/index.md). For more information about setting up a connection, see [Connecting to DataLens](datalens-connect.md). - **WebSQL access**: Enables [SQL queries](web-sql-query.md) against cluster databases from the Yandex Cloud management console using Yandex WebSQL. - **Yandex Query access**: Enables YQL queries against cluster databases from [Yandex Query](../../query/concepts/index.md). This feature is at the [Preview](../../overview/concepts/launch-stages.md) stage. The default value is `false`. - **Statistics sampling**: Enable this option to use the [Performance diagnostics](performance-diagnostics.md) tool in the cluster. - **Deletion protection**: Manages cluster protection against accidental deletion. Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents. 1. Configure the [cluster-level DBMS settings](../concepts/settings-list.md#dbms-cluster-settings), if required. {% note info %} Some MySQL® settings [depend on the selected host class](../concepts/settings-list.md#settings-instance-dependent). {% endnote %} 1. Click **Create cluster**. - CLI {#cli} If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install). The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id ` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions. To create a Managed Service for MySQL® cluster: 1. Check whether the folder has any [subnets](../../vpc/concepts/network.md#subnet) for Managed Service for MySQL® cluster hosts: ```bash yc vpc subnet list ``` If there are no subnets in the folder, [create them](../../vpc/operations/subnet-create.md) in [Yandex Virtual Private Cloud](../../vpc/index.md). 1. View the description of the CLI command to create a Managed Service for MySQL® cluster: ```bash yc managed-mysql cluster create --help ``` 1. Specify the Managed Service for MySQL® cluster parameters in the command: ```bash yc managed-mysql cluster create \ --name= \ --environment \ --network-name \ --host zone-id=,` `subnet-id=,` `assign-public-ip=,` `priority=,` `backup-priority= \ --mysql-version \ --resource-preset \ --user name=,password= \ --database name= \ --disk-size \ --disk-type \ --security-group-ids ``` You need to specify the `subnet-id` if the selected [availability zone](../../overview/concepts/geo-scope.md) has two or more subnets. Where: * `--environment`: Environment, `prestable` or `production`. * `--assign-public-ip`: Public access to the host, `true` or `false`. * `--disk-type`: [Disk type](../concepts/storage.md). * `--priority`: Host priority when selecting a new master host, between `0` and `100`. * `--backup-priority`: Backup priority, between `0` and `100`. * `--mysql-version`: MySQL® version, `5.7 or 8.0`. * `--user`: Contains the MySQL® user `name` and `password`. The username may contain Latin letters, numbers, hyphens, and underscores, and must start with a letter, number, or underscore. It must be from 1 to 32 characters long. The password must be from 8 to 128 characters long. {% note info %} You can also generate a password using Connection Manager. To do this, edit the command, specifying the user properties as follows: ```bash --user name=,generate-password=true ``` To view the password, select your cluster in the [management console](https://console.yandex.cloud), navigate to the **Users** tab, and click **View password** for the relevant user. This will open the page of the Yandex Lockbox secret containing the password. To view passwords, you need the `lockbox.payloadViewer` role. {% endnote %} * `--database name`: Database name. The database name may contain Latin letters, numbers, hyphens, and underscores. It may be up to 63 characters long. Such names as `mysql`, `sys`, `information_schema`, and `performance_schema` are reserved for internal use by Managed Service for MySQL®. You cannot create databases with these names. Specify additional Managed Service for MySQL® cluster settings, if required: ```bash yc managed-mysql cluster create \ ... --backup-window-start \ --backup-retain-period-days= \ --disk-encryption-key-id \ --datalens-access= \ --websql-access= \ --yandexquery-access= \ --deletion-protection \ --performance-diagnostics enabled=true,` `sessions-sampling-interval=,` `statements-sampling-interval= --disk-size-autoscaling disk-size-limit=,` `planned-usage-threshold=,` `emergency-usage-threshold= \ --maintenance-window type=,` `day=,` `hour= ``` Where: * `--backup-window-start`: Backup start time. * `--backup-retain-period-days`: Automatic backup retention period, in days. * `--disk-encryption-key-id`: Disk encryption using a [custom KMS key](../../kms/concepts/key.md). To learn more about disk encryption, see [Storage](../concepts/storage.md#disk-encryption). * `--datalens-access`: Enables access to the cluster from Yandex DataLens. The default value is `false`. For more information about setting up a connection, see [Connecting to a MySQL® cluster from DataLens](datalens-connect.md). * `--websql-access`: Enables [SQL queries](web-sql-query.md) against cluster databases from the Yandex Cloud management console using Yandex WebSQL. The default value is `false`. * `--yandexquery-access`: Enables YQL queries against cluster databases from [Yandex Query](../../query/concepts/index.md). This feature is at the [Preview](../../overview/concepts/launch-stages.md) stage. The default value is `false`. * `--deletion-protection`: Cluster protection from accidental deletion, `true` or `false`. Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents. * `--performance-diagnostics`: Enables statistics collection for [cluster performance diagnostics](performance-diagnostics.md). For `sessions-sampling-interval` and `statements-sampling-interval`, the valid values range from `1` to `86400` seconds. * `--disk-size-autoscaling`: [Storage autoscaling](../concepts/storage.md#disk-size-autoscaling) settings: * `planned-usage-threshold`: Storage usage percentage threshold triggering a storage expansion during the next maintenance window. This is an optional setting. The default value is `0` (automatic expansion disabled). The valid values range from `0` to `100`. * `emergency-usage-threshold`: Storage usage percentage threshold triggering an immediate storage expansion. This is an optional setting. The default value is `0` (automatic expansion disabled). The valid values range from `0` to `100`. * `disk-size-limit`: Maximum storage capacity after expansion, in GB. {% note warning %} * Automatic storage expansion is not supported on dedicated hosts. * When using `planned-usage-threshold`, make sure to set the `--maintenance-window`. * If you specify both thresholds, `emergency-usage-threshold` must be greater than `planned-usage-threshold`. {% endnote %} * `--maintenance-window`: [Maintenance window](../concepts/maintenance.md) settings that apply to both running and stopped clusters. The `type` setting defines the maintenance type: * `anytime`: Any time (default). * `weekly`: On a schedule. For this value, also specify the following: * `day`: Day of week, i.e., `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, or `SUN`. * `hour`: Sequence number of UTC hour interval, from `1` to `24`. > For example, `1` stands for the interval from `00:00` to `01:00`, and `5`, from `04:00` to `05:00`. [Configure the DBMS](../concepts/settings-list.md#dbms-cluster-settings), if required. - Terraform {#tf} With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed. Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license. For more information about the provider resources, see the guides on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../terraform/index.md). If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform). To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../terraform/authentication.md) using the appropriate method. To create a Managed Service for MySQL® cluster: 1. In the configuration file, describe the resources you want to create: * Database cluster: Description of the cluster and its hosts. * Database: Cluster database description. The database name may contain Latin letters, numbers, hyphens, and underscores. It may be up to 63 characters long. Such names as `mysql`, `sys`, `information_schema`, and `performance_schema` are reserved for internal use by Managed Service for MySQL®. You cannot create databases with these names. * User: Cluster user description. * Network: Description of the [cloud network](../../vpc/concepts/network.md#network) where a cluster will be located. If you already have a suitable network, you don't have to describe it again. * Subnets: Description of the [subnets](../../vpc/concepts/network.md#subnet) to connect the cluster hosts to. If you already have suitable subnets, you don't have to describe them again. Here is an example of the configuration file structure: ```hcl resource "yandex_mdb_mysql_cluster" "" { name = "" environment = "" network_id = "" version = "" security_group_ids = [ "" ] deletion_protection = resources { resource_preset_id = "" disk_type_id = "" disk_size = "" } host { zone = "" subnet_id = "" assign_public_ip = priority = backup_priority = } } resource "yandex_mdb_mysql_database" "" { cluster_id = "" name = "" } resource "yandex_mdb_mysql_user" "" { cluster_id = "" name = "" password = "" permission { database_name = "" roles = ["ALL"] } } resource "yandex_vpc_network" "" { name = "" } resource "yandex_vpc_subnet" "" { name = "" zone = "" network_id = "" v4_cidr_blocks = [""] } ``` Where: * `environment`: Environment, `PRESTABLE` or `PRODUCTION`. * `version`: MySQL® version, `5.7 or 8.0`. * `deletion_protection`: Cluster protection against accidental deletion, `true` or `false`. Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents. * `assign_public_ip`: Public access to the host, `true` or `false`. * `priority`: Host priority when selecting a new master host, between `0` and `100`. * `backup_priority`: Backup priority, between `0` and `100`. * `name` and `password`: MySQL® username and password, respectively. The username may contain Latin letters, numbers, hyphens, and underscores, and must start with a letter, number, or underscore. It must be from 1 to 32 characters long. The password must be from 8 to 128 characters long. {% note info %} You can also generate a password using Connection Manager. To do this, specify `generate_password = true` instead of `"password" = ""`. To view the password, select your cluster in the [management console](https://console.yandex.cloud), navigate to the **Users** tab, and click **View password** for the relevant user. This will open the page of the Yandex Lockbox secret containing the password. To view passwords, you need the `lockbox.payloadViewer` role. {% endnote %} * To configure [automatic storage expansion](../concepts/storage.md#disk-size-autoscaling), add the `disk_size_autoscaling` section to the cluster description: ```hcl resource "yandex_mdb_mysql_cluster" "" { ... disk_size_autoscaling { disk_size_limit = emergency_usage_threshold = planned_usage_threshold = } ... } ``` Where: * `disk_size_limit`: Maximum storage capacity after expansion, in GB. * `emergency_usage_threshold`: Storage usage percentage threshold triggering an immediate storage expansion. This is an optional setting. The default value is `0` (automatic expansion disabled). The valid values range from `0` to `100`. * `planned_usage_threshold`: Storage usage percentage threshold triggering a storage expansion during the next maintenance window. This is an optional setting. The default value is `0` (automatic expansion disabled). The valid values range from `0` to `100`. {% note warning %} * Automatic storage expansion is not supported on dedicated hosts. * When using `planned_usage_threshold`, make sure to set the `maintenance_window`. * If you specify both thresholds, `emergency_usage_threshold` must be greater than `planned_usage_threshold`. {% endnote %} * To set up the [maintenance window](../concepts/maintenance.md) that will also apply to stopped clusters, add the `maintenance_window` section to the cluster description: ```hcl resource "yandex_mdb_mysql_cluster" "" { ... maintenance_window { type = "" day = "" hour = } ... } ``` Where: * `type`: Maintenance type. The possible values include: * `ANYTIME`: Any time. * `WEEKLY`: On a schedule. * `day`: Day of week for the `WEEKLY` type, i.e., `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, or `SUN`. * `hour`: Sequence number of UTC hour interval for the `WEEKLY` type, from `1` to `24`. > For example, `1` stands for the interval from `00:00` to `01:00`, and `5`, from `04:00` to `05:00`. * To encrypt the disk with a [custom KMS key](../../kms/concepts/key.md), add the `disk_encryption_key_id` parameter: ```hcl resource "yandex_mdb_mysql_cluster" "" { ... disk_encryption_key_id = ... } ``` To learn more about disk encryption, see [Storage](../concepts/storage.md#disk-encryption). * To enable [access from DataLens](datalens-connect.md) and allow [SQL queries from the management console](web-sql-query.md) using Yandex WebSQL, add the `access` section to the cluster description: ```hcl resource "yandex_mdb_mysql_cluster" "" { ... access { data_lens = web_sql = } ... } ``` * To set the [backup](../concepts/backup.md) start time, add the `backup_window_start` section to your Managed Service for MySQL® cluster description: ```hcl resource "yandex_mdb_mysql_cluster" "" { ... backup_window_start { hours = minutes = } ... } ``` Where: * `hours`: Backup start hour. * `minutes`: Backup start minute. * To set the backup retention period, specify the `backup_retain_period_days` parameter in the Managed Service for MySQL® cluster description: ```hcl resource "yandex_mdb_mysql_cluster" "" { ... backup_retain_period_days = ... } ``` Where `backup_retain_period_days` is automatic backup retention period, in days. The valid values range from `7` to `60`. The default value is `7`. * To enable statistics collection for [cluster performance diagnostics](performance-diagnostics.md), add a `performance_diagnostics` section to your Managed Service for MySQL® cluster description: ```hcl resource "yandex_mdb_mysql_cluster" "" { ... performance_diagnostics { enabled = true sessions_sampling_interval = statements_sampling_interval = } ... } ``` For `sessions_sampling_interval` and `statements_sampling_interval`, the valid values range from `1` to `86400` seconds. For more information about the resources you can create with Terraform, see [this provider article](../../terraform/resources/mdb_mysql_cluster.md). 1. Make sure the configuration files are correct. 1. In the command line, go to the folder where you created the configuration file. 1. Run a check using this command: ```bash terraform plan ``` If the configuration is described correctly, the terminal will display a list of created resources and their parameters. If the configuration contains any errors, Terraform will point them out. This is a test step; no resources will be created. 1. Create your Managed Service for MySQL® cluster. 1. If the configuration does not contain any errors, run this command: ```bash terraform apply ``` 1. Confirm that you want to create the resources. After this, all required resources will be created in the specified folder and the IP addresses of the VMs will be displayed in the terminal. You can check the new resources and their configuration using the [management console](https://console.yandex.cloud). {% note warning "Timeouts" %} The Terraform provider sets the following timeouts for Managed Service for MySQL® cluster operations: * Creating a cluster, including by restoring it from a backup: 15 minutes. * Updating a cluster, including the MySQL® version update: 60 minutes. * Deleting a cluster: 15 minutes. Operations exceeding the timeout are aborted. {% cut "How do I change these limits?" %} Add the `timeouts` section to the cluster description, such as the following: ```hcl resource "yandex_mdb_mysql_cluster" "" { ... timeouts { create = "1h30m" # 1 hour 30 minutes update = "2h" # 2 hours delete = "30m" # 30 minutes } } ``` {% endcut %} {% endnote %} - REST API {#api} 1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable: ```bash export IAM_TOKEN="" ``` 1. Create a file named `body.json` and paste the following code into it: ```json { "folderId": "", "name": "", "environment": "", "networkId": "", "securityGroupIds": [ "", "", ... "" ], "deletionProtection": , "configSpec": { "version": "", "resources": { "resourcePresetId": "", "diskSize": "", "diskTypeId": "" }, "access": { "dataLens": , "webSql": , "yandexQuery": }, "performanceDiagnostics": { "enabled": , "sessionsSamplingInterval": "", "statementsSamplingInterval": "" }, "diskSizeAutoscaling": { "plannedUsageThreshold": "", "emergencyUsageThreshold": "", "diskSizeLimit": "" } }, "databaseSpecs": [ { "name": "" }, { }, { ... }, { } ], "userSpecs": [ { "name": "", "password": "", "permissions": [ { "databaseName": "", "roles": [ "", "", ..., "" ] } ] }, { }, { ... }, { } ], "hostSpecs": [ { "zoneId": "", "subnetId": "", "assignPublicIp": }, { }, { ... }, { } ], "maintenanceWindow": { "weeklyMaintenanceWindow": { "day": "", "hour": "" } } } ``` Where: * `folderId`: Folder ID. You can get it from the [list of your cloud folders](../../resource-manager/operations/folder/get-id.md). * `name`: Cluster name. * `environment`: Cluster environment, `PRODUCTION` or `PRESTABLE`. * `networkId`: ID of the [network](../../vpc/concepts/network.md#network) where your cluster will be deployed. * `securityGroupIds`: [Security group](../concepts/network.md#security-groups) IDs. * `deletionProtection`: Cluster protection against accidental deletion, `true` or `false`. Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents. * `configSpec`: Cluster settings: * `version`: MySQL® version. * `resources`: Cluster resources: * `resourcePresetId`: [Host class](../concepts/instance-types.md). * `diskSize`: Disk size, in bytes. * `diskTypeId`: [Disk type](../concepts/storage.md). * `access`: Settings for cluster access from Yandex Cloud services: * `dataLens`: Access from Yandex DataLens. For more information about setting up a connection, see [Connecting to a MySQL® cluster from DataLens](datalens-connect.md). * `webSql`: [SQL queries](web-sql-query.md) against cluster databases from the Yandex Cloud management console using Yandex WebSQL. * `yandexQuery`: YQL queries against cluster databases from [Yandex Query](../../query/concepts/index.md). This feature is currently at the [Preview](../../overview/concepts/launch-stages.md) stage. The possible values are `true` or `false`. * `performanceDiagnostics`: [Statistics collection](performance-diagnostics.md#activate-stats-collector) settings: * `enabled`: Enables statistics collection, `true` or `false`. * `sessionsSamplingInterval`: Session sampling interval, from `1` to `86400` seconds. * `statementsSamplingInterval`: Statement sampling interval, from `1` to `86400` seconds. * `diskSizeAutoscaling`: [Storage autoscaling](../concepts/storage.md#disk-size-autoscaling) settings: * `plannedUsageThreshold`: Storage usage percentage threshold triggering a storage expansion during the next maintenance window. This is an optional setting. The default value is `0` (automatic expansion disabled). The valid values range from `0` to `100`. * `emergencyUsageThreshold`: Storage usage percentage threshold triggering an immediate storage expansion. This is an optional setting. The default value is `0` (automatic expansion disabled). The valid values range from `0` to `100`. * `diskSizeLimit`: Maximum storage capacity after expansion, in bytes. {% note warning %} * Automatic storage expansion is not supported on dedicated hosts. * When using `plannedUsageThreshold`, make sure to set the `maintenanceWindow`. * If you specify both thresholds, `emergencyUsageThreshold` must be greater than `plannedUsageThreshold`. {% endnote %} * `databaseSpecs`: Database settings as an array of elements, one per database. Each element contains a database `name`. The database name may contain Latin letters, numbers, hyphens, and underscores. It may be up to 63 characters long. Such names as `mysql`, `sys`, `information_schema`, and `performance_schema` are reserved for internal use by Managed Service for MySQL®. You cannot create databases with these names. * `userSpecs`: User settings as an array of elements, one per user. Each element has the following structure: * `name`: Username. * `password`: User password. The password must be from 8 to 128 characters long. You can also generate a password using Connection Manager. Do it by specifying `"generatePassword": true` instead of `"password": ""`. To view the password, select your cluster in the [management console](https://console.yandex.cloud), navigate to the **Users** tab, and click **View password** for the relevant user. This will open the page of the Yandex Lockbox secret containing the password. To view passwords, you need the `lockbox.payloadViewer` role. * `permissions`: User permission settings: * `databaseName`: Name of the database to which the user will have access. * `roles`: Array of user privileges, each provided as a separate string in the array. For the list of possible values, see [User privileges in a cluster](../concepts/user-rights.md#db-privileges). For each database, add a separate element with permission settings to the `permissions` array. * `hostSpecs`: Cluster host settings as an array of elements, one per host. Each element has the following structure: * `zoneId`: [Availability zone](../../overview/concepts/geo-scope.md). * `subnetId`: [Subnet](../../vpc/concepts/network.md#subnet) ID. * `assignPublicIp`: Permission to [connect](connect/index.md) to the host from the internet, `true` or `false`. * `maintenanceWindow`: [Maintenance window](../concepts/maintenance.md) settings (including for disabled clusters). Provide one of the following: * `anytime` (default): Maintenance can take place at any time. * `weeklyMaintenanceWindow`: Scheduled maintenance: * `day`: Day of week, in `DDD` format. The valid values are `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, and `SUN`. * `hour`: Hour of day (UTC) in `HH` format. The valid values range from `1` to `24`. 1. Call the [Cluster.create](../api-ref/Cluster/create.md) method, e.g., via the following [cURL](https://curl.se/) request: ```bash curl \ --request POST \ --header "Authorization: Bearer $IAM_TOKEN" \ --header "Content-Type: application/json" \ --url 'https://mdb.api.cloud.yandex.net/managed-mysql/v1/clusters' \ --data "@body.json" ``` 1. Check the [server response](../api-ref/Cluster/create.md#yandex.cloud.operation.Operation) to make sure your request was successful. - gRPC API {#grpc-api} 1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable: ```bash export IAM_TOKEN="" ``` 1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository: ```bash cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi ``` Below, we assume that the repository contents reside in the `~/cloudapi/` directory. 1. Create a file named `body.json` and paste the following code into it: ```json { "folder_id": "", "name": "", "environment": "", "network_id": "", "security_group_ids": [ "", "", ... "" ], "deletion_protection": , "config_spec": { "version": "", "resources": { "resource_preset_id": "", "disk_size": "", "disk_type_id": "" }, "access": { "data_lens": , "web_sql": , "yandex_query": }, "performance_diagnostics": { "enabled": , "sessions_sampling_interval": "", "statements_sampling_interval": "" }, "disk_size_autoscaling": { "planned_usage_threshold": "", "emergency_usage_threshold": "", "disk_size_limit": "" } }, "database_specs": [ { "name": "" }, { }, { ... }, { } ], "user_specs": [ { "name": "", "password": "", "permissions": [ { "database_name": "", "roles": [ "", "", ..., "" ] } ] } ], "host_specs": [ { "zone_id": "", "subnet_id": "", "assign_public_ip": } ], "maintenance_window": { "weekly_maintenance_window": { "day": "", "hour": "" } } } ``` Where: * `folder_id`: Folder ID. You can get it with the [list of folders in the cloud](../../resource-manager/operations/folder/get-id.md). * `name`: Cluster name. * `environment`: Cluster environment, `PRODUCTION` or `PRESTABLE`. * `network_id`: ID of the [network](../../vpc/concepts/network.md#network) where your cluster will be deployed. * `security_group_ids`: [Security group](../concepts/network.md#security-groups) IDs. * `deletion_protection`: Cluster deletion protection, `true` or `false`. Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents. * `config_spec`: Cluster settings: * `version`: MySQL® version. * `resources`: Cluster resources: * `resource_preset_id`: [Host class](../concepts/instance-types.md). * `disk_size`: Disk size, in bytes. * `disk_type_id`: [Disk type](../concepts/storage.md). * `access`: Settings for cluster access from Yandex Cloud services: * `data_lens`: Access from Yandex DataLens. For more information about setting up a connection, see [Connecting to a MySQL® cluster from DataLens](datalens-connect.md). * `web_sql`: [SQL queries](web-sql-query.md) against cluster databases from the Yandex Cloud management console using Yandex WebSQL. * `yandex_query`: YQL queries against cluster databases from [Yandex Query](../../query/concepts/index.md). This feature is currently at the [Preview](../../overview/concepts/launch-stages.md) stage. The possible values are `true` or `false`. * `performance_diagnostics`: [Statistics collection](performance-diagnostics.md#activate-stats-collector) settings: * `enabled`: Enables statistics collection, `true` or `false`. * `sessions_sampling_interval`: Session sampling interval, from `1` to `86400` seconds. * `statements_sampling_interval`: Statement sampling interval, from `60` to `86400` seconds. * `disk_size_autoscaling`: [Storage autoscaling](../concepts/storage.md#disk-size-autoscaling) settings: * `planned_usage_threshold`: Storage usage percentage threshold triggering a storage expansion during the next maintenance window. This is an optional setting. The default value is `0` (automatic expansion disabled). The valid values range from `0` to `100`. * `emergency_usage_threshold`: Storage usage percentage threshold triggering an immediate storage expansion. This is an optional setting. The default value is `0` (automatic expansion disabled). The valid values range from `0` to `100`. * `disk_size_limit`: Maximum storage capacity after expansion, in bytes. {% note warning %} * Automatic storage expansion is not supported on dedicated hosts. * When using `planned_usage_threshold`, make sure to set the `maintenance_window`. * If you specify both thresholds, `emergency_usage_threshold` must be greater than `planned_usage_threshold`. {% endnote %} * `database_specs`: Database settings as an array of elements, one per database. Each element contains a database `name`. * `user_specs`: User settings as an array of elements, one per user. Each element has the following structure: * `name`: Username. * `password`: User password. The password must be from 8 to 128 characters long. You can also generate a password using Connection Manager. Do it by specifying `"generate_password": true` instead of `"password": ""`. To view the password, select your cluster in the [management console](https://console.yandex.cloud), navigate to the **Users** tab, and click **View password** for the relevant user. This will open the page of the Yandex Lockbox secret containing the password. To view passwords, you need the `lockbox.payloadViewer` role. * `permissions`: User permissions: * `database_name`: Name of the database to which the user will have access. * `roles`: Array of user privileges, each provided as a separate string in the array. For the list of possible values, see [User privileges in a cluster](../concepts/user-rights.md#db-privileges). In the `permissions` array, add a separate element with permission settings for each database. * `host_specs`: Cluster host settings as an array of elements, one per host. Each element has the following structure: * `zone_id`: [Availability zone](../../overview/concepts/geo-scope.md). * `subnet_id`: [Subnet](../../vpc/concepts/network.md#subnet) ID. * `assign_public_ip`: Permission to [connect](connect/index.md) to the host from the internet, `true` or `false`. * `maintenance_window`: [Maintenance window](../concepts/maintenance.md) settings (including for disabled clusters). Provide one of the following: * `anytime` (default): Maintenance can take place at any time. * `weekly_maintenance_window`: Scheduled maintenance: * `day`: Day of week, in `DDD` format. The valid values are `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, and `SUN`. * `hour`: Hour of day (UTC) in `HH` format. The valid values range from `1` to `24`. 1. Call the [ClusterService/Create](../api-ref/grpc/Cluster/create.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request: ```bash grpcurl \ -format json \ -import-path ~/cloudapi/ \ -import-path ~/cloudapi/third_party/googleapis/ \ -proto ~/cloudapi/yandex/cloud/mdb/mysql/v1/cluster_service.proto \ -rpc-header "Authorization: Bearer $IAM_TOKEN" \ -d @ \ mdb.api.cloud.yandex.net:443 \ yandex.cloud.mdb.mysql.v1.ClusterService.Create \ < body.json ``` 1. Check the [server response](../api-ref/grpc/Cluster/create.md#yandex.cloud.operation.Operation) to make sure your request was successful. {% endlist %} {% note warning %} If you specified security group IDs when creating a Managed Service for MySQL® cluster, you may also need to [configure security groups](connect/index.md#configure-security-groups) to connect to the cluster. {% endnote %} ## Creating a cluster copy {#duplicate} You can create a MySQL® cluster with the settings of another one created earlier. Do this by importing the original MySQL® cluster configuration into Terraform. Then you can either create an identical copy or use the imported configuration as the baseline and modify it as needed. The import feature is handy when the original MySQL® cluster has a lot of settings and you need to create a similar one. To create a MySQL® cluster copy: {% list tabs group=instructions %} - Terraform {#tf} 1. If you do not have Terraform yet, [install it](../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform). 1. [Get the authentication credentials](../../tutorials/infrastructure-management/terraform-quickstart.md#get-credentials). You can add them to environment variables or specify them later in the provider configuration file. 1. [Configure and initialize a provider](../../tutorials/infrastructure-management/terraform-quickstart.md#configure-provider). There is no need to create a provider configuration file manually, you can [download it](https://github.com/yandex-cloud-examples/yc-terraform-provider-settings/blob/main/provider.tf). 1. Place the configuration file in a separate working directory and [specify the parameter values](../../tutorials/infrastructure-management/terraform-quickstart.md#configure-provider). If you did not add the authentication credentials to environment variables, specify them in the configuration file. 1. In your current working directory, create a `.tf` file with the following contents: ```hcl resource "yandex_mdb_mysql_cluster" "old" { } ``` 1. Save the ID of the original MySQL® cluster to an environment variable: ```bash export MYSQL_CLUSTER_ID= ``` You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters). 1. Import the original MySQL® cluster settings to the Terraform configuration: ```bash terraform import yandex_mdb_mysql_cluster.old ${MYSQL_CLUSTER_ID} ``` 1. Get the imported configuration: ```bash terraform show ``` 1. Copy it from your terminal and paste it into the `.tf` file. 1. Create a new directory `imported-cluster` and move your configuration file there. 1. Modify the configuration so that you can use it to create a new cluster: * Specify the new cluster name in the `resource` string and the `name` parameter. * Delete the `created_at`, `health`, `id`, and `status` parameters. * In the `host` sections, delete `fqdn`. * If the `maintenance_window` section has `type = "ANYTIME"`, delete the `hour` parameter. * Optionally, make further changes if you need a customized configuration. 1. [Get the authentication credentials](../../tutorials/infrastructure-management/terraform-quickstart.md#get-credentials) in the `imported-cluster` directory. 1. In the same directory, [configure and initialize the provider](../../tutorials/infrastructure-management/terraform-quickstart.md#configure-provider). Instead of manually creating the provider configuration file, you can [download it](https://github.com/yandex-cloud-examples/yc-terraform-provider-settings/blob/main/provider.tf). 1. Move the configuration file to the `imported-cluster` directory and [specify the arguments](../../tutorials/infrastructure-management/terraform-quickstart.md#configure-provider). If you have not set the authentication credentials as environment variables, specify them in the configuration file. 1. Validate your Terraform configuration: ```bash terraform validate ``` Terraform will display any configuration errors detected in your files. 1. Create the required infrastructure: 1. Run this command to view the planned changes: ```bash terraform plan ``` If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources. 1. If everything looks correct, apply the changes: 1. Run this command: ```bash terraform apply ``` 1. Confirm updating the resources. 1. Wait for the operation to complete. All the required resources will be created in the specified folder. You can check resource availability and their settings in the [management console](https://console.yandex.cloud). {% note warning "Timeouts" %} The Terraform provider sets the following timeouts for Managed Service for MySQL® cluster operations: * Creating a cluster, including by restoring it from a backup: 15 minutes. * Updating a cluster, including the MySQL® version update: 60 minutes. * Deleting a cluster: 15 minutes. Operations exceeding the timeout are aborted. {% cut "How do I change these limits?" %} Add the `timeouts` section to the cluster description, such as the following: ```hcl resource "yandex_mdb_mysql_cluster" "" { ... timeouts { create = "1h30m" # 1 hour 30 minutes update = "2h" # 2 hours delete = "30m" # 30 minutes } } ``` {% endcut %} {% endnote %} {% endlist %} ## Examples {#examples} ### Creating a single-host cluster {#creating-a-single-host-cluster} {% list tabs group=instructions %} - CLI {#cli} To create a Managed Service for MySQL® cluster with a single host, provide a single `--host` parameter. Create a Managed Service for MySQL® cluster with the following test specifications: * Name: `my-mysql`. * Version: `8.0`. * Environment: `production`. * Network: `default`. * Security group ID: `enp6saqnq4ie244g67sb`. * One `s2.micro` host in the `b0rcctk2rvtr8efcch64` subnet and `ru-central1-a` availability zone. * Network SSD storage (`network-ssd`): 20 GB. * User: `user1`, password: `user1user1`. * Database: `db1`, where `user1` has full privileges (same as `GRANT ALL PRIVILEGES on db1.*`). * Deletion protection: Enabled. 1. Run this command to create your Managed Service for MySQL® cluster: ```bash yc managed-mysql cluster create \ --name="my-mysql" \ --mysql-version 8.0 \ --environment=production \ --network-name=default \ --security-group-ids enp6saqnq4ie244g67sb \ --host zone-id=ru-central1-a,subnet-id=b0rcctk2rvtr8efcch64 \ --resource-preset s2.micro \ --disk-type network-ssd \ --disk-size 20 \ --user name=user1,password="user1user1" \ --database name=db1 \ --deletion-protection ``` 1. Run this command to change the `user1` permissions: ```bash yc managed-mysql user grant-permission user1 \ --cluster-name="my-mysql" \ --database=db1 \ --permissions ALL ``` - Terraform {#tf} Create a Managed Service for MySQL® cluster and its network with the following test specifications: * Name: `my-mysql`. * Version: `8.0`. * Environment: `PRESTABLE`. * Cloud ID: `b1gq90dgh25bebiu75o`. * Folder ID: `b1gia87mbaomkfvsleds`. * Network: `mynet` (new one). * Host class: `s2.micro` (one host), subnet: `mysubnet`, availability zone: `ru-central1-a`. `mysubnet` CIDR range: `10.5.0.0/24`. * With public access to host. * Security group: `mysql-sg` (new one), allowing internet access to the Managed Service for MySQL® cluster on port `3306`. * Network SSD storage (`network-ssd`): 20 GB. * User: `user1`, password: `user1user1`. * Database: `db1`, where `user1` has full privileges (same as `GRANT ALL PRIVILEGES on db1.*`). * Deletion protection: Enabled. The configuration file for this Managed Service for MySQL® cluster is as follows: ```hcl resource "yandex_mdb_mysql_cluster" "my-mysql" { name = "my-mysql" environment = "PRESTABLE" network_id = yandex_vpc_network.mynet.id version = "8.0" security_group_ids = [ yandex_vpc_security_group.mysql-sg.id ] deletion_protection = true resources { resource_preset_id = "s2.micro" disk_type_id = "network-ssd" disk_size = 20 } host { zone = "ru-central1-a" subnet_id = yandex_vpc_subnet.mysubnet.id assign_public_ip = true } } resource "yandex_mdb_mysql_database" "db1" { cluster_id = yandex_mdb_mysql_cluster.my-mysql.id name = "db1" } resource "yandex_mdb_mysql_user" "user1" { cluster_id = yandex_mdb_mysql_cluster.my-mysql.id name = "user1" password = "user1user1" permission { database_name = yandex_mdb_mysql_database.db1.name roles = ["ALL"] } } resource "yandex_vpc_network" "mynet" { name = "mynet" } resource "yandex_vpc_security_group" "mysql-sg" { name = "mysql-sg" network_id = yandex_vpc_network.mynet.id ingress { description = "MySQL®" port = 3306 protocol = "TCP" v4_cidr_blocks = [ "0.0.0.0/0" ] } } resource "yandex_vpc_subnet" "mysubnet" { name = "mysubnet" zone = "ru-central1-a" network_id = yandex_vpc_network.mynet.id v4_cidr_blocks = ["10.5.0.0/24"] } ``` {% endlist %} ### Creating a multi-host cluster {#creating-multiple-hosts-cluster} {% list tabs group=instructions %} - CLI {#cli} To create a multi-host Managed Service for MySQL® cluster, provide the `--host` parameter for each host in your cluster. Create a Managed Service for MySQL® cluster with the following test specifications: * Name: `my-mysql-3`. * Version: `8.0`. * Environment: `prestable`. * Network: `default`. * Security group ID: `enp6saqnq4ie244g67sb`. * `s2.micro` public hosts: 3. One host will be added to each subnet of the `default` network: * `subnet-a`: `10.5.0.0/24`, availability zone: `ru-central1-a`. * `subnet-b`: `10.6.0.0/24`, availability zone: `ru-central1-b`. * `subnet-d`: `10.7.0.0/24`, availability zone: `ru-central1-d`. The host residing in `subnet-b` will have the backup priority. If this host is not acting as the master, backups will be created from its data. * Network SSD storage (`network-ssd`): 32 GB. * User: `user1`, password: `user1user1`. * Database: `db1`, where `user1` has full privileges (same as `GRANT ALL PRIVILEGES on db1.*`). 1. Run this command to create your Managed Service for MySQL® cluster: ```bash yc managed-mysql cluster create \ --name="my-mysql-3" \ --mysql-version 8.0 \ --environment=prestable \ --network-name=default \ --security-group-ids enp6saqnq4ie244g67sb \ --host zone-id=ru-central1-a,` `subnet-name=subnet-a,` `assign-public-ip=true \ --host zone-id=ru-central1-b,` `subnet-name=subnet-b,` `backup-priority=10,` `assign-public-ip=true \ --host zone-id=ru-central1-d,` `subnet-name=subnet-d,` `assign-public-ip=true \ --resource-preset s2.micro \ --disk-type network-ssd \ --disk-size 32 \ --user name=user1,password="user1user1" \ --database name=db1 ``` 1. Run this command to change the `user1` permissions: ```bash yc managed-mysql user grant-permission user1 \ --cluster-name="my-mysql-3" \ --database=db1 \ --permissions ALL ``` - Terraform {#tf} Create a Managed Service for MySQL® cluster and its supporting network, using the following test specifications: * Name: `my-mysql-3`. * Version: `8.0`. * Environment: `PRESTABLE`. * Cloud ID: `b1gq90dgh25bebiu75o`. * Folder ID: `b1gia87mbaomkfvsleds`. * New network: `mynet`. * `s2.micro` public hosts: 3. One host will be added to each new subnet: * `mysubnet-a`: `10.5.0.0/24`, availability zone: `ru-central1-a`. * `mysubnet-b`: `10.6.0.0/24`, availability zone: `ru-central1-b`. * `mysubnet-d`: `10.7.0.0/24`, availability zone: `ru-central1-d`. These subnets will belong to the `mynet` network. The host residing in `mysubnet-b` will have the backup priority. If this host is not acting as the master, backups will be created from its data. * New security group: `mysql-sg`, allowing connections to Managed Service for MySQL® clusters from the Internet through port `3306`. * Network SSD storage (`network-ssd`): 32 GB. * User: `user1`, password: `user1user1`. * Database: `db1`, where `user1` has full privileges (same as `GRANT ALL PRIVILEGES on db1.*`). The configuration file for this Managed Service for MySQL® cluster is as follows: ```hcl resource "yandex_mdb_mysql_cluster" "my-mysql-3" { name = "my-mysql-3" environment = "PRESTABLE" network_id = yandex_vpc_network.mynet.id version = "8.0" security_group_ids = [ yandex_vpc_security_group.mysql-sg.id ] resources { resource_preset_id = "s2.micro" disk_type_id = "network-ssd" disk_size = 32 } host { zone = "ru-central1-a" subnet_id = yandex_vpc_subnet.mysubnet-a.id assign_public_ip = true } host { zone = "ru-central1-b" subnet_id = yandex_vpc_subnet.mysubnet-b.id assign_public_ip = true backup_priority = 10 } host { zone = "ru-central1-d" subnet_id = yandex_vpc_subnet.mysubnet-d.id assign_public_ip = true } } resource "yandex_mdb_mysql_database" "db1" { cluster_id = yandex_mdb_mysql_cluster.my-mysql-3.id name = "db1" } resource "yandex_mdb_mysql_user" "user1" { cluster_id = yandex_mdb_mysql_cluster.my-mysql-3.id name = "user1" password = "user1user1" permission { database_name = yandex_mdb_mysql_database.db1.name roles = ["ALL"] } } resource "yandex_vpc_network" "mynet" { name = "mynet" } resource "yandex_vpc_security_group" "mysql-sg" { name = "mysql-sg" network_id = yandex_vpc_network.mynet.id ingress { description = "MySQL®" port = 3306 protocol = "TCP" v4_cidr_blocks = [ "0.0.0.0/0" ] } } resource "yandex_vpc_subnet" "mysubnet-a" { name = "mysubnet-a" zone = "ru-central1-a" network_id = yandex_vpc_network.mynet.id v4_cidr_blocks = ["10.5.0.0/24"] } resource "yandex_vpc_subnet" "mysubnet-b" { name = "mysubnet-b" zone = "ru-central1-b" network_id = yandex_vpc_network.mynet.id v4_cidr_blocks = ["10.6.0.0/24"] } resource "yandex_vpc_subnet" "mysubnet-d" { name = "mysubnet-d" zone = "ru-central1-d" network_id = yandex_vpc_network.mynet.id v4_cidr_blocks = ["10.7.0.0/24"] } ``` {% endlist %}