DevTest Labs에 대한 사용자 지정 아티팩트 만들기

아티클
02/12/2024

이 문서에서는 Azure DevTest Labs VM(가상 머신)에 대한 사용자 지정 아티팩트 파일을 만드는 방법을 설명합니다. DevTest Labs 아티팩트는 VM을 프로비저닝하기 위해 수행할 작업을 지정합니다. 아티팩트는 아티팩트 정의 파일과 Git 리포지토리의 폴더에 저장하는 기타 스크립트 파일로 구성됩니다.

랩에 아티팩트 리포지토리를 추가하는 방법에 대한 자세한 내용은 랩에 아티팩트 리포지토리 추가를 참조하세요.
만든 아티팩트를 VM에 추가하는 방법에 대한 자세한 내용은 DevTest Labs VM에 아티팩트 추가를 참조하세요.
모든 랩 VM에 추가할 필수 아티팩트 지정에 대한 자세한 내용은 DevTest Labs VM에 대한 필수 아티팩트 지정을 참조하세요.

아티팩트 정의 파일

아티팩트 정의 파일은 VM에 설치하려는 항목을 지정하는 JSON 표현식입니다. 파일은 아티팩트의 이름, 실행할 명령 및 명령에 사용 가능한 매개 변수를 정의합니다. 아티팩트 정의 파일에서 이름으로 다른 스크립트 파일을 참조할 수 있습니다.

다음 예는 artifactfile.json 아티팩트 정의 파일의 기본 구조를 구성하는 섹션을 보여 줍니다.

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

요소 이름	설명
`$schema`	JSON 스키마 파일의 위치입니다. JSON 스키마 파일은 정의 파일의 유효성을 검사하는 데 도움이 될 수 있습니다.
`title`	랩에 표시할 아티팩트의 이름입니다. 필수입니다.
`description`	랩에 표시할 아티팩트에 대한 설명입니다. 필수입니다.
`iconUri`	랩에 표시할 아티팩트 아이콘의 URI입니다.
`targetOsType`	아티팩트를 설치할 VM의 운영 체제입니다. 지원되는 값: `Windows`, `Linux`. 필수입니다.
`parameters`	VM에 설치할 때 아티팩트를 사용자 지정하는 값입니다.
`runCommand`	VM에서 실행할 아티팩트 설치 명령입니다. 필수입니다.

아티팩트 매개 변수

정의 파일의 매개 변수 섹션에서 사용자가 아티팩트를 설치할 때 입력할 수 있는 값을 지정합니다. 아티팩트 설치 명령에서 다음 값을 참조할 수 있습니다.

매개 변수를 정의하려면 다음 구조를 사용합니다.

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }

요소 이름	설명
`type`	매개 변수 값의 형식입니다. 필수입니다.
`displayName`	랩 사용자에게 표시할 매개 변수의 이름입니다. 필수입니다.
`description`	랩 사용자에게 표시할 매개 변수에 대한 설명입니다. 필수입니다.

허용되는 매개 변수 값 형식은 다음과 같습니다.

Type	설명
`string`	모든 유효한 JSON 문자열
`int`	모든 유효한 JSON 정수
`bool`	모든 유효한 JSON 부울
`array`	모든 유효한 JSON 배열

보안 문자열로 된 비밀

UI에서 마스킹된 문자를 사용하여 보안 문자열 매개 변수로 비밀을 선언하려면 artifactfile.json 파일의 parameters 섹션에서 다음 구문을 사용합니다.


    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "Any text string is allowed, including spaces, and will be presented in UI as masked characters.",
      "allowEmpty": false
    },

PowerShell 스크립트를 실행하기 위한 아티팩트 설치 명령은 ConvertTo-SecureString 명령을 사용하여 만들어진 보안 문자열을 사용합니다.

  "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'), '\"')]"
  }

스크립트는 사용자 디버깅을 위한 출력을 캡처하므로 콘솔에 비밀을 기록하지 마세요.

아티팩트 식 및 함수

식과 함수를 사용하여 아티팩트 설치 명령을 구성할 수 있습니다. 식은 아티팩트가 설치될 때 평가됩니다. 식은 JSON 문자열 값에서 어느 위치에나 나타날 수 있으며 항상 다른 JSON 값을 반환합니다. 표현식을 [ ] 괄호로 묶습니다. 대괄호로 시작하는 리터럴 문자열을 사용해야 하는 경우 두 개의 대괄호 [[를 사용합니다.

일반적으로 함수와 함께 표현식을 사용하여 값을 구성합니다. 함수 호출은 functionName(arg1, arg2, arg3) 형식으로 지정됩니다.

일반적인 기능은 다음과 같습니다.

함수	설명
`parameters(parameterName)`	아티팩트 명령이 실행될 때 제공할 매개 변수 값을 반환합니다.
`concat(arg1, arg2, arg3, ...)`	여러 문자열 값을 결합합니다. 이 함수는 다양한 인수를 취할 수 있습니다.

다음 예제에서는 표현식과 함수를 사용하여 값을 구성합니다.

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

사용자 지정 아티팩트 만들기

사용자 지정 아티팩트를 만들려면 다음을 수행합니다.

아티팩트 정의 파일을 사용하려면 JSON 편집기를 설치합니다. Visual Studio Code는 Windows, Linux 및 macOS에서 사용할 수 있습니다.
샘플 artifactfile.json 정의 파일로 시작합니다.

공용 DevTest Labs 아티팩트 리포지토리에는 사용할 수 있는 풍부한 아티팩트 라이브러리가 있습니다. 아티팩트 정의 파일을 다운로드하고 사용자 지정하여 고유한 아티팩트를 작성할 수 있습니다.

이 문서에서는 https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes에서 artifactfile.json 정의 파일과 artifact.ps1 PowerShell 스크립트를 사용합니다.
IntelliSense를 사용하여 아티팩트 정의 파일을 구성하는 데 사용할 수 있는 유효한 요소와 값 옵션을 확인합니다. 예를 들어 targetOsType 요소를 편집하면 IntelliSense에서 Windows 또는 Linux 옵션을 표시합니다.
공용 또는 프라이빗 Git 아티팩트 리포지토리에 아티팩트를 저장합니다.
- 각 artifactfile.json 아티팩트 정의 파일을 아티팩트 이름과 동일한 이름의 별도 디렉터리에 저장합니다.
- 설치 명령이 참조하는 스크립트를 아티팩트 정의 파일과 동일한 디렉터리에 저장합니다.
다음 스크린샷은 아티팩트 폴더의 예를 보여 줍니다.
사용자 지정 아티팩트를 공용 DevTest Labs 아티팩트 리포지토리에 저장하려면 리포지토리에 대한 끌어오기 요청을 엽니다.
랩에 프라이빗 아티팩트 리포지토리를 추가하려면 DevTest Labs에서 랩에 아티팩트 리포지토리 추가를 참조하세요.

다음을 통해 공유