×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

Unsupported content

 

This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.
BMC Cloud Lifecycle Management 4.1 ... Developing RESTful API API reference Cloud API reference ServiceOfferingInstance class

ServiceOfferingInstance onboard request

Description

This API creates a service offering instance (SOI) for an existing virtual machine (VM). The API supports Single-tier and Multi-tier service offering instances. For additional information, see Onboarding existing VMs (checklist).
The following constraints apply to this API:

  • BMC Cloud Lifecycle Management supports the onboarding of VMware and Amazon Web Services virtual machines.
  • The onboarding of Service Offering Instances can be done with two different input formats:
    • Format 1: Requires manual steps to enroll the servers in BMC Server Automation.
    • Format 2: Servers are enrolled automatically in BMC Server Automation.
  • There will be no validations on whether the LogicalHostingEnvironment passed to the API is topologically correct to have connectivity between the computes as defined in the blueprint.
  • You can onboard only VMs that do not have load balancers or firewalls, that is, you cannot onboard any existing load balancer entries and firewall rules. However, after the VM is onboarded, you can create firewall rules and load balancer entries for the VM.
  • You cannot apply options when you onboard a VM. However, after the VM is onboarded, you can use options associated with the SOI.
  • This API does not support onboarding VMs that have NAT IP addresses.

  • The VM must be configured correctly in BMC Server Automation. For information about enrolling VMs in BMC Server Automation, see Knowledge Base article 000030942.

  • The VM must be powered on.
  • The VM should have the same name in both BMC Server Automation and VMware vCenter Server. If BMC Server Automation and VMware vCenter Server each use a different name for the VM, then set "name" parameter in serverObject to the name used in VMware vCenter Server. Console actions such as start, stop, decommission, modify CPU or memory, and attach or detach storage work only for onboarded service offering instances that have the same name in BMC Server Automation and VMware vCenter Server. Only the offboard service offering instance action can be done through the REST API.
  • If you want the hostname value displayed as the VM name in BMC Cloud Lifecycle Management, set the BBSA_SET_VIRTUALGUESTNAME_AS_VM_HOSTNAME parameter to TRUE in the cloudservices.json file before onboarding.
  • If a static IP address is already marked as reserved in BMC Network Automation IP address management (IPAM), the VM onboard process fails to reserve the static IP address. Failure to reserve a static IP address triggers a rollback of the onboarding process that frees the allocated IP address. This case occurs only when two VMs in the network have the same static IP address.
    Enforced validations to this API:
    • The number of networks defined in the resource set in the service blueprint must be equal to the number of interfaces of the VM
    • Resource set names in the API request should match to the resource set names in blueprint
    • The number of Resource Sets defined in the blueprint must be equal to the number of Resource Sets passed in input for the API.
    • VM should be deployed on an CLM onboarded VirtualCluster/VirtualHost/VirtualResourcePool.
    • The associated VirtualCluster/VirtualHost/VirtualResourcePool of the VM, should be member of a compute pool which is attached to the Network Container passed as input argument.
    • The associated datastores of the VM, should be member of a VDR pool.
    • Switch ports attached to the VM should match to the switch ports of the Network Container (or POD) passed as input argument.

API stability classification

Uncommitted

API overview

HTTP
method

URI

Return
type

Return type
multiplicity

POST

csm/ServiceOfferingInstance/onboard

void

Not applicable

HTTP request message

Query string parameters

This API does not use query string parameters.

Request message headers

This API uses only common headers listed in HTTP request and response headers.

Request message body

This API uses the following objects in the request message body JSON.

Top-level objects

Name

Type

Multi-
plicity

Description

callbackURL

String

0..1

URL to call when the operation finishes

postCallout

String

0..1

Identifier of a callout to run after the operation executes

preCallout

String

0..1

Identifier of a callout to run before the operation executes

timeout

Integer

0..1

Timeout setting. For more information about using the timeout, see Synchronous and asynchronous operations. Timeout values:

  • 0: Immediate timeout
  • -1: Uses the system default timeout value
  • 1..*: Times out in the specified number of seconds

operationParams

OperationParameter

1

Array of input parameters. The following table contains the list of input parameters. For information about setting up the input parameters, see Passing input parameters with an API request.


Input parameters to include in operationParams

Name

Type

Multi-
plicity

Description

actualVMName

String

0..1

VM name used in VMware vCenter Server. Include this parameter when the name used in VMware vCenter Server is different from the name used in BMC Server Automation.

computeContainers

ComputeContainer

1..*

