Criar artefatos personalizados para VMs do DevTest Labs

Artefatos são ferramentas, ações ou software que você pode adicionar às VMs do Azure DevTest Labs. Por exemplo, os artefatos podem executar scripts, instalar ferramentas ou executar ações como ingressar em um domínio. Os usuários do DevTest Labs podem adicionar artefatos às suas VMs e os administradores de laboratório podem especificar artefatos obrigatórios a serem adicionados a todas as VMs de laboratório.

Este artigo descreve como criar artefatos que provisionam VMs de laboratório. Um artefato consiste em um arquivo JSON de definição de artefato e outros arquivos de script armazenados em uma pasta de repositório Git. Você pode armazenar artefatos em um repositório Git público ou privado. Os administradores de laboratório podem adicionar repositórios de artefatos aos laboratórios para que todos os usuários do laboratório possam acessá-los.

Pré-requisitos

• Para criar e trabalhar com arquivos de definição de artefato, você precisa de um editor JSON. O Visual Studio Code está disponível para Windows, Linux e macOS.
• Para armazenar a definição do artefato e os arquivos de script, você precisa de uma conta do GitHub.

Entender arquivos de definição de artefato

Um arquivo de definição de artefato consiste em uma expressão JSON que especifica a ação a ser tomada em uma VM. O arquivo define um nome de artefato, um comando a ser executado e parâmetros disponíveis para o comando. Se o artefato contiver outros arquivos de script, você poderá consultar os arquivos pelo nome no arquivo de definição do artefato.

O exemplo a seguir mostra a estrutura básica de um arquivo de definição de artefato artifactfile.json .

  {
    "$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>"
    }
  }

A definição tem os seguintes elementos obrigatórios e opcionais:

Parâmetros de artefato

A parameters seção do arquivo de definição define as opções e os valores que os usuários podem especificar quando instalam o artefato. Você pode consultar esses parâmetros no runCommand.

A estrutura a seguir define um parâmetro:

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

Cada parâmetro requer um nome e a definição de parâmetro requer os seguintes elementos:

Parâmetros de cadeia de caracteres seguros

Para incluir segredos em uma definição de artefato, declare os segredos como cadeias de caracteres seguras usando a secureStringParam sintaxe na parameters seção do arquivo de definição. O description elemento permite qualquer cadeia de caracteres de texto, incluindo espaços, e apresenta a cadeia de caracteres na interface do usuário como caracteres mascarados.

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

O seguinte runCommand utiliza um script do PowerShell que aproveita a cadeia de caracteres segura criada pelo comando ConvertTo-SecureString. O script captura a saída para depuração, portanto, por segurança, não registre a saída no 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'), '\"')]"
  }

Expressões e funções de artefato

Você pode usar expressões e funções para construir o comando de instalação do artefato. As expressões são avaliadas quando o artefato é instalado.

As expressões podem aparecer em qualquer lugar em um valor de cadeia de caracteres JSON e sempre retornar outro valor JSON. Coloque expressões entre colchetes. [ ] Se você precisar usar uma cadeia de caracteres literal que comece com um colchete, use dois colchetes [[.

Normalmente, você usa expressões com funções para construir um valor. As chamadas de função são formatadas como functionName(arg1, arg2, arg3).

As funções comuns incluem:

O exemplo a seguir usa expressões com a concat função para construir um valor.

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

Criar um artefato personalizado

Você pode criar um artefato personalizado a partir de um arquivo de definição artifactfile.json de exemplo. O repositório público de artefatos do DevTest Labs tem uma biblioteca de artefatos. Você pode baixar um arquivo de definição de artefato e personalizá-lo para criar seus próprios artefatos.

1. Baixe o arquivo de definição artifactfile.json e o script artifact.ps1 do PowerShell de https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

2. Edite o arquivo de definição de artefato para fazer algumas alterações válidas em elementos e valores. No Visual Studio Code, você pode usar o IntelliSense para ver elementos válidos e opções de valor. Por exemplo, quando você edita o elemento targetOsType, o IntelliSense mostra a você as opções Windows ou Linux.

3. Armazene seu artefato em um repositório de artefatos Git público ou privado.

   • Armazene cada artifactfile.json arquivo de definição de artefato em um diretório separado com o mesmo nome do artefato.
   • Armazene os scripts que o comando de instalação faz referência no mesmo diretório que o arquivo de definição de artefato.

   A captura de tela a seguir mostra uma pasta de artefato de exemplo:

   

   Observação

   Para adicionar seus artefatos personalizados ao repositório de artefatos público do DevTest Labs, abra uma solicitação de pull no repositório.

Próximas etapas

• Adicionar artefatos a VMs do DevTest Labs
• Especificar artefatos obrigatórios a serem adicionados a todas as VMs de laboratório
• Adicionar um repositório de artefatos a um laboratório

Conteúdo relacionado

• Diagnosticar falhas de artefatos no laboratório
• Solucionar problemas ao aplicar artefatos