Create custom artifacts for DevTest Labs VMs

Artifacts are tools, actions, or software you can add to Azure DevTest Labs VMs. For example, artifacts can run scripts, install tools, or take actions like joining a domain. DevTest Labs users can add artifacts to their VMs, and lab administrators can specify mandatory artifacts to be added to all lab VMs.

This article describes how to create artifacts that provision lab VMs. An artifact consists of an artifact definition JSON file and other script files stored in a Git repository folder. You can store artifacts in a private or public Git repository. Lab administrators can add artifact repositories to labs so all lab users can access them.

Prerequisites

• To create and work with artifact definition files, you need a JSON editor. Visual Studio Code is available for Windows, Linux, and macOS.
• To store the artifact definition and script files, you need a GitHub account.

Understand artifact definition files

An artifact definition file consists of a JSON expression that specifies the action to take on a VM. The file defines an artifact name, a command to run, and parameters available for the command. If the artifact contains other script files, you can refer to the files by name in the artifact definition file.

The following example shows the basic structure of an artifactfile.json artifact definition file.

  {
    "$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
    "title": "<title>",
    "description": "<description>",
    "iconUri": "",
    "targetOsType": "<os>",
    "parameters": {
      "<paramName>": {
        "type": "<type>",
        "displayName": "<display name>",
        "description": "<description>"
      }
    },
    "runCommand": {
      "commandToExecute": "<command>"
    }
  }

The definition has the following required and optional elements:

Artifact parameters

The parameters section of the definition file defines the options and values users can specify when they install the artifact. You can refer to these parameters in the runCommand.

The following structure defines a parameter:

  "parameters": {
    "<name>": {
      "type": "<type>",
      "displayName": "<display name>",
      "description": "<description>"
    }
  }

Each parameter requires a name, and the parameter definition requires the following elements:

Secure string parameters

To include secrets in an artifact definition, declare the secrets as secure strings by using the secureStringParam syntax in the parameters section of the definition file. The description element allows any text string, including spaces, and presents the string in the UI as masked characters.

    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "<any text string>",
      "allowEmpty": false
    },

The following runCommand uses a PowerShell script that takes the secure string created by using the ConvertTo-SecureString command. The script captures output for debugging, so for security don't log the output to the console.

  "runCommand": {
    "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./artifact.ps1 -StringParam ''', parameters('stringParam'), ''' -SecureStringParam (ConvertTo-SecureString ''', parameters('securestringParam'), ''' -AsPlainText -Force) -IntParam ', parameters('intParam'), ' -BoolParam:$', parameters('boolParam'), ' -FileContentsParam ''', parameters('fileContentsParam'), ''' -ExtraLogLines ', parameters('extraLogLines'), ' -ForceFail:$', parameters('forceFail'), '\"')]"
  }

Artifact expressions and functions

You can use expressions and functions to construct the artifact install command. Expressions evaluate when the artifact installs.

Expressions can appear anywhere in a JSON string value, and always return another JSON value. Enclose expressions with brackets, [ ]. If you need to use a literal string that starts with a bracket, use two brackets [[.

You usually use expressions with functions to construct a value. Function calls are formatted as functionName(arg1, arg2, arg3).

Common functions include:

The following example uses expressions with the concat function to construct a value.

  runCommand": {
      "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./startChocolatey.ps1'
  , ' -RawPackagesList ', parameters('packages')
  , ' -Username ', parameters('installUsername')
  , ' -Password ', parameters('installPassword'))]"
  }

Create a custom artifact

You can create a custom artifact by starting from a sample artifactfile.json definition file. The public DevTest Labs artifact repository has a library of artifacts. You can download an artifact definition file and customize it to create your own artifacts.

1. Download the artifactfile.json definition file and artifact.ps1 PowerShell script from https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

2. Edit the artifact definition file to make some valid changes to elements and values. In Visual Studio Code, you can use IntelliSense to see valid elements and value options. For example, when you edit the targetOsType element, IntelliSense shows you Windows or Linux options.

3. Store your artifact in a public or private Git artifact repository.

   • Store each artifactfile.json artifact definition file in a separate directory named the same as the artifact name.
   • Store the scripts that the install command references in the same directory as the artifact definition file.

   The following screenshot shows an example artifact folder:

   

   Note

   To add your custom artifacts to the public DevTest Labs artifact repository, open a pull request against the repo.

Next steps

• Add artifacts to DevTest Labs VMs
• Specify mandatory artifacts to be added to all lab VMs
• Add an artifact repository to a lab

Related content

• Diagnose artifact failures in the lab
• Troubleshoot issues when applying artifacts