List of ComputeContainers that are to be onboarded.
In the JSON for this parameter, the following ComputeContainer class objects are used in the value object:

  • cloudClass(Required) — Fully qualifed name of the ComputeContainer class
  • serverObject(Required) – the following VirtualGuest class objects are used in the valueobject:
    • cloudClass(Required) — Fully qualifed name of the VirtualGuest class
    • externalID(Required) — URI of the VM and the VMware vCenter Server. For example: /id/SystemObject/Server/c7f77fa8-b38c-4dcc-8f94-bb7f93dd5605,/id/SystemObject/Server/11bd6400-6ed8-47ba-99cc-9c9faceb92e6
    • hostName(Optional) — Name of the host used in BMC Server Automation and VMware vCenter Server. For example: MyVM
    • name(Optional) — VM name used in VMware vCenter Server. It is required to include this parameter when the name used in VMware vCenter Server is different from the name used in BMC Server Automation. For example: TestVM
    • provider (Required) — URI of the BMC Server Automation provider. For example: /provider/cbc4152d-b823-4d19-a916-bf73278bba8e
  • resourceSetObject (Required) — the following ResourceSet class objects are used in the valueobject:
    • cloudClass(Required) — Fully qualifed name of the ResourceSet class
    • name(Required) — Resourceset name from the CLM blueprint. For example: Server Group 1

decommisionDate

Date

0..1

Date on which the service offering instance should be decommissioned

hostedResource

ComputeInfrastructure

0..1

Identifier of the infrastructure resource that hosts the VM. The identifier can be a VirtualCluster, VirtualHost, or VirtualResourcePool GUID:

  • For a virtual cluster, use the identifier of the target ESX cluster.
  • For a virtual resource pool, use the identifier of the resource pool.
  • For a virtual host, use the identifier of the target ESX server.

LogicalHostingEnvironmentId

String

1

LogicalHostingEnvironment identifier on which the Service will be onboarded

name

String

0..1

Name for the new service offering instance. For example: TestSOI

networkContainerID

String

1

Identifier of the network container in which to place the service offering instance

owner

String

1

User name of the service offering instance owner

serviceOffering

String

1

Reconciliation identifier of the service offering

serviceOfferingReconId

String

1

Reconciliation identifier of the service offering

tenant

String

1

Name of the tenant for the service offering instance

virtualGuest

VirtualGuest

1

In the JSON for this parameter, the following VirtualGuest class objects are used in the value object:

  • cloudClass(Required) — Fully qualifed name of the VirtualGuest class
  • externalID(Required) — URI of the VM and the VMware vCenter Server. For example: /id/SystemObject/Server/c7f77fa8-b38c-4dcc-8f94-bb7f93dd5605,/id/SystemObject/Server/11bd6400-6ed8-47ba-99cc-9c9faceb92e6
  • hostName(Optional) — Name of the host used in BMC Server Automation and VMware vCenter Server. For example: MyVM
  • name(Optional) — Name for the new service offering instance. For example: TestVM
  • provider (Required) — URI of the BMC Server Automation provider. For example: /provider/cbc4152d-b823-4d19-a916-bf73278bba8e

HTTP response message

Response message headers

This API uses only common headers listed in HTTP request and response headers.

Response message body

The response message body contains a Task object.

Examples

The following example shows an HTTP request that onboards a single-tier service offering instance using Format 1, which requires manual steps to onboard servers in BMC Server Automation.

To retrieve LogicalHostingEnvironmentId, use the example shown on LogicalHostingEnvironment search request.

{
    "timeout": -1,
    "preCallout": "",
    "postCallout": "",
    "operationParams": [
        {
            "name": "computeContainers",
            "type": "com.bmc.cloud.model.beans.ComputeContainer",
            "multiplicity": "1..*",
            "value": [
                {
                    "cloudClass": "com.bmc.cloud.model.beans.ComputeContainer",
                    "serverObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.VirtualGuest",
                        "hostName": "EPDONB1",
                        "name": "EPDONB1",
                        "provider": "/provider/0eb5f0bd-222d-481e-969f-30ada8629541",                      
						"externalID": "/id/SystemObject/Server/340f7114-b513-429a-9425
						-f70a95cc1955,/id/SystemObject/Server/bd72d0da-9028-4a95-9cda
						-09c42e0f8bfe"
                    },
                    "resourceSetObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.ResourceSet",
                        "name": "RS1"
                    }
                }
            ]
        },
        {
            "name": "serviceOfferingReconId",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "7467D7C5-D395-7133-3271-D38CF73071FA"
        },
        {
            "name": "LogicalHostingEnvironmentId",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "12dd53a6-f6a8-4116-8b6d-880bf436e236"
        },
        {
            "name": "tenant",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "BMC_Tenant"
        },
        {
            "name": "decommissionDate",
            "type": "java.util.Date",
            "multiplicity": "1",
            "value": 1402165833138
        },
        {
            "name": "name",
            "type": "java.lang.String",
            "multiplicity": "0..1",
            "value": "MultiONB"
        },
        {
            "name": "owner",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "pg_enduser"
        }
    ]
}

The following example shows an HTTP request that onboards a multi-tier service offering instance using Format 1, which requires manual steps to onboard servers in BMC Server Automation:

{
    "timeout": -1,
    "preCallout": "",
    "postCallout": "",
    "operationParams": [
        {
            "name": "computeContainers",
            "type": "com.bmc.cloud.model.beans.ComputeContainer",
            "multiplicity": "1..*",
            "value": [
                {
                    "cloudClass": "com.bmc.cloud.model.beans.ComputeContainer",
                    "serverObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.VirtualGuest",
                        "hostName": "EPDONB1",
                        "name": "EPDONB1",
                        "provider": "/provider/0eb5f0bd-222d-481e-969f-30ada8629541",
                        "externalID": "/id/SystemObject/Server/9808b979-61ad-4f72-ad05
						-d59f6bb316d8,/id/SystemObject/Server/bd72d0da-9028-4a95
						-9cda-09c42e0f8bfe"
                        
                    },
                    "resourceSetObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.ResourceSet",
                        "name": "RS1"
                    }
                },
                {
                    "cloudClass": "com.bmc.cloud.model.beans.ComputeContainer",
                    "serverObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.VirtualGuest",
                        "hostName": "EPDONB2",
                        "name": "EPDONB2",
                        "provider": "/provider/0eb5f0bd-222d-481e-969f-30ada8629541",
                        "externalID": "/id/SystemObject/Server/fe0b0d96-639a-4d4d
						-af34-061784567fcc,/id/SystemObject/Server/bd72d0da-9028
						-4a95-9cda-09c42e0f8bfe"
                    },
                    "resourceSetObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.ResourceSet",
                        "name": "RS2"
                    }
                }
            ]
        },
        {
            "name": "serviceOfferingReconId",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "42E5E490-D070-FF0D-A2B1-F3036AAA3DF1"
        },
        {
            "name": "LogicalHostingEnvironmentId",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "12dd53a6-f6a8-4116-8b6d-880bf436e236"
        },
        {
            "name": "tenant",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "BMC_Tenant"
        },
        {
            "name": "decommissionDate",
            "type": "java.util.Date",
            "multiplicity": "1",
            "value": 1402165833138
        },
        {
            "name": "name",
            "type": "java.lang.String",
            "multiplicity": "0..1",
            "value": "MultiONB"
        },
        {
            "name": "owner",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "pg_enduser"
        }
    ]
}

The following example shows an HTTP request that onboards a single-tier service offering instance using Format 2, in which servers are onboarded automatically in BMC Server Automation.

