Chapter 8. Virtual Machine Instances
OpenStack Compute is the central component that provides virtual machines on demand. Compute interacts with the Identity service for authentication, Image service for images (used to launch instances), and the dashboard service for the user and administrative interface.
Red Hat OpenStack Platform allows you to easily manage virtual machine instances in the cloud. The Compute service creates, schedules, and manages instances, and exposes this functionality to other OpenStack components. This chapter discusses these procedures along with procedures to add components like key pairs, security groups, host aggregates and flavors. The term instance is used by OpenStack to mean a virtual machine instance.
8.1. Manage Instances
Before you can create an instance, you need to ensure certain other OpenStack components (for example, a network, key pair and an image or a volume as the boot source) are available for the instance.
This section discusses the procedures to add these components, create and manage an instance. Managing an instance refers to updating, and logging in to an instance, viewing how the instances are being used, resizing or deleting them.
8.1.1. Add Components
Use the following sections to create a network, key pair and upload an image or volume source. These components are used in the creation of an instance and are not available by default. You will also need to create a new security group to allow SSH access to the user.
- In the dashboard, select Project.
- Select Network > Networks, and ensure there is a private network to which you can attach the new instance (to create a network, see Create a Network section in the Networking Guide).
- Select Compute > Access & Security > Key Pairs, and ensure there is a key pair (to create a key pair, see Section 8.2.1.1, “Create a Key Pair”).
Ensure that you have either an image or a volume that can be used as a boot source:
- To view boot-source images, select the Images tab (to create an image, see Section 1.2.1, “Creating an image”).
- To view boot-source volumes, select the Volumes tab (to create a volume, see Create a Volume in the Storage Guide).
- Select Compute > Access & Security > Security Groups, and ensure you have created a security group rule (to create a security group, see Project Security Management in the Users and Identity Management Guide).
8.1.2. Launch an Instance
Launch one or more instances from the dashboard.
By default, the Launch Instance form is used to launch instances. However, you can also enable a Launch Instance wizard that simplifies the steps required. For more information, see Appendix B, Enabling the Launch Instance Wizard.
- In the dashboard, select Project > Compute > Instances.
- Click Launch Instance.
- Fill out the fields (those marked with '* ' are required), and click Launch.
One or more instances are created, and launched based on the options provided.
8.1.2.1. Launch Instance Options
The following table outlines the options available when launching a new instance using the Launch Instance form. The same options are also available in the Launch instance wizard.
Table 8.1. Launch Instance Form Options
Tab | Field | Notes |
---|---|---|
Project and User | Project | Select the project from the dropdown list. |
User | Select the user from the dropdown list. | |
Details | Availability Zone | Zones are logical groupings of cloud resources in which your instance can be placed. If you are unsure, use the default zone. |
Instance Name | A name to identify your instance. | |
Flavor | The flavor determines what resources the instance is given (for example, memory). For default flavor allocations and information on creating new flavors, see Section 8.3, “Manage Flavors”. | |
Instance Count | The number of instances to create with these parameters. "1" is preselected. | |
Instance Boot Source | Depending on the item selected, new fields are displayed allowing you to select the source:
| |
Access and Security | Key Pair | The specified key pair is injected into the instance and is used to remotely access the instance using SSH (if neither a direct login information or a static key pair is provided). Usually one key pair per project is created. |
Security Groups | Security groups contain firewall rules which filter the type and direction of the instance’s network traffic (for more information on configuring groups, see Project Security Management in the Users and Identity Management Guide). | |
Networking | Selected Networks | You must select at least one network. Instances are typically assigned to a private network, and then later given a floating IP address to enable external access. |
Post-Creation | Customization Script Source | You can provide either a set of commands or a script file, which will run after the instance is booted (for example, to set the instance host name or a user password). If Direct Input is selected, write your commands in the Script Data field; otherwise, specify your script file. Note Any script that starts with #cloud-config is interpreted as using the cloud-config syntax (for information on the syntax, see http://cloudinit.readthedocs.org/en/latest/topics/examples.html). |
Advanced Options | Disk Partition | By default, the instance is built as a single partition and dynamically resized as needed. However, you can choose to manually configure the partitions yourself. |
Configuration Drive | If selected, OpenStack writes metadata to a read-only configuration drive that is attached to the instance when it boots (instead of to Compute’s metadata service). After the instance has booted, you can mount this drive to view its contents (enables you to provide files to the instance). |
8.1.4. Resize an Instance
To resize an instance (memory or CPU count), you must select a new flavor for the instance that has the right capacity. If you are increasing the size, remember to first ensure that the host has enough space.
- Ensure communication between hosts by setting up each host with SSH key authentication so that Compute can use SSH to move disks to other hosts (for example, compute nodes can share the same SSH key).
Enable resizing on the original host by setting the
allow_resize_to_same_host
parameter to "True" in your Compute environment file.NoteThe
allow_resize_to_same_host
parameter does not resize the instance on the same host. Even if the parameter equals "True" on all Compute nodes, the scheduler does not force the instance to resize on the same host. This is the expected behavior.- In the dashboard, select Project > Compute > Instances.
- Click the instance’s Actions arrow, and select Resize Instance.
- Select a new flavor in the New Flavor field.
If you want to manually partition the instance when it launches (results in a faster build time):
- Select Advanced Options.
- In the Disk Partition field, select Manual.
- Click Resize.
8.1.5. Connecting to an instance
You can access an instance console by using the dashboard or the command-line interface. You can also directly connect to the serial port of an instance, which allows you to debug even if the network connection fails.
8.1.5.1. Accessing an instance console by using the dashboard
You can connect to the instance console from the dashboard.
Procedure
- In the dashboard, select Compute > Instances.
-
Click the instance’s More button and select Console.
- Log in using the image’s user name and password (for example, a CirrOS image uses cirros/cubswin:)).
8.1.5.2. Accessing an instance console by using the CLI
You can connect directly to the VNC console for an instance by entering the VNC console URL in a browser.
Procedure
To display the VNC console URL for an instance, enter the following command:
$ openstack console url show <vm_name> +-------+------------------------------------------------------+ | Field | Value | +-------+------------------------------------------------------+ | type | novnc | | url | http://172.25.250.50:6080/vnc_auto.html?token= | | | 962dfd71-f047-43d3-89a5-13cb88261eb9 | +-------+-------------------------------------------------------+
- To connect directly to the VNC console, enter the displayed URL in a browser.
8.1.6. View Instance Usage
The following usage statistics are available:
Per Project
To view instance usage per project, select Project > Compute > Overview. A usage summary is immediately displayed for all project instances.
You can also view statistics for a specific period of time by specifying the date range and clicking Submit.
Per Hypervisor
If logged in as an administrator, you can also view information for all projects. Click Admin > System and select one of the tabs. For example, the Resource Usage tab offers a way to view reports for a distinct time period. You might also click Hypervisors to view your current vCPU, memory, or disk statistics.
NoteThe
vCPU Usage
value (x of y
) reflects the number of total vCPUs of all virtual machines (x) and the total number of hypervisor cores (y).
8.1.7. Delete an Instance
- In the dashboard, select Project > Compute > Instances, and select your instance.
- Click Terminate Instance.
Deleting an instance does not delete its attached volumes; you must do this separately (see Delete a Volume in the Storage Guide).
8.1.8. Manage Multiple Instances at Once
If you need to start multiple instances at the same time (for example, those that were down for compute or controller maintenance) you can do so easily at Project > Compute > Instances:
- Click the check boxes in the first column for the instances that you want to start. If you want to select all of the instances, click the check box in the first row in the table.
- Click More Actions above the table and select Start Instances.
Similarly, you can shut off or soft reboot multiple instances by selecting the respective actions.
8.2. Manage Instance Security
You can manage access to an instance by assigning it the correct security group (set of firewall rules) and key pair (enables SSH user access). Further, you can assign a floating IP address to an instance to enable external network access. The sections below outline how to create and manage key pairs, security groups, floating IP addresses and logging in to an instance using SSH. There is also a procedure for injecting an admin
password in to an instance.
For information on managing security groups, see Project Security Management in the Users and Identity Management Guide.
8.2.1. Manage Key Pairs
Key pairs provide SSH access to the instances. Each time a key pair is generated, its certificate is downloaded to the local machine and can be distributed to users. Typically, one key pair is created for each project (and used for multiple instances).
You can also import an existing key pair into OpenStack.
8.2.1.1. Create a Key Pair
- In the dashboard, select Project > Compute > Access & Security.
- On the Key Pairs tab, click Create Key Pair.
- Specify a name in the Key Pair Name field, and click Create Key Pair.
When the key pair is created, a key pair file is automatically downloaded through the browser. Save this file for later connections from external machines. For command-line SSH connections, you can load this file into SSH by executing:
# ssh-add ~/.ssh/os-key.pem
8.2.1.2. Import a Key Pair
- In the dashboard, select Project > Compute > Access & Security.
- On the Key Pairs tab, click Import Key Pair.
- Specify a name in the Key Pair Name field, and copy and paste the contents of your public key into the Public Key field.
- Click Import Key Pair.
8.2.1.3. Delete a Key Pair
- In the dashboard, select Project > Compute > Access & Security.
- On the Key Pairs tab, click the key’s Delete Key Pair button.
8.2.2. Create a Security Group
Security groups are sets of IP filter rules that can be assigned to project instances, and which define networking access to the instance. Security group are project specific; project members can edit the default rules for their security group and add new rule sets.
- In the dashboard, select the Project tab, and click Compute > Access & Security.
- On the Security Groups tab, click + Create Security Group.
- Provide a name and description for the group, and click Create Security Group.
For more information on managing project security, see Project Security Management in the Users and Identity Management Guide.
8.2.3. Create, Assign, and Release Floating IP Addresses
By default, an instance is given an internal IP address when it is first created. However, you can enable access through the public network by creating and assigning a floating IP address (external address). You can change an instance’s associated IP address regardless of the instance’s state.
Projects have a limited range of floating IP address that can be used (by default, the limit is 50), so you should release these addresses for reuse when they are no longer needed. Floating IP addresses can only be allocated from an existing floating IP pool, see Create Floating IP Pools in the Networking Guide.
8.2.3.1. Allocate a Floating IP to the Project
- In the dashboard, select Project > Compute > Access & Security.
- On the Floating IPs tab, click Allocate IP to Project.
- Select a network from which to allocate the IP address in the Pool field.
- Click Allocate IP.
8.2.3.2. Assign a Floating IP
- In the dashboard, select Project > Compute > Access & Security.
- On the Floating IPs tab, click the address' Associate button.
Select the address to be assigned in the IP address field.
NoteIf no addresses are available, you can click the
+
button to create a new address.- Select the instance to be associated in the Port to be Associated field. An instance can only be associated with one floating IP address.
- Click Associate.
8.2.3.3. Release a Floating IP
- In the dashboard, select Project > Compute > Access & Security.
- On the Floating IPs tab, click the address' menu arrow (next to the Associate/Disassociate button).
- Select Release Floating IP.
8.2.4. Log in to an Instance
Prerequisites:
- Ensure that the instance’s security group has an SSH rule (see Project Security Management in the Users and Identity Management Guide).
- Ensure the instance has a floating IP address (external address) assigned to it (see Section 8.2.3, “Create, Assign, and Release Floating IP Addresses”).
- Obtain the instance’s key-pair certificate. The certificate is downloaded when the key pair is created; if you did not create the key pair yourself, ask your administrator (see Section 8.2.1, “Manage Key Pairs”).
To first load the key pair file into SSH, and then use ssh without naming it:
Change the permissions of the generated key-pair certificate.
$ chmod 600 os-key.pem
Check whether
ssh-agent
is already running:# ps -ef | grep ssh-agent
If not already running, start it up with:
# eval `ssh-agent`
On your local machine, load the key-pair certificate into SSH. For example:
$ ssh-add ~/.ssh/os-key.pem
- You can now SSH into the file with the user supplied by the image.
The following example command shows how to SSH into the Red Hat Enterprise Linux guest image with the user cloud-user
:
$ ssh cloud-user@192.0.2.24
You can also use the certificate directly. For example:
$ ssh -i /myDir/os-key.pem cloud-user@192.0.2.24
8.2.5. Inject an admin
Password Into an Instance
You can inject an admin
(root
) password into an instance using the following procedure.
In the
/etc/openstack-dashboard/local_settings
file, set thechange_set_password
parameter value toTrue
.can_set_password: True
Set the
inject_password
parameter to "True" in your Compute environment file.inject_password=true
Restart the Compute service.
# service nova-compute restart
When you use the nova boot
command to launch a new instance, the output of the command displays an adminPass
parameter. You can use this password to log into the instance as the root
user.
The Compute service overwrites the password value in the /etc/shadow
file for the root
user. This procedure can also be used to activate the root
account for the KVM guest images. For more information on how to use KVM guest images, see Section 1.2.1.1, “Use a KVM guest image with Red Hat OpenStack Platform”
You can also set a custom password from the dashboard. To enable this, run the following command after you have set can_set_password
parameter to true
.
# systemctl restart httpd.service
The newly added admin
password fields are as follows:
These fields can be used when you launch or rebuild an instance.
8.3. Manage Flavors
Each created instance is given a flavor (resource template), which determines the instance’s size and capacity. Flavors can also specify secondary ephemeral storage, swap disk, metadata to restrict usage, or special project access (none of the default flavors have these additional attributes defined).
Table 8.3. Default Flavors
Name | vCPUs | RAM | Root Disk Size |
---|---|---|---|
m1.tiny | 1 | 512 MB | 1 GB |
m1.small | 1 | 2048 MB | 20 GB |
m1.medium | 2 | 4096 MB | 40 GB |
m1.large | 4 | 8192 MB | 80 GB |
m1.xlarge | 8 | 16384 MB | 160 GB |
The majority of end users will be able to use the default flavors. However, you can create and manage specialized flavors. For example, you can:
- Change default memory and capacity to suit the underlying hardware needs.
- Add metadata to force a specific I/O rate for the instance or to match a host aggregate.
Behavior set using image properties overrides behavior set using flavors (for more information, see Section 1.2, “Manage images”).
8.3.1. Update Configuration Permissions
By default, only administrators can create flavors or view the complete flavor list (select Admin > System > Flavors). To allow all users to configure flavors, specify the following in the /etc/nova/policy.json
file (nova-api server):
"compute_extension:flavormanage": "",
8.3.2. Create a Flavor
- As an admin user in the dashboard, select Admin > System > Flavors.
Click Create Flavor, and specify the following fields:
Table 8.4. Flavor Options
Tab Field Description Flavor Information
Name
Unique name.
ID
Unique ID. The default value,
auto
, generates a UUID4 value, but you can also manually specify an integer or UUID4 value.VCPUs
Number of virtual CPUs.
RAM (MB)
Memory (in megabytes).
Root Disk (GB)
Ephemeral disk size (in gigabytes); to use the native image size, specify
0
. This disk is not used if Instance Boot Source=Boot from Volume.Epehemeral Disk (GB)
Secondary ephemeral disk size (in gigabytes) available to an instance. This disk is destroyed when an instance is deleted.
The default value is
0
, which implies that no ephemeral disk is created.Swap Disk (MB)
Swap disk size (in megabytes).
Flavor Access
Selected Projects
Projects which can use the flavor. If no projects are selected, all projects have access (
Public=Yes
).- Click Create Flavor.
8.3.3. Update General Attributes
- As an admin user in the dashboard, select Admin > System > Flavors.
- Click the flavor’s Edit Flavor button.
- Update the values, and click Save.
8.3.4. Update Flavor Metadata
In addition to editing general attributes, you can add metadata to a flavor (extra_specs
), which can help fine-tune instance usage. For example, you might want to set the maximum-allowed bandwidth or disk writes.
- Pre-defined keys determine hardware support or quotas. Pre-defined keys are limited by the hypervisor you are using (for libvirt, see Table 8.5, “Libvirt Metadata”).
-
Both pre-defined and user-defined keys can determine instance scheduling. For example, you might specify
SpecialComp=True
; any instance with this flavor can then only run in a host aggregate with the same key-value combination in its metadata.
8.3.4.1. View Metadata
- As an admin user in the dashboard, select Admin > System > Flavors.
-
Click the flavor’s Metadata link (
Yes
orNo
). All current values are listed on the right-hand side under Existing Metadata.
8.3.4.2. Add Metadata
You specify a flavor’s metadata using a key/value
pair.
- As an admin user in the dashboard, select Admin > System > Flavors.
-
Click the flavor’s Metadata link (
Yes
orNo
). All current values are listed on the right-hand side under Existing Metadata. - Under Available Metadata, click on the Other field, and specify the key you want to add (see Table 8.5, “Libvirt Metadata”).
- Click the + button; you can now view the new key under Existing Metadata.
Fill in the key’s value in its right-hand field.
- When finished with adding key-value pairs, click Save.
Table 8.5. Libvirt Metadata
Key | Description |
---|---|
| Action that configures support limits per instance. Valid actions are:
Example: |
| Definition of NUMA topology for the instance. For flavors whose RAM and vCPU allocations are larger than the size of NUMA nodes in the compute hosts, defining NUMA topology enables hosts to better utilize NUMA and improve performance of the guest OS. NUMA definitions defined through the flavor override image definitions. Valid definitions are:
Note
If the values of Example when the instance has 8 vCPUs and 4GB RAM:
The scheduler looks for a host with 2 NUMA nodes with the ability to run 6 CPUs + 3072 MB, or 3 GB, of RAM on one node, and 2 CPUS + 1024 MB, or 1 GB, of RAM on another node. If a host has a single NUMA node with capability to run 8 CPUs and 4 GB of RAM, it will not be considered a valid match. |
| An instance watchdog device can be used to trigger an action if the instance somehow fails (or hangs). Valid actions are:
Example: |
| You can use this parameter to specify the NUMA affinity policy for PCI passthrough devices and SR-IOV interfaces. Set to one of the following valid values:
Example: |
|
A random-number generator device can be added to an instance using its image properties (see If the device has been added, valid actions are:
Example: |
| Maximum permitted RAM to be allowed for video devices (in MB).
Example: |
| Enforcing limit for the instance. Valid options are:
Example: In addition, the VMware driver supports the following quota options, which control upper and lower limits for CPUs, RAM, disks, and networks, as well as shares, which can be used to control relative allocation of available resources among projects:
|
8.4. Manage Instance Snapshots
An instance snapshot allows you to create a new image from an instance. This is very convenient for upgrading base images or for taking a published image and customizing it for local use.
The difference between an image that you upload directly to the Image Service and an image that you create by snapshot is that an image created by snapshot has additional properties in the Image Service database. These properties are found in the image_properties
table and include the following parameters:
Table 8.6. Snapshot Options
Name | Value |
---|---|
image_type | snapshot |
instance_uuid | <uuid of instance that was snapshotted> |
base_image_ref | <uuid of original image of instance that was snapshotted> |
image_location | snapshot |
Snapshots allow you to create new instances based on that snapshot, and potentially restore an instance to that state. Moreover, this can be performed while the instance is running.
By default, a snapshot is accessible to the users and projects that were selected while launching an instance that the snapshot is based on.
8.4.1. Create an Instance Snapshot
If you intend to use an instance snapshot as a template to create new instances, you must ensure that the disk state is consistent. Before you create a snapshot, set the snapshot image metadata property os_require_quiesce=yes
. For example,
$ glance image-update IMAGE_ID --property os_require_quiesce=yes
For this to work, the guest should have the qemu-guest-agent
package installed, and the image should be created with the metadata property parameter hw_qemu_guest_agent=yes
set. For example,
$ glance image-create --name NAME \ --disk-format raw \ --container-format bare \ --file FILE_NAME \ --is-public True \ --property hw_qemu_guest_agent=yes \ --progress
If you unconditionally enable the hw_qemu_guest_agent=yes
parameter, then you are adding another device to the guest. This consumes a PCI slot, and will limit the number of other devices you can allocate to the guest. It also causes Windows guests to display a warning message about an unknown hardware device.
For these reasons, setting the hw_qemu_guest_agent=yes
parameter is optional, and the parameter should be used for only those images that require the QEMU guest agent.
- In the dashboard, select Project > Compute > Instances.
- Select the instance from which you want to create a snapshot.
- In the Actions column, click Create Snapshot.
In the Create Snapshot dialog, enter a name for the snapshot and click Create Snapshot.
The Images category now shows the instance snapshot.
To launch an instance from a snapshot, select the snapshot and click Launch.
8.4.2. Manage a Snapshot
- In the dashboard, select Project > Images.
- All snapshots you created, appear under the Project option.
For every snapshot you create, you can perform the following functions, using the dropdown list:
- Use the Create Volume option to create a volume and entering the values for volume name, description, image source, volume type, size and availability zone. For more information, see Create a Volume in the Storage Guide.
- Use the Edit Image option to update the snapshot image by updating the values for name, description, Kernel ID, Ramdisk ID, Architecture, Format, Minimum Disk (GB), Minimum RAM (MB), public or private. For more information, see Section 1.2.3, “Update an image”.
- Use the Delete Image option to delete the snapshot.
8.4.3. Rebuild an Instance to a State in a Snapshot
In an event that you delete an instance on which a snapshot is based, the snapshot still stores the instance ID. You can check this information using the nova image-list command and use the snapshot to restore the instance.
- In the dashboard, select Project > Compute > Images.
- Select the snapshot from which you want to restore the instance.
- In the Actions column, click Launch Instance.
- In the Launch Instance dialog, enter a name and the other details for the instance and click Launch.
For more information on launching an instance, see Section 8.1.2, “Launch an Instance”.
8.4.4. Consistent Snapshots
Previously, file systems had to be quiesced manually (fsfreeze) before taking a snapshot of active instances for consistent backups.
Compute’s libvirt
driver automatically requests the QEMU Guest Agent to freeze the file systems (and applications if fsfreeze-hook
is installed) during an image snapshot. Support for quiescing file systems enables scheduled, automatic snapshots at the block device level.
This feature is only valid if the QEMU Guest Agent is installed (qemu-ga
) and the image metadata enables the agent (hw_qemu_guest_agent=yes
)
Snapshots should not be considered a substitute for an actual system backup.
8.5. Use Rescue Mode for Instances
Compute has a method to reboot a virtual machine in rescue mode. Rescue mode provides a mechanism for access when the virtual machine image renders the instance inaccessible. A rescue virtual machine allows a user to fix their virtual machine by accessing the instance with a new root password. This feature is useful if an instance’s filesystem is corrupted. By default, rescue mode starts an instance from the initial image attaching the current boot disk as a secondary one.
8.5.1. Preparing an Image for a Rescue Mode Instance
Due to the fact that both the boot disk and the disk for rescue mode have same UUID, sometimes the virtual machine can be booted from the boot disk instead of the disk for rescue mode.
To avoid this issue, you should create a new image as rescue image based on the procedure in Section 1.2.1, “Creating an image”:
The rescue
image is stored in glance
and configured in the nova.conf
as a default, or you can select when you do the rescue.
8.5.1.1. Rescue Image if Using ext4 Filesystem
When the base image uses ext4
filesystem, you can create a rescue image from it using the following procedure:
Change the UUID to a random value using the
tune2fs
command:# tune2fs -U random /dev/DEVICE_NODE
Here DEVICE_NODE is the root device node (for example,
sda
,vda
, and so on).Verify the details of the filesystem, including the new UUID:
# tune2fs -l
-
Update the
/etc/fstab
to use the new UUID. You may need to repeat this for any additional partitions you have, that are mounted in thefstab
by UUID. -
Update the
/boot/grub2/grub.conf
file and update the UUID parameter with the new UUID of the root disk. - Shut down and use this image as your rescue image. This will cause the rescue image to have a new random UUID that will not conflict with the instance that you are rescuing.
The XFS filesystem cannot change the UUID of the root device on the running virtual machine. Reboot the virtual machine until the virtual machine is launched from the disk for rescue mode.
8.5.2. Adding the Rescue Image to the OpenStack Image Service
When you have completed modifying the UUID of your image, use the following commands to add the generated rescue image to the OpenStack Image service:
Add the rescue image to the Image service:
# glance image-create --name IMAGE_NAME --disk-format qcow2 \ --container-format bare --is-public True --file IMAGE_PATH
Here IMAGE_NAME is the name of the image, IMAGE_PATH is the location of the image.
Use the
image-list
command to obtain the IMAGE_ID required for launching an instace in the rescue mode.# glance image-list
You can also upload an image using the OpenStack Dashboard, see Section 1.2.2, “Upload an image”.
8.5.3. Launching an Instance in Rescue Mode
Since you need to rescue an instance with a specific image, rather than the default one, use the
--image
parameter:# nova rescue --image IMAGE_ID VIRTUAL_MACHINE_ID
Here IMAGE_ID is the ID of the image you want to use and VIRTUAL_MACHINE_ID is ID of a virtual machine that you want to rescue.
NoteThe
nova rescue
command allows an instance to perform a soft shut down. This allows the guest operating system to perform a controlled shutdown before the instance is powered off. The shut down behavior is configured usingshutdown_timeout
in your Compute configuration file. The value stands for the overall period (in seconds) a guest operation system is allowed to complete the shutdown. The default timeout is 60 seconds.The timeout value can be overridden on a per image basis by means of
os_shutdown_timeout
that is an image metadata setting allowing different types of operating systems to specify how much time they need to shut down cleanly.- Reboot the virtual machine.
-
Confirm the status of the virtual machine is RESCUE on the controller node by using
nova list
command or by using dashboard. - Log in to the new virtual machine dashboard by using the password for rescue mode.
You can now make the necessary changes to your instance to fix any issues.
8.5.4. Unrescuing an Instance
You can unrescue
the fixed instance to restart it from the boot disk.
Execute the following commands on the controller node.
# nova unrescue VIRTUAL_MACHINE_ID
Here VIRTUAL_MACHINE_ID is ID of a virtual machine that you want to unrescue.
The status of your instance returns to ACTIVE once the unrescue operation has completed successfully. :leveloffset: +3
8.6. Creating a customized instance
Cloud users can specify additional data to use when they launch an instance, such as a shell script that the instance runs on boot. The cloud user can use the following methods to pass data to instances:
- User data
-
Use to include instructions in the instance launch command for
cloud-init
to execute. - Instance metadata
- A list of key-value pairs that you can specify when you create or update an instance.
You can access the additional data passed to the instance by using a config drive or the metadata service.
- Config drive
-
You can attach a config drive to an instance when it boots. The config drive is presented to the instance as a read-only drive. The instance can mount this drive and read files from it. You can use the config drive as a source for
cloud-init
information. Config drives are useful when combined withcloud-init
for server bootstrapping, and when you want to pass large files to your instances. For example, you can configurecloud-init
to automatically mount the config drive and run the setup scripts during the initial instance boot. Config drives are created with the volume label ofconfig-2
, and attached to the instance when it boots. The contents of any additional files passed to the config drive are added to theuser_data
file in theopenstack/{version}/
directory of the config drive.cloud-init
retrieves the user data from this file. - Metadata service
-
Provides a REST API to retrieve data specific to an instance. Instances access this service at
169.254.169.254
or atfe80::a9fe:a9fe
.
cloud-init
can use both a config drive and the metadata service to consume the additional data for customizing an instance. The cloud-init
package supports several data input formats. Shell scripts and the cloud-config
format are the most common input formats:
-
Shell scripts: The data declaration begins with
#!
orContent-Type: text/x-shellscript
. Shell scripts are invoked last in the boot process. -
cloud-config
format: The data declaration begins with#cloud-config
orContent-Type: text/cloud-config
.cloud-config
files must be valid YAML to be parsed and executed bycloud-init
.
cloud-init
has a maximum user data size of 16384 bytes for data passed to an instance. You cannot change the size limit, therefore use gzip compression when you need to exceed the size limit.
Vendor-specific data
The RHOSP administrator can also pass data to instances when they are being created. This data may not be visible to you as the cloud user, for example, a cryptographic token that registers the instance with Active Directory.
The RHOSP administrator uses the vendordata feature to pass data to instances. Vendordata configuration is read only, and is located in one of the following files:
-
/openstack/{version}/vendor_data.json
-
/openstack/{version}/vendor_data2.json
You can view these files using the metadata service or from the config drive on your instance. To access the files by using the metadata service, make a GET request to either http://169.254.169.254/openstack/{version}/vendor_data.json
or http://169.254.169.254/openstack/{version}/vendor_data2.json
.
8.6.1. Customizing an instance by using user data
You can use user data to include instructions in the instance launch command. cloud-init
executes these commands to customize the instance as the last step in the boot process.
Procedure
Create a file with instructions for
cloud-init
. For example, create a bash script that installs and enables a web server on the instance:$ vim /home/scripts/install_httpd #!/bin/bash yum -y install httpd python-psycopg2 systemctl enable httpd --now
Launch an instance with the
--user-data
option to pass the bash script:$ openstack server create \ --image rhel8 \ --flavor default \ --nic net-id=web-server-network \ --security-group default \ --key-name web-server-keypair \ --user-data /home/scripts/install_httpd \ --wait web-server-instance
When the instance state is active, attach a floating IP address:
$ openstack floating ip create web-server-network $ openstack server add floating ip web-server-instance 172.25.250.123
Log in to the instance with SSH:
$ ssh -i ~/.ssh/web-server-keypair cloud-user@172.25.250.123
Check that the customization was successfully performed. For example, to check that the web server has been installed and enabled, enter the following command:
$ curl http://localhost | grep Test <title>Test Page for the Apache HTTP Server on Red Hat Enterprise Linux</title> <h1>Red Hat Enterprise Linux <strong>Test Page</strong></h1>
Review the
/var/log/cloud-init.log
file for relevant messages, such as whether or not thecloud-init
executed:$ sudo less /var/log/cloud-init.log ...output omitted... ...util.py[DEBUG]: Cloud-init v. 0.7.9 finished at Sat, 23 Jun 2018 02:26:02 +0000. Datasource DataSourceOpenStack [net,ver=2]. Up 21.25 seconds
8.6.2. Customizing an instance by using metadata
You can use instance metadata to specify the properties of an instance in the instance launch command.
Procedure
Launch an instance with the
--property <key=value>
option. For example, to mark the instance as a webserver, set the following property:$ openstack server create \ --image rhel8 \ --flavor default \ --property role=webservers \ --wait web-server-instance
Optional: Add an additional property to the instance after it is created, for example:
$ openstack server set \ --property region=emea \ --wait web-server-instance
8.6.3. Customizing an instance by using a config drive
You can create a config drive for an instance that is attached during the instance boot process. You can pass content to the config drive that the config drive makes available to the instance.
Procedure
Enable the config drive, and specify a file that contains content that you want to make available in the config drive. For example, the following command creates a new instance named
config-drive-instance
and attaches a config drive that contains the contents of the filemy-user-data.txt
:(overcloud)$ openstack server create --flavor m1.tiny \ --config-drive true \ --user-data ./my-user-data.txt \ --image cirros config-drive-instance
This command creates the config drive with the volume label of
config-2
, which is attached to the instance when it boots, and adds the contents ofmy-user-data.txt
to theuser_data
file in theopenstack/{version}/
directory of the config drive.- Log in to the instance.
Mount the config drive:
If the instance OS uses
udev
:# mkdir -p /mnt/config # mount /dev/disk/by-label/config-2 /mnt/config
If the instance OS does not use
udev
, you need to first identify the block device that corresponds to the config drive:# blkid -t LABEL="config-2" -odevice /dev/vdb # mkdir -p /mnt/config # mount /dev/vdb /mnt/config