diff --git a/website/source/docs/builders/azure.html.md.erb b/website/source/docs/builders/azure-arm.html.md.erb similarity index 98% rename from website/source/docs/builders/azure.html.md.erb rename to website/source/docs/builders/azure-arm.html.md.erb index e2c83f80b..b08e8506e 100644 --- a/website/source/docs/builders/azure.html.md.erb +++ b/website/source/docs/builders/azure-arm.html.md.erb @@ -1,8 +1,8 @@ --- description: 'Packer supports building VHDs in Azure Resource manager.' layout: docs -page_title: 'Azure - Builders' -sidebar_current: 'docs-builders-azure' +page_title: 'Azure arm - Builders' +sidebar_current: 'docs-builders-azure-arm' --- # Azure Resource Manager Builder @@ -23,7 +23,7 @@ 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-setup.html). +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/). @@ -36,12 +36,12 @@ addition to the options listed here, a builder. ### Required options for authentication: -If you're running packer on an Azure VM with a [managed identity](/docs/builders/azure-setup.html#managed-identities-for-azure-resources) +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-setup.html#create-a-service-principal) +If you want 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`. diff --git a/website/source/docs/builders/azure-chroot.html.md.erb b/website/source/docs/builders/azure-chroot.html.md.erb new file mode 100644 index 000000000..6a67888d9 --- /dev/null +++ b/website/source/docs/builders/azure-chroot.html.md.erb @@ -0,0 +1,101 @@ +--- +description: | + The azure-chroot Packer builder is able to create Azure Managed Images leveraging + a VM in Azure. +layout: docs +page_title: 'Azure chroot - Builders' +sidebar_current: 'docs-builders-azure-chroot' +--- + +# Azure Builder (chroot) + +Type: `azure-chroot` + +The `azure-chroot` builder is able to build Azure managed disk (MD) images. For +more information on managed disks, see [Azure Managed Disks Overview](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/managed-disks-overview). + +The difference between this builder and the `azure-arm` builder is that this +builder is able to build a managed disk image without launching an Azure VM +instance. This can dramatically speed up image builds. It also allows for more +deterministic image content and enables some capabilities that are not possible +with the `azure-arm` builder. + +> **This is an advanced builder** If you're just getting started with Packer, +it is recommend to start with the [azure-arm builder](/docs/builders/azure-arm.html), +which is much easier to use. + +## How Does it Work? + +This builder works by creating a new MD from either an existing source or from +scratch and attaching it to the (already existing) Azure VM where Packer is +running. Once attached, a [chroot](https://en.wikipedia.org/wiki/Chroot) is set +up and made available to the provisioners. After provisioning, the MD is +detached, snapshotted and a MD image is created. + +Using this process, minutes can be shaved off the image creation process +because Packer does not need to launch a VM instance. + +There are some restrictions however: +* The host system must be a similar system (generally the same OS version, + kernel versions, etc.) as the image being built. +* If the source is a user image or managed disk, it must be made available in + the same region as the host system. ([name=Paul Meyer]: we could work around + this restriction by doing a cross-region copy, but that takes away the main + speed advantage.) +* The host system SKU has to allow for all of the specified disks to be + attached. + +## Configuration Reference + +There are many configuration options available for the builder. We'll start +withauthentication parameters, then go over the builder specific options. + +### Authentication options +The Azure builders [share this configuration](/docs/builders/azure.html). + +<%= partial "partials/builder/azure/common/client/_Config-not-required.html" %> + +### Builder specific options + +#### Required: +<%= partial "partials/builder/azure/chroot/_Config-required.html" %> + +#### Optional: +<%= partial "partials/builder/azure/chroot/_Config-not-required.html" %> + +## Chroot Mounts + +The `chroot_mounts` configuration can be used to mount specific devices within +the chroot. By default, the following additional mounts are added into the +chroot by Packer: + +- `/proc` (proc) +- `/sys` (sysfs) +- `/dev` (bind to real `/dev`) +- `/dev/pts` (devpts) +- `/proc/sys/fs/binfmt_misc` (binfmt\_misc) + +These default mounts are usually good enough for anyone and are sane defaults. +However, if you want to change or add the mount points, you may using the +`chroot_mounts` configuration. Here is an example configuration which only +mounts `/prod` and `/dev`: + +``` json +{ + "chroot_mounts": [ + ["proc", "proc", "/proc"], + ["bind", "/dev", "/dev"] + ] +} +``` + +`chroot_mounts` is a list of a 3-tuples of strings. The three components of the +3-tuple, in order, are: + +- The filesystem type. If this is "bind", then Packer will properly bind the + filesystem to another mount point. + +- The source device. + +- The mount directory. + diff --git a/website/source/docs/builders/azure-setup.html.md b/website/source/docs/builders/azure-setup.html.md deleted file mode 100644 index ee73b1715..000000000 --- a/website/source/docs/builders/azure-setup.html.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -description: | - In order to build VMs in Azure, Packer needs various configuration options. - These options and how to obtain them are documented on this page. -layout: docs -page_title: 'Setup - Azure - Builders' -sidebar_current: 'docs-builders-azure-setup' ---- - -# Authorizing Packer Builds in Azure - -In order to build VMs in Azure, Packer needs 6 configuration options to be -specified: - -- `subscription_id` - UUID identifying your Azure subscription (where billing - is handled) - -- `client_id` - UUID identifying the Active Directory service principal that - will run your Packer builds - -- `client_secret` - service principal secret / password - -- `resource_group_name` - name of the resource group where your VHD(s) will - be stored - -- `storage_account` - name of the storage account where your VHD(s) will be - stored - --> Behind the scenes, Packer uses the OAuth protocol to authenticate against -Azure Active Directory and authorize requests to the Azure Service Management -API. These topics are unnecessarily complicated, so we will try to ignore them -for the rest of this document.

