1. REST API for MySQL Cloud Service
  2. Tasks
  3. Service Instances

Create a Service Instance

post

/paas/api/v1.1/instancemgmt/{identityDomainId}/services/MySQLCS/instances

Create a MySQL Cloud Service instance.

Service instance clones: You can create a clone of an existing MySQL Cloud Service instance, but you must first create a snapshot of the service instance you want to clone. See Snapshots REST Endpoints.

Request

Supported Media Types
Path Parameters
Header Parameters
Body ()
Details for the operation to create a MySQL Cloud Service instance.
Root Schema : Create Instance Request Body
Type: object
Title: Create Instance Request Body
Root schema for the nested 'serviceParameters' and 'componentParameters' schemas for the create instance operation. See the nested schema definitions for paramter details.
Show Source
Nested Schema : MySQL Server Component Root Schema
Type: object
Title: MySQL Server Component Root Schema
Contains the nested 'mysql' schema for the request body of the create instance operation.
Show Source
Nested Schema : MySQL Cloud Service Parameters
Type: object
Title: MySQL Cloud Service Parameters
Define service parameters for the create instance operation.
Show Source
  • This required attribute is only available on Oracle Cloud Infrastructure. region is also required; subnet is optional.

    Name of a data center location in the Oracle Cloud Infrastructure region that is specified in region. A region is a localized geographic area, composed of one or more availability domains (data centers).

    The availability domain value format is an account-specific prefix followed by <region>-<ad>. For example, FQCn:US-ASHBURN-AD1 where FQCn is the account-specific prefix.

    See Regions and Availability Domains in Oracle Cloud Infrastructure Services.

  • Default Value: NONE
    Backup destination. Valid values are:
    • BOTH - Both Cloud Storage and Local Storage
    • OSS - Cloud Storage Only
    • NONE - None
    . The default is NONE.
  • URI of the object storage container or bucket for storing MySQL Cloud Service instance backups. This attribute is not required if backupDestination is set to NONE.

    Note:

    • Do not use a container or bucket that you use to back up MySQL Cloud Service instances for any other purpose. For example, do not also use the same container or bucket to back up Oracle Database Cloud Service database deployments. Using one container or bucket for multiple purposes can result in billing errors.
    • You do not have to specify a container or bucket if you provision the service instance without enabling backups.

    On Oracle Cloud Infrastructure Classic, the object storage container does not have to be created ahead of provisioning your MySQL Cloud Service instance.

    To specify the container (existing or new), use one of the following formats:

    • Storage-<identitydomainid>/<containerName>
    • <storageservicename>-<identitydomainid>/<containerName>
    • <restEndPointURL>/<containerName>

    To identify the REST endpoint URL of your object storage service, see Finding the REST Endpoint URL for Your Service Instance in Using Oracle Cloud Infrastructure Object Storage Classic.

    On Oracle Cloud Infrastructure, the object storage bucket must be created before provisioning your MySQL Cloud Service instance. Do not use the same bucket for more than one instance. For the instructions to create a bucket, see Prerequisites for Oracle Platform Services on Oracle Cloud Infrastructure in the Oracle Cloud Infrastructure documentation. Enter the bucket URL in the following format:

    https://swiftobjectstorage.<region>.oraclecloud.com/v1/<namespace>/<bucket>.

    To find out your namespace, sign in to the Oracle Cloud Infrastructure web console, click the tenancy name, and look for the Object Storage Namespace field.

    Example:

    https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/acme/mybucket

  • This attribute is not applicable when provisioning a MySQL Cloud Service instance in Oracle Cloud Infrastructure.

    Flag that specifies whether to create (true) or not create (false) the object storage container if the name specified in cloudStorageContainer does not exist. The default is false.

  • Password for the object storage user. The password must be specified if cloudStorageContainer is set.

    On Oracle Cloud Infrastructure Classic, this is the password for the Oracle Cloud Infrastructure Object Storage Classic user who has read and write access to the container that is specified in cloudStorageContainer.

  • User name for the object storage user. The user name must be specified if cloudStorageContainer is set.

    On Oracle Cloud Infrastructure Classic, this is the user name for the Oracle Cloud Infrastructure Object Storage Classic user who has read and write access to the container that is specified in cloudStorageContainer.

  • Flag that specifies whether to enable (true) or disable (false) notifications by email. If this property is set to true, you must specify a value in notificationEmail.

    Currently, notifications are sent only when service instance provisioning is successful or not successful.

  • This attribute is applicable only to accounts where regions are supported.

    This attribute is not applicable when provisioning MySQL Cloud Service instances in Oracle Cloud Infrastructure.

    The three-part name of a custom IP network to attach this service instance to. For example:

    /Compute-identity_domain/user/object

    A region name must be specified in order to use ipNetwork. Only those IP networks already created in the specified Oracle Cloud Infrastructure Compute Classic region can be used.

    A consequence of using an IP network is that the auto-assigned IP address could change each time the service instance is started. To assign fixed public IP addresses to a service instance that is attached to an IP network, you can first create reserved IP addresses, then provision the service instance to use those persistent IP addresses in ipReservations. Note that to use ipReservations, assignPublicIP must be true.

    See IP Reservations REST Endpoints for information about how to find unused IP reservations and, if needed, create new IP reservations.

  • Default Value: HOURLY
    The billing frequency of the service instance; either MONTHLY or HOURLY.
  • This parameter, when set to true disables the provisioning retry in case of failures.
  • The email that will be used to send notifications to.

    To receive notifications, enableNotification must be set to true.

  • This attribute is only applicable to accounts where regions are supported, including accounts on Oracle Cloud Infrastructure.

    Name of the region where the MySQL Cloud Service instance is to be provisioned.

    (Not applicable on Oracle Cloud Infrastructure) A region name must be specified if you intend to use ipReservations or ipNetwork.

    An Oracle Cloud Infrastructure region must be specified to provision your service instance on Oracle Cloud Infrastructure host resources. Be sure to specify a region that is within the default data region of your account on Oracle Cloud Infrastructure. If the default data region is North America, specify the region such as us-phoenix-1 or us-ashburn-1. If the default data region is EMEA, specify the region as eu-frankfurt-1 or uk-london-1.

    Note the following when provisioning on Oracle Cloud Infrastructure:

    • An availability domain must also be specified using availabilityDomain. See Regions and Availability Domains in Oracle Cloud Infrastructure Services.
    • A subnet can be specified using subnet. See VCNs and Subnets in Oracle Cloud Infrastructure Services. If subnet is not specified, a subnet is automatically assigned to this MySQL Cloud Service instance from a virtual cloud network (VCN) named svc-vcn in the ManagedCompartmentForPaaS compartment.
    • Access rules and IP reservations REST endpoints are not supported.

  • Free-form text that provides additional information about the service instance.
  • Name of MySQL Cloud Service instance. The service name:
    • Must not exceed 50 characters.
    • Must start with a letter.
    • Must contain only letters, numbers, or hyphens.
    • Must not end with a hyphen.
    • Must not contain any other special characters.
    • Must be unique within the identity domain.
  • Public key for the secure shell (SSH). This key will be used for authentication when connecting to the MySQL Cloud Service instance using an SSH client. You generate an SSH public-private key pair using a standard SSH key generation tool.
  • VM operating system user that is valid for variations of compute based services. It will default to the username opc when not specified.
