4bf765758c
This patch works several files that were not in common use back into the documents they should live with. The intended end result of this activity is to make common as lean as possible so it can be more easily translated. Also: Don't include configdrive table in user-guide since it's not relevant for audience Change-Id: Iacd5c68c639e60e8c711cb18351543e477444299
297 lines
18 KiB
XML
297 lines
18 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
version="5.0"
|
|
xml:id="cli_launch_instances">
|
|
<title wordsize="20">Launch instances</title>
|
|
<para>Instances are virtual machines that run inside the
|
|
cloud.</para>
|
|
<para>Before you can launch an instance, gather the following
|
|
parameters:</para>
|
|
<itemizedlist xml:id="instance_parameters">
|
|
<listitem>
|
|
<para>The <emphasis role="bold">instance source</emphasis>
|
|
can be an image, snapshot, or block storage volume
|
|
that contains an image or snapshot.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A <emphasis role="bold">name</emphasis> for your instance.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The <emphasis role="bold">flavor</emphasis> for your
|
|
instance, which defines the compute, memory, and
|
|
storage capacity of nova computing instances. A flavor
|
|
is an available hardware configuration for a server.
|
|
It defines the size of a virtual server that can be
|
|
launched.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Any <emphasis role="bold">user data</emphasis>
|
|
files. A user data file is a special key in the
|
|
metadata service that holds a file that cloud-aware
|
|
applications in the guest instance can access. For
|
|
example, one application that uses user data is the
|
|
<link
|
|
xlink:href="https://help.ubuntu.com/community/CloudInit"
|
|
>cloud-init</link> system, which is an open-source
|
|
package from Ubuntu that is available on various Linux
|
|
distributions and that handles early initialization of
|
|
a cloud instance.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Access and security credentials, which include one
|
|
or both of the following credentials:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A <emphasis role="bold">key pair</emphasis>
|
|
for your instance, which are SSH credentials
|
|
that are injected into images when they are
|
|
launched. For the key pair to be successfully
|
|
injected, the image must contain the
|
|
<literal>cloud-init</literal> package.
|
|
Create at least one key pair for each project.
|
|
If you already have generated a key pair with
|
|
an external tool, you can import it into
|
|
OpenStack. You can use the key pair for
|
|
multiple instances that belong to that
|
|
project.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A <emphasis role="bold">security
|
|
group</emphasis> that defines which
|
|
incoming network traffic is forwarded to
|
|
instances. Security groups hold a set of
|
|
firewall policies, known as <emphasis
|
|
role="italic">security group
|
|
rules</emphasis>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If needed, you can assign a <emphasis role="bold"
|
|
>floating (public) IP address</emphasis> to a
|
|
running instance.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>You can also attach a block storage device, or
|
|
<emphasis role="bold">volume</emphasis>, for
|
|
persistent storage.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note>
|
|
<para>Instances that use the default security group cannot, by
|
|
default, be accessed from any IP address outside of the
|
|
cloud. If you want those IP addresses to access the
|
|
instances, you must modify the rules for the default
|
|
security group.</para>
|
|
<para>You can also assign a floating IP address to a running
|
|
instance to make it accessible from outside the cloud. See
|
|
<xref linkend="manage_ip_addresses"/>.</para>
|
|
</note>
|
|
<para>After you gather the parameters that you need to launch an
|
|
instance, you can launch it from an <link
|
|
linkend="launch_from_image">image</link> or a <link
|
|
linkend="boot_from_volume">volume</link>. You can launch
|
|
an instance directly from one of the available OpenStack
|
|
images or from an image that you have copied to a persistent
|
|
volume. The OpenStack Image Service provides a pool of images
|
|
that are accessible to members of different projects.</para>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="gather_parms">
|
|
<title wordsize="20">Gather parameters to launch an
|
|
instance</title>
|
|
<para>Before you begin, source the OpenStack RC file.</para>
|
|
<procedure>
|
|
<step>
|
|
<para>List the available flavors:</para>
|
|
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput></screen>
|
|
<para>Note the ID of the flavor that you want to use
|
|
for your instance:</para>
|
|
<screen><?db-font-size 55%?><computeroutput>+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
|
|
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
|
|
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
|
|
| 1 | m1.tiny | 512 | 0 | 0 | | 1 | 1.0 | True |
|
|
| 2 | m1.small | 2048 | 20 | 0 | | 1 | 1.0 | True |
|
|
| 3 | m1.medium | 4096 | 40 | 0 | | 2 | 1.0 | True |
|
|
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True |
|
|
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
|
|
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen>
|
|
</step>
|
|
<step>
|
|
<para>List the available images:</para>
|
|
<screen><prompt>$</prompt> <userinput>nova image-list</userinput></screen>
|
|
<para>Note the ID of the image from which you want to
|
|
boot your instance:</para> <screen><?db-font-size 55%?><computeroutput>+--------------------------------------+---------------------------------+--------+--------+
|
|
| ID | Name | Status | Server |
|
|
+--------------------------------------+---------------------------------+--------+--------+
|
|
| 397e713c-b95b-4186-ad46-6126863ea0a9 | cirros-0.3.2-x86_64-uec | ACTIVE | |
|
|
| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.2-x86_64-uec-kernel | ACTIVE | |
|
|
| 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.2-x86_64-uec-ramdisk | ACTIVE | |
|
|
+--------------------------------------+---------------------------------+--------+--------+</computeroutput></screen>
|
|
<para>You can also filter the image list by using
|
|
<command>grep</command> to find a specific
|
|
image, as follows:</para>
|
|
<screen><prompt>$</prompt> <userinput>nova image-list | grep 'kernel'</userinput></screen>
|
|
<screen><?db-font-size 55%?><computeroutput>| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.2-x86_64-uec-kernel | ACTIVE | |</computeroutput></screen>
|
|
</step>
|
|
<step>
|
|
<para>List the available security groups:</para>
|
|
<note>
|
|
<para>If you are an admin user, specify the
|
|
<option>--all-tenants</option> parameter
|
|
to list groups for all tenants.</para>
|
|
</note>
|
|
<screen><prompt>$</prompt> <userinput>nova secgroup-list --all-tenants</userinput></screen>
|
|
<para>Note the ID of the security group that you want to use for your instance:</para><screen><?db-font-size 65%?><computeroutput>+----+---------+-------------+----------------------------------+
|
|
| Id | Name | Description | Tenant_ID |
|
|
+----+---------+-------------+----------------------------------+
|
|
| 2 | default | default | 66265572db174a7aa66eba661f58eb9e |
|
|
| 1 | default | default | b70d90d65e464582b6b2161cf3603ced |
|
|
+----+---------+-------------+----------------------------------+</computeroutput></screen>
|
|
<para>If you have not created any security groups, you
|
|
can assign the instance to only the default
|
|
security group.</para>
|
|
<para>You can view rules for a specified security
|
|
group:</para>
|
|
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules default</userinput> </screen>
|
|
</step>
|
|
<step>
|
|
<para>List the available key pairs and note the name
|
|
of the key pair that you use for SSH
|
|
access.</para>
|
|
<screen><prompt>$</prompt> <userinput>nova keypair-list</userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="launch_from_image">
|
|
<title wordsize="20">Launch an instance from an image</title>
|
|
<procedure>
|
|
<step>
|
|
<para>After you gather required parameters, run the
|
|
following command to launch an instance. Specify
|
|
the server name, flavor ID, and image ID.</para>
|
|
<para>Optionally, you can provide a key name for
|
|
access control and a security group for security.
|
|
You can also include metadata key and value pairs.
|
|
For example, you can add a description for your
|
|
server by providing the <parameter>--meta
|
|
description="My Server"</parameter>
|
|
parameter.</para>
|
|
<para>You can pass user data in a local file at
|
|
instance launch by using the
|
|
<parameter>--user-data
|
|
<replaceable>USER-DATA-FILE</replaceable></parameter>
|
|
parameter.</para>
|
|
<screen><prompt>$</prompt> <userinput>nova boot --flavor <replaceable>FLAVOR_ID</replaceable> --image <replaceable>IMAGE_ID</replaceable> --key-name <replaceable>KEY_NAME</replaceable> \
|
|
--user-data <replaceable>USER_DATA_FILE</replaceable> --security-groups <replaceable>SEC_GROUP</replaceable> --meta <replaceable>KEY=VALUE</replaceable> \
|
|
<replaceable>INSTANCE_NAME</replaceable></userinput></screen>
|
|
<para>The following command launches the
|
|
<literal>MyCirrosServer</literal> instance
|
|
with the <literal>m1.small</literal> flavor (ID of
|
|
<literal>1</literal>),
|
|
<literal>cirros-0.3.2-x86_64-uec</literal>
|
|
image (ID of
|
|
<literal>397e713c-b95b-4186-ad46-6126863ea0a9</literal>),
|
|
<literal>default</literal> security group,
|
|
<literal>KeyPair01</literal> key, and a user
|
|
data file called
|
|
<filename>cloudinit.file</filename>:</para>
|
|
<screen><prompt>$</prompt> <userinput>nova boot --flavor 1 --image 397e713c-b95b-4186-ad46-6126863ea0a9 \
|
|
--security-groups default --key-name KeyPair01 --user-data cloudinit.file \
|
|
<replaceable>myCirrosServer</replaceable></userinput></screen>
|
|
<para>Depending on the parameters that you provide,
|
|
the command returns a list of server
|
|
properties.</para>
|
|
<para>A status of <literal>BUILD</literal> indicates
|
|
that the instance has started, but is not yet
|
|
online.</para>
|
|
<para>A status of <literal>ACTIVE</literal> indicates
|
|
that the instance is active.</para>
|
|
<screen><?db-font-size 50%?><computeroutput>+-------------------------------------+--------------------------------------+
|
|
| Property | Value |
|
|
+-------------------------------------+--------------------------------------+
|
|
| OS-EXT-STS:task_state | scheduling |
|
|
| image | cirros-0.3.2-x86_64-uec |
|
|
| OS-EXT-STS:vm_state | building |
|
|
| OS-EXT-SRV-ATTR:instance_name | instance-00000002 |
|
|
| flavor | m1.small |
|
|
| id | b3cdc6c0-85a7-4904-ae85-71918f734048 |
|
|
| security_groups | [{u'name': u'default'}] |
|
|
| user_id | 376744b5910b4b4da7d8e6cb483b06a8 |
|
|
| OS-DCF:diskConfig | MANUAL |
|
|
| accessIPv4 | |
|
|
| accessIPv6 | |
|
|
| progress | 0 |
|
|
| OS-EXT-STS:power_state | 0 |
|
|
| OS-EXT-AZ:availability_zone | nova |
|
|
| config_drive | |
|
|
| status | BUILD |
|
|
| updated | 2013-07-16T16:25:34Z |
|
|
| hostId | |
|
|
| OS-EXT-SRV-ATTR:host | None |
|
|
| key_name | None |
|
|
| OS-EXT-SRV-ATTR:hypervisor_hostname | None |
|
|
| name | myCirrosServer |
|
|
| adminPass | tVs5pL8HcPGw |
|
|
| tenant_id | 66265572db174a7aa66eba661f58eb9e |
|
|
| created | 2013-07-16T16:25:34Z |
|
|
| metadata | {u'KEY': u'VALUE'} |
|
|
+-------------------------------------+--------------------------------------+</computeroutput></screen>
|
|
<para>Copy the server ID value from the
|
|
<literal>id</literal> field in the output. You
|
|
use this ID to get details for or delete your
|
|
server.</para>
|
|
<para>Copy the administrative password value from the
|
|
<literal>adminPass</literal> field. You use
|
|
this value to log in to your server.</para>
|
|
<note>
|
|
<para>You can also place arbitrary local files
|
|
into the instance file system at creation time
|
|
by using the <option>--file
|
|
<dst-path=src-path></option> option.
|
|
You can store up to five files. For example,
|
|
if you have a special authorized keys file
|
|
named
|
|
<filename>special_authorized_keysfile</filename>
|
|
that you want to put on the instance rather
|
|
than using the regular SSH key injection, you
|
|
can use the <option>--file</option> option as
|
|
shown in the following example:</para>
|
|
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova boot --image ubuntu-cloudimage --flavor 1 vm-name \
|
|
--file /root/.ssh/authorized_keys=special_authorized_keysfile</userinput></screen>
|
|
</note>
|
|
</step>
|
|
<step>
|
|
<para>Check if the instance is online:</para>
|
|
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova list</userinput></screen>
|
|
<para>The list shows the ID, name, status, and private
|
|
(and if assigned, public) IP addresses for all
|
|
instances in the project to which you
|
|
belong:</para>
|
|
<screen><?db-font-size 50%?><computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
|
|
| ID | Name | Status | Task State | Power State | Networks |
|
|
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
|
|
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
|
|
| 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 |
|
|
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
|
|
<para>If the status for the instance is ACTIVE, the
|
|
instance is online.</para>
|
|
<para>To view the available options for the
|
|
<command>nova list</command> command, run the
|
|
following command:</para>
|
|
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova help list</userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
<note>
|
|
<para>If you did not provide a key pair, security groups,
|
|
or rules, you can access the instance only from inside
|
|
the cloud through VNC. Even pinging the instance is
|
|
not possible.</para>
|
|
</note>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<xi:include href="../common/section_cli_nova_boot_from_volume.xml"/>
|
|
</section>
|