You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/devtest-labs/add-artifact-vm.md
+43-46Lines changed: 43 additions & 46 deletions
Original file line number
Diff line number
Diff line change
@@ -1,57 +1,55 @@
1
1
---
2
2
title: Add an artifact to a VM
3
-
description: Learn how to add an artifact to a virtual machine in a lab in Azure DevTest Labs
3
+
description: Learn how to add an artifact to a virtual machine in a lab in Azure DevTest Labs.
4
4
ms.topic: how-to
5
-
ms.date: 06/26/2020
5
+
ms.date: 01/04/2022
6
6
ms.custom: devx-track-azurepowershell
7
7
---
8
8
9
-
# Add an artifact to a VM
10
-
While creating a VM, you can add existing artifacts to it. These artifacts can be from either the [public DevTest Labs Git repository](https://github.com/Azure/azure-devtestlab/tree/master/Artifacts) or from your own Git repository. This article shows you how to add artifacts in the Azure portal, and by using Azure PowerShell.
9
+
# Add artifacts to DevTest Labs VMs
11
10
12
-
Azure DevTest Labs*artifacts*let you specify *actions* that are performed when the VM is provisioned, such as running Windows PowerShell scripts, running Bash commands, and installing software. Artifact *parameters* let you customize the artifact for your particular scenario.
11
+
You can add*artifacts*to Azure DevTest Labs virtual machines (VMs). DevTest Labs artifacts specify actions to perform when provisioning a VM, such as running Windows PowerShell scripts, running Bash commands, or installing software. You can use parameters to customize artifacts for your scenarios.
13
12
14
-
To learn about how to create custom artifacts, see the article: [Create custom artifacts](devtest-lab-artifact-author.md).
13
+
DevTest Labs artifacts can come from the [public DevTest Labs Git repository](https://github.com/Azure/azure-devtestlab/tree/master/Artifacts) or from private Git repositories. To create your own custom artifacts and store them in a repository, see [Create custom artifacts](devtest-lab-artifact-author.md). To add your artifact repository to a lab so lab users can access the custom artifacts, see [Add an artifact repository to your lab in DevTest Labs](add-artifact-repository.md).
This article describes how to add available artifacts to VMs in the Azure portal or by using Azure PowerShell.
16
+
17
+
## Add artifacts to VMs from the Azure portal
18
+
19
+
1. In the [Azure portal](https://go.microsoft.com/fwlink/p/?LinkID=525040), go to the lab that has the VM you want to add artifacts to.
20
+
1. On the lab **Overview** page, under **My virtual machines**, select the VM you want to add artifacts to.
21
+
1. On the VM page, select **Artifacts** in the top menu bar or left navigation.
22
+
1. On the **Artifacts** page, select **Apply artifacts**.
23
+
1. On the **Add artifacts** page, select the arrow next to each artifact you want to add to the VM.
24
+
1. On each **Add artifact** pane, enter any required and optional parameter values, and then select **OK**.
25
+
1. When you're done adding artifacts, select **Install**.
26
+
27
+
After the artifacts install, they appear on the VM's **Artifacts** page.
17
28
18
-
## Use Azure portal
19
-
1. Sign in to the [Azure portal](https://go.microsoft.com/fwlink/p/?LinkID=525040).
20
-
1. Select **All Services**, and then select **DevTest Labs** from the list.
21
-
1. From the list of labs, select the lab containing the VM with which you want to work.
22
-
1. Select **My virtual machines**.
23
-
1. Select the desired VM.
24
-
1. Select **Manage artifacts**.
25
-
1. Select **Apply artifacts**.
26
-
1. On the **Apply artifacts** pane, select the artifact you wish to add to the VM.
27
-
1. On the **Add artifact** pane, enter the required parameter values and any optional parameters that you need.
28
-
1. Select **Add** to add the artifact and return to the **Apply artifacts** pane.
29
-
1. Continue adding artifacts as needed for your VM.
30
-
1. Once you've added your artifacts, you can [change the order in which the artifacts are run](#change-the-order-in-which-artifacts-are-run). You can also go back to [view or modify an artifact](#view-or-modify-an-artifact).
31
-
1. When you're done adding artifacts, select **Apply**
32
-
33
-
### Change the order in which artifacts are run
34
-
By default, the actions of the artifacts are executed in the order in which they are added to the VM.
35
-
The following steps illustrate how to change the order in which the artifacts are run.
29
+
<!-- After you add artifacts, you can modify them or change the order they run in.
30
+
31
+
### View or modify artifacts
32
+
33
+
To view installed artifacts, select **Artifacts** from the top menu bar on the VM's **Overview** page.
34
+
35
+
To modify an artifact, select it from the list on the **Artifacts** page.
36
+
1. On the **Add artifact** pane, make any needed changes, and select **OK** to close the **Add artifact** pane.
37
+
38
+
### Change the order to run artifacts
39
+
40
+
By default, artifact actions execute in the order you added them to the VM. To change the order in which the artifacts are run.
36
41
37
42
1. At the top of the **Apply artifacts** pane, select the link indicating the number of artifacts that have been added to the VM.
38
43
39
44
40
45
1. On the **Selected artifacts** pane, drag and drop the artifacts into the desired order. If you have trouble dragging the artifact, make sure that you are dragging from the left side of the artifact.
41
-
1. Select **OK** when done.
46
+
1. Select **OK** when done. -->
42
47
43
-
### View or modify an artifact
44
-
The following steps illustrate how to view or modify the parameters of an artifact:
48
+
## Add artifacts to VMs by using Azure PowerShell
45
49
46
-
1. At the top of the **Apply artifacts** pane, select the link indicating the number of artifacts that have been added to the VM.
47
-
48
-
49
-
1. On the **Selected artifacts** pane, select the artifact that you want to view or edit.
50
-
1. On the **Add artifact** pane, make any needed changes, and select **OK** to close the **Add artifact** pane.
51
-
1. Select **OK** to close the **Selected artifacts** pane.
The following script applies the specified artifact to the specified VM. The [Invoke-AzResourceAction](/powershell/module/az.resources/invoke-azresourceaction) command is the one that performs the operation.
52
+
The following PowerShell script applies an artifact to a VM by using the [Invoke-AzResourceAction](/powershell/module/az.resources/invoke-azresourceaction) cmdlet.
55
53
56
54
```powershell
57
55
#Requires -Module Az.Resources
@@ -60,13 +58,13 @@ param
60
58
(
61
59
[Parameter(Mandatory=$true, HelpMessage="The ID of the subscription that contains the lab")]
62
60
[string] $SubscriptionId,
63
-
[Parameter(Mandatory=$true, HelpMessage="The name of the lab containing the virtual machine")]
61
+
[Parameter(Mandatory=$true, HelpMessage="The name of the lab that has the VM")]
64
62
[string] $DevTestLabName,
65
-
[Parameter(Mandatory=$true, HelpMessage="The name of the virtual machine")]
63
+
[Parameter(Mandatory=$true, HelpMessage="The name of the VM")]
66
64
[string] $VirtualMachineName,
67
65
[Parameter(Mandatory=$true, HelpMessage="The repository where the artifact is stored")]
68
66
[string] $RepositoryName,
69
-
[Parameter(Mandatory=$true, HelpMessage="The artifact to apply to the virtual machine")]
67
+
[Parameter(Mandatory=$true, HelpMessage="The artifact to apply to the VM")]
title: Create custom artifacts for your Azure DevTest Labs virtual machine
3
-
description: Learn how to create and use artifacts to deploy and set up applications after you provision a virtual machine.
2
+
title: Create custom artifacts for Azure DevTest Labs virtual machines
3
+
description: Learn how to create and use artifacts to deploy and set up applications on DevTest Labs virtual machines.
4
4
ms.topic: how-to
5
-
ms.date: 06/26/2020
5
+
ms.date: 01/04/2022
6
6
---
7
7
8
-
# Create custom artifacts for your DevTest Labs virtual machine
8
+
# Create custom artifacts for DevTest Labs virtual machine
9
9
10
-
Watch the following video for an overview of the steps described in this article:
10
+
You can add *artifacts* to Azure DevTest Labs virtual machines (VMs). DevTest Labs artifacts specify actions to perform when provisioning a VM. An artifact consists of an artifact definition file and other script files that you store in a folder in a Git repository.
This article describes how to create custom artifact files. For information about adding artifacts to VMs, see [Add artifacts to DevTest Labs VMs](add-artifact-vm.md). For information about adding artifact repositories to labs, see [Add an artifact repository to your lab in DevTest Labs](add-artifact-repository.md).
15
13
16
-
## Overview
17
-
You can use *artifacts* to deploy and set up your application after you provision a VM. An artifact consists of an artifact definition file and other script files that are stored in a folder in a Git repository. Artifact definition files consist of JSON expressions that specify what you want to install on a VM. For example, you can define the name of an artifact, a command to run, and available parameters for the command. You can refer to other script files within the artifact definition file by name.
14
+
## Artifact definition files
18
15
19
-
## Artifact definition file format
20
-
The following example shows the sections that make up the basic structure of a definition file:
16
+
Artifact definition files are JSON expressions that specify what you want to install on a VM. The files define the name of an artifact, a command to run, and available parameters for the command. You can refer to other script files by name within the artifact definition file.
17
+
18
+
The following example shows the sections that make up the basic structure of an *artifactfile.json* definition file:
21
19
22
20
```json
23
21
{
@@ -39,18 +37,19 @@ The following example shows the sections that make up the basic structure of a d
39
37
}
40
38
```
41
39
42
-
| Element name |Required? |Description |
43
-
| --- | --- | --- |
44
-
|`$schema`|No |Location of the JSON schema file. The JSON schema file can help you test the validity of the definition file.|
45
-
|`title`|Yes |Name of the artifact displayed in the lab. |
46
-
|`description`|Yes |Description of the artifact displayed in the lab. |
47
-
|`iconUri`|No |URI of the icon displayed in the lab.|
48
-
|`targetOsType`|Yes |Operating system of the VM where the artifact is installed. Supported options are Windows and Linux. |
49
-
|`parameters`|No |Values that are provided when the artifact install command is run on a machine. Parameters help you customize your artifact. |
50
-
|`runCommand`|Yes |Artifact install command that is executed on a VM. |
40
+
| Element name | Description |
41
+
| --- | --- |
42
+
|`$schema`|Location of the JSON schema file. The JSON schema file can help you test the validity of the definition file.|
43
+
|`title`|Name of the artifact to display in the lab. **Required.**|
44
+
|`description`|Description of the artifact to display in the lab. **Required.**|
45
+
|`iconUri`|URI of the icon to display in the lab.|
46
+
|`targetOsType`|Operating system of the VM to install the artifact on. Supported values: `Windows`, `Linux`. **Required.**|
47
+
|`parameters`|Values to customize the artifact when installing on the VM.|
48
+
|`runCommand`|The artifact install command to execute on the VM. **Required.**|
51
49
52
50
### Artifact parameters
53
-
In the parameters section of the definition file, specify which values a user can input when they install an artifact. You can refer to these values in the artifact install command.
51
+
52
+
In the parameters section of the definition file, specify values a user can input when installing an artifact. You can refer to these values in the artifact install command.
54
53
55
54
To define parameters, use the following structure:
56
55
@@ -64,21 +63,24 @@ To define parameters, use the following structure:
64
63
}
65
64
```
66
65
67
-
| Element name | Required? | Description |
68
-
| --- | --- | --- |
69
-
|`type`|Yes |Type of parameter value. See the following list for the allowed types. |
70
-
|`displayName`|Yes |Name of the parameter that is displayed to a user in the lab. |
71
-
|`description`|Yes |Description of the parameter that is displayed in the lab. |
66
+
| Element name | Description |
67
+
| --- | --- |
68
+
|`type`|Type of parameter value. **Required.**|
69
+
|`displayName`|Name of the parameter to display to the lab user. **Required.**|
70
+
|`description`|Description of the parameter to display to the lab user. **Required.**|
71
+
72
+
Allowed parameter value types are:
72
73
73
-
Allowed types are:
74
+
| Type | Description |
75
+
| --- | --- |
76
+
|`string`|Any valid JSON string|
77
+
|`int`|Any valid JSON integer|
78
+
|`bool`|Any valid JSON boolean|
79
+
|`array`|Any valid JSON array|
74
80
75
-
*`string` (any valid JSON string)
76
-
*`int` (any valid JSON integer)
77
-
*`bool` (any valid JSON Boolean)
78
-
*`array` (any valid JSON array)
81
+
### Secrets as secure strings
79
82
80
-
## Secrets as secure strings
81
-
Declare secrets as secure strings. Here's the syntax for declaring a secure string parameter within the `parameters` section of the **artifactfile.json** file:
83
+
To declare secrets as secure string parameters with masked characters in the UI, use the following syntax in the `parameters` section of the *artifactfile.json* file:
82
84
83
85
```json
84
86
@@ -90,29 +92,30 @@ Declare secrets as secure strings. Here's the syntax for declaring a secure stri
90
92
},
91
93
```
92
94
93
-
For the artifact install command, run the PowerShell script that takes the secure string created by using the ConvertTo-SecureString command.
95
+
In the artifact install command, run the PowerShell script that takes the secure string created by using the `ConvertTo-SecureString` command.
For the complete example artifactfile.json and the artifact.ps1 (PowerShell script), see [this sample on GitHub](https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes).
103
+
Don't log secrets to the console, because the script captures output for user debugging.
102
104
103
-
Another important point to note is to not log secrets to the console, as output is captured for user debugging.
105
+
### Artifact expressions and functions
104
106
105
-
## Artifact expressions and functions
106
-
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, [ and ]. If you need to use a literal string that starts with a [ bracket, use two brackets [[.
107
+
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, \[ and \]. If you need to use a literal string that starts with a bracket, use two brackets \[\[.
107
108
108
-
Typically, you use expressions with functions to construct a value. Just like in JavaScript, function calls are formatted as **functionName(arg1, arg2, arg3)**.
109
+
You usually use expressions with functions to construct a value. Function calls are formatted as `functionName(arg1, arg2, arg3)`.
109
110
110
-
The following list shows common functions:
111
+
Common functions include:
111
112
112
-
***parameters(parameterName)**: Returns a parameter value that is provided when the artifact command is run.
113
-
***concat(arg1, arg2, arg3,….. )**: Combines multiple string values. This function can take various arguments.
113
+
| Function | Description |
114
+
| --- | --- |
115
+
|`parameters(parameterName)`|Returns a parameter value to provide when the artifact command runs.|
116
+
|`concat(arg1, arg2, arg3, ...)`|Combines multiple string values. This function can take various arguments.|
114
117
115
-
The following example shows how to use expressions and functions to construct a value:
118
+
The following example uses expressions and functions to construct a value:
116
119
117
120
```json
118
121
runCommand": {
@@ -125,23 +128,30 @@ The following example shows how to use expressions and functions to construct a
125
128
126
129
## Create a custom artifact
127
130
128
-
1. Install a JSON editor. You need a JSON editor to work with artifact definition files. We recommend using [Visual Studio Code](https://code.visualstudio.com/), which is available for Windows, Linux, and OS X.
129
-
2. Get a sample artifactfile.json definition file. Check out the artifacts created by the DevTest Labs team in our [GitHub repository](https://github.com/Azure/azure-devtestlab). We've created a rich library of artifacts that can help you create your own artifacts. Download an artifact definition file and make changes to it to create your own artifacts.
130
-
3. Make use of IntelliSense. Use IntelliSense to see valid elements that you can use to construct an artifact definition file. You also can see the different options for values of an element. For example, when you edit the **targetOsType** element, IntelliSense shows you two choices, for Windows or Linux.
131
-
4. Store the artifact in the [public Git repository for DevTest Labs](https://github.com/Azure/azure-devtestlab/tree/master/Artifacts) or [your own Git repository](devtest-lab-add-artifact-repo.md). In the public repository, you can view artifacts shared by others that you can use directly or customize them to suit your needs.
132
-
133
-
1. Create a separate directory for each artifact. The directory name should be the same as the artifact name.
134
-
2. Store the artifact definition file (artifactfile.json) in the directory that you created.
135
-
3. Store the scripts that are referenced from the artifact install command.
136
-
137
-
Here's an example of how an artifact folder might look:
131
+
To create a custom artifact:
132
+
133
+
- Install a JSON editor to work with artifact definition files. [Visual Studio Code](https://code.visualstudio.com/) is available for Windows, Linux, and MacOS.
134
+
135
+
- Start with a sample *artifactfile.json* definition file.
136
+
137
+
The public [DevTest Labs artifact repository](https://github.com/Azure/azure-devtestlab/tree/master/Artifacts) has a rich library of artifacts you can use. You can download an artifact definition file and customize it to create your own artifacts. This article uses the *artifactfile.json* definition file and *artifact.ps1* PowerShell script at [https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes](https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes).
138
+
139
+
- Use IntelliSense to see valid elements and value options you can use to construct an artifact definition file. For example, when you edit the `targetOsType` element, IntelliSense shows you `Windows` or `Linux` options.
140
+
141
+
- Store your artifacts in public or private Git artifact repositories.
142
+
143
+
- Store each *artifactfile.json* artifact definition file in a separate directory named the same as the artifact name.
144
+
- Store the scripts that the install command references in the same directory as the artifact definition file.
138
145
139
-
140
-
5. If you're using your own repository to store artifacts, add the repository to the lab by following instructions in the article: [Add a Git repository for artifacts and templates](devtest-lab-add-artifact-repo.md).
146
+
The following screenshot shows an an example artifact folder:
147
+
148
+
141
149
142
-
## Related articles
143
-
*[How to diagnose artifact failures in DevTest Labs](devtest-lab-troubleshoot-artifact-failure.md)
144
-
*[Join a VM to an existing Active Directory domain by using a Resource Manager template in DevTest Labs](https://www.visualstudiogeeks.com/blog/DevOps/Join-a-VM-to-existing-AD-domain-using-ARM-template-AzureDevTestLabs)
150
+
- To store your custom artifacts in the public [DevTest Labs artifact repository](https://github.com/Azure/azure-devtestlab/tree/master/Artifacts), open a pull request against the repo.
151
+
- To add your private artifact repository to a lab, see [Add an artifact repository to your lab in DevTest Labs](add-artifact-repository.md).
145
152
146
153
## Next steps
147
-
* Learn how to [add a Git artifact repository to a lab](devtest-lab-add-artifact-repo.md).
154
+
155
+
-[Add artifacts to DevTest Labs VMs](add-artifact-vm.md)
156
+
-[Diagnose artifact failures in the lab](devtest-lab-troubleshoot-artifact-failure.md)
157
+
-[Troubleshoot issues when applying artifacts](devtest-lab-troubleshoot-apply-artifacts.md)
1. On the **Configuration and policies** pane, select **Custom images**.
16
+
This article describes how to create a custom image in the Azure portal. You can also [use PowerShell](devtest-lab-create-custom-image-from-vhd-using-powershell.md) to create a custom image.
29
17
30
-
1. On the **Custom images** pane, select **+Add**.
1. Enter the name of the custom image. This name is displayed in the list of base images when creating a VM.
22
+
To create a custom image from a VHD file in DevTest Labs in the Azure portal, follow these steps:
35
23
36
-
1.Enter the description of the custom image. This description is displayed in the list of base images when creating a VM.
24
+
1.In the [Azure portal](https://go.microsoft.com/fwlink/p/?LinkID=525040), go to the **Overview** page for the lab that has the uploaded VHD file.
37
25
38
-
1.For**OS type**, select either **Windows** or **Linux**.
26
+
1.Select**Configuration and policies** in the left navigation.
39
27
40
-
- If you select **Windows**, specify via the checkbox whether *sysprep* has been run on the machine.
41
-
- If you select **Linux**, specify via the checkbox whether *deprovision* has been run on the machine.
28
+
1. On the **Configuration and policies** pane, select **Custom images** under **Virtual machine bases** in the left navigation.
42
29
43
-
1.Select a**VHD**from the drop-down menu. This is the VHD that will be used to create the new custom image. If necessary, select to **Upload a VHD using PowerShell**.
30
+
1.On the**Custom images**page, select **Add**.
44
31
45
-
1. You can also enter a plan name, plan offer, and plan publisher if the image used to create the customimage is not a licensed image (published by Microsoft).
32
+
46
33
47
-
-**Plan name:** Enter the name of the Marketplace image (SKU) from which this custom image is created
48
-
-**Plan offer:** Enter the product (offer) of the Marketplace image from which this custom image is created
49
-
-**Plan publisher:** Enter the publisher of the Marketplace image from which this custom image is created
34
+
1. On the **Add custom image** page:
50
35
51
-
> [!NOTE]
52
-
> If the image you are using to create a custom image is **not** a licensed image, then these fields are empty and can be filled in if you choose. If the image **is** a licensed image, then the fields are auto populated with the plan information. If you try to change them in this case, a warning message is displayed.
53
-
>
54
-
>
36
+
- Enter a name for the custom image to display in the list of base images for creating a VM.
37
+
- Enter an optional description to display in the base image list.
38
+
- Under **OS type**, select whether the OS for the VHD and custom image is **Windows** or **Linux**.
39
+
- If you select **Windows**, select the checkbox if you ran *sysprep* on the machine before you created the VHD file.
40
+
- If you select **Linux**, select the checkbox if you ran *deprovision* on the machine before you created the VHD file.
55
41
56
-
1.Select**OK** to create the custom image.
42
+
1.Under**VHD**, select the uploaded VHD file for the custom image from the drop-down menu.
57
43
58
-
After a few minutes, the custom image is created and is stored inside the lab’s storage account. When a lab user wants to create a new VM, the image is available in the list of base images.
44
+
1. Optionally, enter a plan name, plan offer, and plan publisher if the VHD image isn't a licensed image published by Microsoft. If the image is a licensed image, these fields are pre-populated with the plan information.
59
45
60
-
46
+
-**Plan name:** Name of the non-Microsoft Marketplace image or SKU used to create the VHD image.
47
+
-**Plan offer:** Product or offer name for the Marketplace image.
48
+
-**Plan publisher:** Publisher of the Marketplace image.
64
53
65
-
## Related blog posts
54
+
After creation, the custom image is stored in the lab's storage account. The custom image appears in the list of VM base images. Lab users can create new VMs based on the custom image.
66
55
67
-
-[Custom images or formulas?](./devtest-lab-faq.yml#blog-post)
68
-
-[Copying Custom Images between Azure DevTest Labs](https://www.visualstudiogeeks.com/blog/DevOps/How-To-Move-CustomImages-VHD-Between-AzureDevTestLabs#copying-custom-images-between-azure-devtest-labs)
56
+
69
57
70
58
## Next steps
71
59
72
-
-[Add a VM to your lab](./devtest-lab-add-vm.md)
60
+
-[Add a VM to your lab](./devtest-lab-add-vm.md)
61
+
-[Compare custom images and formulas in DevTest Labs](devtest-lab-comparing-vm-base-image-types.md)
62
+
-[Copying Custom Images between Azure DevTest Labs](https://www.visualstudiogeeks.com/blog/DevOps/How-To-Move-CustomImages-VHD-Between-AzureDevTestLabs#copying-custom-images-between-azure-devtest-labs)
0 commit comments