Developing Custom Artifacts for DevTest Labs: Tips and Tricks

In Getting started with DevTest Labs Custom Artifact Development we covered getting your development environment established.  Now we'll dive into some general tips and tricks you can use to improve your development experience as well as aid you as you build and debug your artifacts.

Platform-Agnostic Tips and Tricks

Extracting your Azure Resource Manager Template

There doesn't seem to be any way to extract the Azure Resource Manager (RM) template after your VM has been created. If your aim is to recreate your lab VM later via the command line, you will want to store this AzureRM template before you click Create on your VM. To store your Azure RM template, do the following:

  1. Configure your VM from the Lab VM blade in Azure DevTest Labs
  2. Before you click on the Create button, notice there is a View ARM template link at the bottom of the configuration blade
  3. Click View ARM template > , the View Azure Resource Manager Template blade will appear
  4. Click anywhere in the Azure RM text in the new blade, and press Ctrl+a to select everything
  5. Click Ctrl+c to copy the Azure RM text
  6. Open a text editor (such as Visual Studio Code) and create a new file
  7. Press Ctrl+v to paste the Azure RM text into the new file
  8. Save the Azure RM template file to someplace you can refer to later from within your text editor

Keeping your Development Iteration Time Low

You will get a bit faster iteration times if you create a single VM and then just apply your artifact to it over and over, rather than creating a VM every time you want to test your artifact. Apply artifacts to an existing VM by right-clicking on it in the DevTest Labs blade and choosing `Apply artifacts`.

Platform-Specific Tips

Windows artifacts

  1. Find programs or utilities that can be installed in quiet or unattended mode
    For example any installer that can be run using msiexec.exe /q would be easier to work with.  Graphical installers can hang during installation and cause excessive wait times and potential errors.
  2. Leverage package managers in lieu of downloading assets from other locations
    You may want to ensure that some prerequisites are installed prior to your artifact being installed, and having a consistent method of accessing these prerequisites is important.
  3. When using package managers to install dependencies, make sure the packages being used have checksums
    Try to avoid running choco with the --ignore-checksums argument.
  4. Mistakes happen
    If you need to check for error logs on a Windows VM, you can do so by checking the C:\packages\plugins\<<ARTIFACTNAME>> folder on the machine.  You can also check out this blog post by Tarun Arora on troubleshooting failing artifacts.
  5. planning on invoking any platform Cmdlets?
    If you are planning on invoking any platform Cmdlets (Azure, AD management, etc.) from your Powershell script during artifact installation, make sure you include the install step and/or a check command for those Cmdlets.

Linux artifacts

  1. When developing scripts for DevTest labs in Linux it helps iteration time when using getopt style parameter lists.
    To achieve this, each parameter (--param-name) begins a 'token parsing mode' that makes every subsequent parameter taken from the command line to be appended to that parameter's value until another 'token parsing mode' is encountered. You can see examples of how to implement such a token parsing routine in the linux-apt-package and linux-yum-package artifacts.
  2. When iterating on the script, be sure to make yourself familiar with SSH and SCP - Putty on Windows for instance comes with both.
    This makes it very easy to simply write and iterate on the script you are developing on your Azure DevTest lab VM, and then copy it back to your local machine for submitting to Git. Of course, just hooking git up from your lab VM would be fine as well, but that requires authentication to be setup on the VM.
  3. Sorting out how to debug the scripts can be daunting at first.
    Once you understand that there is indeed logging being sent to `/var/log/azure/Microsoft.OSTCExtensions.CustomScripttForLinux/[ver]/extensions.log` it's easier to iterate on your work. The feedback loop is a bit too long, as you have to check-in your artifact to Git first, to the master branch (unless your admin added a feature branch just for you), then you need to run the artifact against an existing or new VM. Here is another opportunity for you to use SCP to just grab the log file from your VM to your local machine so you can peruse it there.
  4. If you want to get further logging fanciness, use the 'logger' utility present on many linux distros by default.
    This writes to stdout as well as to `/var/log/syslog`. If you use this utility you can log into the VM and do a `tail -f /var/log/syslog` to watch your artifact get applied. You can see an example of using the 'logger' utility in the linux-apt-package, linux-yum-package, and linux-npm-package artifacts.
  5. If you develop your Linux artifact on a windows machine (and you haven't made the right choices for line endings, or employed a sensible .gitattributes file) there is a good chance the line endings will be wrong for Linux.
    If you use an editor (such as Visual Studio Code) it will tell you what the line endings are (CRLF for dos/windows and LF for UNIX) in the bottom-right status bar, and you can select a more appropriate line-ending setting for your file during development by clicking on the status bar line-ending indication and selecting the one you want from the menu bar that appears at the top of the screen. Better yet, ensure that you set the appropriate line-ending preference in your .gitattributes file for linux-specific script files.

We hope you enjoy your artifact developing experience with DevTest Labs.  Candid feedback and success stories are always welcome!