openstack_compute_instance_v2

For your information

These instructions are an adapted copy of the official OpenStack Terraform provider documentation in the Terraform Registry.

Manages a V2 VM instance resource within OpenStack.

All arguments including the instance admin password will be stored in the raw state as plain-text. Read more about sensitive data instate.

Example Usage⁠

Basic Instance⁠

resource "openstack_compute_instance_v2" "basic" {
  name            = "basic"
  image_id        = "<image-id>"
  flavor_id       = "1311"
  key_pair        = "<key-pair-name>"

  metadata = {
    this = "that"
  }

  network {
    name = "<network-name>"
  }
}

Instance With Attached Volume⁠

resource "openstack_blockstorage_volume_v3" "myvol" {
  name = "myvol"
  size = 5
}

resource "openstack_compute_instance_v2" "myinstance" {
  name            = "myinstance"
  image_id        = "<image-id>"
  flavor_id       = "1311"
  key_pair        = "<key-pair-name>"

  network {
    name = "<network-name>"
  }
}

resource "openstack_compute_volume_attach_v2" "attached" {
  instance_id = openstack_compute_instance_v2.myinstance.id
  volume_id   = openstack_blockstorage_volume_v3.myvol.id
}

Boot From Volume⁠

resource "openstack_compute_instance_v2" "boot-from-volume" {
  name            = "boot-from-volume"
  flavor_id       = "1011"
  key_pair        = "<key-pair-name>"

  block_device {
    uuid                  = "<image-id>"
    source_type           = "image"
    volume_size           = 5
    boot_index            = 0
    destination_type      = "volume"
    delete_on_termination = true
  }

  network {
    name = "<network-name>"
  }
}

Boot From an Existing Volume⁠

resource "openstack_blockstorage_volume_v3" "myvol" {
  name     = "myvol"
  size     = 5
  image_id = "<image-id>"
}

resource "openstack_compute_instance_v2" "boot-from-volume" {
  name            = "bootfromvolume"
  flavor_id       = "1011"
  key_pair        = "<key-pair-name>"

  block_device {
    uuid                  = openstack_blockstorage_volume_v3.myvol.id
    source_type           = "volume"
    boot_index            = 0
    destination_type      = "volume"
    delete_on_termination = true
  }

  network {
    name = "<network-name>"
  }
}

Boot Instance, Create Volume, and Attach Volume as a Block Device⁠

resource "openstack_compute_instance_v2" "instance_1" {
  name            = "instance_1"
  image_id        = "<image-id>"
  flavor_id       = "1311"
  key_pair        = "<key-pair-name>"

  block_device {
    uuid                  = "<image-id>"
    source_type           = "image"
    destination_type      = "local"
    boot_index            = 0
    delete_on_termination = true
  }

  block_device {
    source_type           = "blank"
    destination_type      = "volume"
    volume_size           = 5
    boot_index            = 1
    delete_on_termination = true
  }
}

Boot Instance and Attach Existing Volume as a Block Device⁠

resource "openstack_blockstorage_volume_v3" "volume_1" {
  name = "volume_1"
  size = 1
}

resource "openstack_compute_instance_v2" "instance_1" {
  name            = "instance_1"
  image_id        = "<image-id>"
  flavor_id       = "1311"
  key_pair        = "<key-pair-name>"

  block_device {
    uuid                  = "<image-id>"
    source_type           = "image"
    destination_type      = "local"
    boot_index            = 0
    delete_on_termination = true
  }

  block_device {
    uuid                  = openstack_blockstorage_volume_v3.volume_1.id
    source_type           = "volume"
    destination_type      = "volume"
    boot_index            = 1
    delete_on_termination = true
  }
}

Instance With Multiple Networks⁠

resource "openstack_networking_floatingip_v2" "myip" {
  pool = "my_pool"
}

resource "openstack_compute_instance_v2" "multi-net" {
  name            = "multi-net"
  image_id        = "<image-id>"
  flavor_id       = "1311"
  key_pair        = "<key-pair-name>"

  network {
    name = "<network1-name>"
  }

  network {
    name = "<network2-name>"
  }
}