To derive serverNetworkInterfaceObject, which holds ipAddressesObject, you must perform the following searches:

  1. Perform a REST search for the Resource Manager (RM) provider. For an example, see Provider search request.
  2. Perform a REST search on the VirtualInfrastructureManager class with "name" as the search criteria. For an example, see VirtualInfrastructureManager search request.
  3. Use the guid the of RM provider and externalID of the Virtual Center (VC) from the responses received in the earlier steps, and search the compute container in the VC. For an example, see ComputeContainer search request.
{
    "timeout": -1,
    "preCallout": "",
    "postCallout": "",
    "operationParams": [
        {
            "name": "computeContainers",
            "type": "com.bmc.cloud.model.beans.ComputeContainer",
            "multiplicity": "1..*",
            "value": [
                {
                    "cloudClass": "com.bmc.cloud.model.beans.ComputeContainer",
                    "serverObject" : {
 					      "cloudClass" : "com.bmc.cloud.model.beans.VirtualGuest",
					      "provider": "/provider/0235987b-11e7-4760-ba1f-d42de6a0f7df",   
						  "externalID" : "/id/SystemObject/Server/195a7ba9-1124-42d2
						  -ba4b-5704708f21a0/Assets/BMC_VMware_
						  VirtualInfrastructureManager/VirtualMachines/MDC1,/
						  id/SystemObject/Server/195a7ba9-1124-42d2-ba4b-5704708f21a0",
 			              "name" : "MDC1",
 					      "serverNetworkInterfaceObject" : [ {
        "cloudClass" : "com.bmc.cloud.model.beans.ServerNetworkInterface",
        "guid" : "123bc558-ed94-433e-b1d0-9810e0b9b97e",
        "ipAddressesObject" : [ {
          "cloudClass" : "com.bmc.cloud.model.beans.IPAddress",
          "guid" : "5d7619a3-cca5-4799-b00f-ef7dd6cfd454",
          "ipAddress" : "10.21.15.131",
          "isPublic" : false
        } ],
        "isAttachedToManagementNetwork" : false,
        "isDHCP" : false,
        "isPublicIP" : false
      }, {
        "cloudClass" : "com.bmc.cloud.model.beans.ServerNetworkInterface",
        "guid" : "bde88a2d-2b7e-4b26-837d-fef962b3961a",
        "ipAddressesObject" : [ {
          "cloudClass" : "com.bmc.cloud.model.beans.IPAddress",
          "guid" : "a51d71d6-e704-464b-a3b5-46ec963dca31",
          "ipAddress" : "10.1.23.93",
          "isPublic" : false
        } ],
        "isAttachedToManagementNetwork" : false,
        "isDHCP" : false,
        "isPublicIP" : false
      } ]
    },
                    "resourceSetObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.ResourceSet",
                        "name": "RS1"
                    }
                }
            ]
        },
        {
            "name": "serviceOfferingReconId",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "C86D47F7-AADA-5A8E-8ED9-4882B513B0E0"
        },
        {
            "name": "LogicalHostingEnvironmentId",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "3e25d184-b207-45ff-a310-aaeb4bc02cbf"
        },
        {
            "name": "tenant",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "MD_Tenant"
        },
        {
            "name": "owner",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "md_user1"
        },
        {
            "name": "name",
            "type": "java.lang.String",
            "multiplicity": "0..1",
            "value": "SingleONB"
        }
    ]
}

The following example shows an HTTP request that onboards a multi-tier service offering instance using Format 2, in which servers are onboarded automatically in BMC Server Automation:

{
    "timeout": -1,
    "preCallout": "",
    "postCallout": "",
    "operationParams": [
        {
            "name": "computeContainers",
            "type": "com.bmc.cloud.model.beans.ComputeContainer",
            "multiplicity": "1..*",
            "value": [
                {
                    "cloudClass": "com.bmc.cloud.model.beans.ComputeContainer",
                    "serverObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.VirtualGuest",
                        "provider": "/provider/0eb5f0bd-222d-481e-969f-30ada8629541",
                        "externalID": "/id/SystemObject/Server/bd72d0da-9028-4a95-9cda-09c42e0f8bfe/Assets/BMC_VMware_VirtualInfrastructureManager/Virtual Machines/EPDONB1,/id/SystemObject/Server/bd72d0da-9028-4a95-9cda-09c42e0f8bfe",
                        "name": "EPDONB1",
                        "serverNetworkInterfaceObject": [
                            {
                                "cloudClass": "com.bmc.cloud.model.beans.ServerNetworkInterface",
                                "guid": "42240588-5aa5-4f3d-acfd-f7f98616ce3a",
                                "ipAddressesObject": [
                                    {
                                        "cloudClass": "com.bmc.cloud.model.beans.IPAddress",
                                        "guid": "bcbde380-fe56-4f81-85d4-6b26cc47cd7b",
                                        "ipAddress": "169.254.48.17",
                                        "isPublic": false
                                    }
                                ],
                                "isAttachedToManagementNetwork": false,
                                "isDHCP": false,
                                "isPublicIP": false
                            },
                            {
                                "cloudClass": "com.bmc.cloud.model.beans.ServerNetworkInterface",
                                "guid": "a58c2ad6-1765-4cfe-8a0a-85eb814b861c",
                                "ipAddressesObject": [
                                    {
                                        "cloudClass": "com.bmc.cloud.model.beans.IPAddress",
                                        "guid": "1a3afe69-d2ac-4c4c-9409-f80af58f46bd",
                                        "ipAddress": "10.1.23.12",
                                        "isPublic": false
                                    }
                                ],
                                "isAttachedToManagementNetwork": false,
                                "isDHCP": false,
                                "isPublicIP": false
                            }
                        ]
                    },
                    "resourceSetObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.ResourceSet",
                        "name": "RS1"
                    }
                },
                {
                    "cloudClass": "com.bmc.cloud.model.beans.ComputeContainer",
                    "serverObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.VirtualGuest",
                        "provider": "/provider/0eb5f0bd-222d-481e-969f-30ada8629541",
                        "externalID": "/id/SystemObject/Server/bd72d0da-9028-4a95-9cda-09c42e0f8bfe/Assets/BMC_VMware_VirtualInfrastructureManager/Virtual Machines/EPDONB2,/id/SystemObject/Server/bd72d0da-9028-4a95-9cda-09c42e0f8bfe",
                        "name": "EPDONB2",
                        "serverNetworkInterfaceObject": [
                            {
                                "cloudClass": "com.bmc.cloud.model.beans.ServerNetworkInterface",
                                "guid": "b2030712-b5ee-4184-9e5a-4c2e448efbd6",
                                "ipAddressesObject": [
                                    {
                                        "cloudClass": "com.bmc.cloud.model.beans.IPAddress",
                                        "guid": "59b3add0-0c2c-44ca-89ab-d08cab4e45e6",
                                        "ipAddress": "169.254.169.235",
                                        "isPublic": false
                                    }
                                ],
                                "isAttachedToManagementNetwork": false,
                                "isDHCP": false,
                                "isPublicIP": false
                            },
                            {
                                "cloudClass": "com.bmc.cloud.model.beans.ServerNetworkInterface",
                                "guid": "b7d6b631-7d7a-458d-b7ff-1e4b71a77fd7",
                                "ipAddressesObject": [
                                    {
                                        "cloudClass": "com.bmc.cloud.model.beans.IPAddress",
                                        "guid": "39de4605-f5aa-455a-9e72-b88509f60f6e",
                                        "ipAddress": "10.1.23.33",
                                        "isPublic": false
                                    }
                                ],
                                "isAttachedToManagementNetwork": false,
                                "isDHCP": false,
                                "isPublicIP": false
                            }
                        ]
                    },
                    "resourceSetObject": {
                        "cloudClass": "com.bmc.cloud.model.beans.ResourceSet",
                        "name": "RS2"
                    }
                }
            ]
        },
        {
            "name": "serviceOfferingReconId",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "42E5E490-D070-FF0D-A2B1-F3036AAA3DF1"
        },
        {
            "name": "LogicalHostingEnvironmentId",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "12dd53a6-f6a8-4116-8b6d-880bf436e236"
        },
        {
            "name": "tenant",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "BMC_Tenant"
        },
        {
            "name": "decommissionDate",
            "type": "java.util.Date",
            "multiplicity": "1",
            "value": 1402165833138
        },
        {
            "name": "name",
            "type": "java.lang.String",
            "multiplicity": "0..1",
            "value": "MultiONB"
        },
        {
            "name": "owner",
            "type": "java.lang.String",
            "multiplicity": "1",
            "value": "pg_enduser"
        }
    ]
}

The following example shows an HTTP response to the request. The response returns a Task object because the request is still being processed and is only 95% complete.

HTTP/1.1 200 OK
Date: Wed, 28 Mar 2012 08:41:47 GMT
BMC-Transaction-ID: 7206a3c3-b3f1-4ce9-8eb2-7c6622b790a6
Content-Type: application/json; charset=UTF-8
Content-Length: 680
Server: Jetty(6.1.x)

[
  {
    "cloudClass": "com.bmc.cloud.model.beans.Task", 
    "className": "ServiceOfferingInstance", 
    "completionTime": "-1", 
    "creationTime": "2012/03/28 01:41:47 PDT", 
    "errors": [ ], 
    "guid": "c003cf0e-70b9-4621-b1b9-618dd297a35f", 
    "isCallout": false, 
    "isError": false, 
    "isSuccess": false, 
    "operationName": "onboard", 
    "parentTaskInternalUUID": "37ebe4bf-49b0-4b06-a2da-26bd4d2f1cb8", 
    "taskInternalUUID": "dabfd81b-ff40-49f6-8511-f1755cd27bfd", 
    "taskProgress": 95, 
    "taskState": "SUSPENDED", 
    "taskStatusURI": "http://10.1.8.49:8080/csm/task/dabfd81b-ff40-49f6-8511-f1755cd27bfd/status", 
    "taskSubState": "createResourceSets"
  }
]

This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

Last modified by Lisa Greene on Mar 09, 2016
contributor-updated

Comments

Log in or register to comment.

ServiceOfferingInstance offboard request
ServiceOfferingInstance opsDecommission request
© Copyright 2024 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.