Nested Schema : MySQL Server Component Parameters
Type: object
Title: MySQL Server Component Parameters
Parameters for the 'mysql' schema defined in componentParameters as part of the create instance operation.
Show Source
  • Default Value: mydatabase
    Initial database schema name of your choice, up to 64 characters; can contain letters, numbers and special characters (_,$). The default name is mydatabase.
  • Default Value: 25
    Storage volume size for MySQL data. The number must be between 25 and 1024 GB. Default value is 25.
  • Default Value: No
    Allowed Values: [ "Yes", "No" ]
    Indicate whether to configure MySQL Enterprise Monitor during provisioning. The value can only be one of the valid choices, either Yes or No and the default is No.
  • Password for MySQL Enterprise Monitor agent. The password must be at least 8 characters long with at least one lower case letter, one upper case letter, one number and one special character.
  • Name for the Enterprise Monitor agent user. Agent User name should start with a letter, consist of letters and numbers, and be between 2 to 32 characters.
  • Password for MySQL Enterprise Monitor manager. The password must be at least 8 characters long with at least one lower case letter, one upper case letter, one number and one special character.
  • Name for the Enterprise Monitor manager user. Manager User name should start with a letter, consist of letters and numbers, and be between 2 to 32 characters.
  • Default Value: utf8mb4
    MySQL server character set. See Supported Character Sets and Collations for the character sets MySQL supports. Although the MySQL Server 5.7 default is 'latin1', MySQL Cloud Service sets this to 'utf8mb4' by default.
  • Default Value:
    MySQL server collation. See Supported Character Sets and Collations for the permissible collations of each character set.
  • Default Value: 18443
    Port for the MySQL Enterprise Monitor. The default is 18443.
  • MySQL server options and variables. Only comma separated key value pairs with no spaces are permitted (e.g., option1=value,option2=value). MySQL server options that are available as MySQL Server Component Parameters, such as mysqlPort, are not permitted in a mysqlOptions string. See Server System Variables for information about MySQL server options.
  • Default Value: 3306
    Port for the MySQL server. Port must be in the range of 3200-3399. The default is 3306.
  • Default Value: SYSTEM
    MySQL server time zone. The default value is SYSTEM, which indicates that the server time zone is the same as the system time zone. The value can be given as a named time zone, such as 'Europe/Paris', 'US/Eastern', or 'Asia/Shanghai'. See MySQL Server Time Zone Support for related information.
  • Default Value: root
    Administration user for connecting to the service via the MySQL protocol. User name should start with a letter, consist of letters and numbers, and be between 2 to 32 characters. The default is root.
  • Password for MySQL administration user. The password must meet the following requirements:
    • Starts with a letter
    • Is between 8 and 30 characters long
    • Contains letters, at least one number, and optionally, any number of these special characters: dollar sign ($), pound sign (#), and underscore (_).
  • Default Value: oc3
    Desired compute shape. A shape defines the number of Oracle Compute Units (OCPUs) and amount of memory (RAM). Valid shapes include:
    • oc3: 1 OCPU, 7.5 GB memory
    • oc4: 2 OCPUs, 15 GB memory
    • oc5: 4 OCPUs, 30 GB memory
    • oc6: 8 OCPUs, 60 GB memory
    • oc7: 16 OCPUs, 120 GB memory
    • oc1m: 1 OCPU, 15 GB memory
    • oc2m: 2 OCPUs, 30 GB memory
    • oc3m: 4 OCPUs, 60 GB memory
    • oc4m: 8 OCPUs, 120 GB memory
    • oc5m: 16 OCPUs, 240 GB memory
    .

    See About Shapes in Using Oracle Compute Cloud Service for more information about shapes.

  • The name of the snapshot of the service instance specified by sourceServiceName that is to be used to create a "snapshot clone". This parameter is valid only if sourceServiceName is specified.
  • When present, indicates that the service instance should be created as a "snapshot clone" of another service instance. Provide the name of the existing service instance whose snapshot is to be used. dbName, mysqlCharset, mysqlCollation, mysqlEMPort, enterpriseMonitor, and associated MySQL server component parameters do not apply when cloning a service from a snapshot. For those parameters, the clone operation uses the values defined in the snapshot of the source service instance.
  • This optional attribute is only applicable when provisioning MySQL Cloud Service instances on Oracle Cloud Infrastructure. region and availabilityDomain, however, are required.

    The Oracle Cloud Identifier (OCID) of a subnet from a virtual cloud network (VCN) created on Oracle Cloud Infrastructure.

    You can specify a subnet that you have created yourself, or you can let MySQL Cloud Service automatically assign a subnet for you.

    To specify a subnet you have created: Use subnet to specify the OCID of the subnet from a VCN that you have created on Oracle Cloud Infrastructure. For the instructions to create a VCN and subnet, see Prerequisites for Oracle Platform Services on Oracle Cloud Infrastructure in the Oracle Cloud Infrastructure documentation. The OCID is a unique autogenerated ID. To find out the OCID of the subnet, go to the Oracle Cloud Infrastructure web console, select the Networking tab, click the VCN that your subnet is in, and look for the OCID field under the subnet that you want to use.

    To let MySQL Cloud Service assign a subnet for you: Do not include subnet in your provisioning request payload. When excluded, MySQL Cloud Service automatically assigns a subnet from the VCN named svc-vcn in the ManagedCompartmentForPaaS compartment.

Response

Supported Media Types

202 Response

Accepted. See Status Codes for information about other possible HTTP status codes.
Body ()
Root Schema : Response Body
Type: object
Title: Response Body
The response body contains information about the operation.
Show Source

Examples

The following example shows how to create a MySQL Cloud Service instance by submitting a POST request on the REST endpoint using cURL.

Note: The command in this example uses the URL structure https://rest_server_url/resource-path, where rest_server_url is the Oracle Public Cloud or Oracle Cloud Machine REST server to contact for your identity domain or tenant name. See Send Requests for the appropriate URL structure to use on Oracle Public Cloud or Oracle Cloud Machine.

For configuring backups, the cloudStorageContainer definition depends on your setup. For additional information, see Finding the REST Endpoint URL for Your Cloud Account.

cURL Command

curl -i -X POST \
  -u "username:password" \
  -H "X-ID-TENANT-NAME: ExampleIdentityDomain" \
  -d @createMysqlInstance.json \
  -H "Accept: application/json" \
  -H "Content-Type: application/vnd.com.oracle.oracloud.provisioning.Service+json" \
  https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/MySQLCS/instances

Example of Request Body

The following shows an example of the request body in JSON format. It represents the contents of createMysqlInstance.json in the cURL example above. 

{
  "serviceParameters": {
    "serviceName": "ExampleInstance",
    "serviceDescription": "My example instance.",
    "meteringFrequency": "HOURLY",
    "backupDestination": "NONE",
    "cloudStorageContainer": "Storage-StorageIdentityDomain/MySQLCS",
    "cloudStorageUser": "yourcloudStorageUserName",
    "cloudStoragePassword": "password",
    "cloudStorageContainerAutoGenerate": true,
    "region": "uscom-east-1",
    "vmPublicKeyText": "yourSSHPublicKeyString"
  },
  "componentParameters": {
    "mysql": {
      "shape": "oc3",
      "mysqlUserName": "yourMySQLUserName",
      "mysqlUserPassword": "password",
      "mysqlPort": "3306",
      "mysqlEMPort": "18443",
      "dbStorage": 25,
      "dbName": "mydatabase",
      "mysqlCharset": "utf8mb4",
      "mysqlTimezone": "SYSTEM",
      "mysqlCollation": "utf8mb4_general_ci",
      "enterpriseMonitor": "Yes",
      "enterpriseMonitorManagerUser": "yourEnterpriseManagerMonitorUserName",
      "enterpriseMonitorManagerPassword": "password",
      "enterpriseMonitorAgentUser": "yourEnterpriseAgentUserName",
      "enterpriseMonitorAgentPassword": "password"
    }
  }
}

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 202 Accepted
Date: Wed, 30 Nov 2016 22:54:28 GMT
Transfer-Encoding: chunked
Location: https://rest_server_url/paas/api/v1.1/activitylog/ExampleIdentityDomain/job/3465
Content-Type: application/json
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
Service-URI: https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/MySQLCS/instances/MyTestInstance
Retry-After: 60
Access-Control-Allow-Methods: GET, POST, DELETE, PUT, OPTIONS, HEAD
X-ORACLE-DMS-ECID: 3ae14bc-78-3-2382197d3-2-18960cea7e06338c6410
Access-Control-Allow-Origin: *
X-Frame-Options: DENY

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "details": {
        "message": "Submitted job to create service [MyTestInstance] in domain [ExampleIdentityDomain].",
        "jobId": "3465"
    }
}