diff --git a/doc/source/index.rst b/doc/source/index.rst index 6c6bc7dfd7..82e4e41c2a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -284,6 +284,7 @@ looking parts of our architecture. These are collected below. user/feature-classification user/filter-scheduler user/flavors + user/manage-ip-addresses user/placement user/quotas user/support-matrix diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index cebceb5c59..ae85f6551c 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -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 --------------------- diff --git a/doc/source/user/launch-instance-from-image.rst b/doc/source/user/launch-instance-from-image.rst new file mode 100644 index 0000000000..700fab6797 --- /dev/null +++ b/doc/source/user/launch-instance-from-image.rst @@ -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 `` + 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. + diff --git a/doc/source/user/launch-instance-from-volume.rst b/doc/source/user/launch-instance-from-volume.rst new file mode 100644 index 0000000000..eacd7661df --- /dev/null +++ b/doc/source/user/launch-instance-from-volume.rst @@ -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. diff --git a/doc/source/user/launch-instance-using-ISO-image.rst b/doc/source/user/launch-instance-using-ISO-image.rst new file mode 100644 index 0000000000..2e018b7c0f --- /dev/null +++ b/doc/source/user/launch-instance-using-ISO-image.rst @@ -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 \ + --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 +`_ +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. diff --git a/doc/source/user/launch-instances.rst b/doc/source/user/launch-instances.rst new file mode 100644 index 0000000000..15f4786cfa --- /dev/null +++ b/doc/source/user/launch-instances.rst @@ -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 `__ 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` +or a :doc:`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 + diff --git a/doc/source/user/manage-ip-addresses.rst b/doc/source/user/manage-ip-addresses.rst new file mode 100644 index 0000000000..97732fb07a --- /dev/null +++ b/doc/source/user/manage-ip-addresses.rst @@ -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.