github.com/StackPointCloud/packer@v0.10.2-0.20180716202532-b28098e0f79b/website/source/docs/builders/openstack.html.md (about)

     1  ---
     2  description: |
     3      The openstack Packer builder is able to create new images for use with
     4      OpenStack. The builder takes a source image, runs any provisioning necessary
     5      on the image after launching it, then creates a new reusable image. This
     6      reusable image can then be used as the foundation of new servers that are
     7      launched within OpenStack.
     8  layout: docs
     9  page_title: 'OpenStack - Builders'
    10  sidebar_current: 'docs-builders-openstack'
    11  ---
    12  
    13  # OpenStack Builder
    14  
    15  Type: `openstack`
    16  
    17  The `openstack` Packer builder is able to create new images for use with
    18  [OpenStack](http://www.openstack.org). The builder takes a source image, runs
    19  any provisioning necessary on the image after launching it, then creates a new
    20  reusable image. This reusable image can then be used as the foundation of new
    21  servers that are launched within OpenStack. The builder will create temporary
    22  keypairs that provide temporary access to the server while the image is being
    23  created. This simplifies configuration quite a bit.
    24  
    25  The builder does *not* manage images. Once it creates an image, it is up to you
    26  to use it or delete it.
    27  
    28  ~> **Note:** To use OpenStack builder with the OpenStack Newton (Oct 2016)
    29  or earlier, we recommend you use Packer v1.1.2 or earlier version.
    30  
    31  ~> **OpenStack Liberty or later requires OpenSSL!** To use the OpenStack
    32  builder with OpenStack Liberty (Oct 2015) or later you need to have OpenSSL
    33  installed *if you are using temporary key pairs*, i.e. don't use
    34  [`ssh_keypair_name`](openstack.html#ssh_keypair_name) nor
    35  [`ssh_password`](/docs/templates/communicator.html#ssh_password). All major
    36  OS'es have OpenSSL installed by default except Windows. This have been
    37  resolved in OpenStack Ocata(Feb 2017).
    38  
    39  
    40  ## Configuration Reference
    41  
    42  There are many configuration options available for the builder. They are
    43  segmented below into two categories: required and optional parameters. Within
    44  each category, the available configuration keys are alphabetized.
    45  
    46  In addition to the options listed here, a
    47  [communicator](/docs/templates/communicator.html) can be configured for this
    48  builder.
    49  
    50  ### Required:
    51  
    52  -   `flavor` (string) - The ID, name, or full URL for the desired flavor for the
    53      server to be created.
    54  
    55  -   `image_name` (string) - The name of the resulting image.
    56  
    57  -   `identity_endpoint` (string) - The URL to the OpenStack Identity service.
    58      If not specified, Packer will use the environment variables `OS_AUTH_URL`,
    59      if set. This is not required if using `cloud.yaml`.
    60  
    61  -   `source_image` (string) - The ID or full URL to the base image to use. This
    62      is the image that will be used to launch a new server and provision it.
    63      Unless you specify completely custom SSH settings, the source image must
    64      have `cloud-init` installed so that the keypair gets assigned properly.
    65  
    66  -   `source_image_name` (string) - The name of the base image to use. This
    67      is an alternative way of providing `source_image` and only either of them
    68      can be specified.
    69  
    70  -   `username` or `user_id` (string) - The username or id used to connect to
    71      the OpenStack service. If not specified, Packer will use the environment
    72      variable `OS_USERNAME` or `OS_USERID`, if set. This is not required if
    73      using access token instead of password or if using `cloud.yaml`.
    74  
    75  -   `password` (string) - The password used to connect to the OpenStack service.
    76      If not specified, Packer will use the environment variables `OS_PASSWORD`,
    77      if set. This is not required if using access token instead of password or
    78      if using `cloud.yaml`.
    79  
    80  
    81  ### Optional:
    82  
    83  -   `availability_zone` (string) - The availability zone to launch the
    84      server in. If this isn't specified, the default enforced by your OpenStack
    85      cluster will be used. This may be required for some OpenStack clusters.
    86  
    87  -   `cacert` (string) - Custom CA certificate file path.
    88      If omitted the `OS_CACERT` environment variable can be used.
    89  
    90  -   `cert` (string) - Client certificate file path for SSL client authentication.
    91      If omitted the `OS_CERT` environment variable can be used.
    92  
    93  -   `cloud` (string) - An entry in a `clouds.yaml` file. See the OpenStack
    94      os-client-config
    95      [documentation](https://docs.openstack.org/os-client-config/latest/user/configuration.html)
    96      for more information about `clouds.yaml` files. If omitted, the `OS_CLOUD`
    97      environment variable is used.
    98  
    99  -   `config_drive` (boolean) - Whether or not nova should use ConfigDrive for
   100      cloud-init metadata.
   101  
   102  -   `domain_name` or `domain_id` (string) - The Domain name or ID you are
   103      authenticating with. OpenStack installations require this if identity v3 is used.
   104      Packer will use the environment variable `OS_DOMAIN_NAME` or `OS_DOMAIN_ID`, if set.
   105  
   106  -   `endpoint_type` (string) - The endpoint type to use. Can be any of "internal",
   107      "internalURL", "admin", "adminURL", "public", and "publicURL". By default
   108      this is "public".
   109  
   110  -   `floating_ip` (string) - A specific floating IP to assign to this instance.
   111  
   112  -   `floating_ip_pool` (string) - The name of the floating IP pool to use to
   113      allocate a floating IP.
   114  
   115  -   `image_members` (array of strings) - List of members to add to the image
   116      after creation. An image member is usually a project (also called the
   117      "tenant") with whom the image is shared.
   118  
   119  -   `image_visibility` (string) - One of "public", "private", "shared", or
   120      "community".
   121  
   122  -   `insecure` (boolean) - Whether or not the connection to OpenStack can be
   123      done over an insecure connection. By default this is false.
   124  
   125  -   `key` (string) - Client private key file path for SSL client authentication.
   126      If omitted the `OS_KEY` environment variable can be used.
   127  
   128  -   `metadata` (object of key/value strings) - Glance metadata that will be
   129      applied to the image.
   130  
   131  -   `instance_name` (string) - Name that is applied to the server instance
   132      created by Packer. If this isn't specified, the default is same as `image_name`.
   133  
   134  -   `instance_metadata` (object of key/value strings) - Metadata that is
   135      applied to the server instance created by Packer. Also called server
   136      properties in some documentation. The strings have a max size of 255 bytes
   137      each.
   138  
   139  -   `networks` (array of strings) - A list of networks by UUID to attach to
   140      this instance.
   141  
   142  -   `rackconnect_wait` (boolean) - For rackspace, whether or not to wait for
   143      Rackconnect to assign the machine an IP address before connecting via SSH.
   144      Defaults to false.
   145  
   146  -   `region` (string) - The name of the region, such as "DFW", in which to
   147      launch the server to create the AMI. If not specified, Packer will use the
   148      environment variable `OS_REGION_NAME`, if set.
   149  
   150  -   `reuse_ips` (boolean) - Whether or not to attempt to reuse existing
   151      unassigned floating ips in the project before allocating a new one. Note
   152      that it is not possible to safely do this concurrently, so if you are
   153      running multiple openstack builds concurrently, or if other processes are
   154      assigning and using floating IPs in the same openstack project while packer
   155      is running, you should not set this to true. Defaults to false.
   156  
   157  -   `security_groups` (array of strings) - A list of security groups by name to
   158      add to this instance.
   159  
   160  -   `ssh_interface` (string) - The type of interface to connect via SSH. Values
   161      useful for Rackspace are "public" or "private", and the default behavior is
   162      to connect via whichever is returned first from the OpenStack API.
   163  
   164  -   `ssh_ip_version` (string) - The IP version to use for SSH connections, valid
   165      values are `4` and `6`. Useful on dual stacked instances where the default
   166      behavior is to connect via whichever IP address is returned first from the
   167      OpenStack API.
   168  
   169  -   `ssh_keypair_name` (string) - If specified, this is the key that will be
   170      used for SSH with the machine. By default, this is blank, and Packer will
   171      generate a temporary keypair.
   172      [`ssh_password`](/docs/templates/communicator.html#ssh_password) is used.
   173      [`ssh_private_key_file`](/docs/templates/communicator.html#ssh_private_key_file)
   174      or `ssh_agent_auth` must be specified when `ssh_keypair_name` is utilized.
   175  
   176  -   `ssh_agent_auth` (boolean) - If true, the local SSH agent will be used to
   177      authenticate connections to the source instance. No temporary keypair will
   178      be created, and the values of `ssh_password` and `ssh_private_key_file` will
   179      be ignored. To use this option with a key pair already configured in the source
   180      image, leave the `ssh_keypair_name` blank. To associate an existing key pair
   181      with the source instance, set the `ssh_keypair_name` field to the name
   182      of the key pair.
   183  
   184  -   `temporary_key_pair_name` (string) - The name of the temporary key pair
   185      to generate. By default, Packer generates a name that looks like
   186      `packer_<UUID>`, where &lt;UUID&gt; is a 36 character unique identifier.
   187  
   188  -   `tenant_id` or `tenant_name` (string) - The tenant ID or name to boot the
   189      instance into. Some OpenStack installations require this. If not specified,
   190      Packer will use the environment variable `OS_TENANT_NAME` or `OS_TENANT_ID`,
   191      if set. Tenant is also called Project in later versions of OpenStack.
   192  
   193  -   `token` (string) - the token (id) to use with token based authorization.
   194      Packer will use the environment variable `OS_TOKEN`, if set.
   195  
   196  -   `use_floating_ip` (boolean) - *Deprecated* use `floating_ip` or `floating_ip_pool`
   197      instead.
   198  
   199  -   `user_data` (string) - User data to apply when launching the instance. Note
   200      that you need to be careful about escaping characters due to the templates
   201      being JSON. It is often more convenient to use `user_data_file`, instead.
   202  
   203  -   `user_data_file` (string) - Path to a file that will be used for the user
   204      data when launching the instance.
   205  
   206  ## Basic Example: DevStack
   207  
   208  Here is a basic example. This is a example to build on DevStack running in a VM.
   209  
   210  ``` json
   211  {
   212    "type": "openstack",
   213    "identity_endpoint": "http://<destack-ip>:5000/v3",
   214    "tenant_name": "admin",
   215    "domain_name": "Default",
   216    "username": "admin",
   217    "password": "<your admin password>",
   218    "region": "RegionOne",
   219    "ssh_username": "root",
   220    "image_name": "Test image",
   221    "source_image": "<image id>",
   222    "flavor": "m1.tiny",
   223    "insecure": "true"
   224  }
   225  ```
   226  
   227  ## Basic Example: Rackspace public cloud
   228  
   229  Here is a basic example. This is a working example to build a Ubuntu 12.04 LTS
   230  (Precise Pangolin) on Rackspace OpenStack cloud offering.
   231  
   232  ``` json
   233  {
   234    "type": "openstack",
   235    "username": "foo",
   236    "password": "foo",
   237    "region": "DFW",
   238    "ssh_username": "root",
   239    "image_name": "Test image",
   240    "source_image": "23b564c9-c3e6-49f9-bc68-86c7a9ab5018",
   241    "flavor": "2"
   242  }
   243  ```
   244  
   245  ## Basic Example: Private OpenStack cloud
   246  
   247  This example builds an Ubuntu 14.04 image on a private OpenStack cloud, powered
   248  by Metacloud.
   249  
   250  ``` json
   251  {
   252    "type": "openstack",
   253    "ssh_username": "root",
   254    "image_name": "ubuntu1404_packer_test_1",
   255    "source_image": "91d9c168-d1e5-49ca-a775-3bfdbb6c97f1",
   256    "flavor": "2"
   257  }
   258  ```
   259  
   260  In this case, the connection information for connecting to OpenStack doesn't
   261  appear in the template. That is because I source a standard OpenStack script
   262  with environment variables set before I run this. This script is setting
   263  environment variables like:
   264  
   265  -   `OS_AUTH_URL`
   266  -   `OS_TENANT_ID`
   267  -   `OS_USERNAME`
   268  -   `OS_PASSWORD`
   269  
   270  This is slightly different when identity v3 is used:
   271  
   272  -   `OS_AUTH_URL`
   273  -   `OS_USERNAME`
   274  -   `OS_PASSWORD`
   275  -   `OS_DOMAIN_NAME`
   276  -   `OS_TENANT_NAME`
   277  
   278  This will authenticate the user on the domain and scope you to the project.
   279  A tenant is the same as a project. It's optional to use names or IDs in v3.
   280  This means you can use `OS_USERNAME` or `OS_USERID`, `OS_TENANT_ID` or
   281  `OS_TENANT_NAME` and `OS_DOMAIN_ID` or `OS_DOMAIN_NAME`.
   282  
   283  The above example would be equivalent to an RC file looking like this :
   284  
   285  ``` shell
   286  export OS_AUTH_URL="https://identity.myprovider/v3"
   287  export OS_USERNAME="myuser"
   288  export OS_PASSWORD="password"
   289  export OS_USER_DOMAIN_NAME="mydomain"
   290  export OS_PROJECT_DOMAIN_NAME="mydomain"
   291  ```
   292  
   293  ## Notes on OpenStack Authorization
   294  
   295  The simplest way to get all settings for authorization against OpenStack is to
   296  go into the OpenStack Dashboard (Horizon) select your *Project* and navigate
   297  *Project, Access & Security*, select *API Access* and *Download OpenStack RC
   298  File v3*. Source the file, and select your wanted region
   299  by setting environment variable `OS_REGION_NAME` or `OS_REGION_ID` and
   300  `export OS_TENANT_NAME=$OS_PROJECT_NAME` or `export OS_TENANT_ID=$OS_PROJECT_ID`.
   301  
   302  ~&gt; `OS_TENANT_NAME` or `OS_TENANT_ID` must be used even with Identity v3,
   303  `OS_PROJECT_NAME` and `OS_PROJECT_ID` has no effect in Packer.
   304  
   305  To troubleshoot authorization issues test you environment variables with the
   306  OpenStack cli. It can be installed with
   307  
   308      $ pip install --user python-openstackclient
   309  
   310  ### Authorize Using Tokens
   311  
   312  To authorize with a access token only `identity_endpoint` and `token` is needed,
   313  and possibly `tenant_name` or `tenant_id` depending on your token type. Or use
   314  the following environment variables:
   315  
   316  -   `OS_AUTH_URL`
   317  -   `OS_TOKEN`
   318  -   One of `OS_TENANT_NAME` or `OS_TENANT_ID`