CloudShell Colony

#Installing the Azure DevOps Plugin

##Step 1: Installing

1. Open the CloudShell Colony Plugin page in Visual Studio's Marketplace.
2. Click Get it free.
3. Log in to VisualStudio.com and select the organization that will use this plugin. Click Install.

NOTE: If you are not the organization’s admin, you may send a request to the admin to install the plugin for you.

Your plugin is now installed.

##Step 2: Configuring the Azure DevOps Plugin

1. Open your VisualStudio.com project

   • Open the Project Settings/Services page
   • Click New service connection and select CloudShell Colony.
   • To the Connection Name, enter "Colony".

2. In CloudShell Colony, open the Settings page and click Integrations.

   • Under the Azure DevOps icon click Connect Now.
   • Copy the automatically generated token.
   • Switch back to Azure DevOps Web UI and paste the token into this field.

     NOTE: The token value is generated by CloudShell Colony.

   • Click Verify connection and make sure the connection succeeds.

#Launching a Sandbox from your Azure DevOps Pipeline

After installing and configuring the Azure DevOps plugin, you can launch sandboxes from your Azure DevOps Pipeline.

Use the available build steps to create a sandbox from any blueprint, retrieve its details, start your tests and end the sandbox when it's no longer needed.

##Preparing the Azure DevOps Build

1. Open your visualstudio.com project.
2. In the Build and release page, create a new build or edit an existing build.
3. Create a New Task in one of your build agent’s jobs.
4. In the New Task form search for Cloudshell Colony.

The following tasks are displayed:

• CloudShell Colony End Sandbox (ends a sandbox with CloudShellColony).
• CloudShell Colony Start Sandbox (starts a sandbox with CloudShell Colony).

NOTE: If you do not see above tasks, it means that the plugin was not successfully installed.

##Launching a Sandbox

1. Add the CloudShell Colony Start Sandbox task to your pipeline.

2. Open the task settings and enter the following parameters:

   • Service Connection – Enter "Colony". This is the name of the connection that you entered when you created the Colony service connection during the plugin configuration.
   • Timeout- Set the timeout for this step, if your sandbox will not be ready when the timeout is reached, CloudShell Colony will abort the deployment.
   • Space name - enter a name for your CloudShell Colony space.
   • Blueprint name - Enter the name of the blueprint you would like to use for creating this sandbox.

   NOTE: To specify one of CloudShell Colony’s sample blueprints, use a [sample] prefix.

   • Sandbox name - Enter a name for the sandbox
   • Artifacts - If this blueprint has artifacts, you may specify them in a comma separated list of artifact names and their values. e.g., artifact1 name=value1, artifact2 name=value2
   • Inputs - If this blueprint has inputs, you may specify them in a comma separated list of input names and their values. e.g., input1 name=value1, input2 name=value2

3. Expand the Output Variable section and in the Reference name field, enter "Colony". CloudShell Colony uses this variable to return the following sandbox details:

   • Colony.Sandbox_Id– the identifier of the created sandbox. You will use this identifier to end your sandbox when needed.
   • Colony.Sandbox_Details– All the sandbox details including instances' IP addresses, ports and other infrastructure details required to properly run your tests. You may query this parameter to get the required information. ##Ending a Sandbox from your Pipeline

4. Add the CloudShell Colony End Sandbox task to your pipeline.

5. Open the task's settings and enter the following parameters:

   • Service Connection – Enter "Colony". This is the name of the connection that you entered when you created the Colony service connection during the plugin configuration.
   • Space name- Enter the name of your CloudShell Colony space.
   • Sandbox ID- Enter the ID of the sandbox you want to end. Use $(Colony.Sandbox_Id) to dynamically get the sandbox Id from the CloudShell Colony object that was returned from a Start Sandbox task.