resource "openstack_compute_floatingip_associate_v2" "myip" {
  floating_ip = openstack_networking_floatingip_v2.myip.address
  instance_id = openstack_compute_instance_v2.multi-net.id
  fixed_ip    = openstack_compute_instance_v2.multi-net.network.1.fixed_ip_v4
}

Instance With Personality⁠

resource "openstack_compute_instance_v2" "personality" {
  name            = "personality"
  image_id        = "<image-id>"
  flavor_id       = "1311"
  key_pair        = "<key-pair-name>"

  personality {
    file    = "/path/to/file/on/instance.txt"
    content = "contents of file"
  }

  network {
    name = "<network-name>"
  }
}

Instance with Multiple Ephemeral Disks⁠

For your information

Applicable only to Private Clouds

resource "openstack_compute_instance_v2" "multi-eph" {
  name            = "multi_eph"
  image_id        = <image-id>
  flavor_id       = "1311"
  key_pair        = "<key-pair-name>"

  block_device {
    boot_index            = 0
    delete_on_termination = true
    destination_type      = "local"
    source_type           = "image"
    uuid                  = "<image-id>"
  }

  block_device {
    boot_index            = -1
    delete_on_termination = true
    destination_type      = "local"
    source_type           = "blank"
    volume_size           = 1
    guest_format          = "ext4"
  }

  block_device {
    boot_index            = -1
    delete_on_termination = true
    destination_type      = "local"
    source_type           = "blank"
    volume_size           = 1
  }
}

Instance with Boot Disk and Swap Disk⁠

For your information

Applicable only to Private Clouds

resource "openstack_compute_flavor_v2" "flavor-with-swap" {
  name  = "flavor-with-swap"
  ram   = "8096"
  vcpus = "2"
  disk  = "20"
  swap  = "4096"
}

resource "openstack_compute_instance_v2" "vm-swap" {
  name            = "vm_swap"
  flavor_id       = openstack_compute_flavor_v2.flavor-with-swap.id
  key_pair        = "<key-pair-name>"

  block_device {
    boot_index            = 0
    delete_on_termination = true
    destination_type      = "local"
    source_type           = "image"
    uuid                  = "<image-id>"
  }

  block_device {
    boot_index            = -1
    delete_on_termination = true
    destination_type      = "local"
    source_type           = "blank"
    guest_format          = "swap"
    volume_size           = 4
  }
}

Instance with User Data (cloud-init)⁠

resource "openstack_compute_instance_v2" "instance_1" {
  name            = "basic"
  image_id        = "<image-id>"
  flavor_id       = "1311"
  key_pair        = "<key-pair-name>"
  user_data       = "#cloud-config\nhostname: instance_1.example.com\nfqdn: instance_1.example.com"

  network {
    name = "<network-name>"
  }
}

user_data can come from a variety of sources: inline, read in from the file function, or the template_cloudinit_config resource.

Argument Reference⁠

The following arguments are supported:

region — (Optional) The region in which to create the server instance. Ifomitted, the region argument of the provider is used. Changing thiscreates a new server.
name — (Required) A unique name for the resource.
image_id — (Optional; Required if image_name is empty and not bootingfrom a volume. Do not specify if booting from a volume.) The image ID ofthe desired image for the server. Changing this rebuilds the existingserver.
image_name — (Optional; Required if image_id is empty and not bootingfrom a volume. Do not specify if booting from a volume.) The name of thedesired image for the server. Changing this rebuilds the existing server.
flavor_id — (Optional; Required if flavor_name is empty) The flavor ID ofthe desired flavor for the server. Changing this resizes the existing server.
flavor_name — (Optional; Required if flavor_id is empty) The name of thedesired flavor for the server. Changing this resizes the existing server.
user_data — (Optional) The user data to provide when launching the instance.Changing this creates a new server.
availability_zone_hints — (Optional) The availability zone in which tocreate the server. This argument is preferred to availability_zone whenscheduling the server on a particular host or node. Conflicts with availability_zone. Changing this creates anew server.
availability_zone — (Optional) The availability zone in which to createthe server. Conflicts with availability_zone_hints. Changing this createsa new server.
network — (Optional) An array of one or more networks to attach to theinstance. The network object structure is documented below. Changing thiscreates a new server.
network_mode — (Optional) Special string for network option to createthe server. network_mode can be "auto" or "none".Please see the following reference for more information. Conflicts with network.
metadata — (Optional) Metadata key/value pairs to make available fromwithin the instance. Changing this updates the existing server metadata.
config_drive — (Optional) Whether to use the config_drive feature toconfigure the instance. Changing this creates a new server.
admin_pass — (Optional) The administrative password to assign to the server.Changing this changes the root password on the existing server.
key_pair — (Optional) The name of a key pair to put on the server. The keypair must already be created and associated with the tenant's account.Changing this creates a new server.
block_device — (Optional) Configuration of block devices. The block_devicestructure is documented below. Changing this creates a new server.You can specify multiple block devices which will create an instance withmultiple disks. This configuration is very flexible, so please see thefollowing reference for more information.
scheduler_hints — (Optional) Provide the Nova scheduler with hints on howthe instance should be launched. The available hints are described below.

