From 9e10a4797322c01dabaf0693bc2c54ad014bf766 Mon Sep 17 00:00:00 2001 From: Karin Levenstein Date: Thu, 24 Apr 2014 10:09:42 -0400 Subject: [PATCH] UG Edits: Migrate Instances, Conf Drive - Edits to the Migrate Instances and Conf Drive sections of the CLI chapter - Patch split from https://review.openstack.org/#/c/89581/ Change-Id: I7fef7f8e03aa1aa7362326169c961eb977d8d5c0 --- .../section_cli_nova_config-drive.xml | 175 ++++++++---------- .../section_cli_nova_migrate_instances.xml | 135 ++++++-------- 2 files changed, 138 insertions(+), 172 deletions(-) diff --git a/doc/user-guide/section_cli_nova_config-drive.xml b/doc/user-guide/section_cli_nova_config-drive.xml index 28292e7389..a7ccd3ca01 100644 --- a/doc/user-guide/section_cli_nova_config-drive.xml +++ b/doc/user-guide/section_cli_nova_config-drive.xml @@ -9,36 +9,35 @@ xml:id="config-drive"> Store metadata on a configuration drive You can configure OpenStack to write metadata to a special - configuration drive that attaches to the instance when it - boots. The instance can mount this drive and read files from - it to get information that is normally available through the - metadata service. - One use case for the configuration drive is to pass a - networking configuration when you do not use DHCP to assign IP - addresses to instances. For example, you might pass the IP - configuration for the instance through the configuration - drive, which the instance can mount and access before you - configure the network settings for the instance. - Any modern guest operating system that is capable of - mounting an ISO9660 or VFAT file system can use the - configuration drive. + >metadata service. This metadata is different from the user + data. + One use case for using the configuration drive is to pass a networking + configuration when you do not use DHCP to assign IP addresses to + instances. For example, you might pass the IP address configuration for + the instance through the configuration drive, which the instance can + mount and access before you configure the network settings for the + instance. + Any modern guest operating system that is capable of mounting an ISO + 9660 or VFAT file system can use the configuration drive.
Requirements and guidelines + To use the configuration drive, you must follow the following + requirements for the compute host and image. Compute host requirements - The following hypervisors support the - configuration drive: libvirt, xenserver, hyper-v, - and vmware. + The following hypervisors support the configuration drive: + libvirt, XenServer, Hyper-V, and VMWare. - To use configuration drive with libvirt, - xenserver, or vmware, you must first install the - genisoimage package on each - compute host. Otherwise, instances do not boot - properly. + To use configuration drive with libvirt, XenServer, or + VMWare, you must first install the + genisoimage package on each compute + host. Otherwise, instances do not boot properly. Use the mkisofs_cmd flag to set the path where you install the @@ -49,15 +48,13 @@ need to set this flag. - To use configuration drive with hyper-v, you - must set the mkisofs_cmd value - to the full path to an - mkisofs.exe installation. + To use configuration drive with Hyper-V, you must set the + mkisofs_cmd value to the full path to + an mkisofs.exe installation. Additionally, you must set the qemu_img_cmd value in the - hyperv configuration - section to the full path to an - qemu-img command + hyperv configuration section to the + full path to an qemu-img command installation. @@ -67,21 +64,18 @@ An image built with a recent version of the cloud-init package can automatically access metadata passed through the - configuration drive. The - cloud-init package version - 0.7.1 works with Ubuntu and Fedora-based images, - such as RHEL. + configuration drive. The cloud-init + package version 0.7.1 works with Ubuntu and Fedora based + images, such as Red Hat Enterprise Linux. If an image does not have the - cloud-init package - installed, you must customize the image to run a - script that mounts the configuration drive on - boot, reads the data from the drive, and takes - appropriate action such as adding the public key - to an account. See for details - on how data is organized on the configuration + cloud-init package installed, you + must customize the image to run a script that mounts the + configuration drive on boot, reads the data from the drive, + and takes appropriate action such as adding the public key + to an account. See + for details about how data is organized on the configuration drive. @@ -94,21 +88,19 @@ Guidelines - Do not rely on the presence of the EC2 metadata - present in the configuration drive, as this - content might be removed in a future release. For - example, do not rely on files in the - ec2 directory. + Do not rely on the presence of the EC2 metadata in the + configuration drive, because this content might be removed + in a future release. For example, do not rely on files in + the ec2 directory. - When you create images that access configuration - drive data and multiple directories are under the - openstack directory, - always select the highest API version by date that - your consumer supports. For example, if your guest - image supports the 2012-03-05, 2012-08-05, - 2013-04-13 versions, try 2013-04-13 first and fall - back to a previous version if 2013-04-13 is not + When you create images that access configuration drive + data and multiple directories are under the + openstack directory, always select + the highest API version by date that your consumer supports. + For example, if your guest image supports the 2012-03-05, + 2012-08-05, and 2013-04-13 versions, try 2013-04-13 first + and fall back to a previous version if 2013-04-13 is not present. @@ -121,39 +113,34 @@ --config-drive=true parameter to the nova boot command. - This example enables the configuration drive and - passes user data, two files, and two key/value - metadata pairs, all of which are accessible from - the configuration drive: + The following example enables the configuration drive and + passes user data, two files, and two key/value metadata + pairs, all of which are accessible from the configuration + drive: $ nova boot --config-drive=true --image my-image-name --key-name mykey --flavor 1 --user-data ./my-user-data.txt myinstance --file /etc/network/interfaces=/home/myuser/instance-interfaces --file known_hosts=/home/myuser/.ssh/known_hosts --meta role=webservers --meta essential=false - You can also configure the Compute service to - always create a configuration drive. - Set this option in the - /etc/nova/nova.conf - file: + You can also configure the Compute service to always + create a configuration drive by setting the following option + in the /etc/nova/nova.conf file: force_config_drive=true If a user passes the - --config-drive=true - flag to the nova boot - command, an administrator cannot disable the - configuration drive. + --config-drive=true flag to the + nova boot command, an + administrator cannot disable the configuration + drive. - The configuration drive has the - config-2 volume label. If - your guest operating system supports accessing - disk by label, you can mount the configuration - drive as the - /dev/disk/by-label/config-2 - device. - For example: + If your guest operating system supports accessing disk by + label, you can mount the configuration drive as the + /dev/disk/by-label/configurationDriveVolumeLabel + device. In the following example, the configuration drive + has the config-2 volume label. # mkdir -p /mnt/config # mount /dev/disk/by-label/config-2 /mnt/config - Make sure that you use at least version 0.3.1 - of CirrOS for configuration drive support. + Ensure that you use at least version 0.3.1 of CirrOS + for configuration drive support. If your guest operating system does not use udev, the @@ -175,8 +162,8 @@ Configuration drive contents - In this example, the contents of the configuration - drive are: + In this example, the contents of the configuration drive are + as follows: ec2/2009-04-04/meta-data.json ec2/2009-04-04/user-data ec2/latest/meta-data.json @@ -195,11 +182,10 @@ openstack/latest/user_data OpenStack metadata format The following example shows the contents of the - openstack/2012-08-10/meta_data.json - and - openstack/latest/meta_data.json - files. These files are identical. The file contents - are formatted for readability: + openstack/2012-08-10/meta_data.json and + openstack/latest/meta_data.json files. + These files are identical. The file contents are formatted for + readability. Note the effect of the --file /etc/network/interfaces=/home/myuser/instance-interfaces @@ -214,10 +200,10 @@ openstack/latest/user_data EC2 metadata format The following example shows the contents of the - ec2/2009-04-04/meta-data.json, - latest/meta-data.json files. - These files are identical. The file contents are - formatted to improve readability: + ec2/2009-04-04/meta-data.json and the + ec2/latest/meta-data.json files. These + files are identical. The file contents are formatted to improve + readability. @@ -239,11 +225,10 @@ openstack/latest/user_data /etc/nova/nova.conf file: config_drive_format=iso9660 - By default, you cannot attach the configuration - drive image as a CD drive instead of as a disk drive. - To attach a CD drive, add this line to the - /etc/nova/nova.conf - file: + By default, you cannot attach the configuration drive image as + a CD drive instead of as a disk drive. To attach a CD drive, add + the following line to the + /etc/nova/nova.conf file: config_drive_cdrom=true For legacy reasons, you can configure the configuration drive to use VFAT format instead of ISO @@ -260,8 +245,8 @@ openstack/latest/user_data
Configuration drive reference - The following table shows the configuration options for - the configuration drive: + The following table shows the configuration options for the + configuration drive.
diff --git a/doc/user-guide/section_cli_nova_migrate_instances.xml b/doc/user-guide/section_cli_nova_migrate_instances.xml index 41d6919a67..579ea1af4b 100644 --- a/doc/user-guide/section_cli_nova_migrate_instances.xml +++ b/doc/user-guide/section_cli_nova_migrate_instances.xml @@ -4,83 +4,73 @@ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="cli_migrate_instances"> - Use snapshots to migrate instance + Use snapshots to migrate instances + To use snapshots to migrate instances from OpenStack projects to clouds, complete these steps. + + + In the source project, perform the following steps: + + + Create a snapshot of the instance. + + + Download the snapshot as an image. + + + + In the destination project, perform the following steps: + + + Import the snapshot to the new environment. + + + Boot a new instance from the snapshot. + + + - Some cloud providers allow only administrators to - perform these steps. - - To use snapshots to migrate instances from OpenStack - projects to clouds, complete these steps: - - - Create a snapshot of the instance. - - - Download the snapshot as an image. - - - Import the snapshot to the new environment. - - - Boot a new instance from the snapshot. - - - - Perform the and procedures in the source - project. - Perform the and in the destination - project. + Some cloud providers allow only administrators to perform this task.
Create a snapshot of the instance - Always shut down the source VM before you take the - snapshot to make sure that all data is flushed to - disk. + Shut down the source VM before you take the snapshot to ensure that all data is flushed to disk. + If necessary, list the instances to view get the instance name. $ nova list - +--------------------------------------+------------+--------+------------------------------+ - | ID | Name | Status | Networks | - +--------------------------------------+------------+--------+------------------------------+ - | c41f3074-c82a-4837-8673-fa7e9fea7e11 | example | ACTIVE | private=10.0.0.3 | - +--------------------------------------+------------+--------+------------------------------+ ++--------------------------------------+------------+--------+------------------------------+ +| ID | Name | Status | Networks | ++--------------------------------------+------------+--------+------------------------------+ +| c41f3074-c82a-4837-8673-fa7e9fea7e11 | myInstance | ACTIVE | private=10.0.0.3 | ++--------------------------------------+------------+--------+------------------------------+ $ nova stop example - Confirm that the instance shows a SHUTOFF - status. + Use the nova list command to confirm that the instance shows a + SHUTOFF status. $ nova list - +--------------------------------------+------------+---------+------------------------------+ - | ID | Name | Status | Networks | - +--------------------------------------+------------+---------+------------------------------+ - | c41f3074-c82a-4837-8673-fa7e9fea7e11 | example | SHUTOFF | private=10.0.0.3 | - +--------------------------------------+------------+---------+------------------------------+ - ++--------------------------------------+------------+---------+------------------------------+ +| ID | Name | Status | Networks | ++--------------------------------------+------------+---------+------------------------------+ +| c41f3074-c82a-4837-8673-fa7e9fea7e11 | myInstance | SHUTOFF | private=10.0.0.3 | ++--------------------------------------+------------+---------+------------------------------+ Use the nova image-create command to take a snapshot. Use the nova image-list command to check the status until the status is ACTIVE: - $ nova list - +--------------------------------------+------------+---------+------------------------------+ - | ID | Name | Status | Networks | - +--------------------------------------+------------+---------+------------------------------+ - | c41f3074-c82a-4837-8673-fa7e9fea7e11 | example | SHUTOFF | private=10.0.0.3 | - +--------------------------------------+------------+---------+------------------------------+ - $ nova image-create --poll example examplesnapshot - Instance snapshotting... 50% complete + $ nova image-create --poll myInstance myInstanceSnapshot +Instance snapshotting... 50% complete $ nova image-list - +--------------------------------------+---------------------------------+--------+--------+ - | ID | Name | Status | Server | - +--------------------------------------+---------------------------------+--------+--------+ - | 657ebb01-6fae-47dc-986a-e49c4dd8c433 | cirros-0.3.2-x86_64-uec | ACTIVE | | - | 72074c6d-bf52-4a56-a61c-02a17bf3819b | cirros-0.3.2-x86_64-uec-kernel | ACTIVE | | - | 3c5e5f06-637b-413e-90f6-ca7ed015ec9e | cirros-0.3.2-x86_64-uec-ramdisk | ACTIVE | | - | f30b204e-1ce6-40e7-b8d9-b353d4d84e7d | examplesnapshot | ACTIVE | | - +--------------------------------------+---------------------------------+--------+--------+ ++--------------------------------------+---------------------------------+--------+--------+ +| ID | Name | Status | Server | ++--------------------------------------+---------------------------------+--------+--------+ +| 657ebb01-6fae-47dc-986a-e49c4dd8c433 | cirros-0.3.2-x86_64-uec | ACTIVE | | +| 72074c6d-bf52-4a56-a61c-02a17bf3819b | cirros-0.3.2-x86_64-uec-kernel | ACTIVE | | +| 3c5e5f06-637b-413e-90f6-ca7ed015ec9e | cirros-0.3.2-x86_64-uec-ramdisk | ACTIVE | | +| f30b204e-1ce6-40e7-b8d9-b353d4d84e7d | myInstanceSnapshot | ACTIVE | | ++--------------------------------------+---------------------------------+--------+--------+
@@ -90,16 +80,16 @@ Get the image ID: $ nova image-list -+--------------------------------------+------------------+--------+--------------------------------------+ -| ID | Name | Status | Server | -+--------------------------------------+------------------+--------+--------------------------------------+ -| f30b204e-1ce6-40e7-b8d9-b353d4d84e7d | examplesnapshot | ACTIVE | c41f3074-c82a-4837-8673-fa7e9fea7e11 | -+--------------------------------------+------------------+--------+--------------------------------------+ ++--------------------------------------+-------------------+--------+--------------------------------------+ +| ID | Name | Status | Server | ++--------------------------------------+-------------------+--------+--------------------------------------+ +| f30b204e-1ce6-40e7-b8d9-b353d4d84e7d | myInstanceSnapshot| ACTIVE | c41f3074-c82a-4837-8673-fa7e9fea7e11 | ++--------------------------------------+-------------------+--------+--------------------------------------+ Download the snapshot by using the image ID that was returned in the previous step: - $ glance image-download --file snapshot.raw f30b204e-1ce6-40e7-b8d9-b353d4d84e7d + $ glance image-download --file snapshot.raw f30b204e-1ce6-40e7-b8d9-b353d4d84e7d The glance image-download command requires the image ID and cannot use @@ -110,30 +100,21 @@ - Make the image available to the new environment, - either through http or with direct upload to a + Make the image available to the new environment, either through HTTP or with direct upload to a machine (scp).
Import the snapshot to new environment - - In the new project or cloud environment, import the snapshot: - $ glance image-create --copy-from IMAGE_URL - - + $ glance image-create --copy-from IMAGE_URL
Boot a new instance from the snapshot - - In the new project or cloud environment, use the snapshot to create the new instance: - $ nova boot --flavor m1.tiny --image EXAMPLE_SNAPSHOT NEW_INSTANCE - - + $ nova boot --flavor m1.tiny --image myInstanceSnapshot myNewInstance