App Deployment
In this article, we’ll learn how to implement the App’s deployment.
To deploy an App successfully, you need to implement the following 4 methods:
- Deploy method creates the App’s VM instance.
- PowerOn method spins up the VM.
- remote_refresh_ip updates the deployed App’s IP address.
- GetVmDetails method gets information about the VM itself, its operating system, specifications and networking information.
These methods are executed in the above order during the deployment of an App in the sandbox (either automatically as part of the default sandbox setup script that runs when reserving a sandbox or manually by the user after adding an App to an active sandbox). Once the App is deployed, these methods can be run as individual commands from the deployed App’s commands pane, with the exception of the Deploy command which is no longer needed once the App is deployed.
Deploy method
Creates the App’s VM instance.
Signature
The deploy method accepts three inputs: context, request, and cancellation_context.
This Github Sample is by QualiSystems
def Deploy(self, context, request, cancellation_context=None):
Inputs
context
context: context is a ResourceCommandContext object that contains:
- reservation - current reservation details
- connectors – details of any visual connectors between the Cloud Provider App and other endpoints in the sandbox
- connectivity - CloudShell server connectivity data for authentication with CloudShell Automation API
- resource - resource configuration settings entered when creating the Cloud Provider resource in the Inventory dashboard
This Github Sample is by QualiSystems
cloudshell/shell/core/driver_context.py view raw
class ResourceCommandContext:
def __init__(self, connectivity, resource, reservation, connectors):
self.connectivity = connectivity # Connectivity details that can help connect to the APIs
""":type : ConnectivityContext"""
self.resource = resource # The details of the resource using the driver
""":type : ResourceContextDetails"""
self.reservation = reservation # The details of the reservation
""":type : ReservationContextDetails"""
self.connectors = connectors # The list of visual connectors and routes that are connected to the resource (the resource will be considered as the source end point)
""":type : list[Connector]"""
Request
request: request is an AppContext object that contains:
- Resource deployment path (in the App template’s Deployment Paths page)
- Deployed App configuration (in the App template’s App Resource page)
Example: app_request_json for App "Ubuntu OCI 18.04" that is connected to a single subnet service...
{
" ""driverRequest":" "{
" ""actions":" "[
" "{
" ""actionParams":" "{
" ""cidr":" ""10.0.1.32/28",
" ""subnetId":" ""ocid1.subnet.oc1.uk-london-1.aa...ovena",
" ""isPublic":" true",
" ""vnicName":" null",
" ""subnetServiceAttributes":" "[
" "
],
" ""type":" ""connectToSubnetParams"" "
},
" ""actionId":" ""bw23c565-5aba-40wa-9fba-69287rf542cf",
" ""type":" ""connectSubnet"" "
},
" "{
" ""actionParams":" "{
" ""appName":" ""Ubuntu OCI 18.04",
" ""deployment":" "{
"
""deploymentPath":" ""OCI Shell.OCI VM from Image",
" ""attributes":" "[
" "{
" ""attributeName":" ""OCI Shell.OCI VM from Image.Inbound Ports",
" ""attributeValue":" ""22",
" ""type":" ""attribute"" "
},
" "{
" ""attributeName":" ""OCI Shell.OCI VM from Image.Skip VNIC src or dst check",
" ""attributeValue":" ""False",
" ""type":" ""attribute"" "
},
" "{
" ""attributeName":" ""OCI Shell.OCI VM from Image.Autoload",
" ""attributeValue":" ""True",
" ""type":" ""attribute"" "
},
" "{
" ""attributeName":" ""OCI Shell.OCI VM from Image.Wait for IP",
" ""attributeValue":" ""True",
" ""type":" ""attribute"" "
},
" "{
" ""attributeName":" ""OCI Shell.OCI VM from Image.Image ID",
" ""attributeValue":" ""ocid1.image.oc1.uk-london-1.aausaaaagcmjzblg9wliwb2fxpr7t4nv7j4ertujgosyoctlkismlwi3cbq",
" ""type":" ""attribute"" "
},
" "{
" ""attributeName":" ""OCI Shell.OCI VM from Image.VM Shape",
" ""attributeValue":" ""VM.Standard2.4",
" ""type":" ""attribute"" "
},
" "{
" ""attributeName":" ""OCI Shell.OCI VM from Image.Add Public IP",
" ""attributeValue":" ""True",
" ""type":" ""attribute"" "
},
" "{
" ""attributeName":" ""OCI Shell.OCI VM from Image.Requested Private IP",
" ""attributeValue":" ""32.2.2.4;11.0.0.4;35.0.0.20",
" ""type":" ""attribute"" "
}" "
],
" ""type":" ""deployAppDeploymentInfo"" "
},
" ""appResource":" "{
" ""attributes":" "[
" "{
" ""attributeName":" ""Password",
" ""attributeValue":" ""encrypted password here",
" ""type":" ""attribute"" "
},
" "{
" ""attributeName":" ""Public IP",
" ""attributeValue":" """,
" ""type":" ""attribute"" "
},
" "{
" ""attributeName":" ""User",
" ""attributeValue":" ""ubuntu",
" ""type":" ""attribute"" "
}" "
],
" ""type":" ""appResourceInfo"" "
},
" ""type":" ""deployAppParams"" "
},
" ""actionId":" ""c1256ebf-01d9-4804-4oi9-63ad31s4s281",
" ""type":" ""deployApp"" "
}" "
]" "
}
}
cancellation_context
CloudShell supports the canceling of App command executions.
This Github Sample is by QualiSystems
cloudshell/shell/core/driver_context.py view raw
def __init__(self):
self.is_cancelled = False
""":type : bool"""
To allow the cancellation of a command on the Cloud Provider’s Apps, we need to:
- Check for cancellation before each operation. If cancelled, delete cloud objects created by operation.
- Return the appropriate result.
Usage example:
This Github Sample is by QualiSystems
src/heavenly_cloud_service_wrapper.py view raw
if cancellation_context.is_cancelled:
# rollback what we created for current executing command then raise exception
# HeavenlyCloudService.rollback()
raise Exception('Operation cancelled')
Output
DriverResponse object that contains a list of action results.
Error handling
If App deployment fails, return a "success false” action result.
Deploy method implementation
The deploy method should perform the following steps:
-
Retrieve the cloud provider resource’s connection credentials.
-
(Steps 4 - 8 are performed within the deploy logic) Generate a unique name for the App. For example, "My-App_968e-a950”. Deployed Apps are classified as resources in CloudShell and therefore must have a unique name.
-
Create a VM instance using the deployment path attributes (the HeavenlyCloud service represents your custom cloud SDK).
-
If VM deployment is successful:
- Collect VM details (operating system, specifications, networking information).
- Optionally, override App resource attribute values. For example, if we generate a unique password for each VM instance, we will also want to update this password in the Password attribute on the Deployed App Resource for future use (to allow the sandbox end-user to connect to the VM).
- If needed, add additional data to the action result. This key-value data will be available from all API resource queries. It can be useful for implementing custom logic during the lifecycle of the sandbox. Example.
-
If VM deployment fails, return a "fail” result.
Note that the links in the above workflow pertain to a driver of an L2 implementation. However, the only difference between L2 and L3 driver implementations is that L2 implements ApplyConnectivityChanges while L3 uses the PrepareSandboxInfra and CleanSandboxInfra methods.
DeployAppResult JSON example
Example...
{
" ""actionId":"aac7cc0c-a215-4aee-8fc1-f72020.1.034423",
" ""deployedAppAdditionalData":{
},
" ""deployedAppAddress":"192.168.0.5",
" ""deployedAppAttributes":[
" "{
" ""attributeName":"Password",
" ""attributeValue":"123456"" "
},
" "{
" ""attributeName":"User",
" ""attributeValue":"super user"" "
}" "
],
" ""errorMessage":"",
" ""infoMessage":"",
" ""success":true,
" ""type":"DeployApp",
" ""vmDetailsData":{
" ""appName":"",
" ""errorMessage":"",
" ""vmInstanceData":[
" "{
" ""hidden":false,
" ""key":"Cloud Name",
" ""value":"white"" "
},
" "{
" ""hidden":false,
" ""key":"Cloud Index",
" ""value":"0"" "
},
" "{
" ""hidden":false,
" ""key":"Cloud Size",
" ""value":"not so big"" "
},
" "{
" ""hidden":false,
" ""key":"Instance Name",
" ""value":"angel vm__ca11f5"" "
},
" "{
" ""hidden":true,
" ""key":"Hidden stuff",
" ""value":"something not for UI"" "
}" "
],
" ""vmNetworkData":[
" "{
" ""interfaceId":0,
" ""isPredefined":false,
" ""isPrimary":true,
" ""networkData":[
" "{
" ""hidden":false,
" ""key":"MaxSpeed",
" ""value":"1KB"" "
},
" "{
" ""hidden":false,
" ""key":"Network Type",
" ""value":"Ethernet"" "
}" "
],
" ""networkId":0,
" ""privateIpAddress":"10.0.0.0",
" ""publicIpAddress":"8.8.8.0"" "
},
" "{
" ""interfaceId":1,
" ""isPredefined":false,
" ""isPrimary":false,
" ""networkData":[
" "{
" ""hidden":false,
" ""key":"MaxSpeed",
" ""value":"1KB"" "
},
" "{
" ""hidden":false,
" ""key":"Network Type",
" ""value":"Ethernet"" "
}" "
],
" ""networkId":1,
" ""privateIpAddress":"10.0.0.1",
" ""publicIpAddress":"8.8.8.1"" "
}" "
]" "
},
" ""vmName":"angel vm__ca11f5",
" ""vmUuid":"027ad770-9ecb-4936-a7df-aeaf526dfc34"
}
DeployAppResult properties
| Name | Type | Description |
|---|---|---|
| actionId | string | (Mandatory) The action GUID as received (deploy_app_action.actionId) result must include the action id it results for, so server can match result to action. |
| deployedAppAddress | string | (Mandatory) The primary ip address of the VM instance. This value will be set as the deployed App’s resource address in CloudShell. |
| errorMessage | string | (Optional) Error message to be displayed to the sandbox end-user if VM deployment fails. |
| infoMessage | string | (Optional) Info message to be displayed to the sandbox end-user if VM deployment succeeds. |
| success | bool | (Mandatory) |
| type | string | (Read only) DeployApp object type. It is automatically set in DeployAppResult object type (in cloudshell-cp-core). |
| vmName | string | Unique name of the resource in CloudShell. |
| vmUuid | string | Unique resource id. Populate vmUuid with the unique id of the resource in your custom cloud provider. Cloudshell does not use this id, but will keep it for other method calls. |
| deployedAppAdditionalData | dictionary | Container used to persist custom data in resource, similar to AWS Tags. Included in all resource API query results. For example, reading the custom data and returning it in the VM Details. |
| deployedAppAttributes | array | Contains data describing the deployed app attributes, and are displayed in the App’s Attributes pane in the sandbox. It should be used to change default attribute values on the deployed App resource. For example User & Password attributes exist as part of the default deployed App model. If your custom cloud provider generates a password in runtime for the VM, you should update the deployedAppAttributes property accordingly. |
| vmDetailsData | object | Contains vmNetworkData and vmInstanceData. Displayed in the App’s VM Details pane. For details about the return data, see the GetVmDetails method’s Return value section below. |
PowerOn method
The PowerOn method spins up the VM. It is run automatically when reserving the sandbox, as part of CloudShell’s default sandbox setup script, and can also be run manually by the sandbox end-user from the deployed App’s commands pane. During PowerOn, the VM’s IP address and a green live status icon are displayed on the App in sandbox.
You don’t have to implement this method if the deploy method has been configured to spin up the VM. If PowerOn does not fail, CloudShell will set resource state to "online” once the VM is up.
Signature
def PowerOn(self, context, ports)
Inputs
context
context: context is a ResourceRemoteCommandContext object that contains:
- connectivity - CloudShell server connectivity data for authentication with CloudShell Automation API
- resource - resource configuration settings entered by the user when creating the Cloud Provider resource in the Inventory dashboard
- remote_reservation – reservation details
- remote_endpoints- will contain a single ResourceContextDetails object which provides data for the operation.
Ports
Legacy argument. Obsolete for custom cloud providers.
PowerOn method implementation
The PowerOn method should perform the following steps:
-
Retrieve the cloud provider resource’s connection credentials.
-
Convert the deployed_app_json context from string to object.
The json contains information about the CloudShell server, the deployed App and reservation.
For details, copy the json contents into your preferred JSON editor. For example:
-
Power on the deployed App resource.
PowerOn implementation example
This Github Sample is by QualiSystems
def PowerOn(self, context, ports):
"""
Will power on the compute resource
:param ResourceRemoteCommandContext context:
:param ports:
"""
with LoggingSessionContext(context) as logger, ErrorHandlingContext(logger):
self._log(logger, 'power_on_context', context)
self._log(logger, 'power_on_ports', ports)
cloud_provider_resource = L2HeavenlyCloudShell.create_from_context(context)
resource_ep = context.remote_endpoints[0]
deployed_app_dict = json.loads(resource_ep.app_context.deployed_app_json)
vm_uid = deployed_app_dict['vmdetails']['uid']
HeavenlyCloudServiceWrapper.power_on(cloud_provider_resource,vm_uid)
Return value
None
Error handling
In case of an error, the command should raise an exception.
remote_refresh_ip
The remote_refresh_ip method retrieves the VM’s updated IP address from the cloud provider and sets it on the deployed App resource. The IP of the main network interface also needs to be retrieved from the cloud provider. Both private and public IPs are retrieved, as appropriate.
remote_refresh_ip is run automatically during the sandbox’s setup, after the VM is created and connected to networks, and can also be run manually by the sandbox end-user by running the Refresh IP command in the sandbox.
Note: This method is mandatory. However, you can choose to disable the call to this method during setup using the Wait for IP attribute. For details, see Controlling App Deployment Orchestration.
Signature
def remote_refresh_ip(self, context, ports, cancellation_context):
Inputs
context
context: context is a ResourceRemoteCommandContext object that contains:
- connectivity - CloudShell server connectivity data for authentication with CloudShell Automation API
- resource - resource configuration settings entered when creating the Cloud Provider resource in the Inventory dashboard
- remote_reservation – reservation details
- remote_endpoints - will contain a single ResourceContextDetails object which provides data for the operation.
This Github Sample is by QualiSystems
cloudshell/shell/core/driver_context.py view raw
def __init__(self, connectivity, resource, remote_reservation, remote_endpoints):
self.connectivity = connectivity # Connectivity details that can help connect to the APIs
""":type : ConnectivityContext"""
self.resource = resource # The details of the resource using the driver
""":type : ResourceContextDetails"""
self.remote_reservation = remote_reservation # The details of the remote reservation
""":type : ReservationContextDetails"""
self.remote_endpoints = remote_endpoints
""":type : list[ResourceContextDetails]"""
Ports
Legacy argument. Obsolete for custom cloud providers.
Cancellation context
This Github Sample is by QualiSystems
cloudshell/shell/core/driver_context.py view raw
def __init__(self):
self.is_cancelled = False
""":type : bool"""
Return value
None.
Unlike other methods that update data using the result, remote_refresh_ip updates the deployed App resource with the IP by calling cloudshell-automation-api. However, if you implemented a return output, make sure to convert the remote_refresh_ip object to a string and pass the value to the "IP” attribute on the deployed App.
Error handling
If the operation fails, the command should raise an exception.
remote_refresh_ip method implementation
This method should perform the following steps:
-
Retrieve the Cloud Provider resource’s connection credentials.
-
Convert the deployed_app_json context from string to object.
-
Retrieve previously known private/public IPs (if there are any), VM instance id.
-
Verify that the deployed App’s private IP is the same as the ip in the cloud provider. If it’s different, update the deployed App ip with the IP on the cloud provider.
-
If the IPs are different, update the deployed App IP with the IP on the cloud provider by calling UpdateResourceAddress.
-
If the operation fails, display an error to the sandbox end-user.
-
-
If needed, verify that the deployed App’s public IP is the same as the ip in the cloud provider.
- If the IPs are different, update the deployed App ip with the ip on the cloud provider by calling SetAttributeValue and setting the Public IP attribute.
- If the operation fails, display an error to the sandbox end-user.
GetVmDetails method
The GetVmDetails method gets information about the App’s VM, operating system, specifications and networking information. It is called by the default setup script when reserving the sandbox, after the RefreshIp method is called, and can also be run manually by the sandbox end-user on deployed Apps from the App’s VM Details pane.
Note: The implementation is expected to query the cloud provider for the details, but not return any cached or stored data.
Signature
def GetVmDetails(self, context, requests, cancellation_context):
Inputs
context
context: context is a ResourceCommandContext object that contains:
-
connectivity - CloudShell server connectivity data for authentication with CloudShell Automation API
-
resource - resource configuration settings entered when creating the Cloud Provider resource in the Inventory dashboard
-
reservation – reservation details
-
connectors – details of any visual connectors between the Cloud Provider App and other endpoints in the sandbox
This Github Sample is by QualiSystems
cloudshell/shell/core/driver_context.py view raw
class ResourceCommandContext:
def __init__(self, connectivity, resource, reservation, connectors):
self.connectivity = connectivity # Connectivity details that can help connect to the APIs
""":type : ConnectivityContext"""
self.resource = resource # The details of the resource using the driver
""":type : ResourceContextDetails"""
self.reservation = reservation # The details of the reservation
""":type : ReservationContextDetails"""
self.connectors = connectors # The list of visual connectors and routes that are connected to the resource (the resource will be considered as the source end point)
""":type : list[Connector]"""
Requests
JSON string that contains a list of items containing App requests and deployed App data. This method can be called for a set of VMs.
Cancellation request
This Github Sample is by QualiSystems
cloudshell/shell/core/driver_context.py view raw
def __init__(self):
self.is_cancelled = False
""":type : bool"""
Return value
VmDetailsData object in a serialized JSON.
This Github Sample is by QualiSystems
package/cloudshell/cp/core/models.py view raw
def __init__(self, vmInstanceData=None, vmNetworkData=None,appName = '',errorMessage = ''):
"""
:param vmInstanceData: [VmDetailsProperty]
:param vmNetworkData: [VmDetailsNetworkInterface]
:param appName: str
:param errorMessage: str
"""
self.vmInstanceData = vmInstanceData if vmInstanceData else [] # type: [VmDetailsProperty]
self.vmNetworkData = vmNetworkData if vmNetworkData else [] # type: [VmDetailsNetworkInterface]
self.appName = appName
self.errorMessage = errorMessage
vmDetailsData properties
vmDetailsData is used to describe the App’s VM. All properties are optional.
| Name | Type | Description |
|---|---|---|
| appName | String | The App’s name. No need to assign it in the deploy operation. Must be assigned in getVmDetails method. |
| errorMessage | string | Indication message to be displayed to the sandbox end-user when getting the vmDetails. |
| vmNetworkData | array | Array of cloudshell-cp-core VmDetailsNetworkInterface object. Create a vmNetworkData object for each VM NIC you wish to associate with resource. See the VmDetailsNetworkInterface table below. |
| vmInstanceData | array | Array of cloudshell-cp-core’s VmDetailsProperty. Contains data about the VM instance attributes. It should be used to change persist values of the VM resource. For example to persist Storage and operating system data. See the VmDetailsProperty table below. |
VmDetailsNetworkInterface
| Name | Type | Description |
|---|---|---|
| interfaceId | String | The network interface id with which the address is associated. |
| networkId | string | The unique id of the network associated with the network interface. |
| isPrimary | bool | Determines if NIC is primary. Primary affects the default selected network in VmDetailsTab in cloudshell |
| isPredefined | bool | Determines if NIC is predefined. Predefined means that the network existed before the sandbox reservation. for example, a Static Management network that is not modeled in the blueprint. |
| networkData | array | Array of cloudshell-cp-core VmDetailsProperty. Contains data describing the NIC. Examples of network properties include Device Index and MAC Address. |
| privateIpAddress | string | NIC address. |
| publicIpAddress | string | The public ip associated with the NIC’s private ip. |
VmDetailsProperty
| Name | Type | Description |
|---|---|---|
| key | string | |
| value | string | |
| hidden | bool | Determines if the property is displayed to the sandbox end-user. |
GetVmDetails method implementation
This method should perform the following steps:
-
For each request, do the following:
-
Query the cloud provider for the VM’s configuration and networks.
-
Populate vmInstanceData with the data (key-value) you wish to persist on the VM resource. For example to persist the VM’s Storage & operating system data.
-
Create vmNetworkData. vmNetworkData is a list of VmDetailsNetworkInterface, one for each VM NIC you wish to associate with the resource.