For your information

When you import an instance belonging to a server group, the scheduler_hints block in a state file remains empty and Terraform will require to recreate an instance in the server group. For more information about the ways to avoid the problem, see the Importing an instance belonging to a server group.

personality — (Optional) Customize the personality of an instance bydefining one or more files and their contents. The personality structureis described below. Changing this rebuilds the existing server.
stop_before_destroy — (Optional) Whether to try stopping instance gracefullybefore destroying it, thus giving chance for guest OS daemons to stop correctly.If instance doesn't stop within timeout, it will be destroyed anyway.
force_delete — (Optional) Whether to force the OpenStack instance to beforcefully deleted. This is useful for environments that have reclaim / softdeletion enabled.
power_state — (Optional) Provide the VM state. Only 'active', 'shutoff'and 'shelved_offloaded' are supported values. Note: If the initial power_state is the shutoffthe VM will be stopped immediately after build and the provisioners likeremote-exec or files are not supported.
tags — (Optional) A set of string tags for the instance. Changing thisupdates the existing instance tags.
vendor_options — (Optional) Map of additional vendor-specific options.Supported options are described below.

The network block supports:

uuid — (Required unless port or name is provided) The network UUID toattach to the server. Changing this creates a new server.
name — (Required unless uuid or port is provided) The human-readablename of the network. Changing this creates a new server.
port — (Required unless uuid or name is provided) The port UUID of anetwork to attach to the server. Changing this creates a new server.
fixed_ip_v4 — (Optional) Specifies a fixed IPv4 address to be used on thisnetwork. Changing this creates a new server.
access_network — (Optional) Specifies if this network should be used forprovisioning access. Accepts true or false. Defaults to false.

The block_device block supports:

uuid — (Required unless source_type is set to "blank" ) The UUID ofthe image, volume, or snapshot. Changing this creates a new server.
source_type — (Required) The source type of the device. Must be one of "blank", "image", "volume", or "snapshot". Changing this creates a newserver.
volume_size — The size of the volume to create (in gigabytes). Requiredin the following combinations: source=image and destination=volume,source=blank and destination=local, and source=blank and destination=volume.Changing this creates a new server.
guest_format — (Optional) Specifies the guest server disk file system format,such as ext2, ext3, ext4, xfs or swap. Swap block device mappingshave the following restrictions: source_type must be blank and destination_typemust be local and only one swap disk per server and the size of the swap diskmust be less than or equal to the swap size of the flavor. Changing thiscreates a new server.
boot_index — (Optional) The boot index of the volume. It defaults to 0.Changing this creates a new server.
destination_type — (Optional) The type that gets created. Possible valuesare "volume" and "local". Changing this creates a new server.
delete_on_termination — (Optional) Delete the volume / block device upontermination of the instance. Defaults to false. Changing this creates anew server.
volume_type — (Optional) The volume type that will be used, for example SSDor HDD storage. The available options depend on how your specific OpenStackcloud is configured and what classes of storage are provided. Changing thiscreates a new server.
device_type — (Optional) The low-level device type that will be used. Mostcommon thing is to leave this empty. Changing this creates a new server.
disk_bus — (Optional) The low-level disk bus that will be used. Most commonthing is to leave this empty. Changing this creates a new server.
multiattach — (Optional) Enable the attachment of multiattach-capablevolumes. Applicable only to Private Clouds.

