This discussion is archived
2 Replies Latest reply: Apr 2, 2013 10:24 PM by jack.yu RSS

Determine the required parameters in a VM/AssemblyInstance creation...

jack.yu Newbie
Currently Being Moderated
Oracle Enterprise Manager Cloud Control's Cloud API documentation [12.1.0.2 EM with 12.1.0.4 Cloud Service Portal Plugin|http://docs.oracle.com/cd/E24628_01/doc.121/e28814/cloud_part5.htm#sthref1171] illustrates some examples on creating VM and Assembly service instances via POSTing to either a Zone or a ServiceTemplate resource.

However, the documentation doesn't exactly specify nor indicate what are the attributes and/or "params" that ought to be included in such as request.

In the current interpretation of service instance creation requests (thus, POST content-type of a service instance with the intention to create a new instance of a service), we have denoted it as a "CREATE" or "DEPLOYMENT" to better synchronized with current IT nomenclature.

As part of the introspective nature of the Cloud API, the primary attributes/params of a "DEPLOYMENT" requests are included as part of the application/oracle.com.cloud.common.ServiceTemplate resource, which means each resource type extending the ServiceTemplate may choose to populate "deployment_params" attribute. Furthermore, for ServiceTemplate in the IaaS family (application/oracle.com.cloud.common.VMTemplate and application/oracle.com.cloud.common.AssemblyTemplate), we will always populate the "deployment_params" attribute.


