From 8b482933cffda27124b5351685fc253025bfb3f5 Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Wed, 5 Feb 2020 17:15:40 -0500 Subject: [PATCH 1/2] 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. From c99dc565440438e7c4ceac8fc0897e41131c4702 Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Thu, 6 Feb 2020 17:00:00 -0500 Subject: [PATCH 2/2] Update Azure ARM documentation * Change generated documentation to indicate what image selection options are required, and when. * Refactor the structure of the documentation to highlight required options for different types of builds --- builder/azure/arm/config.go | 32 ++-- builder/azure/arm/config.hcl2spec.go | 158 +++++++++--------- .../docs/builders/azure-arm.html.md.erb | 58 +++---- .../azure/arm/_Config-not-required.html.md | 17 -- .../azure/arm/_Config-required.html.md | 22 ++- 5 files changed, 137 insertions(+), 150 deletions(-) diff --git a/builder/azure/arm/config.go b/builder/azure/arm/config.go index 3b701eae7..5c99e1569 100644 --- a/builder/azure/arm/config.go +++ b/builder/azure/arm/config.go @@ -147,20 +147,20 @@ type Config struct { // If set to true, Virtual Machines deployed from the latest version of the // Image Definition won't use this Image Version. SharedGalleryImageVersionExcludeFromLatest bool `mapstructure:"shared_gallery_image_version_exclude_from_latest" required:"false"` - // PublisherName for your base image. See + // Name of the publisher to use for your base image (Azure Marketplace Images only). See // [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) // for details. // // CLI example `az vm image list-publishers --location westus` ImagePublisher string `mapstructure:"image_publisher" required:"true"` - // Offer for your base image. See + // Name of the publisher's offer to use for your base image (Azure Marketplace Images only). See // [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) // for details. // // CLI example // `az vm image list-offers --location westus --publisher Canonical` ImageOffer string `mapstructure:"image_offer" required:"true"` - // SKU for your base image. See + // SKU of the image offer to use for your base image (Azure Marketplace Images only). See // [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) // for details. // @@ -176,24 +176,24 @@ type Config struct { // CLI example // `az vm image list --location westus --publisher Canonical --offer UbuntuServer --sku 16.04.0-LTS --all` ImageVersion string `mapstructure:"image_version" required:"false"` - // Specify a custom VHD to use. If this value is set, do + // URL to a custom VHD to use for your base image. If this value is set, do + // not set image_publisher, image_offer, image_sku, or image_version. + ImageUrl string `mapstructure:"image_url" required:"true"` + // Name of a custom managed image to use for your base image. If this value is set, do // not set image_publisher, image_offer, image_sku, or image_version. - ImageUrl string `mapstructure:"image_url" required:"false"` - // 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](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) - // to learn more about managed images. - CustomManagedImageResourceGroupName string `mapstructure:"custom_managed_image_resource_group_name" required:"false"` - // 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](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) // to learn more about managed images. - CustomManagedImageName string `mapstructure:"custom_managed_image_name" required:"false"` - customManagedImageID string + CustomManagedImageName string `mapstructure:"custom_managed_image_name" required:"true"` + + // Name of a custom managed image's resource group to use for your base image. If this + // value is set, image_publisher, image_offer, image_sku, or image_version. + // `custom_managed_image_name` must also be set. See + // [documentation](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) + // to learn more about managed images. + CustomManagedImageResourceGroupName string `mapstructure:"custom_managed_image_resource_group_name" required:"true"` + customManagedImageID string Location string `mapstructure:"location"` // Size of the VM used for building. This can be changed when you deploy a diff --git a/builder/azure/arm/config.hcl2spec.go b/builder/azure/arm/config.hcl2spec.go index c3fbc8036..0224a90ee 100644 --- a/builder/azure/arm/config.hcl2spec.go +++ b/builder/azure/arm/config.hcl2spec.go @@ -36,9 +36,9 @@ type FlatConfig struct { ImageOffer *string `mapstructure:"image_offer" required:"true" cty:"image_offer"` ImageSku *string `mapstructure:"image_sku" required:"true" cty:"image_sku"` ImageVersion *string `mapstructure:"image_version" required:"false" cty:"image_version"` - ImageUrl *string `mapstructure:"image_url" required:"false" cty:"image_url"` - CustomManagedImageResourceGroupName *string `mapstructure:"custom_managed_image_resource_group_name" required:"false" cty:"custom_managed_image_resource_group_name"` - CustomManagedImageName *string `mapstructure:"custom_managed_image_name" required:"false" cty:"custom_managed_image_name"` + ImageUrl *string `mapstructure:"image_url" required:"true" cty:"image_url"` + CustomManagedImageName *string `mapstructure:"custom_managed_image_name" required:"true" cty:"custom_managed_image_name"` + CustomManagedImageResourceGroupName *string `mapstructure:"custom_managed_image_resource_group_name" required:"true" cty:"custom_managed_image_resource_group_name"` Location *string `mapstructure:"location" cty:"location"` VMSize *string `mapstructure:"vm_size" required:"false" cty:"vm_size"` ManagedImageResourceGroupName *string `mapstructure:"managed_image_resource_group_name" cty:"managed_image_resource_group_name"` @@ -146,83 +146,83 @@ func (*FlatConfig) HCL2Spec() map[string]hcldec.Spec { "shared_gallery_image_version_end_of_life_date": &hcldec.AttrSpec{Name: "shared_gallery_image_version_end_of_life_date", Type: cty.String, Required: false}, "shared_image_gallery_replica_count": &hcldec.AttrSpec{Name: "shared_image_gallery_replica_count", Type: cty.Number, Required: false}, "shared_gallery_image_version_exclude_from_latest": &hcldec.AttrSpec{Name: "shared_gallery_image_version_exclude_from_latest", Type: cty.Bool, Required: false}, - "image_publisher": &hcldec.AttrSpec{Name: "image_publisher", Type: cty.String, Required: false}, - "image_offer": &hcldec.AttrSpec{Name: "image_offer", Type: cty.String, Required: false}, - "image_sku": &hcldec.AttrSpec{Name: "image_sku", Type: cty.String, Required: false}, - "image_version": &hcldec.AttrSpec{Name: "image_version", Type: cty.String, Required: false}, - "image_url": &hcldec.AttrSpec{Name: "image_url", Type: cty.String, Required: false}, + "image_publisher": &hcldec.AttrSpec{Name: "image_publisher", Type: cty.String, Required: false}, + "image_offer": &hcldec.AttrSpec{Name: "image_offer", Type: cty.String, Required: false}, + "image_sku": &hcldec.AttrSpec{Name: "image_sku", Type: cty.String, Required: false}, + "image_version": &hcldec.AttrSpec{Name: "image_version", Type: cty.String, Required: false}, + "image_url": &hcldec.AttrSpec{Name: "image_url", Type: cty.String, Required: false}, + "custom_managed_image_name": &hcldec.AttrSpec{Name: "custom_managed_image_name", Type: cty.String, Required: false}, "custom_managed_image_resource_group_name": &hcldec.AttrSpec{Name: "custom_managed_image_resource_group_name", Type: cty.String, Required: false}, - "custom_managed_image_name": &hcldec.AttrSpec{Name: "custom_managed_image_name", Type: cty.String, Required: false}, - "location": &hcldec.AttrSpec{Name: "location", Type: cty.String, Required: false}, - "vm_size": &hcldec.AttrSpec{Name: "vm_size", Type: cty.String, Required: false}, - "managed_image_resource_group_name": &hcldec.AttrSpec{Name: "managed_image_resource_group_name", Type: cty.String, Required: false}, - "managed_image_name": &hcldec.AttrSpec{Name: "managed_image_name", Type: cty.String, Required: false}, - "managed_image_storage_account_type": &hcldec.AttrSpec{Name: "managed_image_storage_account_type", Type: cty.String, Required: false}, - "managed_image_os_disk_snapshot_name": &hcldec.AttrSpec{Name: "managed_image_os_disk_snapshot_name", Type: cty.String, Required: false}, - "managed_image_data_disk_snapshot_prefix": &hcldec.AttrSpec{Name: "managed_image_data_disk_snapshot_prefix", Type: cty.String, Required: false}, - "managed_image_zone_resilient": &hcldec.AttrSpec{Name: "managed_image_zone_resilient", Type: cty.Bool, Required: false}, - "azure_tags": &hcldec.BlockAttrsSpec{TypeName: "azure_tags", ElementType: cty.String, Required: false}, - "resource_group_name": &hcldec.AttrSpec{Name: "resource_group_name", Type: cty.String, Required: false}, - "storage_account": &hcldec.AttrSpec{Name: "storage_account", Type: cty.String, Required: false}, - "temp_compute_name": &hcldec.AttrSpec{Name: "temp_compute_name", Type: cty.String, Required: false}, - "temp_resource_group_name": &hcldec.AttrSpec{Name: "temp_resource_group_name", Type: cty.String, Required: false}, - "build_resource_group_name": &hcldec.AttrSpec{Name: "build_resource_group_name", Type: cty.String, Required: false}, - "build_key_vault_name": &hcldec.AttrSpec{Name: "build_key_vault_name", Type: cty.String, Required: false}, - "private_virtual_network_with_public_ip": &hcldec.AttrSpec{Name: "private_virtual_network_with_public_ip", Type: cty.Bool, Required: false}, - "virtual_network_name": &hcldec.AttrSpec{Name: "virtual_network_name", Type: cty.String, Required: false}, - "virtual_network_subnet_name": &hcldec.AttrSpec{Name: "virtual_network_subnet_name", Type: cty.String, Required: false}, - "virtual_network_resource_group_name": &hcldec.AttrSpec{Name: "virtual_network_resource_group_name", Type: cty.String, Required: false}, - "custom_data_file": &hcldec.AttrSpec{Name: "custom_data_file", Type: cty.String, Required: false}, - "plan_info": &hcldec.BlockSpec{TypeName: "plan_info", Nested: hcldec.ObjectSpec((*FlatPlanInformation)(nil).HCL2Spec())}, - "polling_duration_timeout": &hcldec.AttrSpec{Name: "polling_duration_timeout", Type: cty.String, Required: false}, - "os_type": &hcldec.AttrSpec{Name: "os_type", Type: cty.String, Required: false}, - "os_disk_size_gb": &hcldec.AttrSpec{Name: "os_disk_size_gb", Type: cty.Number, Required: false}, - "disk_additional_size": &hcldec.AttrSpec{Name: "disk_additional_size", Type: cty.List(cty.Number), Required: false}, - "disk_caching_type": &hcldec.AttrSpec{Name: "disk_caching_type", Type: cty.String, Required: false}, - "allowed_inbound_ip_addresses": &hcldec.AttrSpec{Name: "allowed_inbound_ip_addresses", Type: cty.List(cty.String), Required: false}, - "user_name": &hcldec.AttrSpec{Name: "user_name", Type: cty.String, Required: false}, - "password": &hcldec.AttrSpec{Name: "password", Type: cty.String, Required: false}, - "communicator": &hcldec.AttrSpec{Name: "communicator", Type: cty.String, Required: false}, - "pause_before_connecting": &hcldec.AttrSpec{Name: "pause_before_connecting", Type: cty.String, Required: false}, - "ssh_host": &hcldec.AttrSpec{Name: "ssh_host", Type: cty.String, Required: false}, - "ssh_port": &hcldec.AttrSpec{Name: "ssh_port", Type: cty.Number, Required: false}, - "ssh_username": &hcldec.AttrSpec{Name: "ssh_username", Type: cty.String, Required: false}, - "ssh_password": &hcldec.AttrSpec{Name: "ssh_password", Type: cty.String, Required: false}, - "ssh_keypair_name": &hcldec.AttrSpec{Name: "ssh_keypair_name", Type: cty.String, Required: false}, - "temporary_key_pair_name": &hcldec.AttrSpec{Name: "temporary_key_pair_name", Type: cty.String, Required: false}, - "ssh_clear_authorized_keys": &hcldec.AttrSpec{Name: "ssh_clear_authorized_keys", Type: cty.Bool, Required: false}, - "ssh_private_key_file": &hcldec.AttrSpec{Name: "ssh_private_key_file", Type: cty.String, Required: false}, - "ssh_pty": &hcldec.AttrSpec{Name: "ssh_pty", Type: cty.Bool, Required: false}, - "ssh_timeout": &hcldec.AttrSpec{Name: "ssh_timeout", Type: cty.String, Required: false}, - "ssh_agent_auth": &hcldec.AttrSpec{Name: "ssh_agent_auth", Type: cty.Bool, Required: false}, - "ssh_disable_agent_forwarding": &hcldec.AttrSpec{Name: "ssh_disable_agent_forwarding", Type: cty.Bool, Required: false}, - "ssh_handshake_attempts": &hcldec.AttrSpec{Name: "ssh_handshake_attempts", Type: cty.Number, Required: false}, - "ssh_bastion_host": &hcldec.AttrSpec{Name: "ssh_bastion_host", Type: cty.String, Required: false}, - "ssh_bastion_port": &hcldec.AttrSpec{Name: "ssh_bastion_port", Type: cty.Number, Required: false}, - "ssh_bastion_agent_auth": &hcldec.AttrSpec{Name: "ssh_bastion_agent_auth", Type: cty.Bool, Required: false}, - "ssh_bastion_username": &hcldec.AttrSpec{Name: "ssh_bastion_username", Type: cty.String, Required: false}, - "ssh_bastion_password": &hcldec.AttrSpec{Name: "ssh_bastion_password", Type: cty.String, Required: false}, - "ssh_bastion_private_key_file": &hcldec.AttrSpec{Name: "ssh_bastion_private_key_file", Type: cty.String, Required: false}, - "ssh_file_transfer_method": &hcldec.AttrSpec{Name: "ssh_file_transfer_method", Type: cty.String, Required: false}, - "ssh_proxy_host": &hcldec.AttrSpec{Name: "ssh_proxy_host", Type: cty.String, Required: false}, - "ssh_proxy_port": &hcldec.AttrSpec{Name: "ssh_proxy_port", Type: cty.Number, Required: false}, - "ssh_proxy_username": &hcldec.AttrSpec{Name: "ssh_proxy_username", Type: cty.String, Required: false}, - "ssh_proxy_password": &hcldec.AttrSpec{Name: "ssh_proxy_password", Type: cty.String, Required: false}, - "ssh_keep_alive_interval": &hcldec.AttrSpec{Name: "ssh_keep_alive_interval", Type: cty.String, Required: false}, - "ssh_read_write_timeout": &hcldec.AttrSpec{Name: "ssh_read_write_timeout", Type: cty.String, Required: false}, - "ssh_remote_tunnels": &hcldec.AttrSpec{Name: "ssh_remote_tunnels", Type: cty.List(cty.String), Required: false}, - "ssh_local_tunnels": &hcldec.AttrSpec{Name: "ssh_local_tunnels", Type: cty.List(cty.String), Required: false}, - "ssh_public_key": &hcldec.AttrSpec{Name: "ssh_public_key", Type: cty.List(cty.Number), Required: false}, - "ssh_private_key": &hcldec.AttrSpec{Name: "ssh_private_key", Type: cty.List(cty.Number), Required: false}, - "winrm_username": &hcldec.AttrSpec{Name: "winrm_username", Type: cty.String, Required: false}, - "winrm_password": &hcldec.AttrSpec{Name: "winrm_password", Type: cty.String, Required: false}, - "winrm_host": &hcldec.AttrSpec{Name: "winrm_host", Type: cty.String, Required: false}, - "winrm_port": &hcldec.AttrSpec{Name: "winrm_port", Type: cty.Number, Required: false}, - "winrm_timeout": &hcldec.AttrSpec{Name: "winrm_timeout", Type: cty.String, Required: false}, - "winrm_use_ssl": &hcldec.AttrSpec{Name: "winrm_use_ssl", Type: cty.Bool, Required: false}, - "winrm_insecure": &hcldec.AttrSpec{Name: "winrm_insecure", Type: cty.Bool, Required: false}, - "winrm_use_ntlm": &hcldec.AttrSpec{Name: "winrm_use_ntlm", Type: cty.Bool, Required: false}, - "async_resourcegroup_delete": &hcldec.AttrSpec{Name: "async_resourcegroup_delete", Type: cty.Bool, Required: false}, + "location": &hcldec.AttrSpec{Name: "location", Type: cty.String, Required: false}, + "vm_size": &hcldec.AttrSpec{Name: "vm_size", Type: cty.String, Required: false}, + "managed_image_resource_group_name": &hcldec.AttrSpec{Name: "managed_image_resource_group_name", Type: cty.String, Required: false}, + "managed_image_name": &hcldec.AttrSpec{Name: "managed_image_name", Type: cty.String, Required: false}, + "managed_image_storage_account_type": &hcldec.AttrSpec{Name: "managed_image_storage_account_type", Type: cty.String, Required: false}, + "managed_image_os_disk_snapshot_name": &hcldec.AttrSpec{Name: "managed_image_os_disk_snapshot_name", Type: cty.String, Required: false}, + "managed_image_data_disk_snapshot_prefix": &hcldec.AttrSpec{Name: "managed_image_data_disk_snapshot_prefix", Type: cty.String, Required: false}, + "managed_image_zone_resilient": &hcldec.AttrSpec{Name: "managed_image_zone_resilient", Type: cty.Bool, Required: false}, + "azure_tags": &hcldec.BlockAttrsSpec{TypeName: "azure_tags", ElementType: cty.String, Required: false}, + "resource_group_name": &hcldec.AttrSpec{Name: "resource_group_name", Type: cty.String, Required: false}, + "storage_account": &hcldec.AttrSpec{Name: "storage_account", Type: cty.String, Required: false}, + "temp_compute_name": &hcldec.AttrSpec{Name: "temp_compute_name", Type: cty.String, Required: false}, + "temp_resource_group_name": &hcldec.AttrSpec{Name: "temp_resource_group_name", Type: cty.String, Required: false}, + "build_resource_group_name": &hcldec.AttrSpec{Name: "build_resource_group_name", Type: cty.String, Required: false}, + "build_key_vault_name": &hcldec.AttrSpec{Name: "build_key_vault_name", Type: cty.String, Required: false}, + "private_virtual_network_with_public_ip": &hcldec.AttrSpec{Name: "private_virtual_network_with_public_ip", Type: cty.Bool, Required: false}, + "virtual_network_name": &hcldec.AttrSpec{Name: "virtual_network_name", Type: cty.String, Required: false}, + "virtual_network_subnet_name": &hcldec.AttrSpec{Name: "virtual_network_subnet_name", Type: cty.String, Required: false}, + "virtual_network_resource_group_name": &hcldec.AttrSpec{Name: "virtual_network_resource_group_name", Type: cty.String, Required: false}, + "custom_data_file": &hcldec.AttrSpec{Name: "custom_data_file", Type: cty.String, Required: false}, + "plan_info": &hcldec.BlockSpec{TypeName: "plan_info", Nested: hcldec.ObjectSpec((*FlatPlanInformation)(nil).HCL2Spec())}, + "polling_duration_timeout": &hcldec.AttrSpec{Name: "polling_duration_timeout", Type: cty.String, Required: false}, + "os_type": &hcldec.AttrSpec{Name: "os_type", Type: cty.String, Required: false}, + "os_disk_size_gb": &hcldec.AttrSpec{Name: "os_disk_size_gb", Type: cty.Number, Required: false}, + "disk_additional_size": &hcldec.AttrSpec{Name: "disk_additional_size", Type: cty.List(cty.Number), Required: false}, + "disk_caching_type": &hcldec.AttrSpec{Name: "disk_caching_type", Type: cty.String, Required: false}, + "allowed_inbound_ip_addresses": &hcldec.AttrSpec{Name: "allowed_inbound_ip_addresses", Type: cty.List(cty.String), Required: false}, + "user_name": &hcldec.AttrSpec{Name: "user_name", Type: cty.String, Required: false}, + "password": &hcldec.AttrSpec{Name: "password", Type: cty.String, Required: false}, + "communicator": &hcldec.AttrSpec{Name: "communicator", Type: cty.String, Required: false}, + "pause_before_connecting": &hcldec.AttrSpec{Name: "pause_before_connecting", Type: cty.String, Required: false}, + "ssh_host": &hcldec.AttrSpec{Name: "ssh_host", Type: cty.String, Required: false}, + "ssh_port": &hcldec.AttrSpec{Name: "ssh_port", Type: cty.Number, Required: false}, + "ssh_username": &hcldec.AttrSpec{Name: "ssh_username", Type: cty.String, Required: false}, + "ssh_password": &hcldec.AttrSpec{Name: "ssh_password", Type: cty.String, Required: false}, + "ssh_keypair_name": &hcldec.AttrSpec{Name: "ssh_keypair_name", Type: cty.String, Required: false}, + "temporary_key_pair_name": &hcldec.AttrSpec{Name: "temporary_key_pair_name", Type: cty.String, Required: false}, + "ssh_clear_authorized_keys": &hcldec.AttrSpec{Name: "ssh_clear_authorized_keys", Type: cty.Bool, Required: false}, + "ssh_private_key_file": &hcldec.AttrSpec{Name: "ssh_private_key_file", Type: cty.String, Required: false}, + "ssh_pty": &hcldec.AttrSpec{Name: "ssh_pty", Type: cty.Bool, Required: false}, + "ssh_timeout": &hcldec.AttrSpec{Name: "ssh_timeout", Type: cty.String, Required: false}, + "ssh_agent_auth": &hcldec.AttrSpec{Name: "ssh_agent_auth", Type: cty.Bool, Required: false}, + "ssh_disable_agent_forwarding": &hcldec.AttrSpec{Name: "ssh_disable_agent_forwarding", Type: cty.Bool, Required: false}, + "ssh_handshake_attempts": &hcldec.AttrSpec{Name: "ssh_handshake_attempts", Type: cty.Number, Required: false}, + "ssh_bastion_host": &hcldec.AttrSpec{Name: "ssh_bastion_host", Type: cty.String, Required: false}, + "ssh_bastion_port": &hcldec.AttrSpec{Name: "ssh_bastion_port", Type: cty.Number, Required: false}, + "ssh_bastion_agent_auth": &hcldec.AttrSpec{Name: "ssh_bastion_agent_auth", Type: cty.Bool, Required: false}, + "ssh_bastion_username": &hcldec.AttrSpec{Name: "ssh_bastion_username", Type: cty.String, Required: false}, + "ssh_bastion_password": &hcldec.AttrSpec{Name: "ssh_bastion_password", Type: cty.String, Required: false}, + "ssh_bastion_private_key_file": &hcldec.AttrSpec{Name: "ssh_bastion_private_key_file", Type: cty.String, Required: false}, + "ssh_file_transfer_method": &hcldec.AttrSpec{Name: "ssh_file_transfer_method", Type: cty.String, Required: false}, + "ssh_proxy_host": &hcldec.AttrSpec{Name: "ssh_proxy_host", Type: cty.String, Required: false}, + "ssh_proxy_port": &hcldec.AttrSpec{Name: "ssh_proxy_port", Type: cty.Number, Required: false}, + "ssh_proxy_username": &hcldec.AttrSpec{Name: "ssh_proxy_username", Type: cty.String, Required: false}, + "ssh_proxy_password": &hcldec.AttrSpec{Name: "ssh_proxy_password", Type: cty.String, Required: false}, + "ssh_keep_alive_interval": &hcldec.AttrSpec{Name: "ssh_keep_alive_interval", Type: cty.String, Required: false}, + "ssh_read_write_timeout": &hcldec.AttrSpec{Name: "ssh_read_write_timeout", Type: cty.String, Required: false}, + "ssh_remote_tunnels": &hcldec.AttrSpec{Name: "ssh_remote_tunnels", Type: cty.List(cty.String), Required: false}, + "ssh_local_tunnels": &hcldec.AttrSpec{Name: "ssh_local_tunnels", Type: cty.List(cty.String), Required: false}, + "ssh_public_key": &hcldec.AttrSpec{Name: "ssh_public_key", Type: cty.List(cty.Number), Required: false}, + "ssh_private_key": &hcldec.AttrSpec{Name: "ssh_private_key", Type: cty.List(cty.Number), Required: false}, + "winrm_username": &hcldec.AttrSpec{Name: "winrm_username", Type: cty.String, Required: false}, + "winrm_password": &hcldec.AttrSpec{Name: "winrm_password", Type: cty.String, Required: false}, + "winrm_host": &hcldec.AttrSpec{Name: "winrm_host", Type: cty.String, Required: false}, + "winrm_port": &hcldec.AttrSpec{Name: "winrm_port", Type: cty.Number, Required: false}, + "winrm_timeout": &hcldec.AttrSpec{Name: "winrm_timeout", Type: cty.String, Required: false}, + "winrm_use_ssl": &hcldec.AttrSpec{Name: "winrm_use_ssl", Type: cty.Bool, Required: false}, + "winrm_insecure": &hcldec.AttrSpec{Name: "winrm_insecure", Type: cty.Bool, Required: false}, + "winrm_use_ntlm": &hcldec.AttrSpec{Name: "winrm_use_ntlm", Type: cty.Bool, Required: false}, + "async_resourcegroup_delete": &hcldec.AttrSpec{Name: "async_resourcegroup_delete", Type: cty.Bool, Required: false}, } return s } diff --git a/website/source/docs/builders/azure-arm.html.md.erb b/website/source/docs/builders/azure-arm.html.md.erb index 1c9bd3777..16e0e4c93 100644 --- a/website/source/docs/builders/azure-arm.html.md.erb +++ b/website/source/docs/builders/azure-arm.html.md.erb @@ -22,21 +22,23 @@ 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/). -## 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. +## Configuration Reference -### Managed Identity +There are many configuration options available for the builder. We'll start +with authentication parameters, then go over the Azure ARM builder specific +options. In addition to the options listed here, a [communicator](/docs/templates/communicator.html) can be configured for this builder. -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. As Packer will attempt to use the Managed Identity -and subscription of the VM that Packer is running on. +### Authentication options +<%= partial "partials/builder/azure/common/client/_Config" %> -### Interactive User Authentication +#### Managed Identity +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. 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 +#### 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`. @@ -60,34 +62,19 @@ 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. -<%= partial "partials/builder/azure/common/client/_Config" %> -## 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. +### Azure ARM builder specific options 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. Images can be obtained from -the Azure Marketplace or from within a users' subscription - see [Using Custom Images](#using-custom-images) +a managed image you **must** start with a managed image. -### Using Azure Marketplace Images +### Required: <%= 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: +When creating a VHD the following additional options are required: - `capture_container_name` (string) - Destination container name. Essentially the "directory" where your VHD will be organized in Azure. The captured @@ -103,7 +90,7 @@ When creating a VHD the following options are required: - `storage_account` (string) - Storage account under which the final artifact will be stored. -When creating a Managed Imaged the following options are required: +When creating a managed image the following additional 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 @@ -119,6 +106,7 @@ When creating a Managed Imaged the following options are required: [documentation](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) to learn more about managed images. +#### Shared Image Gallery 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 @@ -140,12 +128,6 @@ 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 @@ -177,6 +159,12 @@ 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. +### 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. diff --git a/website/source/partials/builder/azure/arm/_Config-not-required.html.md b/website/source/partials/builder/azure/arm/_Config-not-required.html.md index 7ed6fe482..6f040efe1 100644 --- a/website/source/partials/builder/azure/arm/_Config-not-required.html.md +++ b/website/source/partials/builder/azure/arm/_Config-not-required.html.md @@ -59,23 +59,6 @@ CLI example `az vm image list --location westus --publisher Canonical --offer UbuntuServer --sku 16.04.0-LTS --all` -- `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](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) - 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](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) - to learn more about managed images. - - `location` (string) - Location - `vm_size` (string) - Size of the VM used for building. This can be changed when you deploy a VM from your VHD. See diff --git a/website/source/partials/builder/azure/arm/_Config-required.html.md b/website/source/partials/builder/azure/arm/_Config-required.html.md index 696875dac..fba192a62 100644 --- a/website/source/partials/builder/azure/arm/_Config-required.html.md +++ b/website/source/partials/builder/azure/arm/_Config-required.html.md @@ -1,22 +1,38 @@ -- `image_publisher` (string) - PublisherName for your base image. See +- `image_publisher` (string) - Name of the publisher to use for your base image (Azure Marketplace Images only). See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details. CLI example `az vm image list-publishers --location westus` -- `image_offer` (string) - Offer for your base image. See +- `image_offer` (string) - Name of the publisher's offer to use for your base image (Azure Marketplace Images only). See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details. CLI example `az vm image list-offers --location westus --publisher Canonical` -- `image_sku` (string) - SKU for your base image. See +- `image_sku` (string) - SKU of the image offer to use for your base image (Azure Marketplace Images only). See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details. CLI example `az vm image list-skus --location westus --publisher Canonical --offer UbuntuServer` + +- `image_url` (string) - URL to a custom VHD to use for your base image. If this value is set, do + not set image_publisher, image_offer, image_sku, or image_version. + +- `custom_managed_image_name` (string) - Name of a custom managed image to use for your base image. 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](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) + to learn more about managed images. + +- `custom_managed_image_resource_group_name` (string) - Name of a custom managed image's resource group to use for your base image. If this + value is set, image_publisher, image_offer, image_sku, or image_version. + `custom_managed_image_name` must also be set. See + [documentation](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images) + to learn more about managed images. \ No newline at end of file