The scheduler_hints block supports:

group — (Optional) A UUID of a Server Group. The instance will be placedinto that group.
different_host — (Optional) A list of instance UUIDs. The instance willbe scheduled on a different host than all other instances.
same_host — (Optional) A list of instance UUIDs. The instance will bescheduled on the same host of those specified.
query — (Optional) A conditional query that a compute node must pass inorder to host an instance. The query must use the JsonFilter syntaxwhich is described here.At this time, only simple queries are supported. Compound queries using and, or, or not are not supported. Applicable only to Private Clouds An example of a simple query is:
```
[">=", "$free_ram_mb", "1024"]
```
target_cell — (Optional) The name of a cell to host the instance.Applicable only to Private Clouds.
different_cell — (Optional) The names of cells where not to build the instance.Applicable only to Private Clouds.
build_near_host_ip — (Optional) An IP Address in CIDR form. The instancewill be placed on a compute node that is in the same subnet. Applicable onlyto Private Clouds.
additional_properties — (Optional) Arbitrary key/value pairs of additionalproperties to pass to the scheduler.

The personality block supports:

file — (Required) The absolute path of the destination file.
content — (Required) The contents of the file. Limited to 255 bytes.

The vendor_options block supports:

ignore_resize_confirmation — (Optional) Boolean to control whetherto ignore manual confirmation of the instance resizing. This can be helpfulto work with some OpenStack clouds which automatically confirm resizing ofinstances after some timeout.
detach_ports_before_destroy — (Optional) Whether to try to detach all attachedports to the vm before destroying it to make sure the port state is correctafter the vm destruction. This is helpful when the port is not deleted.

Attributes Reference⁠

The following attributes are exported:

region — See Argument Reference above.
name — See Argument Reference above.
access_ip_v4 — The first detected Fixed IPv4 address.
access_ip_v6 — The first detected Fixed IPv6 address.
metadata — See Argument Reference above.
flavor_id — See Argument Reference above.
flavor_name — See Argument Reference above.
network/uuid — See Argument Reference above.
network/name — See Argument Reference above.
network/port — See Argument Reference above.
network/fixed_ip_v4 — The Fixed IPv4 address of the Instance on thatnetwork.
network/fixed_ip_v6 — The Fixed IPv6 address of the Instance on thatnetwork.
network/mac — The MAC address of the NIC on that network.
all_metadata — Contains all instance metadata, even metadata not setby Terraform.
tags — See Argument Reference above.
all_tags — The collection of tags assigned on the instance, which havebeen explicitly and implicitly added.
created — The creation time of the instance.
updated — The time when the instance was last updated.

Notes⁠

Multiple Ephemeral Disks⁠

For your information

Applicable only to Private Clouds

It's possible to specify multiple block_device entries to create an instancewith multiple ephemeral (local) disks. In order to create multiple ephemeraldisks, the sum of the total amount of ephemeral space must be less than orequal to what the chosen flavor supports.

The following example shows how to create an instance with multiple ephemeraldisks:

resource "openstack_compute_instance_v2" "foo" {
  name            = "terraform-test"

  block_device {
    boot_index            = 0
    delete_on_termination = true
    destination_type      = "local"
    source_type           = "image"
    uuid                  = "<image-id>"
  }

  block_device {
    boot_index            = -1
    delete_on_termination = true
    destination_type      = "local"
    source_type           = "blank"
    volume_size           = 1
  }

  block_device {
    boot_index            = -1
    delete_on_termination = true
    destination_type      = "local"
    source_type           = "blank"
    volume_size           = 1
  }
}

Instances and Ports⁠

Neutron Ports are a great feature and provide a lot of functionality. However,there are some notes to be aware of when mixing Instances and Ports:

