b2235bf3fb
Execluded all XML files in the directory doc/common/tables because they are autogenerated. The XML root element of Docbook XML files should match the following format: <ELEMENT 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="THE_XML_ID_OF_THE_ELEMENT"> Change-Id: If12091be81ec8b2e6e53bfcb4c3a883a65e24736
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="section_cli_nova_boot_from_volume.xml"/>
|
|
</section>
|