Criar artefatos personalizados para Máquinas Virtuais do DevTest Labs

Artefactos são ferramentas, ações ou software que podes adicionar às VMs do Azure DevTest Labs. Por exemplo, os artefactos podem executar scripts, instalar ferramentas ou tomar ações como juntar-se a um domínio. Os utilizadores do DevTest Labs podem adicionar artefactos às suas VMs, e os administradores de laboratório podem especificar artefactos obrigatórios a serem adicionados a todas as VMs de laboratório.

Este artigo descreve como criar artefactos que fornecem VMs de laboratório. Um artefacto consiste num ficheiro JSON de definição de artefacto e outros ficheiros de script armazenados numa pasta de repositório Git. Pode armazenar artefactos num repositório Git privado ou público. Os administradores de laboratório podem adicionar repositórios de artefactos aos laboratórios para que todos os utilizadores possam aceder a eles.

Pré-requisitos

• Para criar e trabalhar com ficheiros de definição de artefactos, precisas de um editor JSON. O Visual Studio Code está disponível para Windows, Linux e macOS.
• Para armazenar a definição de artefactos e os ficheiros de script, precisas de uma conta no GitHub.

Compreender ficheiros de definição de artefactos

Um ficheiro de definição de artefacto consiste numa expressão JSON que especifica a ação a tomar numa VM. O ficheiro define um nome de artefacto, um comando a executar e parâmetros disponíveis para o comando. Se o artefacto contiver outros ficheiros de script, pode referir-se aos ficheiros pelo nome no ficheiro de definição do artefacto.

O exemplo seguinte mostra a estrutura básica de um ficheiro de definição de artefactos 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 do artefato

A parameters secção do ficheiro de definição define as opções e valores que os utilizadores podem especificar quando instalam o artefacto. Pode referir-se a estes parâmetros no runCommand.

A seguinte estrutura define um parâmetro:

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

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

Parâmetros de string seguros

Para incluir segredos numa definição de artefacto, declare os segredos como strings seguras usando a secureStringParam sintaxe na parameters secção do ficheiro de definição. O description elemento permite qualquer cadeia de texto, incluindo espaços, e apresenta a cadeia na interface como caracteres mascarados.

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

O seguinte runCommand utiliza um script PowerShell que recebe a string segura criada ao usar o ConvertTo-SecureString comando. O script capta a saída para depuração, por isso, por segurança, não registas a saída na consola.

  "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 artefactos

Podes usar expressões e funções para construir o comando de instalação de artefactos. As expressões avaliam quando o artefacto é instalado.

As expressões podem aparecer em qualquer lugar de um valor de string JSON e devolver sempre outro valor JSON. Inclua expressões entre parênteses, [ ]. Se precisares de usar uma cadeia de caracteres literal que comece por um colchete, usa dois colchetes [[.

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

Funções comuns incluem:

O exemplo seguinte 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 artefacto personalizado

Pode criar um artefacto personalizado começando por um ficheiro de definição de amostra artifactfile.json. O repositório público de artefactos DevTest Labs tem uma biblioteca de artefactos. Podes descarregar um ficheiro de definição de artefactos e personalizá-lo para criar os teus próprios artefactos.

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

2. Edite o ficheiro de definição de artefactos para fazer algumas alterações válidas aos elementos e valores. No Visual Studio Code, 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 as opções Windows ou Linux.

3. Guarda o teu artefacto num repositório Git público ou privado.

   • Armazene cada ficheiro de definição de artifactfile.json artefacto num diretório separado com o mesmo nome do artefacto.
   • Armazene os scripts referenciados pelo comando de instalação no mesmo diretório do ficheiro de definição do artefacto.

   A captura de ecrã seguinte mostra um exemplo de pasta de artefactos:

   

   Observação

   Para adicionar os seus artefactos personalizados ao repositório público de artefactos do DevTest Labs, abra um pull request contra o repositório.

Próximos passos

• Adicionar artefatos às VMs DevTest Labs
• Especifique artefactos obrigatórios a adicionar a todas as VMs de laboratório
• Adicionar um repositório de artefactos a um laboratório

Conteúdo relacionado

• Diagnosticar falhas de artefactos no laboratório
• Resolução de problemas ao aplicar artefactos