In OpenStack environments prior to the Kilo release, deleting or recreatingan Instance will cause the Instance's Port(s) to be deleted. One way of workingaround this is to taint any Port(s) used in Instances which are to be recreated.See here for further information.
When attaching an Instance to one or more networks using Ports, place thesecurity groups on the Port and not the Instance. If you place the securitygroups on the Instance, the security groups will not be applied upon creation,but they will be applied upon a refresh. This is a known OpenStack bug.
Network IP information is not available within an instance for networks thatare attached with Ports. This is mostly due to the flexibility Neutron Portsprovide when it comes to IP addresses. For example, a Neutron Port can havemultiple Fixed IP addresses associated with it. It's not possible to know whichsingle IP address the user would want returned to the Instance's stateinformation. Therefore, in order for a Provisioner to connect to an Instancevia it's network Port, customize the connection information:

resource "openstack_networking_port_v2" "port_1" {
  name           = "port_1"
  admin_state_up = "true"

  network_id = "0a1d0a27-cffa-4de3-92c5-9d3fd3f2e74d"
}

resource "openstack_compute_instance_v2" "instance_1" {
  name = "instance_1"

  network {
    port = openstack_networking_port_v2.port_1.id
  }

  connection {
    user        = "root"
    host        = openstack_networking_port_v2.port_1.fixed_ip.0.ip_address
    private_key = "~/path/to/key"
  }

  provisioner "remote-exec" {
    inline = [
      "echo terraform executed > /tmp/foo",
    ]
  }
}

Instances and Networks⁠

Instances almost always require a network. Here are some notes to be aware ofwith how Instances and Networks relate:

In scenarios where you only have one network available, you can create aninstance without specifying a network block. OpenStack will automaticallylaunch the instance on this network.
If you have access to more than one network, you will need to specify a networkwith a network block. Not specifying a network will result in the followingerror:

