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.

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.