github.com/aclaygray/packer@v1.3.2/website/source/docs/builders/azure.html.md (about) 1 --- 2 description: 'Packer supports building VHDs in Azure Resource manager.' 3 layout: docs 4 page_title: 'Azure - Builders' 5 sidebar_current: 'docs-builders-azure' 6 --- 7 8 # Azure Resource Manager Builder 9 10 Type: `azure-arm` 11 12 Packer supports building VHDs in [Azure Resource Manager](https://azure.microsoft.com/en-us/documentation/articles/resource-group-overview/). Azure provides new users a [$200 credit for the first 30 days](https://azure.microsoft.com/en-us/free/); after which you will incur costs for VMs built and stored using Packer. 13 14 Unlike most Packer builders, the artifact produced by the ARM builder is a VHD (virtual hard disk), not a full virtual machine image. This means you will need to [perform some additional steps](https://github.com/Azure/packer-azure/issues/201) in order to launch a VM from your build artifact. 15 16 Azure uses a combination of OAuth and Active Directory to authorize requests to the ARM API. Learn how to [authorize access to ARM](/docs/builders/azure-setup.html). 17 18 The documentation below references command output from the [Azure CLI](https://azure.microsoft.com/en-us/documentation/articles/xplat-cli-install/). 19 20 ## Configuration Reference 21 22 The following configuration options are available for building Azure images. In addition to the options listed here, a 23 [communicator](/docs/templates/communicator.html) can be configured for this 24 builder. 25 26 ### Required: 27 28 - `client_id` (string) The Active Directory service principal associated with your builder. 29 30 - `client_secret` (string) The password or secret for your service principal. 31 32 - `subscription_id` (string) Subscription under which the build will be performed. **The service principal specified in `client_id` must have full access to this subscription, unless build_resource_group_name option is specified in which case it needs to have owner access to the existing resource group specified in build_resource_group_name parameter.** 33 34 - `image_publisher` (string) PublisherName for your base image. See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details. 35 36 CLI example `az vm image list-publishers --location westus` 37 38 - `image_offer` (string) Offer for your base image. See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details. 39 40 CLI example `az vm image list-offers --location westus --publisher Canonical` 41 42 - `image_sku` (string) SKU for your base image. See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details. 43 44 CLI example `az vm image list-skus --location westus --publisher Canonical --offer UbuntuServer` 45 46 #### VHD or Managed Image 47 48 The Azure builder can create either a VHD, or a managed image. If you 49 are creating a VHD, you **must** start with a VHD. Likewise, if you 50 want to create a managed image you **must** start with a managed 51 image. When creating a VHD the following two options are required. 52 53 - `capture_container_name` (string) Destination container name. Essentially the "directory" where your VHD will be 54 organized in Azure. The captured VHD's URL will be `https://<storage_account>.blob.core.windows.net/system/Microsoft.Compute/Images/<capture_container_name>/<capture_name_prefix>.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.vhd`. 55 56 - `capture_name_prefix` (string) VHD prefix. The final artifacts will be named `PREFIX-osDisk.UUID` and 57 `PREFIX-vmTemplate.UUID`. 58 59 - `resource_group_name` (string) Resource group under which the final artifact will be stored. 60 61 - `storage_account` (string) Storage account under which the final artifact will be stored. 62 63 When creating a managed image the following two options are required. 64 65 - `managed_image_name` (string) Specify the managed image name where the result of the Packer build will be saved. The 66 image name must not exist ahead of time, and will not be overwritten. If this value is set, the value 67 `managed_image_resource_group_name` must also be set. See [documentation](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) 68 to learn more about managed images. 69 70 - `managed_image_resource_group_name` (string) Specify the managed image resource group name where the result of the Packer build will be 71 saved. The resource group must already exist. If this value is set, the value `managed_image_name` must also be 72 set. See [documentation](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) to 73 learn more about managed images. 74 75 #### Resource Group Usage 76 77 The Azure builder can either provision resources into a new resource group that 78 it controls (default) or an existing one. The advantage of using a packer 79 defined resource group is that failed resource cleanup is easier because you 80 can simply remove the entire resource group, however this means that the 81 provided credentials must have permission to create and remove resource groups. 82 By using an existing resource group you can scope the provided credentials to 83 just this group, however failed builds are more likely to leave unused 84 artifacts. 85 86 To have packer create a resource group you **must** provide: 87 88 - `location` (string) Azure datacenter in which your VM will build. 89 90 CLI example `az account list-locations` 91 92 and optionally: 93 94 - `temp_resource_group_name` (string) name assigned to the temporary resource 95 group created during the build. If this value is not set, a random value will 96 be assigned. This resource group is deleted at the end of the build. 97 98 To use an existing resource group you **must** provide: 99 100 - `build_resource_group_name` (string) - Specify an existing resource group 101 to run the build in. 102 103 Providing `temp_resource_group_name` or `location` in combination with `build_resource_group_name` is not allowed. 104 105 ### Optional: 106 107 - `azure_tags` (object of name/value strings) - the user can define up to 15 tags. Tag names cannot exceed 512 108 characters, and tag values cannot exceed 256 characters. Tags are applied to every resource deployed by a Packer 109 build, i.e. Resource Group, VM, NIC, VNET, Public IP, KeyVault, etc. 110 111 - `cloud_environment_name` (string) One of `Public`, `China`, `Germany`, or 112 `USGovernment`. Defaults to `Public`. Long forms such as 113 `USGovernmentCloud` and `AzureUSGovernmentCloud` are also supported. 114 115 - `custom_data_file` (string) Specify a file containing custom data to inject into the cloud-init process. The contents 116 of the file are read, base64 encoded, and injected into the ARM template. The custom data will be passed to 117 cloud-init for processing at the time of provisioning. See [documentation](http://cloudinit.readthedocs.io/en/latest/topics/examples.html) 118 to learn more about custom data, and how it can be used to influence the provisioning process. 119 120 - `custom_managed_image_name` (string) Specify the source managed image's name to use. If this value is set, do not set 121 image_publisher, image_offer, image_sku, or image_version. If this value is set, the value 122 `custom_managed_image_resource_group_name` must also be set. See [documentation](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) 123 to learn more about managed images. 124 125 - `custom_managed_image_resource_group_name` (string) Specify the source managed image's resource group used to use. If this 126 value is set, do not set image_publisher, image_offer, image_sku, or image_version. If this value is set, the 127 value `custom_managed_image_name` must also be set. See [documentation](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) 128 to learn more about managed images. 129 130 - `image_version` (string) Specify a specific version of an OS to boot from. Defaults to `latest`. There may be a 131 difference in versions available across regions due to image synchronization latency. To ensure a consistent 132 version across regions set this value to one that is available in all regions where you are deploying. 133 134 CLI example `az vm image list --location westus --publisher Canonical --offer UbuntuServer --sku 16.04.0-LTS --all` 135 136 - `image_url` (string) Specify a custom VHD to use. If this value is set, do not set image\_publisher, image\_offer, 137 image\_sku, or image\_version. 138 139 - `managed_image_storage_account_type` (string) Specify the storage 140 account type for a managed image. Valid values are Standard_LRS 141 and Premium\_LRS. The default is Standard\_LRS. 142 143 - `os_disk_size_gb` (number) Specify the size of the OS disk in GB (gigabytes). Values of zero or less than zero are 144 ignored. 145 146 - `disk_additional_size` (array of integers) - The size(s) of any additional 147 hard disks for the VM in gigabytes. If this is not specified then the VM 148 will only contain an OS disk. The number of additional disks and maximum size of a disk depends on the configuration of your VM. See [Windows](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/about-disks-and-vhds) or [Linux](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/about-disks-and-vhds) for more information. 149 150 For VHD builds the final artifacts will be named `PREFIX-dataDisk-<n>.UUID.vhd` and stored in the specified capture container along side the OS disk. The additional disks are included in the deployment template `PREFIX-vmTemplate.UUID`. 151 152 For Managed build the final artifacts are included in the managed image. The additional disk will have the same storage account type as the OS disk, as specified with the `managed_image_storage_account_type` setting. 153 154 - `os_type` (string) If either `Linux` or `Windows` is specified Packer will 155 automatically configure authentication credentials for the provisioned machine. For 156 `Linux` this configures an SSH authorized key. For `Windows` this 157 configures a WinRM certificate. 158 159 - `plan_info` (object) - Used for creating images from Marketplace images. Please refer to [Deploy an image with 160 Marketplace terms](https://aka.ms/azuremarketplaceapideployment) for more details. Not all Marketplace images 161 support programmatic deployment, and support is controlled by the image publisher. 162 163 An example plan_info object is defined below. 164 165 ```json 166 { 167 "plan_info": { 168 "plan_name": "rabbitmq", 169 "plan_product": "rabbitmq", 170 "plan_publisher": "bitnami" 171 } 172 } 173 ``` 174 175 `plan_name` (string) - The plan name, required. 176 `plan_product` (string) - The plan product, required. 177 `plan_publisher` (string) - The plan publisher, required. 178 `plan_promotion_code` (string) - Some images accept a promotion code, optional. 179 180 Images created from the Marketplace with `plan_info` **must** specify `plan_info` whenever the image is deployed. 181 The builder automatically adds tags to the image to ensure this information is not lost. The following tags are 182 added. 183 184 1. PlanName 185 1. PlanProduct 186 1. PlanPublisher 187 1. PlanPromotionCode 188 189 - `shared_image_gallery` (object) Use a [Shared Gallery image](https://azure.microsoft.com/en-us/blog/announcing-the-public-preview-of-shared-image-gallery/) as the source for this build. *VHD targets are incompatible with this build type* - the target must be a *Managed Image*. 190 ``` 191 "shared_image_gallery": { 192 "subscription": "00000000-0000-0000-0000-00000000000", 193 "resource_group": "ResourceGroup", 194 "gallery_name": "GalleryName", 195 "image_name": "ImageName", 196 "image_version": "1.0.0" 197 } 198 "managed_image_name": "TargetImageName", 199 "managed_image_resource_group_name": "TargetResourceGroup" 200 ``` 201 202 - `temp_compute_name` (string) temporary name assigned to the VM. If this value is not set, a random value will be 203 assigned. Knowing the resource group and VM name allows one to execute commands to update the VM during a Packer 204 build, e.g. attach a resource disk to the VM. 205 206 - `tenant_id` (string) The account identifier with which your `client_id` and `subscription_id` are associated. If not 207 specified, `tenant_id` will be looked up using `subscription_id`. 208 209 - `private_virtual_network_with_public_ip` (boolean) This value allows you to set a `virtual_network_name` and obtain 210 a public IP. If this value is not set and `virtual_network_name` is defined Packer is only allowed to be executed 211 from a host on the same subnet / virtual network. 212 213 - `virtual_network_name` (string) Use a pre-existing virtual network for the VM. This option enables private 214 communication with the VM, no public IP address is **used** or **provisioned** (unless you set `private_virtual_network_with_public_ip`). 215 216 - `virtual_network_resource_group_name` (string) If virtual\_network\_name is set, this value **may** also be set. If 217 virtual\_network\_name is set, and this value is not set the builder attempts to determine the resource group 218 containing the virtual network. If the resource group cannot be found, or it cannot be disambiguated, this value 219 should be set. 220 221 - `virtual_network_subnet_name` (string) If virtual\_network\_name is set, this value **may** also be set. If 222 virtual\_network\_name is set, and this value is not set the builder attempts to determine the subnet to use with 223 the virtual network. If the subnet cannot be found, or it cannot be disambiguated, this value should be set. 224 225 - `vm_size` (string) Size of the VM used for building. This can be changed 226 when you deploy a VM from your VHD. See 227 [pricing](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/) information. Defaults to `Standard_A1`. 228 229 CLI example `az vm list-sizes --location westus` 230 231 - `async_resourcegroup_delete` (boolean) If you want packer to delete the temporary resource group asynchronously set this value. It's a boolean value 232 and defaults to false. **Important** Setting this true means that your builds are faster, however any failed deletes are not reported. 233 234 ## Basic Example 235 236 Here is a basic example for Azure. 237 238 ``` json 239 { 240 "type": "azure-arm", 241 242 "client_id": "fe354398-d7sf-4dc9-87fd-c432cd8a7e09", 243 "client_secret": "keepitsecret&#*$", 244 "resource_group_name": "packerdemo", 245 "storage_account": "virtualmachines", 246 "subscription_id": "44cae533-4247-4093-42cf-897ded6e7823", 247 "tenant_id": "de39842a-caba-497e-a798-7896aea43218", 248 249 "capture_container_name": "images", 250 "capture_name_prefix": "packer", 251 252 "os_type": "Linux", 253 "image_publisher": "Canonical", 254 "image_offer": "UbuntuServer", 255 "image_sku": "14.04.4-LTS", 256 257 "azure_tags": { 258 "dept": "engineering" 259 }, 260 261 "location": "West US", 262 "vm_size": "Standard_A2" 263 } 264 ``` 265 266 ## Deprovision 267 268 Azure VMs should be deprovisioned at the end of every build. For Windows this means executing sysprep, and for Linux this means executing the waagent deprovision process. 269 270 Please refer to the Azure [examples](https://github.com/hashicorp/packer/tree/master/examples/azure) for complete examples showing the deprovision process. 271 272 ### Windows 273 274 The following provisioner snippet shows how to sysprep a Windows VM. Deprovision should be the last operation executed by a build. The code below will wait for sysprep to write the image status in the registry and will exit after that. The possible states, in case you want to wait for another state, [are documented here](https://technet.microsoft.com/en-us/library/hh824815.aspx) 275 276 ``` json 277 { 278 "provisioners": [ 279 { 280 "type": "powershell", 281 "inline": [ 282 "& $env:SystemRoot\\System32\\Sysprep\\Sysprep.exe /oobe /generalize /quiet /quit", 283 "while($true) { $imageState = Get-ItemProperty HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Setup\\State | Select ImageState; if($imageState.ImageState -ne 'IMAGE_STATE_GENERALIZE_RESEAL_TO_OOBE') { Write-Output $imageState.ImageState; Start-Sleep -s 10 } else { break } }" 284 ] 285 } 286 ] 287 } 288 ``` 289 290 ### Linux 291 292 The following provisioner snippet shows how to deprovision a Linux VM. Deprovision should be the last operation executed by a build. 293 294 ``` json 295 { 296 "provisioners": [ 297 { 298 "execute_command": "chmod +x {{ .Path }}; {{ .Vars }} sudo -E sh '{{ .Path }}'", 299 "inline": [ 300 "/usr/sbin/waagent -force -deprovision+user && export HISTSIZE=0 && sync" 301 ], 302 "inline_shebang": "/bin/sh -x", 303 "type": "shell" 304 } 305 ] 306 } 307 ``` 308 309 To learn more about the Linux deprovision process please see WALinuxAgent's [README](https://github.com/Azure/WALinuxAgent/blob/master/README.md). 310 311 #### skip\_clean 312 313 Customers have reported issues with the deprovision process where the builder hangs. The error message is similar to the following. 314 315 Build 'azure-arm' errored: Retryable error: Error removing temporary script at /tmp/script_9899.sh: ssh: handshake failed: EOF 316 317 One solution is to set skip\_clean to true in the provisioner. This prevents Packer from cleaning up any helper scripts uploaded to the VM during the build. 318 319 ## Defaults 320 321 The Azure builder attempts to pick default values that provide for a just works experience. These values can be changed by the user to more suitable values. 322 323 - The default user name is packer not root as in other builders. Most distros on Azure do not allow root to SSH to a VM hence the need for a non-root default user. Set the ssh\_username option to override the default value. 324 - The default VM size is Standard\_A1. Set the vm\_size option to override the default value. 325 - The default image version is latest. Set the image\_version option to override the default value. 326 - By default a temporary resource group will be created and destroyed as part of the build. If you do not have permissions to do so, use `build_resource_group_name` to specify an existing resource group to run the build in. 327 328 ## Implementation 329 330 ~> **Warning!** This is an advanced topic. You do not need to understand the implementation to use the Azure 331 builder. 332 333 The Azure builder uses ARM 334 [templates](https://azure.microsoft.com/en-us/documentation/articles/resource-group-authoring-templates/) to deploy 335 resources. ARM templates allow you to express the what without having to express the how. 336 337 The Azure builder works under the assumption that it creates everything it needs to execute a build. When the build has 338 completed it simply deletes the resource group to cleanup any runtime resources. Resource groups are named using the 339 form `packer-Resource-Group-<random>`. The value `<random>` is a random value that is generated at every invocation of 340 packer. The `<random>` value is re-used as much as possible when naming resources, so users can better identify and 341 group these transient resources when seen in their subscription. 342 343 > The VHD is created on a user specified storage account, not a random one created at runtime. When a virtual machine 344 > is captured the resulting VHD is stored on the same storage account as the source VHD. The VHD created by Packer must 345 > persist after a build is complete, which is why the storage account is set by the user. 346 347 The basic steps for a build are: 348 349 1. Create a resource group. 350 2. Validate and deploy a VM template. 351 3. Execute provision - defined by the user; typically shell commands. 352 4. Power off and capture the VM. 353 5. Delete the resource group. 354 6. Delete the temporary VM's OS disk. 355 356 The templates used for a build are currently fixed in the code. There is a template for Linux, Windows, and KeyVault. 357 The templates are themselves templated with place holders for names, passwords, SSH keys, certificates, etc. 358 359 ### What's Randomized? 360 361 The Azure builder creates the following random values at runtime. 362 363 - Administrator Password: a random 32-character value using the *password alphabet*. 364 - Certificate: a 2,048-bit certificate used to secure WinRM communication. The certificate is valid for 24-hours, which starts roughly at invocation time. 365 - Certificate Password: a random 32-character value using the *password alphabet* used to protect the private key of the certificate. 366 - Compute Name: a random 15-character name prefixed with pkrvm; the name of the VM. 367 - Deployment Name: a random 15-character name prefixed with pkfdp; the name of the deployment. 368 - KeyVault Name: a random 15-character name prefixed with pkrkv. 369 - NIC Name: a random 15-character name prefixed with pkrni. 370 - Public IP Name: a random 15-character name prefixed with pkrip. 371 - OS Disk Name: a random 15-character name prefixed with pkros. 372 - Resource Group Name: a random 33-character name prefixed with packer-Resource-Group-. 373 - Subnet Name: a random 15-character name prefixed with pkrsn. 374 - SSH Key Pair: a 2,048-bit asymmetric key pair; can be overridden by the user. 375 - Virtual Network Name: a random 15-character name prefixed with pkrvn. 376 377 The default alphabet used for random values is **0123456789bcdfghjklmnpqrstvwxyz**. The alphabet was reduced (no 378 vowels) to prevent running afoul of Azure decency controls. 379 380 The password alphabet used for random values is **0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ**. 381 382 ### Windows 383 384 The Windows implementation is very similar to the Linux build, with the exception that it deploys a template to 385 configure KeyVault. Packer communicates with a Windows VM using the WinRM protocol. Windows VMs on Azure default to 386 using both password and certificate based authentication for WinRM. The password is easily set via the VM ARM template, 387 but the certificate requires an intermediary. The intermediary for Azure is KeyVault. The certificate is uploaded to a 388 new KeyVault provisioned in the same resource group as the VM. When the Windows VM is deployed, it links to the 389 certificate in KeyVault, and Azure will ensure the certificate is injected as part of deployment. 390 391 The basic steps for a Windows build are: 392 393 1. Create a resource group. 394 2. Validate and deploy a KeyVault template. 395 3. Validate and deploy a VM template. 396 4. Execute provision - defined by the user; typically shell commands. 397 5. Power off and capture the VM. 398 6. Delete the resource group. 399 7. Delete the temporary VM's OS disk. 400 401 A Windows build requires two templates and two deployments. Unfortunately, the KeyVault and VM cannot be deployed at 402 the same time hence the need for two templates and deployments. The time required to deploy a KeyVault template is 403 minimal, so overall impact is small. 404 405 406 See the [examples/azure](https://github.com/hashicorp/packer/tree/master/examples/azure) folder in the packer project 407 for more examples.