openstack
/
nova
Code Issues Proposed changes

Merge "Migrate "launch instance" user guide docs" into stable/pike

This commit is contained in:
Zuul 2018-02-05 16:08:01 +00:00 committed by Gerrit Code Review
parent 602bcbf791 2d49eb8e4f
commit a64909b48e
7 changed files with 974 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/index.rst
View File

@ -263,6 +263,7 @@ looking parts of our architecture. These are collected below.
user/conductor
user/feature-classification
user/filter-scheduler
user/manage-ip-addresses
user/placement
user/quotas
user/support-matrix

10
doc/source/user/index.rst
View File

@ -2,6 +2,16 @@
User Documentation
==================
End user guide
--------------
.. toctree::
:maxdepth: 1
launch-instances
.. todo:: The rest of this document should probably move to the admin guide.
Architecture Overview
---------------------

143
doc/source/user/launch-instance-from-image.rst Normal file
View File

@ -0,0 +1,143 @@
================================
Launch an instance from an image
================================
Follow the steps below to launch an instance from an image.
#. After you gather required parameters, run the following command to
launch an instance. Specify the server name, flavor ID, and image ID.
.. code-block:: console
$ openstack server create --flavor FLAVOR_ID --image IMAGE_ID --key-name KEY_NAME \
--user-data USER_DATA_FILE --security-group SEC_GROUP_NAME --property KEY=VALUE \
INSTANCE_NAME
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
``--property description="My Server"`` parameter.
You can pass user data in a local file at instance launch by using the
``--user-data USER-DATA-FILE`` parameter.
.. important::
If you boot an instance with an INSTANCE_NAME greater than 63 characters,
Compute truncates it automatically when turning it into a host name to
ensure the correct work of dnsmasq. The corresponding warning is written
into the ``neutron-dnsmasq.log`` file.
The following command launches the ``MyCirrosServer`` instance with the
``m1.small`` flavor (ID of ``1``), ``cirros-0.3.2-x86_64-uec`` image (ID
of ``397e713c-b95b-4186-ad46-6126863ea0a9``), ``default`` security
group, ``KeyPair01`` key, and a user data file called
``cloudinit.file``:
.. code-block:: console
$ openstack server create --flavor 1 --image 397e713c-b95b-4186-ad46-6126863ea0a9 \
--security-group default --key-name KeyPair01 --user-data cloudinit.file \
myCirrosServer
Depending on the parameters that you provide, the command returns a list
of server properties.
.. code-block:: console
+--------------------------------------+-----------------------------------------------+
| Field | Value |
+--------------------------------------+-----------------------------------------------+
| OS-DCF:diskConfig | MANUAL |
| OS-EXT-AZ:availability_zone | |
| OS-EXT-SRV-ATTR:host | None |
| OS-EXT-SRV-ATTR:hypervisor_hostname | None |
| OS-EXT-SRV-ATTR:instance_name | |
| OS-EXT-STS:power_state | NOSTATE |
| OS-EXT-STS:task_state | scheduling |
| OS-EXT-STS:vm_state | building |
| OS-SRV-USG:launched_at | None |
| OS-SRV-USG:terminated_at | None |
| accessIPv4 | |
| accessIPv6 | |
| addresses | |
| adminPass | E4Ksozt4Efi8 |
| config_drive | |
| created | 2016-11-30T14:48:05Z |
| flavor | m1.tiny |
| hostId | |
| id | 89015cc9-bdf1-458a-8518-fdca2b4a5785 |
| image | cirros (397e713c-b95b-4186-ad46-6126863ea0a9) |
| key_name | KeyPair01 |
| name | myCirrosServer |
| os-extended-volumes:volumes_attached | [] |
| progress | 0 |
| project_id | 5669caad86a04256994cdf755df4d3c1 |
| properties | |
| security_groups | [{u'name': u'default'}] |
| status | BUILD |
| updated | 2016-11-30T14:48:05Z |
| user_id | c36cec73b0e44876a4478b1e6cd749bb |
| metadata | {u'KEY': u'VALUE'} |
+--------------------------------------+-----------------------------------------------+
A status of ``BUILD`` indicates that the instance has started, but is
not yet online.
A status of ``ACTIVE`` indicates that the instance is active.
#. Copy the server ID value from the ``id`` field in the output. Use the
ID to get server details or to delete your server.
#. Copy the administrative password value from the ``adminPass`` field. Use the
password to log in to your server.
.. note::
You can also place arbitrary local files into the instance file
system at creation time by using the ``--file <dst-path=src-path>``
option. You can store up to five files. For example, if you have a
special authorized keys file named ``special_authorized_keysfile`` that
you want to put on the instance rather than using the regular SSH key
injection, you can use the ``--file`` option as shown in the following
example.
.. code-block:: console
$ openstack server create --image ubuntu-cloudimage --flavor 1 vm-name \
--file /root/.ssh/authorized_keys=special_authorized_keysfile
#. Check if the instance is online.
.. code-block:: console
$ openstack server list
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:
.. code-block:: console
+-------------+----------------------+--------+------------+-------------+------------------+------------+
| ID | Name | Status | Task State | Power State | Networks | Image Name |
+-------------+----------------------+--------+------------+-------------+------------------+------------+
| 84c6e57d... | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 | cirros |
| 8a99547e... | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 | centos |
+-------------+----------------------+--------+------------+-------------+------------------+------------+
If the status for the instance is ACTIVE, the instance is online.
#. To view the available options for the :command:`openstack server list`
command, run the following command:
.. code-block:: console
$ openstack help server list
.. note::
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.