Here are some examples: (all paths are relative to the EM end point)
<h4>Get the list of IaaS Service Templates to introspect</h4>
-----
GET /em/cloud/service_family_type/iaas?service_templates
-----
{
"service_templates" : {
"media_type" : "application/oracle.com.cloud.common.ServiceTemplate+json" ,
"total" : "5" ,
"elements" :
[
{
"uri" : "/em/cloud/iaas/servicetemplate/vm/oracle%3AdefaultService%3Aem%3Aprovisioning%3A1%3Acmp%3AVirtualization%3ATemplate%3AD7B887836B230A4BE0431780578C7C12%3A0.1" ,
"name" : "saved template from ssa" ,
"media_type" : "application/oracle.com.cloud.common.VMTemplate+json" ,
"type" : "Template"
} ,
{
"uri" : "/em/cloud/iaas/servicetemplate/vm/oracle%3AdefaultService%3Aem%3Aprovisioning%3A1%3Acmp%3AVirtualization%3ATemplate%3AD766060CF1D07533E0431780578CA840%3A0.1" ,
"name" : "Template1" ,
"media_type" : "application/oracle.com.cloud.common.VMTemplate+json" ,
"type" : "Template"
} ,
{
"uri" : "/em/cloud/iaas/servicetemplate/vm/oracle%3AdefaultService%3Aem%3Aprovisioning%3A1%3Acmp%3AVirtualization%3ATemplate%3AD7BDEC41C65F7C74E0431980578C221C%3A0.1" ,
"name" : "aaa" ,
"media_type" : "application/oracle.com.cloud.common.VMTemplate+json" ,
"type" : "Template"
} ,
{
"uri" : "/em/cloud/iaas/servicetemplate/assembly/oracle%3AdefaultService%3Aem%3Aprovisioning%3A1%3Acmp%3AVirtualization%3AAssembly%3AD766B6DD3BDE0F7BE0431780578CA8D8%3A0.1" ,
"name" : "Env Assembly" ,
"media_type" : "application/oracle.com.cloud.common.AssemblyTemplate+json" ,
"type" : "Assembly"
} ,
{
"uri" : "/em/cloud/iaas/servicetemplate/assembly/oracle%3AdefaultService%3Aem%3Aprovisioning%3A1%3Acmp%3AVirtualization%3AAssembly%3AD766898D34A66DCAE0431980578C55B6%3A0.1" ,
"name" : "sidb_asm" ,
"media_type" : "application/oracle.com.cloud.common.AssemblyTemplate+json" ,
"type" : "Assembly"
}
]
}
}
-----
<h4>Select a VMTemplate to introspect the deployment parameters</h4>
-----
GET /em/cloud/iaas/servicetemplate/vm/oracle%3AdefaultService%3Aem%3Aprovisioning%3A1%3Acmp%3AVirtualization%3ATemplate%3AD7B887836B230A4BE0431780578C7C12%3A0.1?deployment_params
-----
{
"deployment_params" :
[
{
"name" : "zone" ,
"description" : "'zone' attribute is the URI of the zone that the 'application/oracle.com.cloud.common.VM' resource is to be created in" ,
"type" : "STRING" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "based_on" ,
"description" : "'based_on' attribute is the URI of the service template or format String of the originated source which the deployed 'application/oracle.com.cloud.common.VM' resource is to be followed" ,
"type" : "STRING" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "cpu" ,
"description" : "The information that determined how much 'CPU' is to be allocated to the deployed resource" ,
"type" : "LIST" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "memory" ,
"description" : "The information that determined how much 'MEMORY' is to be allocated to the deployed resource" ,
"type" : "NUMBER" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "disks" ,
"description" : "The list of disks to be included in the deployed resource" ,
"type" : "LIST" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "params.domain_type" ,
"description" : "The domain type of the Virtual Machine" ,
"type" : "STRING" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "params.network_profile" ,
"description" : "The identifier of the network profile to be used for the network instances of the Virtual Machine" ,
"type" : "STRING" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "params.server_prefix" ,
"description" : "The server prefix to be specified for the Virtual Machine" ,
"type" : "STRING" ,
"require" : "true" ,
"sensitive" : "false"
} ,
{
"name" : "params.server_size" ,
"description" : "The name of the server instance size" ,
"type" : "STRING" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "params.request_name" ,
"description" : "The request name to be tracked for the Virtual Machine creation" ,
"type" : "STRING" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "params.request_description" ,
"description" : "The request description to be tracked for the Virtual Machine creation" ,
"type" : "STRING" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "params.vnc_password" ,
"description" : "The VNC password for the Virtual Machine" ,
"type" : "STRING" ,
"require" : "true" ,
"sensitive" : "true"
} ,
{
"name" : "params.root_password" ,
"description" : "The Root password for the Virtual Machine" ,
"type" : "STRING" ,
"require" : "true" ,
"sensitive" : "true"
} ,
{
"name" : "params.start_vm" ,
"description" : "Whether or not the Virtual Machine should be started after creation" ,
"type" : "STRING" ,
"defaultValue" : "YES" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "params.ha_enabled" ,
"description" : "Whether or not the Virtual Machine should be HA enabled" ,
"type" : "STRING" ,
"defaultValue" : "NO" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "params.disks_overwrite" ,
"description" : "Whether or not the default Virtual Machine disks should be overwritten" ,
"type" : "STRING" ,
"defaultValue" : "NO" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "params.networks" ,
"description" : "Whether or not the default Virtual Machine disks should be overwritten" ,
"type" : "LIST" ,
"require" : "false" ,
"sensitive" : "false"
}
]
}
-----
<h4>Similarly, for Assembly Template </h4>
-----
GET /em/cloud/iaas/servicetemplate/assembly/oracle%3AdefaultService%3Aem%3Aprovisioning%3A1%3Acmp%3AVirtualization%3AAssembly%3AD766B6DD3BDE0F7BE0431780578CA8D8%3A0.1?deployment_params
-----
{
"deployment_params" :
[
{
"name" : "zone" ,
"description" : "'zone' attribute is the URI of the zone that the 'application/oracle.com.cloud.common.AssemblyInstance' resource is to be created in" ,
"type" : "STRING" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "based_on" ,
"description" : "'based_on' attribute is the URI of the service template or format String of the originated source which the deployed 'application/oracle.com.cloud.common.AssemblyInstance' resource is to be followed" ,
"type" : "STRING" ,
"require" : "false" ,
"sensitive" : "false"
} ,
{
"name" : "deployment_plan" ,
"description" : "'deployment_plan' attribute describes the configuration of which the deployed 'application/oracle.com.cloud.common.AssemblyInstance' resource is to be used in the XML deployment plan format" ,
"type" : "STRING" ,
"require" : "false" ,
"sensitive" : "false"
}
]
}
-----

