{"type":"doc","content":[{"type":"paragraph","content":[{"text":"This tutorial details how to deploy a virtual machine from either a running or a powered off virtual machine in the ITS Private Cloud and reconfigure the operating system (hostname, domain, gateway, dns, etc.) using the VSS CLI. It assumes you already have set up a VSS account with access to the REST API, a virtual machine with ","type":"text"},{"text":"operating system","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"VMware Tools installed","type":"text","marks":[{"type":"strong"}]},{"text":" which will be the source virtual machine.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"If you do not have a virtual machine with operating system installed, please refer to ","type":"text"},{"text":"Deploying a Development Environment","type":"text","marks":[{"type":"link","attrs":{"href":"https://eis-vss.atlassian.net/wiki/spaces/VSSPublic/pages/1356726285#DeployingaDevelopmentEnvironment-Deploying-a-Development-Environment"}}]},{"text":".","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"Source-Virtual-Machine"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-Source-Virtual-Machine"}},"macroMetadata":{"macroId":{"value":"4966ae9a-7ef4-480f-8eae-80f8215a9a24"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"DeployandreconfigureInstancefromClone-Source-Virtual-Machine"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-DeployandreconfigureInstancefromClone-Source-Virtual-Machine"}},"macroMetadata":{"macroId":{"value":"dc902093-561a-463b-989c-12a7d9ab6a11"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"text":"Source Virtual Machine","type":"text"}]},{"type":"paragraph","content":[{"text":"A source virtual machine can be either a powered on or off virtual machine. However, the power state is relevant in terms of deployment time. This is because when cloning a running virtual machine, first it creates a snapshot and then starts copying the data. Even though the memory data is not kept, it takes time to generate the snapshot. For this example, we will be using a powered on virtual machine with Ubuntu installed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Optional*","type":"text","marks":[{"type":"strong"}]},{"text":" First obtain the vm identifier ","type":"text"},{"text":"moref","type":"text","marks":[{"type":"code"}]},{"text":" (managed object reference) of the source virtual machine:","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"This version of the VSS CLI supports managing virtual machines not only using the UUID and Moref but using names. In case of multiple results, the CLI prompts to select the right instance.","type":"text"}]}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"vss-cli compute vm ls -f name=Front\n\nmoref name folder.path cpu_count memory_gb power_state ip_address\n------- ---------------- ------------------------- ----------- ----------- ------------- ------------\nvm-2182 2004T-Frontend-1 VSS > Development > Dev03 1 1 poweredOff","type":"text"}]},{"type":"paragraph","content":[{"text":"Save the ","type":"text"},{"text":"moref","type":"text","marks":[{"type":"code"}]},{"text":" in ","type":"text"},{"text":"MOREF","type":"text","marks":[{"type":"code"}]},{"text":" environment variable.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"Launch-Instance"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-Launch-Instance"}},"macroMetadata":{"macroId":{"value":"ed73ee4f-1883-4334-ad2d-98de0b30f68f"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"DeployandreconfigureInstancefromClone-Launch-Instance"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-DeployandreconfigureInstancefromClone-Launch-Instance"}},"macroMetadata":{"macroId":{"value":"8ef6beae-b417-4f33-819b-10cb0442c3cf"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"text":"Launch Instance","type":"text"}]},{"type":"paragraph","content":[{"text":"Launching an instance ","type":"text"},{"text":"from-clone","type":"text","marks":[{"type":"code"}]},{"text":" is simpler than ","type":"text"},{"text":"shell","type":"text","marks":[{"type":"code"}]},{"text":" since the ","type":"text"},{"text":"from-clone","type":"text","marks":[{"type":"code"}]},{"text":" command carbon copies source virtual machine specifications and creates an instance with just name and ","type":"text"},{"text":"--description/-d","type":"text","marks":[{"type":"code"}]},{"text":", however to make this example more realistic, we will specify a different logical folder, otherwise the ","type":"text"},{"text":"from-clone","type":"text","marks":[{"type":"code"}]},{"text":" command will use the source virtual machine folder, network, disks and domain.","type":"text"}]},{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"vss-cli compute vm mk from-clone --help","type":"text","marks":[{"type":"code"}]},{"text":" to obtain the list of arguments and options required:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"Usage: vss-cli compute vm mk from-clone [OPTIONS] [NAME]\n\n Clone virtual machine from running or powered off vm.\n\n If name argument is not specified, -clone suffix will be added to\n resulting virtual machine.\n\nOptions:\n -s, --source TEXT Source virtual machine or template MOREF or\n UUID. [required]\n -d, --description TEXT A brief description. [required]\n -b, --client TEXT Client department.\n -a, --admin TEXT Admin name, phone number and email separated\n by `:` i.e. \"John\n Doe:416-123-1234:john.doe@utoronto.ca\"\n -r, --inform TEXT Informational contact emails in comma\n separated\n -u, --usage [Test|Prod|Dev|QA] Vm usage.\n -o, --os TEXT Guest operating system id.\n -m, --memory INTEGER Memory in GB.\n -c, --cpu INTEGER Cpu count.\n --cores-per-socket INTEGER Cores per socket.\n -f, --folder TEXT Logical folder moref name or path.\n --scsi TEXT SCSI Controller Spec =.\n -i, --disk TEXT Disk spec\n ==.\n optional: backing_mode, backing_sharing\n -n, --net TEXT Network adapter =.\n -t, --domain TEXT Target fault domain name or moref.\n --notes TEXT Custom notes.\n -p, --custom-spec TEXT Guest OS custom specification in JSON\n format.\n -e, --extra-config TEXT Extra configuration key=value format.\n --power-on Power on after successful deployment.\n --template Mark the VM as template after deployment.\n --vss-service TEXT VSS Service related to VM\n --instances INTEGER Number of instances to deploy [default: 1]\n -w, --firmware TEXT Firmware type.\n --tpm Add Trusted Platform Module device.\n --storage-type TEXT Storage type.\n --snapshot TEXT Snapshot to clone.\n --retire-type [timedelta|datetime]\n Retirement request type.\n --retire-warning INTEGER Days before retirement date to notify\n --retire-value TEXT Value for given retirement type. i.e.\n ,,\n --help Show this message and exit.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"Network"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-Network"}},"macroMetadata":{"macroId":{"value":"7e3db73d-d503-4414-8ada-50f9bf80c9db"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"DeployandreconfigureInstancefromClone-Network"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-DeployandreconfigureInstancefromClone-Network"}},"macroMetadata":{"macroId":{"value":"21c749c7-d0fe-4501-90f2-328faf360462"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"text":"Network","type":"text"}]},{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"vss-cli compute net ls","type":"text","marks":[{"type":"code"}]},{"text":" to list available network segments to your account. You must have at least ","type":"text"},{"text":"VL-1584-VSS-PUBLIC","type":"text","marks":[{"type":"code"}]},{"text":" which is our public network.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"This version of the VSS CLI supports managing networks not only using the moref, but also using names. In case of multiple results, the CLI prompts to select the right instance.","type":"text"}]}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"vss-cli compute net ls -f name=PUBLIC\n\nmoref name description subnet ports\n----------------- ------------------ ------------------ -------------- -------\ndvportgroup-11052 VL-1584-VSS-PUBLIC VSS Public network 142.1.216.0/23 32","type":"text"}]},{"type":"paragraph","content":[{"text":"Save ","type":"text"},{"text":"dvportgroup-11052","type":"text","marks":[{"type":"code"}]},{"text":" in ","type":"text"},{"text":"NET","type":"text","marks":[{"type":"code"}]},{"text":" environment variable:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"export NET=dvportgroup-11052","type":"text"}]},{"type":"paragraph","content":[{"text":"By default, the network adapter will use ","type":"text"},{"text":"vmxnet3","type":"text","marks":[{"type":"strong"}]},{"text":" which provides ideal performance, however a few legacy operating systems does not have the drivers. In such case, you can specify which adapter type between: ","type":"text"},{"text":"e1000e*","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"e1000","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"vmxnet2","type":"text","marks":[{"type":"strong"}]},{"text":" or ","type":"text"},{"text":"vmxnet3","type":"text","marks":[{"type":"strong"}]},{"text":". To do so, append the adapter type to the network adapter network as follows:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"export NET=dvportgroup-11052=e1000e","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"Folder"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-Folder"}},"macroMetadata":{"macroId":{"value":"655df7ad-d528-46b0-bd7f-00595b95885e"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"DeployandreconfigureInstancefromClone-Folder"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-DeployandreconfigureInstancefromClone-Folder"}},"macroMetadata":{"macroId":{"value":"bd93ca42-e43c-4ceb-9000-30f7f91baf8f"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"text":"Folder","type":"text"}]},{"type":"paragraph","content":[{"text":"Logical folders can be listed by running ","type":"text"},{"text":"vss-cli compute folder ls","type":"text","marks":[{"type":"code"}]},{"text":". Select the target ","type":"text"},{"text":"moref","type":"text","marks":[{"type":"code"}]},{"text":" folder to store the virtual machine on:","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"This version of the VSS CLI supports managing logical folders not only using the moref, but also using name or path. In case of multiple results, the CLI prompts to select the right instance.","type":"text"}]}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"vss-cli compute folder ls -f name=API\n\nmoref name path parent.name\n----------- --------------- --------------------------------- ---------------\ngroup-v6736 APIDemo jm > Demo > APIDemo jm","type":"text"}]},{"type":"paragraph","content":[{"text":"Set the ","type":"text"},{"text":"FOLDER","type":"text","marks":[{"type":"code"}]},{"text":" environment variable to the target folder (the folder moref may vary):","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"export FOLDER=group-v6736","type":"text"}]},{"type":"paragraph","content":[{"text":"Before proceeding to deploy the virtual machine, a guest operating system customization specification needs to be created.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"Customization-Spec"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-Customization-Spec"}},"macroMetadata":{"macroId":{"value":"14fb0bea-fa95-468d-b577-b0d3983387c7"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"DeployandreconfigureInstancefromClone-Customization-Spec"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-DeployandreconfigureInstancefromClone-Customization-Spec"}},"macroMetadata":{"macroId":{"value":"065e3470-7e0a-476d-9a66-3848260f2105"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"text":"Customization Spec","type":"text"}]},{"type":"paragraph","content":[{"text":"Customizing a guest operating system is helpful to prevent conflicts if virtual machines are identical after deployed. To customize the guest operating system, VMware Tools and Perl must be installed in the source virtual machine.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"vss-cli compute vm mk from-clone","type":"text","marks":[{"type":"code"}]},{"text":" command provides the option ","type":"text"},{"text":"-p/--custom-spec","type":"text","marks":[{"type":"code"}]},{"text":" to pass the guest os customization spec, which is structured as follows:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"hostname\": \"string\",\n \"domain\": \"string\",\n \"dns\": [\n \"string\"\n ],\n \"dns_suffix\": [\n \"string\"\n ],\n \"interfaces\": [{\"dhcp\": \"bool\",\n \"ip\": \"string\",\n \"mask\": \"string\",\n \"gateway\": [\"string\"]\n }]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Since we are running on a DHCP-enabled network, we will just update the hostname and domain. The customization spec added will be:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"hostname\": \"fe1\",\n \"domain\": \"eis.utoronto.ca\",\n \"interfaces\": [{\"dhcp\": true}]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Serializing the above JSON structure would be something like:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"none"},"content":[{"text":"'{\"hostname\": \"fe1\", \"domain\": \"eis.utoronto.ca\", \"interfaces\": [{\"dhcp\": true}]}'","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Passing above JSON data structure to ","type":"text"},{"text":"--custom-spec","type":"text","marks":[{"type":"code"}]},{"text":" in Linux, macOS, or Unix and Windows PowerShell use the single quote ","type":"text"},{"text":"'","type":"text","marks":[{"type":"code"}]},{"text":" to enclose it. On the Windows command prompt, use the double quote ","type":"text"},{"text":"\"","type":"text","marks":[{"type":"code"}]},{"text":" to enclose the data structure and escape the double quotes from the data structure using the backslash ","type":"text"},{"text":"\\","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"Deployment"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-Deployment"}},"macroMetadata":{"macroId":{"value":"47b22d5a-f53c-49ad-a8cb-af2d0c6726a6"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"DeployandreconfigureInstancefromClone-Deployment"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-DeployandreconfigureInstancefromClone-Deployment"}},"macroMetadata":{"macroId":{"value":"d4236cb4-47b7-4675-b6f5-8c9258d0d867"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"text":"Deployment","type":"text"}]},{"type":"paragraph","content":[{"text":"At this point, we have all requirements to run ","type":"text"},{"text":"vss-cli compute vm mk from-clone","type":"text","marks":[{"type":"code"}]},{"text":" command to submit a deployment request. For this example, the request is made for 2GB of memory, 2 vCPU, 2x40GB disks and to reconfigure the hostname and domain.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Deploy multiple instances with the ","type":"text"},{"text":"--instances","type":"text","marks":[{"type":"code"}]},{"text":" flag.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Cloning a virtual machine from a specific snapshot state, use the ","type":"text"},{"text":"--snapshot","type":"text","marks":[{"type":"code"}]},{"text":" flag with the snapshot ","type":"text"},{"text":"id","type":"text","marks":[{"type":"code"}]},{"text":". For more information about how to list snapshots, please refer to the Snapshot example.","type":"text"}]}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"vss-cli compute vm mk --wait from-clone --power-on --source Frontend \\\n--client EIS --folder APIDemo \\\n--memory 2 --cpu 2 --disk 40 --disk 40 --net VSS \\\n--custom-spec '{\"hostname\": \"fe2\", \"domain\": \"eis.utoronto.ca\", \"interfaces\": [{\"dhcp\": true}]}' \\\n--storage-type hdd \\\n--description \"Frontend 2\" Frontend2","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"To wait for the deployment to complete, you could use the ","type":"text"},{"text":"--wait","type":"text","marks":[{"type":"code"}]},{"text":" flag at the ","type":"text"},{"text":"mk","type":"text","marks":[{"type":"code"}]},{"text":" command level: i.e. ","type":"text"},{"text":"vss-cli compute vm mk --wait from-clone ...`","type":"text","marks":[{"type":"code"}]}]}]},{"type":"paragraph","content":[{"text":"Wait a few minutes until the virtual machine is deployed.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"vss-cli request new ls -s created_on=desc -c 1\n\n id created_on updated_on status vm_moref vm_name approval.approved built_from\n---- --------------------------- --------------------------- --------- ---------- --------------- ------------------- ------------\n 76 2020-04-24 Fri 16:36:15 EDT 2020-04-24 Fri 16:37:31 EDT PROCESSED vm-2183 2004T-Frontend2 True clone","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"Access-Virtual-Machine"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-Access-Virtual-Machine"}},"macroMetadata":{"macroId":{"value":"b86e1bc7-5d6a-4a76-88a6-176d24b4f7ce"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"DeployandreconfigureInstancefromClone-Access-Virtual-Machine"},"legacyAnchorId":{"value":"DeployandreconfigureInstancefromClone-DeployandreconfigureInstancefromClone-Access-Virtual-Machine"}},"macroMetadata":{"macroId":{"value":"f9b3690d-4540-4a9a-9b1a-bedace2792b0"},"schemaVersion":{"value":"1"},"title":"Anchor"}}}},{"text":"Access Virtual Machine","type":"text"}]},{"type":"paragraph","content":[{"text":"Since we added the ","type":"text"},{"text":"--power-on","type":"text","marks":[{"type":"code"}]},{"text":" option, the virtual machine should have been powered on right after the Guest Operating System Customization task completed.","type":"text"}]},{"type":"paragraph","content":[{"text":"In a few minutes the virtual machine will show the hostname and ip configuration by running ","type":"text"},{"text":"vss-cli compute vm get guest","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"vss-cli compute vm get Frontend2 guest\n\nhostname : fe2\nip_address : 142.1.217.228, fe80::250:56ff:fe92:323f\nfull_name : CentOS 8 (64-bit)\nguest_id : centos8_64Guest\nrunning_status : guestToolsRunning","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Guest Host Name","type":"text","marks":[{"type":"strong"}]},{"text":" shows that the hostname has been changed, and now you will be able to access via either ","type":"text"},{"text":"ssh","type":"text","marks":[{"type":"code"}]},{"text":" or the virtual machine console:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"ssh username@","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"vss-cli compute vm get Frontend2 vsphere-link -l","type":"text"}]}],"version":1}

Browser not supported