335
doc/source/user/launch-instance-from-volume.rst Normal file
View File

@ -0,0 +1,335 @@
================================
Launch an instance from a volume
================================
You can boot instances from a volume instead of an image.
To complete these tasks, use these parameters on the
:command:`openstack server create` command:
.. tabularcolumns:: |p{0.3\textwidth}|p{0.25\textwidth}|p{0.4\textwidth}|
.. list-table::
:header-rows: 1
:widths: 30 15 30
* - Task
- openstack server create parameter
- Information
* - Boot an instance from an image and attach a non-bootable
volume.
- ``--block-device``
- :ref:`Boot_instance_from_image_and_attach_non-bootable_volume`
* - Create a volume from an image and boot an instance from that
volume.
- ``--block-device``
- :ref:`Create_volume_from_image_and_boot_instance`
* - Boot from an existing source image, volume, or snapshot.
- ``--block-device``
- :ref:`Create_volume_from_image_and_boot_instance`
* - Attach a swap disk to an instance.
- ``--swap``
- :ref:`Attach_swap_or_ephemeral_disk_to_an_instance`
* - Attach an ephemeral disk to an instance.
- ``--ephemeral``
- :ref:`Attach_swap_or_ephemeral_disk_to_an_instance`
.. note::
To attach a volume to a running instance, see
`Attach a volume to an instance`_.
.. _Attach a volume to an instance: https://docs.openstack.org/cinder/latest/cli/cli-manage-volumes.html#attach-a-volume-to-an-instance
.. _Boot_instance_from_image_and_attach_non-bootable_volume:
Boot instance from image and attach non-bootable volume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a non-bootable volume and attach that volume to an instance that
you boot from an image.
To create a non-bootable volume, do not create it from an image. The
volume must be entirely empty with no partition table and no file
system.
#. Create a non-bootable volume.
.. code-block:: console
$ openstack volume create --size 8 my-volume
+---------------------+--------------------------------------+
| Field | Value |
+---------------------+--------------------------------------+
| attachments | [] |
| availability_zone | nova |
| bootable | false |
| consistencygroup_id | None |
| created_at | 2016-11-25T10:37:08.850997 |
| description | None |
| encrypted | False |
| id | b8f7bbec-6274-4cd7-90e7-60916a5e75d4 |
| migration_status | None |
| multiattach | False |
| name | my-volume |
| properties | |
| replication_status | disabled |
| size | 8 |
| snapshot_id | None |
| source_volid | None |
| status | creating |
| type | None |
| updated_at | None |
| user_id | 0678735e449149b0a42076e12dd54e28 |
+---------------------+--------------------------------------+
#. List volumes.
.. code-block:: console
$ openstack volume list
+--------------------------------------+--------------+-----------+------+-------------+
| ID | Display Name | Status | Size | Attached to |
+--------------------------------------+--------------+-----------+------+-------------+
| b8f7bbec-6274-4cd7-90e7-60916a5e75d4 | my-volume | available | 8 | |
+--------------------------------------+--------------+-----------+------+-------------+
#. Boot an instance from an image and attach the empty volume to the
instance.
.. code-block:: console
$ openstack server create --flavor 2 --image 98901246-af91-43d8-b5e6-a4506aa8f369 \
--block-device source=volume,id=d620d971-b160-4c4e-8652-2513d74e2080,dest=volume,shutdown=preserve \
myInstanceWithVolume
+--------------------------------------+--------------------------------------------+
| Field | Value |
+--------------------------------------+--------------------------------------------+
| OS-DCF:diskConfig | MANUAL |
| OS-EXT-AZ:availability_zone | nova |
| OS-EXT-SRV-ATTR:host | - |
| OS-EXT-SRV-ATTR:hypervisor_hostname | - |
| OS-EXT-SRV-ATTR:instance_name | instance-00000004 |
| OS-EXT-STS:power_state | 0 |
| OS-EXT-STS:task_state | scheduling |
| OS-EXT-STS:vm_state | building |
| OS-SRV-USG:launched_at | - |
| OS-SRV-USG:terminated_at | - |
| accessIPv4 | |
| accessIPv6 | |
| adminPass | ZaiYeC8iucgU |
| config_drive | |
| created | 2014-05-09T16:34:50Z |
| flavor | m1.small (2) |
| hostId | |
| id | 1e1797f3-1662-49ff-ae8c-a77e82ee1571 |
| image | cirros-0.3.5-x86_64-uec (98901246-af91-... |
| key_name | - |
| metadata | {} |
| name | myInstanceWithVolume |
| os-extended-volumes:volumes_attached | [{"id": "d620d971-b160-4c4e-8652-2513d7... |
| progress | 0 |
| security_groups | default |
| status | BUILD |
| tenant_id | ccef9e62b1e645df98728fb2b3076f27 |
| updated | 2014-05-09T16:34:51Z |
| user_id | fef060ae7bfd4024b3edb97dff59017a |
+--------------------------------------+--------------------------------------------+
.. _Create_volume_from_image_and_boot_instance:
Create volume from image and boot instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can create a volume from an existing image, volume, or snapshot.
This procedure shows you how to create a volume from an image, and use
the volume to boot an instance.
#. List the available images.
.. code-block:: console
$ openstack image list
+-----------------+---------------------------------+--------+
| ID | Name | Status |
+-----------------+---------------------------------+--------+
| 484e05af-a14... | Fedora-x86_64-20-20131211.1-sda | active |
| 98901246-af9... | cirros-0.3.5-x86_64-uec | active |
| b6e95589-7eb... | cirros-0.3.5-x86_64-uec-kernel | active |
| c90893ea-e73... | cirros-0.3.5-x86_64-uec-ramdisk | active |
+-----------------+---------------------------------+--------+
Note the ID of the image that you want to use to create a volume.
If you want to create a volume to a specific storage backend, you need
to use an image which has *cinder_img_volume_type* property.
In this case, a new volume will be created as *storage_backend1* volume
type.
.. code-block:: console
$ openstack image show 98901246-af9d-4b61-bea8-09cc6dc41829
+------------------+------------------------------------------------------+
| Field | Value |
+------------------+------------------------------------------------------+
| checksum | ee1eca47dc88f4879d8a229cc70a07c6 |
| container_format | bare |
| created_at | 2016-10-08T14:59:05Z |
| disk_format | qcow2 |
| file | /v2/images/9fef3b2d-c35d-4b61-bea8-09cc6dc41829/file |
| id | 98901246-af9d-4b61-bea8-09cc6dc41829 |
| min_disk | 0 |
| min_ram | 0 |
| name | cirros-0.3.5-x86_64-uec |
| owner | 8d8ef3cdf2b54c25831cbb409ad9ae86 |
| protected | False |
| schema | /v2/schemas/image |
| size | 13287936 |
| status | active |
| tags | |
| updated_at | 2016-10-19T09:12:52Z |
| virtual_size | None |
| visibility | public |
+------------------+------------------------------------------------------+
#. List the available flavors.
.. code-block:: console
$ openstack flavor list
+-----+-----------+-------+------+-----------+-------+-----------+
| ID | Name | RAM | Disk | Ephemeral | VCPUs | Is_Public |
+-----+-----------+-------+------+-----------+-------+-----------+
| 1 | m1.tiny | 512 | 1 | 0 | 1 | True |
| 2 | m1.small | 2048 | 20 | 0 | 1 | True |
| 3 | m1.medium | 4096 | 40 | 0 | 2 | True |
| 4 | m1.large | 8192 | 80 | 0 | 4 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | 8 | True |
+-----+-----------+-------+------+-----------+-------+-----------+
Note the ID of the flavor that you want to use to create a volume.
#. To create a bootable volume from an image and launch an instance from
this volume, use the ``--block-device`` parameter.
For example:
.. code-block:: console
$ openstack server create --flavor FLAVOR --block-device \
source=SOURCE,id=ID,dest=DEST,size=SIZE,shutdown=PRESERVE,bootindex=INDEX \
NAME
The parameters are:
- ``--flavor``
The flavor ID or name.
- ``--block-device``
source=SOURCE,id=ID,dest=DEST,size=SIZE,shutdown=PRESERVE,bootindex=INDEX
**source=SOURCE**
The type of object used to create the block device. Valid values
are ``volume``, ``snapshot``, ``image``, and ``blank``.
**id=ID**
The ID of the source object.
**dest=DEST**
The type of the target virtual device. Valid values are ``volume``
and ``local``.
**size=SIZE**
The size of the volume that is created.
**shutdown={preserve\|remove}**
What to do with the volume when the instance is deleted.
``preserve`` does not delete the volume. ``remove`` deletes the
volume.
**bootindex=INDEX**
Orders the boot disks. Use ``0`` to boot from this volume.
- ``NAME``. The name for the server.
#. Create a bootable volume from an image. Cinder makes a volume bootable
when ``--image`` parameter is passed.
.. code-block:: console
$ openstack volume create --image IMAGE_ID --size SIZE_IN_GB bootable_volume
#. Create a VM from previously created bootable volume. The volume is not
deleted when the instance is terminated.
.. code-block:: console
$ openstack server create --flavor 2 --volume VOLUME_ID \
--block-device source=volume,id=$VOLUME_ID,dest=volume,size=10,shutdown=preserve,bootindex=0 \
myInstanceFromVolume
+--------------------------------------+--------------------------------+
| Field | Value |
+--------------------------------------+--------------------------------+
| OS-EXT-STS:task_state | scheduling |
| image | Attempt to boot from volume |
| | - no image supplied |
| OS-EXT-STS:vm_state | building |
| OS-EXT-SRV-ATTR:instance_name | instance-00000003 |
| OS-SRV-USG:launched_at | None |
| flavor | m1.small |
| id | 2e65c854-dba9-4f68-8f08-fe3... |
| security_groups | [{u'name': u'default'}] |
| user_id | 352b37f5c89144d4ad053413926... |
| 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 | 2014-02-02T13:29:54Z |
| hostId | |
| OS-EXT-SRV-ATTR:host | None |
| OS-SRV-USG:terminated_at | None |
| key_name | None |
| OS-EXT-SRV-ATTR:hypervisor_hostname | None |
| name | myInstanceFromVolume |
| adminPass | TzjqyGsRcJo9 |
| tenant_id | f7ac731cc11f40efbc03a9f9e1d... |
| created | 2014-02-02T13:29:53Z |
| os-extended-volumes:volumes_attached | [{"id": "2fff50ab..."}] |
| metadata | {} |
+--------------------------------------+--------------------------------+
#. List volumes to see the bootable volume and its attached
``myInstanceFromVolume`` instance.
.. code-block:: console
$ openstack volume list
+---------------------+-----------------+--------+------+---------------------------------+
| ID | Display Name | Status | Size | Attached to |
+---------------------+-----------------+--------+------+---------------------------------+
| c612f739-8592-44c4- | bootable_volume | in-use | 10 | Attached to myInstanceFromVolume|
| b7d4-0fee2fe1da0c | | | | on /dev/vda |
+---------------------+-----------------+--------+------+---------------------------------+
.. _Attach_swap_or_ephemeral_disk_to_an_instance:
Attach swap or ephemeral disk to an instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the ``nova boot`` ``--swap`` parameter to attach a swap disk on boot
or the ``nova boot`` ``--ephemeral`` parameter to attach an ephemeral
disk on boot. When you terminate the instance, both disks are deleted.
Boot an instance with a 512 MB swap disk and 2 GB ephemeral disk.
.. code-block:: console
$ nova boot --flavor FLAVOR --image IMAGE_ID --swap 512 \
--ephemeral size=2 NAME
.. note::
The flavor defines the maximum swap and ephemeral disk size. You
cannot exceed these maximum values.

147
doc/source/user/launch-instance-using-ISO-image.rst Normal file
View File

@ -0,0 +1,147 @@
==================================
Launch an instance using ISO image
==================================
.. _Boot_instance_from_ISO_image:
Boot an instance from an ISO image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OpenStack supports booting instances using ISO images. But before you
make such instances functional, use the :command:`openstack server create`
command with the following parameters to boot an instance:
.. code-block:: console
$ openstack server create --image ubuntu-14.04.2-server-amd64.iso \
--nic net-id = NETWORK_UUID \
--flavor 2 INSTANCE_NAME
+--------------------------------------+--------------------------------------------+
| Field | Value |
+--------------------------------------+--------------------------------------------+
| OS-DCF:diskConfig | MANUAL |
| OS-EXT-AZ:availability_zone | nova |
| OS-EXT-SRV-ATTR:host | - |
| OS-EXT-SRV-ATTR:hypervisor_hostname | - |
| OS-EXT-SRV-ATTR:instance_name | instance-00000004 |
| OS-EXT-STS:power_state | 0 |
| OS-EXT-STS:task_state | scheduling |
| OS-EXT-STS:vm_state | building |
| OS-SRV-USG:launched_at | - |
| OS-SRV-USG:terminated_at | - |
| accessIPv4 | |
| accessIPv6 | |
| adminPass | ZaiYeC8iucgU |
| config_drive | |
| created | 2015-06-01T16:34:50Z |
| flavor | m1.small (2) |
| hostId | |
| id | 1e1797f3-1662-49ff-ae8c-a77e82ee1571 |
| image | ubuntu-14.04.2-server-amd64.iso |
| key_name | - |
| metadata | {} |
| name | INSTANCE_NAME |
| os-extended-volumes:volumes_attached | [] |
| progress | 0 |
| security_groups | default |
| status | BUILD |
| tenant_id | ccef9e62b1e645df98728fb2b3076f27 |
| updated | 2014-05-09T16:34:51Z |
| user_id | fef060ae7bfd4024b3edb97dff59017a |
+--------------------------------------+--------------------------------------------+
In this command, ``ubuntu-14.04.2-server-amd64.iso`` is the ISO image,
and ``INSTANCE_NAME`` is the name of the new instance. ``NETWORK_UUID``
is a valid network id in your system.
Create a bootable volume for the instance to reside on after shutdown.
#. Create the volume:
.. code-block:: console
$ openstack volume create \
--size <SIZE_IN_GB> \
--bootable VOLUME_NAME
#. Attach the instance to the volume:
.. code-block:: console
$ openstack server add volume
INSTANCE_NAME \
VOLUME_NAME \
--device /dev/vda
.. note::
You need the Block Storage service to preserve the instance after
shutdown. The ``--block-device`` argument, used with the
legacy :command:`nova boot`, will not work with the OpenStack
:command:`openstack server create` command. Instead, the
:command:`openstack volume create` and
:command:`openstack server add volume` commands create persistent storage.
After the instance is successfully launched, connect to the instance
using a remote console and follow the instructions to install the
system as using ISO images on regular computers. When the installation
is finished and system is rebooted, the instance asks you again to
install the operating system, which means your instance is not usable.
If you have problems with image creation, please check the
`Virtual Machine Image Guide
<https://docs.openstack.org/image-guide/create-images-manually.html>`_
for reference.
.. _Make_instance_booted_from_ISO_image_functional:
Make the instances booted from ISO image functional
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now complete the following steps to make your instances created
using ISO image actually functional.
#. Delete the instance using the following command.
.. code-block:: console
$ openstack server delete INSTANCE_NAME
#. After you delete the instance, the system you have just installed
using your ISO image remains, because the parameter
``shutdown=preserve`` was set, so run the following command.
.. code-block:: console
$ openstack volume list
+--------------------------+-------------------------+-----------+------+-------------+
| ID | Display Name | Status | Size | Attached to |
+--------------------------+-------------------------+-----------+------+-------------+
| 8edd7c97-1276-47a5-9563- |dc01d873-d0f1-40b6-bfcc- | available | 10 | |
| 1025f4264e4f | 26a8d955a1d9-blank-vol | | | |
+--------------------------+-------------------------+-----------+------+-------------+
You get a list with all the volumes in your system. In this list,
you can find the volume that is attached to your ISO created
instance, with the false bootable property.
#. Upload the volume to glance.
.. code-block:: console
$ openstack image create --volume SOURCE_VOLUME IMAGE_NAME
$ openstack image list
+-------------------+------------+--------+
| ID | Name | Status |
+-------------------+------------+--------+
| 74303284-f802-... | IMAGE_NAME | active |
+-------------------+------------+--------+
The ``SOURCE_VOLUME`` is the UUID or a name of the volume that is attached to
your ISO created instance, and the ``IMAGE_NAME`` is the name that
you give to your new image.
#. After the image is successfully uploaded, you can use the new
image to boot instances.
The instances launched using this image contain the system that
you have just installed using the ISO image.

168
doc/source/user/launch-instances.rst Normal file
View File

@ -0,0 +1,168 @@
================
Launch instances
================
Instances are virtual machines that run inside the cloud.
Before you can launch an instance, gather the following parameters:
- The **instance source** can be an image, snapshot, or block storage
volume that contains an image or snapshot.
- A **name** for your instance.
- The **flavor** 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.
- Any **user data** 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
`cloud-init <https://help.ubuntu.com/community/CloudInit>`__ 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.
- Access and security credentials, which include one or both of the
following credentials:
- A **key pair** 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
``cloud-init`` 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.
- A **security group** that defines which incoming network traffic
is forwarded to instances. Security groups hold a set of firewall
policies, known as *security group rules*.
- If needed, you can assign a **floating (public) IP address** to a
running instance.
- You can also attach a block storage device, or **volume**, for
persistent storage.
.. note::
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.
You can also assign a floating IP address to a running instance to
make it accessible from outside the cloud. See
:doc:`manage-ip-addresses`.
After you gather the parameters that you need to launch an instance,
you can launch it from an :doc:`image<launch-instance-from-image>`
or a :doc:`volume<launch-instance-from-volume>`. 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.
Gather parameters to launch an instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before you begin, source the OpenStack RC file.
#. Create a flavor.
.. code-block:: console
$ openstack flavor create --ram 512 --disk 1 --vcpus 1 m1.tiny
#. List the available flavors.
.. code-block:: console
$ openstack flavor list
Note the ID of the flavor that you want to use for your instance::
+-----+-----------+-------+------+-----------+-------+-----------+
| ID | Name | RAM | Disk | Ephemeral | VCPUs | Is_Public |
+-----+-----------+-------+------+-----------+-------+-----------+
| 1 | m1.tiny | 512 | 1 | 0 | 1 | True |
| 2 | m1.small | 2048 | 20 | 0 | 1 | True |
| 3 | m1.medium | 4096 | 40 | 0 | 2 | True |
| 4 | m1.large | 8192 | 80 | 0 | 4 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | 8 | True |
+-----+-----------+-------+------+-----------+-------+-----------+
#. List the available images.
.. code-block:: console
$ openstack image list
Note the ID of the image from which you want to boot your instance::
+--------------------------------------+---------------------------------+--------+
| ID | Name | Status |
+--------------------------------------+---------------------------------+--------+
| 397e713c-b95b-4186-ad46-6126863ea0a9 | cirros-0.3.5-x86_64-uec | active |
| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.5-x86_64-uec-kernel | active |
| 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.5-x86_64-uec-ramdisk | active |
+--------------------------------------+---------------------------------+--------+
You can also filter the image list by using :command:`grep` to find a specific
image, as follows:
.. code-block:: console
$ openstack image list | grep 'kernel'
| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.5-x86_64-uec-kernel | active |
#. List the available security groups.
.. code-block:: console
$ openstack security group list
.. note::
If you are an admin user, this command will list groups for all tenants.
Note the ID of the security group that you want to use for your instance::
+--------------------------------------+---------+------------------------+----------------------------------+
| ID | Name | Description | Project |
+--------------------------------------+---------+------------------------+----------------------------------+
| b0d78827-0981-45ef-8561-93aee39bbd9f | default | Default security group | 5669caad86a04256994cdf755df4d3c1 |
| ec02e79e-83e1-48a5-86ad-14ab9a8c375f | default | Default security group | 1eaaf6ede7a24e78859591444abf314a |
+--------------------------------------+---------+------------------------+----------------------------------+
If you have not created any security groups, you can assign the instance
to only the default security group.
You can view rules for a specified security group:
.. code-block:: console
$ openstack security group rule list default
#. List the available key pairs, and note the key pair name that you use for
SSH access.
.. code-block:: console
$ openstack keypair list
Launch an instance
~~~~~~~~~~~~~~~~~~
You can launch an instance from various sources.
.. toctree::
:maxdepth: 2
launch-instance-from-image.rst
launch-instance-from-volume.rst
launch-instance-using-ISO-image.rst

170
doc/source/user/manage-ip-addresses.rst Normal file
View File

@ -0,0 +1,170 @@
===================
Manage IP addresses
===================
.. todo:: This needs quite a bit of work since nova-network has been
deprecated since Newton, and the network resource related compute
APIs which are for nova-network or that proxy to neutron have been
deprecated, along with their respective CLIs in python-novaclient.
Each instance has a private, fixed IP address and can also have a
public, or floating IP address. Private IP addresses are used for
communication between instances, and public addresses are used for
communication with networks outside the cloud, including the Internet.
When you launch an instance, it is automatically assigned a private IP
address that stays the same until you explicitly terminate the instance.
Rebooting an instance has no effect on the private IP address.
A pool of floating IP addresses, configured by the cloud administrator,
is available in OpenStack Compute. The project quota defines the maximum
number of floating IP addresses that you can allocate to the project.
After you allocate a floating IP address to a project, you can:
- Associate the floating IP address with an instance of the project. Only one
floating IP address can be allocated to an instance at any given time.
- Disassociate a floating IP address from an instance in the project.
- Delete a floating IP from the project which automatically deletes that IP's
associations.
Use the :command:`openstack` commands to manage floating IP addresses.
List floating IP address information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To list all pools that provide floating IP addresses, run:
.. code-block:: console
$ openstack floating ip pool list
+--------+
| name |
+--------+
| public |
| test |
+--------+
.. note::
If this list is empty, the cloud administrator must configure a pool
of floating IP addresses.
To list all floating IP addresses that are allocated to the current project,
run:
.. code-block:: console
$ openstack floating ip list
+--------------------------------------+---------------------+------------------+------+
| ID | Floating IP Address | Fixed IP Address | Port |
+--------------------------------------+---------------------+------------------+------+
| 760963b2-779c-4a49-a50d-f073c1ca5b9e | 172.24.4.228 | None | None |
| 89532684-13e1-4af3-bd79-f434c9920cc3 | 172.24.4.235 | None | None |
| ea3ebc6d-a146-47cd-aaa8-35f06e1e8c3d | 172.24.4.229 | None | None |
+--------------------------------------+---------------------+------------------+------+
For each floating IP address that is allocated to the current project,
the command outputs the floating IP address, the ID for the instance
to which the floating IP address is assigned, the associated fixed IP
address, and the pool from which the floating IP address was
allocated.
Associate floating IP addresses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can assign a floating IP address to a project and to an instance.
#. Run the following command to allocate a floating IP address to the
current project. By default, the floating IP address is allocated from
the public pool. The command outputs the allocated IP address:
.. code-block:: console
$ openstack floating ip create public
+---------------------+--------------------------------------+
| Field | Value |
+---------------------+--------------------------------------+
| created_at | 2016-11-30T15:02:05Z |
| description | |
| fixed_ip_address | None |
| floating_ip_address | 172.24.4.236 |
| floating_network_id | 0bf90de6-fc0f-4dba-b80d-96670dfb331a |
| headers | |
| id | c70ad74b-2f64-4e60-965e-f24fc12b3194 |
| port_id | None |
| project_id | 5669caad86a04256994cdf755df4d3c1 |
| project_id | 5669caad86a04256994cdf755df4d3c1 |
| revision_number | 1 |
| router_id | None |
| status | DOWN |
| updated_at | 2016-11-30T15:02:05Z |
+---------------------+--------------------------------------+
#. List all project instances with which a floating IP address could be
associated.
.. code-block:: console
$ openstack server list
+---------------------+------+---------+------------+-------------+------------------+------------+
| ID | Name | Status | Task State | Power State | Networks | Image Name |
+---------------------+------+---------+------------+-------------+------------------+------------+
| d5c854f9-d3e5-4f... | VM1 | ACTIVE | - | Running | private=10.0.0.3 | cirros |
| 42290b01-0968-43... | VM2 | SHUTOFF | - | Shutdown | private=10.0.0.4 | centos |
+---------------------+------+---------+------------+-------------+------------------+------------+
#. Associate an IP address with an instance in the project, as follows:
.. code-block:: console
$ openstack server add floating ip INSTANCE_NAME_OR_ID FLOATING_IP_ADDRESS
For example:
.. code-block:: console
$ openstack server add floating ip VM1 172.24.4.225
The instance is now associated with two IP addresses:
.. code-block:: console
$ openstack server list
+------------------+------+--------+------------+-------------+-------------------------------+------------+
| ID | Name | Status | Task State | Power State | Networks | Image Name |
+------------------+------+--------+------------+-------------+-------------------------------+------------+
| d5c854f9-d3e5... | VM1 | ACTIVE | - | Running | private=10.0.0.3, 172.24.4.225| cirros |
| 42290b01-0968... | VM2 | SHUTOFF| - | Shutdown | private=10.0.0.4 | centos |
+------------------+------+--------+------------+-------------+-------------------------------+------------+
After you associate the IP address and configure security group rules
for the instance, the instance is publicly available at the floating IP
address.
.. note::
The :command:`openstack server` command does not allow users to associate a
floating IP address with a specific fixed IP address using the optional
``--fixed-address`` parameter, which legacy commands required as an
argument.
Disassociate floating IP addresses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To disassociate a floating IP address from an instance:
.. code-block:: console
$ openstack server remove floating ip INSTANCE_NAME_OR_ID FLOATING_IP_ADDRESS
To remove the floating IP address from a project:
.. code-block:: console
$ openstack floating ip delete FLOATING_IP_ADDRESS
The IP address is returned to the pool of IP addresses that is available
for all projects. If the IP address is still associated with a running
instance, it is automatically disassociated from that instance.