Documentation update
This commit is contained in:
Paul Meyer
parent
11ef06b94d
commit
066ae0aa07
|
|
@ -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`.
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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.<br /><br />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
|
||||
<a href="http://aka.ms/devicelogin" class="uri">http://aka.ms/devicelogin</a>,
|
||||
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
|
||||
<a href="https://docs.microsoft.com/en-gb/azure/active-directory/managed-identities-azure-resources/overview"
|
||||
class="uri">managed identities azure resources overview</a> 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.
|
||||
|
|
@ -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).
|
||||
|
||||
|
|
@ -94,8 +94,11 @@
|
|||
<li<%= sidebar_current("docs-builders-azure") %>>
|
||||
<a href="/docs/builders/azure.html">Azure</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-builders-azure-setup") %>>
|
||||
<a href="/docs/builders/azure-setup.html">Setup</a>
|
||||
<li<%= sidebar_current("docs-builders-azure-arm") %>>
|
||||
<a href="/docs/builders/azure-arm.html">ARM</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-builders-azure-chroot") %>>
|
||||
<a href="/docs/builders/azure-chroot.html">chroot</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue