github.com/raghuse92/packer@v1.3.2/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 ~> **Note:** OpenStack Block Storage volume support is available only for 40 V3 Block Storage API. It's available in OpenStack since Mitaka release 41 (Apr 2016). 42 43 ## Configuration Reference 44 45 There are many configuration options available for the builder. They are 46 segmented below into two categories: required and optional parameters. Within 47 each category, the available configuration keys are alphabetized. 48 49 In addition to the options listed here, a 50 [communicator](/docs/templates/communicator.html) can be configured for this 51 builder. 52 53 ### Required: 54 55 - `flavor` (string) - The ID, name, or full URL for the desired flavor for the 56 server to be created. 57 58 - `image_name` (string) - The name of the resulting image. 59 60 - `identity_endpoint` (string) - The URL to the OpenStack Identity service. 61 If not specified, Packer will use the environment variables `OS_AUTH_URL`, 62 if set. This is not required if using `cloud.yaml`. 63 64 - `source_image` (string) - The ID or full URL to the base image to use. This 65 is the image that will be used to launch a new server and provision it. 66 Unless you specify completely custom SSH settings, the source image must 67 have `cloud-init` installed so that the keypair gets assigned properly. 68 69 - `source_image_name` (string) - The name of the base image to use. This 70 is an alternative way of providing `source_image` and only either of them 71 can be specified. 72 73 - `source_image_filter` (map) - The search filters for determining the base 74 image to use. This is an alternative way of providing `source_image` and 75 only one of these methods can be used. `source_image` will override the 76 filters. 77 78 - `username` or `user_id` (string) - The username or id used to connect to 79 the OpenStack service. If not specified, Packer will use the environment 80 variable `OS_USERNAME` or `OS_USERID`, if set. This is not required if 81 using access token instead of password or if using `cloud.yaml`. 82 83 - `password` (string) - The password used to connect to the OpenStack service. 84 If not specified, Packer will use the environment variables `OS_PASSWORD`, 85 if set. This is not required if using access token instead of password or 86 if using `cloud.yaml`. 87 88 89 ### Optional: 90 91 - `availability_zone` (string) - The availability zone to launch the 92 server in. If this isn't specified, the default enforced by your OpenStack 93 cluster will be used. This may be required for some OpenStack clusters. 94 95 - `cacert` (string) - Custom CA certificate file path. 96 If omitted the `OS_CACERT` environment variable can be used. 97 98 - `cert` (string) - Client certificate file path for SSL client authentication. 99 If omitted the `OS_CERT` environment variable can be used. 100 101 - `cloud` (string) - An entry in a `clouds.yaml` file. See the OpenStack 102 os-client-config 103 [documentation](https://docs.openstack.org/os-client-config/latest/user/configuration.html) 104 for more information about `clouds.yaml` files. If omitted, the `OS_CLOUD` 105 environment variable is used. 106 107 - `config_drive` (boolean) - Whether or not nova should use ConfigDrive for 108 cloud-init metadata. 109 110 - `domain_name` or `domain_id` (string) - The Domain name or ID you are 111 authenticating with. OpenStack installations require this if identity v3 is used. 112 Packer will use the environment variable `OS_DOMAIN_NAME` or `OS_DOMAIN_ID`, if set. 113 114 - `endpoint_type` (string) - The endpoint type to use. Can be any of "internal", 115 "internalURL", "admin", "adminURL", "public", and "publicURL". By default 116 this is "public". 117 118 - `floating_ip` (string) - A specific floating IP to assign to this instance. 119 120 - `floating_ip_network` (string) - The ID or name of an external network that 121 can be used for creation of a new floating IP. 122 123 - `floating_ip_pool` (string) - *Deprecated* use `floating_ip_network` 124 instead. 125 126 - `image_members` (array of strings) - List of members to add to the image 127 after creation. An image member is usually a project (also called the 128 "tenant") with whom the image is shared. 129 130 - `image_visibility` (string) - One of "public", "private", "shared", or 131 "community". 132 133 - `insecure` (boolean) - Whether or not the connection to OpenStack can be 134 done over an insecure connection. By default this is false. 135 136 - `key` (string) - Client private key file path for SSL client authentication. 137 If omitted the `OS_KEY` environment variable can be used. 138 139 - `metadata` (object of key/value strings) - Glance metadata that will be 140 applied to the image. 141 142 - `instance_name` (string) - Name that is applied to the server instance 143 created by Packer. If this isn't specified, the default is same as `image_name`. 144 145 - `instance_metadata` (object of key/value strings) - Metadata that is 146 applied to the server instance created by Packer. Also called server 147 properties in some documentation. The strings have a max size of 255 bytes 148 each. 149 150 - `networks` (array of strings) - A list of networks by UUID to attach to 151 this instance. 152 153 - `ports` (array of strings) - A list of ports by UUID to attach to 154 this instance. 155 156 - `rackconnect_wait` (boolean) - For rackspace, whether or not to wait for 157 Rackconnect to assign the machine an IP address before connecting via SSH. 158 Defaults to false. 159 160 - `region` (string) - The name of the region, such as "DFW", in which to 161 launch the server to create the image. If not specified, Packer will use the 162 environment variable `OS_REGION_NAME`, if set. 163 164 - `reuse_ips` (boolean) - Whether or not to attempt to reuse existing 165 unassigned floating ips in the project before allocating a new one. Note 166 that it is not possible to safely do this concurrently, so if you are 167 running multiple openstack builds concurrently, or if other processes are 168 assigning and using floating IPs in the same openstack project while packer 169 is running, you should not set this to true. Defaults to false. 170 171 - `security_groups` (array of strings) - A list of security groups by name to 172 add to this instance. 173 174 - `source_image_filter` (object) - Filters used to populate filter options. 175 Example: 176 177 ``` json 178 { 179 "source_image_filter": { 180 "filters": { 181 "name": "ubuntu-16.04", 182 "visibility": "protected", 183 "owner": "d1a588cf4b0743344508dc145649372d1", 184 "tags": ["prod", "ready"] 185 }, 186 "most_recent": true 187 } 188 } 189 ``` 190 191 This selects the most recent production Ubuntu 16.04 shared to you by the given owner. 192 NOTE: This will fail unless *exactly* one image is returned, or `most_recent` is set to true. 193 In the example of multiple returned images, `most_recent` will cause this to succeed by selecting 194 the newest image of the returned images. 195 196 - `filters` (map of strings) - filters used to select a `source_image`. 197 NOTE: This will fail unless *exactly* one image is returned, or `most_recent` is set to true. 198 Of the filters described in [ImageService](https://developer.openstack.org/api-ref/image/v2/), the following 199 are valid: 200 201 - name (string) 202 203 - owner (string) 204 205 - tags (array of strings) 206 207 - visibility (string) 208 209 - `most_recent` (boolean) - Selects the newest created image when true. 210 This is most useful for selecting a daily distro build. 211 212 You may set use this in place of `source_image` If `source_image_filter` is provided 213 alongside `source_image`, the `source_image` will override the filter. The filter 214 will not be used in this case. 215 216 - `ssh_interface` (string) - The type of interface to connect via SSH. Values 217 useful for Rackspace are "public" or "private", and the default behavior is 218 to connect via whichever is returned first from the OpenStack API. 219 220 - `ssh_ip_version` (string) - The IP version to use for SSH connections, valid 221 values are `4` and `6`. Useful on dual stacked instances where the default 222 behavior is to connect via whichever IP address is returned first from the 223 OpenStack API. 224 225 - `ssh_keypair_name` (string) - If specified, this is the key that will be 226 used for SSH with the machine. By default, this is blank, and Packer will 227 generate a temporary keypair. 228 [`ssh_password`](/docs/templates/communicator.html#ssh_password) is used. 229 [`ssh_private_key_file`](/docs/templates/communicator.html#ssh_private_key_file) 230 or `ssh_agent_auth` must be specified when `ssh_keypair_name` is utilized. 231 232 - `ssh_agent_auth` (boolean) - If true, the local SSH agent will be used to 233 authenticate connections to the source instance. No temporary keypair will 234 be created, and the values of `ssh_password` and `ssh_private_key_file` will 235 be ignored. To use this option with a key pair already configured in the source 236 image, leave the `ssh_keypair_name` blank. To associate an existing key pair 237 with the source instance, set the `ssh_keypair_name` field to the name 238 of the key pair. 239 240 - `temporary_key_pair_name` (string) - The name of the temporary key pair 241 to generate. By default, Packer generates a name that looks like 242 `packer_<UUID>`, where <UUID> is a 36 character unique identifier. 243 244 - `tenant_id` or `tenant_name` (string) - The tenant ID or name to boot the 245 instance into. Some OpenStack installations require this. If not specified, 246 Packer will use the environment variable `OS_TENANT_NAME` or `OS_TENANT_ID`, 247 if set. Tenant is also called Project in later versions of OpenStack. 248 249 - `token` (string) - the token (id) to use with token based authorization. 250 Packer will use the environment variable `OS_TOKEN`, if set. 251 252 - `use_floating_ip` (boolean) - *Deprecated* use `floating_ip` or `floating_ip_pool` 253 instead. 254 255 - `user_data` (string) - User data to apply when launching the instance. Note 256 that you need to be careful about escaping characters due to the templates 257 being JSON. It is often more convenient to use `user_data_file`, instead. 258 259 - `user_data_file` (string) - Path to a file that will be used for the user 260 data when launching the instance. 261 262 - `use_blockstorage_volume` (boolean) - Use Block Storage service volume for 263 the instance root volume instead of Compute service local volume (default). 264 265 - `volume_name` (string) - Name of the Block Storage service volume. If this 266 isn't specified, random string will be used. 267 268 - `volume_type` (string) - Type of the Block Storage service volume. If this 269 isn't specified, the default enforced by your OpenStack cluster will be 270 used. 271 272 - `volume_availability_zone` (string) - Availability zone of the Block 273 Storage service volume. If omitted, Compute instance availability zone will 274 be used. If both of Compute instance and Block Storage volume availability 275 zones aren't specified, the default enforced by your OpenStack cluster will 276 be used. 277 278 - `image_disk_format` (string) - Disk format of the resulting image. 279 This option works if `use_blockstorage_volume` is true. 280 281 ## Basic Example: DevStack 282 283 Here is a basic example. This is a example to build on DevStack running in a VM. 284 285 ``` json 286 { 287 "type": "openstack", 288 "identity_endpoint": "http://<destack-ip>:5000/v3", 289 "tenant_name": "admin", 290 "domain_name": "Default", 291 "username": "admin", 292 "password": "<your admin password>", 293 "region": "RegionOne", 294 "ssh_username": "root", 295 "image_name": "Test image", 296 "source_image": "<image id>", 297 "flavor": "m1.tiny", 298 "insecure": "true" 299 } 300 ``` 301 302 ## Basic Example: Rackspace public cloud 303 304 Here is a basic example. This is a working example to build a Ubuntu 12.04 LTS 305 (Precise Pangolin) on Rackspace OpenStack cloud offering. 306 307 ``` json 308 { 309 "type": "openstack", 310 "username": "foo", 311 "password": "foo", 312 "region": "DFW", 313 "ssh_username": "root", 314 "image_name": "Test image", 315 "source_image": "23b564c9-c3e6-49f9-bc68-86c7a9ab5018", 316 "flavor": "2" 317 } 318 ``` 319 320 ## Basic Example: Private OpenStack cloud 321 322 This example builds an Ubuntu 14.04 image on a private OpenStack cloud, powered 323 by Metacloud. 324 325 ``` json 326 { 327 "type": "openstack", 328 "ssh_username": "root", 329 "image_name": "ubuntu1404_packer_test_1", 330 "source_image": "91d9c168-d1e5-49ca-a775-3bfdbb6c97f1", 331 "flavor": "2" 332 } 333 ``` 334 335 In this case, the connection information for connecting to OpenStack doesn't 336 appear in the template. That is because I source a standard OpenStack script 337 with environment variables set before I run this. This script is setting 338 environment variables like: 339 340 - `OS_AUTH_URL` 341 - `OS_TENANT_ID` 342 - `OS_USERNAME` 343 - `OS_PASSWORD` 344 345 This is slightly different when identity v3 is used: 346 347 - `OS_AUTH_URL` 348 - `OS_USERNAME` 349 - `OS_PASSWORD` 350 - `OS_DOMAIN_NAME` 351 - `OS_TENANT_NAME` 352 353 This will authenticate the user on the domain and scope you to the project. 354 A tenant is the same as a project. It's optional to use names or IDs in v3. 355 This means you can use `OS_USERNAME` or `OS_USERID`, `OS_TENANT_ID` or 356 `OS_TENANT_NAME` and `OS_DOMAIN_ID` or `OS_DOMAIN_NAME`. 357 358 The above example would be equivalent to an RC file looking like this : 359 360 ``` shell 361 export OS_AUTH_URL="https://identity.myprovider/v3" 362 export OS_USERNAME="myuser" 363 export OS_PASSWORD="password" 364 export OS_USER_DOMAIN_NAME="mydomain" 365 export OS_PROJECT_DOMAIN_NAME="mydomain" 366 ``` 367 368 ## Basic Example: Instance with Block Storage root volume 369 370 A basic example of Instance with a remote root Block Storage service volume. 371 This is a working example to build an image on private OpenStack cloud powered 372 by Selectel VPC. 373 374 ``` json 375 { 376 "type": "openstack", 377 "identity_endpoint": "https://api.selvpc.com/identity/v3", 378 "tenant_id": "2e90c5c04c7b4c509be78723e2b55b77", 379 "username": "foo", 380 "password": "foo", 381 "region": "ru-3", 382 "ssh_username": "root", 383 "image_name": "Test image", 384 "source_image": "5f58ea7e-6264-4939-9d0f-0c23072b1132", 385 "networks": "9aab504e-bedf-48af-9256-682a7fa3dabb", 386 "flavor": "1001", 387 "availability_zone": "ru-3a", 388 "use_blockstorage_volume": true, 389 "volume_type": "fast.ru-3a" 390 } 391 ``` 392 393 ## Notes on OpenStack Authorization 394 395 The simplest way to get all settings for authorization against OpenStack is to 396 go into the OpenStack Dashboard (Horizon) select your *Project* and navigate 397 *Project, Access & Security*, select *API Access* and *Download OpenStack RC 398 File v3*. Source the file, and select your wanted region 399 by setting environment variable `OS_REGION_NAME` or `OS_REGION_ID` and 400 `export OS_TENANT_NAME=$OS_PROJECT_NAME` or `export OS_TENANT_ID=$OS_PROJECT_ID`. 401 402 ~> `OS_TENANT_NAME` or `OS_TENANT_ID` must be used even with Identity v3, 403 `OS_PROJECT_NAME` and `OS_PROJECT_ID` has no effect in Packer. 404 405 To troubleshoot authorization issues test you environment variables with the 406 OpenStack cli. It can be installed with 407 408 $ pip install --user python-openstackclient 409 410 ### Authorize Using Tokens 411 412 To authorize with a access token only `identity_endpoint` and `token` is needed, 413 and possibly `tenant_name` or `tenant_id` depending on your token type. Or use 414 the following environment variables: 415 416 - `OS_AUTH_URL` 417 - `OS_TOKEN` 418 - One of `OS_TENANT_NAME` or `OS_TENANT_ID`