• Introduction
• The CloudShell DevGuide
• Setting up the Development Environment
• Extending cloudshell with shells
• Getting Started
• Shell Drivers Overview
• The Shell Project Guide
• Modeling Shells with TOSCA
• Managing the Shell’s Data Model
• Getting Information from CloudShell
• Commands Visibility and Usability
• Driver Deep Dive
• Auto-discovery for Inventory Shells
• Discovering Inventory using SNMP
• Debugging Shell Driver Commands
• Deploying to Production
• Customizing Shells
• Common Driver Recipes
• Tips and Tricks
• Sharing a Shell with the Community
• 1st Gen Shells
• Orchestration scripts
• Getting Started
• Getting Information from CloudShell
• Script commands Visibility and Usability
• Scripts Deep Dive
• Common Orchestration Script Recipes
• CloudShell's OOB Orchestration
• Configuration management
• Overview
• Custom Scripts
• Adding Your Script to an App
• Tips and Tricks for Custom Scripts
• Ansible
• Ansible Playbook Examples
• Adding the Playbook to an App
• Tips and Tricks for Ansible Playbooks
• Extending cloudshell with cloud providers
• Getting Started with Cloud Providers
• Creating the Cloud Provider Shell
• The Cloud Provider Model
• Extending the Shell's Data Model
• Removing the Address Field
• Configuring Deployment Paths
• Controlling App Deployment Orchestration
• The Cloud Provider Interface
• Resource Discovery
• App Deployment
• Power off and Delete VM
• L2 Network Connectivity
• L3 Network Connectivity
• Cloudshell apis
• Available CloudShell APIs
• Automating CloudShell Sandboxes for DevOps
• Reference
• Python Coding Standards
• Shellfoundry
• Quali’s Shell Framework (Python 2)
• Quali’s Shell Framework (Python 3)
• Converting 1st Gen Shells into 2nd Gen
• Categories in 1st Gen Service Shells
• Mapping Connections using App Sub-resources
• L1 Switch Shells
• Short Development Videos
• Resource Scripts
• Custom Routing for Azure Apps
• Custom Sandbox Metadata
• Shells that Load a Static VM
• Intellisense in Shells and Scripts (using Docstrings)
• AWS Traffic Mirroring
• Common CloudShell Packages
• Migrating Shells to Python 3

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:

1. Deploy creates the App’s VM instance.
2. PowerOn spins up the VM.
3. remote_refresh_ip updates the deployed App’s IP address.
4. GetVmDetails 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.

def Deploy(self, context, request, cancellation_context=None):

Inputs

context

context: context is a ResourceCommandContext object that contains:

1. connectivity - CloudShell server connectivity data for authentication with CloudShell Automation API
2. resource - resource configuration settings entered when creating the Cloud Provider resource in the Inventory dashboard
3. reservation - current reservation details
4. connectors – details of any visual connectors between the Cloud Provider App and other endpoints in the sandbox

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 object that contains the resource deployment path and deployed App configuration (in the App template’s App Resource page).

cancellation_context

CloudShell supports the canceling of App command executions.

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:

1. Check for cancellation before each operation. If cancelled, delete cloud objects created by operation.
2. Return the appropriate result.

Usage example

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:

1. Retrieve the cloud provider resource’s connection credentials.
2. Retrieve the Deploy action.
3. Call the Deploy logic of the selected deployment type.
4. (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.
5. Create a VM instance using the deployment path attributes (the HeavenlyCloud service represents your custom cloud SDK).
6. 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.
7. If VM deployment fails, return a “fail” result.
8. Return DeployAppResult.
9. Return DriverResponse.

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

{
  "actionId": "aac7cc0c-a215-4aee-8fc1-f79.3.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

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 is a ResourceRemoteCommandContext object that contains:

1. connectivity - CloudShell server connectivity data for authentication with CloudShell Automation API
2. resource - resource configuration settings entered by the user when creating the Cloud Provider resource in the Inventory dashboard
3. remote_reservation – reservation details
4. 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:

1) Retrieve the cloud provider resource’s connection credentials.

2) 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:

3) Power on the deployed App resource.

PowerOn implementation example

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 is a ResourceRemoteCommandContext object that contains:

1. connectivity - CloudShell server connectivity data for authentication with CloudShell Automation API
2. resource - resource configuration settings entered when creating the Cloud Provider resource in the Inventory dashboard
3. remote_reservation – reservation details
4. remote_endpoints - will contain a single ResourceContextDetails object which provides data for the operation.

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

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:

1. Retrieve the Cloud Provider resource’s connection credentials.
2. Convert the deployed_app_json context from string to object.
3. Retrieve previously known private/public IPs (if there are any), VM instance id.
4. 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.
5. 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 is a ResourceCommandContext object that contains:

1. connectivity - CloudShell server connectivity data for authentication with CloudShell Automation API
2. resource - resource configuration settings entered when creating the Cloud Provider resource in the Inventory dashboard
3. reservation – reservation details
4. connectors – details of any visual connectors between the Cloud Provider App and other endppoints in the sandbox

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

def __init__(self):
    self.is_cancelled = False
    """:type : bool"""

Return value

VmDetailsData object in a serialized JSON.

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.

VmDetailsNetworkInterface

VmDetailsProperty

GetVmDetails method implementation

This method should perform the following steps:

1. Retrieve cloud provider resource connection credentials.
2. Convert the JSON string to object
3. For each request, do the following:
   • Retrieve identifiers.
   • 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.
   • Collect as VmDetailsData result.
4. Convert to JSON and return the result.