* openstack_compute_instance_v2.instance: Error creating OpenStack server:
Expected HTTP response code [201 202] when accessing [POST https://example.com:8774/v2.1/servers], but got 409 instead
{"conflictingRequest": {"message": "Multiple possible networks found, use a Network ID to be more specific.", "code": 409}}

If you intend to use the openstack_compute_interface_attach_v2 resource,you still need to make sure one of the above points is satisfied. An instancecannot be created without a valid network configuration even if you intend to touse openstack_compute_interface_attach_v2 after the instance has been created.

Importing instances⁠

Importing instances can be tricky, since the nova api does not offer allinformation provided at creation time for later retrieval.Network interface attachment order, and number and sizes of ephemeraldisks are examples of this.

Importing basic instance⁠

Assume you want to import an instance with one ephemeral root disk,and one network interface.

Your configuration would look like the following:

resource "openstack_compute_instance_v2" "basic_instance" {
  name            = "basic"
  flavor_id       = "<flavor-id>"
  key_pair        = "<key-pair-name>"
  image_id        = "<image-id>"

  network {
    name = "<network-name>"
  }
}

Then you execute

terraform import openstack_compute_instance_v2.basic_instance instance_id

Importing an instance with multiple emphemeral disks⁠

The importer cannot read the emphemeral disk configurationof an instance, so just specify image_id as in the configurationof the basic instance example.

Importing instance with multiple network interfaces.⁠

Nova returns the network interfaces grouped by network, thus not in creationorder.That means that if you have multiple network interfaces you must takecare of the order of networks in your configuration.

As example we want to import an instance with one ephemeral root disk,and 3 network interfaces.

Examples

resource "openstack_compute_instance_v2" "boot-from-volume" {
  name            = "boot-from-volume"
  flavor_id       = "<flavor-id>"
  key_pair        = "<key-pair-name>"
  image_id        = "<image-id>"

  network {
    name = "<network1>"
  }
  network {
    name = "<network2>"
  }
  network {
    name = "<network1>"
    fixed_ip_v4 = "<fixed_ip_v4>"
  }

}

In the above configuration the networks are out of order compared to what novaand thus the import code returns, which means the plan will notbe empty after import.

So either with care check the plan and modify configuration, or read thenetwork order in the state file after import and modify yourconfiguration accordingly.

A note on ports. If you have created a neutron port independent of aninstance, then the import code has no way to detect that the port is createdidenpendently, and therefore on deletion of imported instances you might haveport resources in your project, which you expected to be created by theinstance and thus to also be deleted with the instance.

Importing instances with multiple block storage volumes.⁠

We have an instance with two block storage volumes, one bootable and onenon-bootable.Note that we only configure the bootable device as block_device.The other volumes can be specified as openstack_blockstorage_volume_v3

resource "openstack_compute_instance_v2" "instance_2" {
  name            = "instance_2"
  image_id        = "<image-id>"
  flavor_id       = "<flavor-id>"
  key_pair        = "<key-pair-name>"

  block_device {
    uuid                  = "<image-id>"
    source_type           = "image"
    destination_type      = "volume"
    boot_index            = 0
    delete_on_termination = true
  }

   network {
    name = "<network-name>"
  }
}
resource "openstack_blockstorage_volume_v3" "volume_1" {
  size = 5
  name = "<volume-name>"
}
resource "openstack_compute_volume_attach_v2" "va_1" {
  volume_id   = openstack_blockstorage_volume_v3.volume_1.id
  instance_id = openstack_compute_instance_v2.instance_2.id
}

To import the instance outlined in the above configurationdo the following:

terraform import openstack_compute_instance_v2.instance_2 instance_id
import openstack_blockstorage_volume_v3.volume_1 volume_id
terraform import openstack_compute_volume_attach_v2.va_1
instance_id/volume_id

A note on block storage volumes, the importer does not readdelete_on_termination flag, and always assumes true. If youimport an instance created with delete_on_termination false,you end up with "orphaned" volumes after destruction ofinstances.

Importing an instance belonging to a server group⁠

When you import an instance belonging to a server group to a state file, the scheduler_hints block remains empty in the state file. It means that Terraform considers the instance as not belonging to any server group. Due to this, when you add the scheduler_hints block with a server group UUID to a configuration file and check or apply changes, Terraform requires to create a new instance in the specified server group.

Ways to avoid the problem:

skip the description of the group argument in the scheduler_hints block of the configuration file. However, in this case, Terraform does not have information about the server group to which the instance belongs.
(recommended) manually add a UUID of a server group to the group argument in the scheduler_hints block of the state file.

Example Usage⁠​

Basic Instance⁠​

Instance With Attached Volume⁠​

Boot From Volume⁠​

Boot From an Existing Volume⁠​

Boot Instance, Create Volume, and Attach Volume as a Block Device⁠​

Boot Instance and Attach Existing Volume as a Block Device⁠​

Instance With Multiple Networks⁠​

Instance With Personality⁠​

Instance with Multiple Ephemeral Disks⁠​

Instance with Boot Disk and Swap Disk⁠​

Instance with User Data (cloud-init)⁠​

Argument Reference⁠​

Attributes Reference⁠​

Notes⁠​

Multiple Ephemeral Disks⁠​

Instances and Ports⁠​

Instances and Networks⁠​

Importing instances⁠​

Importing basic instance⁠​

Importing an instance with multiple emphemeral disks⁠​

Importing instance with multiple network interfaces.⁠​

Importing instances with multiple block storage volumes.⁠​

Importing an instance belonging to a server group⁠​

Example Usage⁠

Basic Instance⁠

Instance With Attached Volume⁠

Boot From Volume⁠

Boot From an Existing Volume⁠

Boot Instance, Create Volume, and Attach Volume as a Block Device⁠

Boot Instance and Attach Existing Volume as a Block Device⁠

Instance With Multiple Networks⁠

Instance With Personality⁠

Instance with Multiple Ephemeral Disks⁠

Instance with Boot Disk and Swap Disk⁠

Instance with User Data (cloud-init)⁠

Argument Reference⁠

Attributes Reference⁠

Notes⁠

Multiple Ephemeral Disks⁠

Instances and Ports⁠

Instances and Networks⁠

Importing instances⁠

Importing basic instance⁠

Importing an instance with multiple emphemeral disks⁠

Importing instance with multiple network interfaces.⁠

Importing instances with multiple block storage volumes.⁠

Importing an instance belonging to a server group⁠