One could think of some ways to use this information in its integration. In particular, when Enterprise Manager were upgraded to a newer version, additional optional parameters may be added or some existing parameters may no longer be needed. These changes may be automatically discovered via the above introspection.

For example, a client may cache the deployment parameters and before POSTing to create a new service instance, compare the API's deployment parameters with the cached copy to determine whether there are additional "require"="true" parameters. Even though Enterprise Manager will include missing required parameters/attributes in its 400 response, by introspecting deployment_parameters, a client can determine, a priori, what may be needed.
  • 1. Re: Determine the required parameters in a VM/AssemblyInstance creation...
    jack.yu Newbie
    Currently Being Moderated
    The following additional parameters may be specified (though all of them are optional) as part of the Assembly Instance creation request:
    -----
    {
    "name" : "params.assembly_instance_name" ,
    "description" : "The name of the assembly instance" ,
    "type" : "STRING" ,
    "require" : "false" ,
    "sensitive" : "false"
    } ,
    {
    "name" : "params.request_name" ,
    "description" : "The request name to be tracked for the Assembly Instance creation" ,
    "type" : "STRING" ,
    "require" : "false" ,
    "sensitive" : "false"
    } ,
    {
    "name" : "params.request_description" ,
    "description" : "The request description to be tracked for the Assembly Instance creation" ,
    "type" : "STRING" ,
    "require" : "false" ,
    "sensitive" : "false"
    } ,
    {
    "name" : "params.vnc_password" ,
    "description" : "The VNC password for all the Virtual Machines in the assembly" ,
    "type" : "STRING" ,
    "require" : "false" ,
    "sensitive" : "true"
    } ,
    {
    "name" : "params.root_password" ,
    "description" : "The Root password for all the Virtual Machines in the assembly" ,
    "type" : "STRING" ,
    "require" : "false" ,
    "sensitive" : "true"
    } ,
    {
    "name" : "params.server_size" ,
    "description" : "The name of the server instance size for all the Virtual Machines in the assembly" ,
    "type" : "STRING" ,
    "require" : "false" ,
    "sensitive" : "false"
    } ,
    {
    "name" : "params.network_profile" ,
    "description" : "The id of the network profile for all the networks in all the Virtual Machines in the assembly" ,
    "type" : "STRING" ,
    "require" : "false" ,
    "sensitive" : "false"
    }
    -----
    For example,
    -----
    {
    "params":{
    "assembly_instance_name":"QA Assembly",
    "request_name":"Quarterly Testing 1",
    "request_description":"Here is the request to create an QA Assembly for Quarterly testing",
    "vnc_password":"secret",
    "root_password":"secret",
    "server_size":"Small",
    "network_profile":"oracle:defaultService:em:provisioning:1:netConfig:D7C43DB9969841F5E0431980578CB5C1"
    }
    }
    -----

    When both "deployment_plan" and "params" are specified during Assembly Instance creation request, the values in the "params" attribute would take precedent. For example,if "deployment_plan" contained various server size specifications for the assembly while "params.server_size" were specified to be "Small", all Virtual Machines created would be of size "Small" instead of the values specified in the "deployment_plan".
  • 2. Re: Determine the required parameters in a VM/AssemblyInstance creation...
    jack.yu Newbie
    Currently Being Moderated
    For Assembly instance creation, the setting of root_password has multiple levels:
    1. deployment plan's <HardwareConfiguration>'s <RootPasswordGuid> may contain a valid GUID to an EM credential object
    2. deployment plans' <HardwareConfiguration>'s <RootPassword> may contain a plain text
    3. POST body's "params" attribute may contain "root_password" with plain text

    The assembly instance creation will observe the following heuristics
    1. if <RootPasswordGuid> is specified and is a valid EM credential object, it will be used (and ignore all else)
    2. if <RootPasswordGuid> is not specified or contains an invalid value, and if "params.root_password" is not set, then <RootPassword> will be used
    3. if <RootPasswordGuid> is not specified or contains an invalid value, and if "params.root_password" is set, then "params.root_password" will be used (and ignore <RootPassword>)