2 Replies Latest reply: Apr 3, 2013 12:24 AM by jack.yu RSS

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

    jack.yu
      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
          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
            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>)