You do not need to understand how -OAuth works in order to use Packer with Azure, though the Active Directory -terms "service principal" and "role" will be useful for understanding Azure's -access policies. - -In order to get all of the items above, you will need a username and password -for your Azure account. - -## Device Login - -Device login is an alternative way to authorize in Azure Packer. Device login -only requires you to know your Subscription ID. (Device login is only supported -for Linux based VMs.) Device login is intended for those who are first time -users, and just want to ''kick the tires.'' We recommend the SPN approach if -you intend to automate Packer. - -> Device login is for **interactive** builds, and SPN is for **automated** builds. - -There are three pieces of information you must provide to enable device login -mode: - -1. SubscriptionID -2. Resource Group - parent resource group that Packer uses to build an image. -3. Storage Account - storage account where the image will be placed. - -> Device login mode is enabled by not setting client\_id and client\_secret. - -> Device login mode is for the Public and US Gov clouds only. - -The device login flow asks that you open a web browser, navigate to -http://aka.ms/devicelogin, -and input the supplied code. This authorizes the Packer for Azure application -to act on your behalf. An OAuth token will be created, and stored in the user's -home directory (\~/.azure/packer/oauth-TenantID.json). This token is used if -the token file exists, and it is refreshed as necessary. The token file -prevents the need to continually execute the device login flow. Packer will ask -for two device login auth, one for service management endpoint and another for -accessing temp keyvault secrets that it creates. - -## Managed identities for Azure resources - --> Managed identities for Azure resources is the new name for the service -formerly known as Managed Service Identity (MSI). - -Managed identities is an alternative way to authorize in Azure Packer. Managed -identities for Azure resources are automatically managed by Azure and enable -you to authenticate to services that support Azure AD authentication without -needing to insert credentials into your buildfile. Navigate to -managed identities azure resources overview to learn more about -this feature. - -This feature will be used when no `subscription_id`, `client_id` or -`client_secret` is set in your buildfile. - -## Install the Azure CLI - -To get the credentials above, we will need to install the Azure CLI. Please -refer to Microsoft's official [installation -guide](https://azure.microsoft.com/en-us/documentation/articles/xplat-cli-install/). - -The guides below use [JMESPath](http://jmespath.org/) queries to select and reformat output from the AZ CLI commands. JMESPath is [part of the Azure CLI](https://docs.microsoft.com/en-us/cli/azure/query-azure-cli?view=azure-cli-latest) and can be used in the same way as the `jq` tool. - -## Guided Setup - -The Packer project includes a [setup -script](https://github.com/hashicorp/packer/blob/master/contrib/azure-setup.sh) -that can help you setup your account. It uses an interactive bash script to log -you into Azure, name your resources, and export your Packer configuration. - -## Manual Setup - -If you want more control, or the script does not work for you, you can also use -the manual instructions below to setup your Azure account. You will need to -manually keep track of the various account identifiers, resource names, and -your service principal password. - -### Identify Your Tenant and Subscription IDs - -Login using the Azure CLI - -``` shell -$ az login -# Note, we have launched a browser for you to login. For old experience with device code, use "az login --use-device-code" -``` - -Once you've completed logging in, you should get a JSON array like the one -below: - -``` shell -[ - { - "cloudName": "AzureCloud", - "id": "$uuid", - "isDefault": false, - "name": "Pay-As-You-Go", - "state": "Enabled", - "tenantId": "$tenant_uuid", - "user": { - "name": "my_email@anywhere.com", - "type": "user" - } - } -] -``` - -Get your account information - -``` shell -$ az account list --output table --query '[].{Name:name,subscription_id:id}' -$ az account set --subscription ACCOUNTNAME -$ az account show --output json --query 'id' -``` - -This will print out one line that look like this: - - 4f562e88-8caf-421a-b4da-e3f6786c52ec - -This is your `subscription_id`. Note it for later. - -### Create a Resource Group - -A [resource -group](https://azure.microsoft.com/en-us/documentation/articles/resource-group-overview/#resource-groups) -is used to organize related resources. Resource groups and storage accounts are -tied to a location. To see available locations, run: - -``` shell -$ az account list-locations -$ LOCATION=xxx -$ GROUPNAME=xxx -# ... - -$ az group create --name $GROUPNAME --location $LOCATION -``` - -Your storage account (below) will need to use the same `GROUPNAME` and -`LOCATION`. - -### Create a Storage Account - -We will need to create a storage account where your Packer artifacts will be -stored. We will create a `LRS` storage account which is the least expensive -price/GB at the time of writing. - -``` shell -$ az storage account create \ - --name STORAGENAME - --resource-group $GROUPNAME \ - --location $LOCATION \ - --sku Standard_LRS \ - --kind Storage -``` - --> `LRS` and `Standard_LRS` are meant as literal "LRS" or "Standard\_LRS" -and not as variables. - -Make sure that `GROUPNAME` and `LOCATION` are the same as above. Also, ensure -that `GROUPNAME` is less than 24 characters long and contains only lowercase -letters and numbers. - -### Create a Service Principal - -A service principal acts on behalf of an application (Packer) on your Azure -subscription. To create an application and service principal for use with -Packer, run the below command specifying the subscription. This will grant -Packer the contributor role to the subscription. -The output of this command is your service principal credentials, save these in -a safe place as you will need these to configure Packer. - -``` shell -az ad sp create-for-rbac -n "Packer" --role contributor \ - --scopes /subscriptions/{SubID} -``` - -The service principal credentials. - -``` shell -{ - "appId": "AppId", - "displayName": "Packer", - "name": "http://Packer", - "password": "Password", - "tenant": "TenantId" -} -``` - -There are a lot of pre-defined roles and you can define your own with more -granular permissions, though this is out of scope. You can see a list of -pre-configured roles via: - -``` shell -$ az role definition list --output table --query '[].{name:roleName, description:description}' -``` - -If you would rather use a certificate to autenticate your service principal, -please follow the [Azure Active Directory documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-certificate-credentials#register-your-certificate-with-azure-ad). - -### Configuring Packer - -Now (finally) everything has been setup in Azure and our service principal has -been created. You can use the output from creating your service principal in -your template. Use the value from the `appId` field above as a value for -`client_id` in your configuration and set `client_secret` to the `password` -value from above. diff --git a/website/source/docs/builders/azure.html.md b/website/source/docs/builders/azure.html.md new file mode 100644 index 000000000..62bfdb25b --- /dev/null +++ b/website/source/docs/builders/azure.html.md @@ -0,0 +1,101 @@ +--- +description: | + Packer is able to create Azure VM images. To achieve this, Packer comes with + multiple builders depending on the strategy you want to use to build the images. +layout: docs +page_title: 'Azure images - Builders' +sidebar_current: 'docs-builders-azure' +--- + +# Azure Virtual Machine Image Builders + +Packer can create Azure virtual machine images through variety of ways +depending on the strategy that you want to use for building the images. +Packer supports the following builders for Azure images at the moment: + +- [azure-arm](/docs/builders/azure-arm.html) - Uses Azure Resource + Manager (ARM) to launch a virtual machine (VM) from which a new image is + captured after provisioning. If in doubt, use this builder; it is the + easiest builder to get started with. + +- [azure-chroot](/docs/builders/azure-chroot.html) - Uses ARM to create + a managed disk that is attached to an existing Azure VM that Packer is + running on. Provisioning leverages [Chroot](https://en.wikipedia.org/wiki/Chroot) + environment. After provisioning, the disk is detached an image is created + from this disk. This is an **advanced builder and should not be used by + newcomers**. However, it is also the fastest way to build a VM image in + Azure. + +-> **Don't know which builder to use?** If in doubt, use the [azure-arm +builder](/docs/builders/azure-arm.html). It is much easier to use. + +# Authentication for Azure + +The Packer Azure builders provide a couple of ways to authenticate to Azure. The +following methods are available and are explained below: + +- Azure Active Directory interactive login. Interactive login is available + for the Public and US Gov clouds only. +- Azure Managed Identity +- Azure Active Directory Service Principal + +-> **Don't know which authentication method to use?** Go with interactive +login to try out the builders. If you need packer to run automatically, +switch to using a Service Principal or Managed Identity. + +No matter which method you choose, the identity you use will need the +appropriate permissions on Azure resources for Packer to operate. The minimal +set of permissions is highly dependent on the builder and its configuration. +An easy way to get started is to assign the identity the `Contributor` role at +the subscription level. + +## Azure Active Directory interactive login + +If your organization allows it, you can use a command line interactive login +method based on oAuth 'device code flow'. Packer will select this method when +you only specify a `subscription_id` in your builder configuration. When you +run Packer, it will ask you to visit a web site and input a code. This web site +will then authenticate you, satisfying any two-factor authentication policies +that your organization might have. The tokens are cached under the `.azure/packer` +directory in your home directory and will be reused if they are still valid +on subsequent runs. + +## Azure Managed Identity + +Azure provides the option to assign an identity to a virtual machine ([Azure +documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm)). Packer can +use a system assigned identity for a VM where Packer is running to orchestrate +Azure API's. This is the default behavior and requires no configuration +properties to be set. It does, however, require that you run Packer on an +Azure VM. + +To enable this method, [let Azure assign a system-assigned identity to your VM](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm). +Then, [grant your VM access to the appropriate resources](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/howto-assign-access-portal). +To get started, try assigning the `Contributor` role at the subscription level to +your VM. Then, when you discover your exact scenario, scope the permissions +appropriately or isolate Packer builds in a separate subscription. + +## Azure Active Directory Service Principal + +Azure Active Directory models service accounts as 'Service Principal' (SP) +objects. An SP represents an application accessing your Azure resources. It +is identified by a client ID (aka application ID) and can use a password or a +certificate to authenticate. To use a Service Principal, specify the +`subscription_id` and `client_id`, as well as either `client_secret`, +`client_cert_path` or `client_jwt`. Each of these last three represent a different +way to authenticate the SP to AAD: + +- `client_secret` - allows the user to provide a password/secret registered + for the AAD SP. +- `client_cert_path` - allows usage of a certificate to be used to + authenticate as the specified AAD SP. +- `client_jwt` - For advanced scenario's where the used cannot provide Packer + the full certificate, they can provide a JWT bearer token for client auth + (RFC 7523, Sec. 2.2). These bearer tokens are created and signed using a + certificate registered in AAD and have a user-chosen expiry time, limiting + the validity of the token. This is also the underlying mechanism used to + authenticate when using `client_cert_path`. + +To create a service principal, you can follow [the Azure documentation on this +subject](https://docs.microsoft.com/en-us/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest). + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 6593ae9f9..878c6653a 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -94,8 +94,11 @@ > Azure