From 8b482933cffda27124b5351685fc253025bfb3f5 Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Wed, 5 Feb 2020 17:15:40 -0500 Subject: [PATCH] docs/azure-arm: Refactor docs to clear up required options This changes separates the required configurations options needed when using Azure Marketplace images vs Custom user built Images. --- .../docs/builders/azure-arm.html.md.erb | 79 +++++++++++-------- 1 file changed, 47 insertions(+), 32 deletions(-) diff --git a/website/source/docs/builders/azure-arm.html.md.erb b/website/source/docs/builders/azure-arm.html.md.erb index 77d01a294..1c9bd3777 100644 --- a/website/source/docs/builders/azure-arm.html.md.erb +++ b/website/source/docs/builders/azure-arm.html.md.erb @@ -9,18 +9,12 @@ sidebar_current: 'docs-builders-azure-arm' Type: `azure-arm` -Packer supports building VHDs in [Azure Resource +Packer supports building VHDs and Managed Images 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. -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. - 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.html#authentication-for-azure). @@ -28,20 +22,22 @@ ARM](/docs/builders/azure.html#authentication-for-azure). The documentation below references command output from the [Azure CLI](https://azure.microsoft.com/en-us/documentation/articles/xplat-cli-install/). -## Configuration Reference +## Authentication: +There are three options for Authenticationg to Azure, two of which require certain +configuration options in order to properly build an Azure Arm Image. -The following configuration options are available for building Azure images. In -addition to the options listed here, a -[communicator](/docs/templates/communicator.html) can be configured for this -builder. +### Managed Identity -### Required options for authentication: If you're running packer on an Azure VM with a [managed identity](/docs/builders/azure.html#azure-managed-identity) -you don't need to specify any additional configuration options. -If you would like to use interactive user authentication, you should specify -`subscription_id` only. Packer will use cached credentials or redirect you -to a website to log in. -If you want to use a [service principal](/docs/builders/azure.html#azure-active-directory-service-principal) +you don't need to specify any additional configuration options. As Packer will attempt to use the Managed Identity +and subscription of the VM that Packer is running on. + +### Interactive User Authentication +To use interactive user authentication, you should specify `subscription_id` only. +Packer will use cached credentials or redirect you to a website to log in. + +### Service Principal +To use a [service principal](/docs/builders/azure.html#azure-active-directory-service-principal) you should specify `subscription_id`, `client_id` and one of `client_secret`, `client_cert_path` or `client_jwt`. @@ -64,16 +60,34 @@ you should specify `subscription_id`, `client_id` and one of `client_secret`, Directory docs](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-certificate-credentials) for more information. -### Required: +<%= partial "partials/builder/azure/common/client/_Config" %> -<%= partial "partials/builder/azure/arm/Config-required" %> +## Configuration Reference + +The following configuration options are available for building Azure images. In +addition to the options listed here, a [communicator](/docs/templates/communicator.html) can be configured for this +builder. -#### VHD or Managed Image The Azure builder can create either a VHD, or a managed image. If you are creating a VHD, you **must** start with a VHD. Likewise, if you want to create -a managed image you **must** start with a managed image. When creating a VHD -the following options are required. +a managed image you **must** start with a managed image. Images can be obtained from +the Azure Marketplace or from within a users' subscription - see [Using Custom Images](#using-custom-images) + +### Using Azure Marketplace Images + +<%= partial "partials/builder/azure/arm/Config-required" %> + +### Using Custom Images + +- `image_url` (string) - Specify a custom VHD to use. If this value is set, do not set image_publisher, image_offer, image_sku, or image_version. + +- `custom_managed_image_resource_group_name` (string) - Specify the source managed image's resource group used to use. If this value is set, do not set image_publisher, image_offer, image_sku, or image_version. If this value is set, the value custom_managed_image_name must also be set. See documentation to learn more about managed images. + +- `custom_managed_image_name` (string) - Specify the source managed image's name to use. If this value is set, do not set image_publisher, image_offer, image_sku, or image_version. If this value is set, the value custom_managed_image_resource_group_name must also be set. See documentation to learn more about managed images. + + +When creating a VHD the following options are required: - `capture_container_name` (string) - Destination container name. Essentially the "directory" where your VHD will be organized in Azure. The captured @@ -89,7 +103,7 @@ the following options are required. - `storage_account` (string) - Storage account under which the final artifact will be stored. -When creating a managed image the following options are required. +When creating a Managed Imaged the following options are required: - `managed_image_name` (string) - Specify the managed image name where the result of the Packer build will be saved. The image name must not exist @@ -108,7 +122,9 @@ When creating a managed image the following options are required. Managed images can optionally be published to [Shared Image Gallery](https://azure.microsoft.com/en-us/blog/announcing-the-public-preview-of-shared-image-gallery/) as Shared Gallery Image version. Shared Image Gallery **only** works with Managed Images. **A VHD cannot be published to -a Shared Image Gallery**. When publishing to a Shared Image Gallery the following options are required. +a Shared Image Gallery**. + +When publishing to a Shared Image Gallery the following options are required. - `shared_image_gallery_destination` (object) The name of the Shared Image Gallery under which the managed image will be published as Shared Gallery Image version. @@ -124,6 +140,12 @@ Following is an example. "managed_image_name": "TargetImageName", "managed_image_resource_group_name": "TargetResourceGroup" + +### Optional: + +<%= partial "partials/builder/azure/arm/Config-not-required" %> +<%= partial "partials/builder/azure/common/client/_Config-not-required" %> + #### Resource Group Usage The Azure builder can either provision resources into a new resource group that @@ -155,13 +177,6 @@ To use an existing resource group you **must** provide: Providing `temp_resource_group_name` or `location` in combination with `build_resource_group_name` is not allowed. -<%= partial "partials/builder/azure/common/client/_Config" %> - -### Optional: - -<%= partial "partials/builder/azure/arm/Config-not-required" %> -<%= partial "partials/builder/azure/common/client/_Config-not-required" %> - ## Basic Example Here is a basic example for Azure.