openstack
/
openstack-manuals
Code Issues Proposed changes

Remove the user-guide 

The useful content in the user guide is all being moved to
project-specific docsets. We can remove the guide here, and replace it
with a /user/ landing page that provides links to all of the known user
guides for services and clients.

Change-Id: I7005b4288b94e755f406fd6a8e3273265b643042
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit is contained in:
Doug Hellmann 2017-07-10 15:01:09 -04:00 committed by Petr Kovar
parent a112d4df5a
commit 1fd07e6e31
103 changed files with 110 additions and 40146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
README.rst
View File

@ -22,7 +22,6 @@ It includes these manuals:
* Command-Line Interface Reference
* Configuration Reference
* Documentation Contributor Guide
* End User Guide
* High Availability Guide
* Installation Tutorials
* Networking Guide
@ -54,17 +53,18 @@ virtual environment and build all guides (HTML only):
You can also build a specific guide.
For example, to build *OpenStack End User Guide*, use the following command::
For example, to build *OpenStack Virtual Machine Image Guide*, use the
following command::
$ tox -e build -- user-guide
$ tox -e build -- image-guide
You can find the root of the generated HTML documentation at::
doc/user-guide/build/html/index.html
doc/image-guide/build/html/index.html
To build a specific guide with a PDF file, add a ``-pdf`` option like::
$ tox -e build -- user-guide --pdf
$ tox -e build -- image-guide --pdf
The generated PDF file will be copied to the root directory of the
generated HTML documentation.

7
doc-tools-check-languages.conf
View File

@ -7,12 +7,12 @@ declare -A BOOKS=(
["cs"]="install-guide"
["de"]="install-guide"
["fr"]="install-guide"
["id"]="image-guide install-guide user-guide"
["ja"]="ha-guide image-guide install-guide ops-guide user-guide"
["id"]="image-guide install-guide"
["ja"]="ha-guide image-guide install-guide ops-guide"
["ko_KR"]="install-guide"
["ru"]="install-guide"
["tr_TR"]="image-guide install-guide arch-design"
["zh_CN"]="install-guide user-guide"
["zh_CN"]="install-guide"
)
# draft books
@ -48,7 +48,6 @@ declare -A SPECIAL_BOOKS=(
["install-guide"]="RST"
["networking-guide"]="RST"
["ops-guide"]="RST"
["user-guide"]="RST"
# Do not translate for now, we need to fix our scripts first to
# generate the content properly.
["install-guide-debconf"]="skip"

5
doc/common/app-support.rst
View File

@ -60,10 +60,7 @@ The following books explain how to configure and run an OpenStack cloud:
* `Virtual Machine Image Guide <https://docs.openstack.org/image-guide/>`_
The following books explain how to use the OpenStack Dashboard and
command-line clients:
* `End User Guide <https://docs.openstack.org/user-guide/>`_
The following book explains how to use the command-line clients:
* `Command-Line Interface Reference
<https://docs.openstack.org/cli-reference/>`_

7
doc/contributor-guide/source/blueprints-and-specs.rst
View File

@ -204,9 +204,6 @@ Guides for deployers and administrators
Guides for end users
--------------------
* `OpenStack End User Guide <https://docs.openstack.org/user-guide/>`_:
Shows OpenStack end users how to create and manage resources in an
OpenStack cloud with the OpenStack dashboard and OpenStack client commands.
* `OpenStack API Guide
<https://developer.openstack.org/api-guide/quick-start/>`_:
A brief overview of how to send REST API requests to endpoints for
@ -222,10 +219,6 @@ Guides for end users
- Source location
- Target location
* - OpenStack End User Guide
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/user-guide
- https://docs.openstack.org/user-guide/
* - OpenStack API Guide
- https://git.openstack.org/cgit/openstack/api-site/tree/api-quick-start
- https://developer.openstack.org/api-guide/quick-start/

2
doc/contributor-guide/source/docs-builds.rst
View File

@ -183,7 +183,7 @@ To get the ``.html`` output locally, switch to the directory containing a
The RST source is built into HTML using Sphinx, so that it is displayed on
the *docs.openstack.org/<guide-name>*. For example:
https://docs.openstack.org/user-guide/.
https://docs.openstack.org/image-guide/.
Using Tox to check builds
-------------------------

8
doc/contributor-guide/source/rst-conv/references.rst
View File

@ -61,14 +61,14 @@ To link to some external locations, format the RST source as follows:
.. code-block:: none
Here is a link to the User guide: https://docs.openstack.org/user-guide/.
Here is a link to the Image guide: https://docs.openstack.org/image-guide/.
Here is an external web link with a link title:
`User guide <https://docs.openstack.org/user-guide/>`_.
`Image guide <https://docs.openstack.org/image-guide/>`_.
**Output**
Here is a link to the User guide: https://docs.openstack.org/user-guide/.
Here is a link to the Image guide: https://docs.openstack.org/image-guide/.
Here is an external web link with a link title:
`User guide <https://docs.openstack.org/user-guide/>`_.
`Image guide <https://docs.openstack.org/image-guide/>`_.

3
doc/contributor-guide/source/topic-tags.rst
View File

@ -53,9 +53,6 @@ Based on the topic your request refers to, use the following tags:
[training]
Training labs, Training guides, and Upstream Training materials
[user-guide]
OpenStack End User Guide
[WIP]
A marker that means the commit is a work in progress

4
doc/image-guide/source/centos-image.rst
View File

@ -390,5 +390,5 @@ The underlying image file that you created with the
For example, you can upload the ``/tmp/centos.qcow2``
image to the Image service by using the :command:`openstack image create`
command. For more information, see the
`Create or update an image
<https://docs.openstack.org/user-guide/common/cli-manage-images.html#create-or-update-an-image-glance>`__.
`python-openstackclient command list
<https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/image.html>`__.

4
doc/image-guide/source/fedora-image.rst
View File

@ -279,5 +279,5 @@ The underlying image file that you created with the
For example, you can upload the ``/tmp/fedora.qcow2``
image to the Image service by using the :command:`openstack image create`
command. For more information, see the
`Create or update an image
<https://docs.openstack.org/user-guide/common/cli-manage-images.html#create-or-update-an-image-glance>`__.
`python-openstackclient command list
<https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/image.html>`__.

4
doc/image-guide/source/obtain-images.rst
View File

@ -9,8 +9,8 @@ support the SSH key pair and user data injection.
Because many of the images disable SSH password authentication
by default, boot the image with an injected key pair.
You can ``SSH`` into the instance with the private key and default
login account. See the `OpenStack End User Guide
<https://docs.openstack.org/user-guide/configure-access-and-security-for-instances.html>`_
login account. See `Configure access and security for instances
<https://docs.openstack.org/horizon/latest/user/configure-access-and-security-for-instances.html>`_
for more information on how to create and inject key pairs with OpenStack.
CentOS

3
doc/image-guide/source/openstack-images.rst
View File

@ -276,8 +276,7 @@ Process user data and other metadata (cloud-init)
In addition to the ssh public key, an image might need
additional information from OpenStack, such as
`Provide user data to instances <https://docs.openstack.org/
user-guide/cli-provide-user-data-to-instances.html>`_,
to povide user data to instances,
that the user submitted when requesting the image.
For example, you might want to set the host name of the instance
when it is booted. Or, you might wish to configure your image

27
doc/user-guide/setup.cfg
View File

@ -1,27 +0,0 @@
[metadata]
name = openstackuserguide
summary = OpenStack End User Guide
author = OpenStack
author-email = openstack-docs@lists.openstack.org
home-page = https://docs.openstack.org/
classifier =
Environment :: OpenStack
Intended Audience :: Information Technology
Intended Audience :: System Administrators
License :: OSI Approved :: Apache Software License
Operating System :: POSIX :: Linux
Topic :: Documentation
[global]
setup-hooks =
pbr.hooks.setup_hook
[files]
[build_sphinx]
warning-is-error = 1
build-dir = build
source-dir = source
[wheel]
universal = 1

30
doc/user-guide/setup.py
View File

@ -1,30 +0,0 @@
#!/usr/bin/env python
# Copyright (c) 2013 Hewlett-Packard Development Company, L.P.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# THIS FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT
import setuptools
# In python < 2.7.4, a lazy loading of package `pbr` will break
# setuptools if some other modules registered functions in `atexit`.
# solution from: http://bugs.python.org/issue15881#msg170215
try:
import multiprocessing # noqa
except ImportError:
pass
setuptools.setup(
setup_requires=['pbr'],
pbr=True)

127
doc/user-guide/source/backup-db-incremental.rst
View File

@ -1,127 +0,0 @@
=======================
Use incremental backups
=======================
Incremental backups let you chain together a series of backups. You
start with a regular backup. Then, when you want to create a subsequent
incremental backup, you specify the parent backup.
Restoring a database instance from an incremental backup is the same as
creating a database instance from a regular backup—the Database service
handles the complexities of applying the chain of incremental backups.
This example shows you how to use incremental backups with a MySQL
database.
**Assumptions.** Assume that you have created a regular
backup for the following database instance:
- Instance name: ``guest1``
- ID of the instance (``INSTANCE_ID``):
``792a6a56-278f-4a01-9997-d997fa126370``
- ID of the regular backup artifact (``BACKUP_ID``):
``6dc3a9b7-1f3e-4954-8582-3f2e4942cddd``
Create and use incremental backups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. **Create your first incremental backup**
Use the :command:`trove backup-create` command and specify:
- The ``INSTANCE_ID`` of the database instance you are doing the
incremental backup for (in this example,
``792a6a56-278f-4a01-9997-d997fa126370``)
- The name of the incremental backup you are creating: ``backup1.1``
- The ``BACKUP_ID`` of the parent backup. In this case, the parent
is the regular backup, with an ID of
``6dc3a9b7-1f3e-4954-8582-3f2e4942cddd``
.. code-block:: console
$ trove backup-create INSTANCE_ID backup1.1 --parent BACKUP_ID
+-------------+--------------------------------------+
| Property | Value |
+-------------+--------------------------------------+
| created | 2014-03-19T14:09:13 |
| description | None |
| id | 1d474981-a006-4f62-b25f-43d7b8a7097e |
| instance_id | 792a6a56-278f-4a01-9997-d997fa126370 |
| locationRef | None |
| name | backup1.1 |
| parent_id | 6dc3a9b7-1f3e-4954-8582-3f2e4942cddd |
| size | None |
| status | NEW |
| updated | 2014-03-19T14:09:13 |
+-------------+--------------------------------------+
Note that this command returns both the ID of the database instance
you are incrementally backing up (``instance_id``) and a new ID for
the new incremental backup artifact you just created (``id``).
#. **Create your second incremental backup**
The name of your second incremental backup is ``backup1.2``. This
time, when you specify the parent, pass in the ID of the incremental
backup you just created in the previous step (``backup1.1``). In this
example, it is ``1d474981-a006-4f62-b25f-43d7b8a7097e``.
.. code-block:: console
$ trove backup-create INSTANCE_ID backup1.2 --parent BACKUP_ID
+-------------+--------------------------------------+
| Property | Value |
+-------------+--------------------------------------+
| created | 2014-03-19T14:09:13 |
| description | None |
| id | bb84a240-668e-49b5-861e-6a98b67e7a1f |
| instance_id | 792a6a56-278f-4a01-9997-d997fa126370 |
| locationRef | None |
| name | backup1.2 |
| parent_id | 1d474981-a006-4f62-b25f-43d7b8a7097e |
| size | None |
| status | NEW |
| updated | 2014-03-19T14:09:13 |
+-------------+--------------------------------------+
#. **Restore using incremental backups**
Now assume that your ``guest1`` database instance is damaged and you
need to restore it from your incremental backups. In this example,
you use the :command:`trove create` command to create a new database
instance called ``guest2``.
To incorporate your incremental backups, you simply use the
`--backup`` parameter to pass in the ``BACKUP_ID`` of your most
recent incremental backup. The Database service handles the
complexities of applying the chain of all previous incremental
backups.
.. code-block:: console
$ trove create guest2 10 --size 1 --backup BACKUP_ID
+-------------------+-----------------------------------------------------------+
| Property | Value |
+-------------------+-----------------------------------------------------------+
| created | 2014-03-19T14:10:56 |
| datastore | {u'version': u'mysql-5.5', u'type': u'mysql'} |
| datastore_version | mysql-5.5 |
| flavor | {u'id': u'10', u'links': |
| | [{u'href': u'https://10.125.1.135:8779/v1.0/ |
| | 626734041baa4254ae316de52a20b390/flavors/10', u'rel': |
| | u'self'}, {u'href': u'https://10.125.1.135:8779/ |
| | flavors/10', u'rel': u'bookmark'}]} |
| id | a3680953-eea9-4cf2-918b-5b8e49d7e1b3 |
| name | guest2 |
| status | BUILD |
| updated | 2014-03-19T14:10:56 |
| volume | {u'size': 1} |
+-------------------+-----------------------------------------------------------+

232
doc/user-guide/source/backup-db.rst
View File

@ -1,232 +0,0 @@
=============================
Backup and restore a database
=============================
You can use Database services to backup a database and store the backup
artifact in the Object Storage service. Later on, if the original
database is damaged, you can use the backup artifact to restore the
database. The restore process creates a database instance.
This example shows you how to back up and restore a MySQL database.
#. **Backup the database instance**
As background, assume that you have created a database
instance with the following
characteristics:
- Name of the database instance: ``guest1``
- Flavor ID: ``10``
- Root volume size: ``2``
- Databases: ``db1`` and ``db2``
- Users: The ``user1`` user with the ``password`` password
First, get the ID of the ``guest1`` database instance by using the
:command:`trove list` command:
.. code-block:: console
$ trove list
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+
| 97b4b853-80f6-414f-ba6f-c6f455a79ae6 | guest1 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+
Back up the database instance by using the :command:`trove backup-create`
command. In this example, the backup is called ``backup1``. In this
example, replace ``INSTANCE_ID`` with
``97b4b853-80f6-414f-ba6f-c6f455a79ae6``:
.. note::
This command syntax pertains only to python-troveclient version
1.0.6 and later. Earlier versions require you to pass in the backup
name as the first argument.
.. code-block:: console
$ trove backup-create INSTANCE_ID backup1
+-------------+--------------------------------------+
| Property | Value |
+-------------+--------------------------------------+
| created | 2014-03-18T17:09:07 |
| description | None |
| id | 8af30763-61fd-4aab-8fe8-57d528911138 |
| instance_id | 97b4b853-80f6-414f-ba6f-c6f455a79ae6 |
| locationRef | None |
| name | backup1 |
| parent_id | None |
| size | None |
| status | NEW |
| updated | 2014-03-18T17:09:07 |
+-------------+--------------------------------------+
Note that the command returns both the ID of the original instance
(``instance_id``) and the ID of the backup artifact (``id``).
Later on, use the :command:`trove backup-list` command to get this
information:
.. code-block:: console
$ trove backup-list
+--------------------------------------+--------------------------------------+---------+-----------+-----------+---------------------+
| id | instance_id | name | status | parent_id | updated |
+--------------------------------------+--------------------------------------+---------+-----------+-----------+---------------------+
| 8af30763-61fd-4aab-8fe8-57d528911138 | 97b4b853-80f6-414f-ba6f-c6f455a79ae6 | backup1 | COMPLETED | None | 2014-03-18T17:09:11 |
+--------------------------------------+--------------------------------------+---------+-----------+-----------+---------------------+
You can get additional information about the backup by using the
:command:`trove backup-show` command and passing in the ``BACKUP_ID``,
which is ``8af30763-61fd-4aab-8fe8-57d528911138``.
.. code-block:: console
$ trove backup-show BACKUP_ID
+-------------+----------------------------------------------------+
| Property | Value |
+-------------+----------------------------------------------------+
| created | 2014-03-18T17:09:07 |
| description | None |
| id | 8af...138 |
| instance_id | 97b...ae6 |
| locationRef | http://10.0.0.1:.../.../8af...138.xbstream.gz.enc |
| name | backup1 |
| parent_id | None |
| size | 0.17 |
| status | COMPLETED |
| updated | 2014-03-18T17:09:11 |
+-------------+----------------------------------------------------+
#. **Restore a database instance**
Now assume that your ``guest1`` database instance is damaged and you
need to restore it. In this example, you use the :command:`trove create`
command to create a new database instance called ``guest2``.
- You specify that the new ``guest2`` instance has the same flavor
(``10``) and the same root volume size (``2``) as the original
``guest1`` instance.
- You use the ``--backup`` argument to indicate that this new
instance is based on the backup artifact identified by
``BACKUP_ID``. In this example, replace ``BACKUP_ID`` with
``8af30763-61fd-4aab-8fe8-57d528911138``.
.. code-block:: console
$ trove create guest2 10 --size 2 --backup BACKUP_ID
+-------------------+----------------------------------------------+
| Property | Value |
+-------------------+----------------------------------------------+
| created | 2014-03-18T17:12:03 |
| datastore | {u'version': u'mysql-5.5', u'type': u'mysql'}|
|datastore_version | mysql-5.5 |
| flavor | {u'id': u'10', u'links': [{u'href': ...]} |
| id | ac7a2b35-a9b4-4ff6-beac-a1bcee86d04b |
| name | guest2 |
| status | BUILD |
| updated | 2014-03-18T17:12:03 |
| volume | {u'size': 2} |
+-------------------+----------------------------------------------+
#. **Verify backup**
Now check that the new ``guest2`` instance has the same
characteristics as the original ``guest1`` instance.
Start by getting the ID of the new ``guest2`` instance.
.. code-block:: console
$ trove list
+-----------+--------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+-----------+--------+-----------+-------------------+--------+-----------+------+
| 97b...ae6 | guest1 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
| ac7...04b | guest2 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
+-----------+--------+-----------+-------------------+--------+-----------+------+
Use the :command:`trove show` command to display information about the new
guest2 instance. Pass in guest2's ``INSTANCE_ID``, which is
``ac7a2b35-a9b4-4ff6-beac-a1bcee86d04b``.
.. code-block:: console
$ trove show INSTANCE_ID
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-03-18T17:12:03 |
| datastore | mysql |
| datastore_version | mysql-5.5 |
| flavor | 10 |
| id | ac7a2b35-a9b4-4ff6-beac-a1bcee86d04b |
| ip | 10.0.0.3 |
| name | guest2 |
| status | ACTIVE |
| updated | 2014-03-18T17:12:06 |
| volume | 2 |
| volume_used | 0.18 |
+-------------------+--------------------------------------+
Note that the data store, flavor ID, and volume size have the same
values as in the original ``guest1`` instance.
Use the :command:`trove database-list` command to check that the original
databases (``db1`` and ``db2``) are present on the restored instance.
.. code-block:: console
$ trove database-list INSTANCE_ID
+--------------------+
| name |
+--------------------+
| db1 |
| db2 |
| performance_schema |
| test |
+--------------------+
Use the :command:`trove user-list` command to check that the original user
(``user1``) is present on the restored instance.
.. code-block:: console
$ trove user-list INSTANCE_ID
+--------+------+-----------+
| name | host | databases |
+--------+------+-----------+
| user1 | % | db1, db2 |
+--------+------+-----------+
#. **Notify users**
Tell the users who were accessing the now-disabled ``guest1``
database instance that they can now access ``guest2``. Provide them
with ``guest2``'s name, IP address, and any other information they
might need. (You can get this information by using the
:command:`trove show` command.)
#. **Clean up**
At this point, you might want to delete the disabled ``guest1``
instance, by using the :command:`trove delete` command.
.. code-block:: console
$ trove delete INSTANCE_ID

52
doc/user-guide/source/cli-access-instance-through-a-console.rst
View File

@ -1,52 +0,0 @@
====================================
Access an instance through a console
====================================
VNC or SPICE is used to view the console output of an instance, regardless of
whether or not the console log has output. This allows relaying keyboard and
mouse activity to and from an instance.
There are three remote console access methods commonly used with
OpenStack:
novnc
An in-browser VNC client implemented using HTML5 Canvas and
WebSockets
spice
A complete in-browser client solution for interaction with
virtualized instances
xvpvnc
A Java client offering console access to an instance
Example:
To access an instance through a remote console, run the following
command:
.. code-block:: console
$ openstack console url show INSTANCE_NAME --xvpvnc
The command returns a URL from which you can access your instance:
.. code-block:: console
+--------+------------------------------------------------------------------------------+
| Type | Url |
+--------+------------------------------------------------------------------------------+
| xvpvnc | http://192.168.5.96:6081/console?token=c83ae3a3-15c4-4890-8d45-aefb494a8d6c |
+--------+------------------------------------------------------------------------------+
``--xvpvnc`` can be replaced by any of the above values as connection
types.
When using SPICE to view the console of an instance, a browser plugin
can be used directly on the instance page, or the
:command:`openstack console url show` command can be used with it, as well, by
returning a token-authenticated address, as in the example above.
For further information and comparisons (including security
considerations), see the `Security
Guide <https://docs.openstack.org/security-guide/compute.html>`__.

132
doc/user-guide/source/cli-ceilometer.rst
View File

@ -1,132 +0,0 @@
=======================
Measure cloud resources
=======================
Telemetry measures cloud resources in OpenStack. It collects data
related to billing. Currently, this metering service is available
through only the :command:`ceilometer` command-line client.
To model data, Telemetry uses the following abstractions:
Meter
Measures a specific aspect of resource usage,
such as the existence of a running instance, or
ongoing performance, such as the CPU utilization
for an instance. Meters exist for each type of
resource. For example, a separate ``cpu_util``
meter exists for each instance. The lifecycle
of a meter is decoupled from the existence of
its related resource. The meter persists after
the resource goes away.
A meter has the following attributes:
* String name
* A unit of measurement
* A type, which indicates whether values increase
monotonically (cumulative), are interpreted as
a change from the previous value (delta), or are
stand-alone and relate only to the current duration (gauge)
Sample
An individual data point that is associated with a specific meter.
A sample has the same attributes as the associated meter, with
the addition of time stamp and value attributes. The value attribute
is also known as the sample ``volume``.
Statistic
A set of data point aggregates over a time duration. (In contrast,
a sample represents a single data point.) The Telemetry service
employs the following aggregation functions:
* **count**. The number of samples in each period.
* **max**. The maximum number of sample volumes in each period.
* **min**. The minimum number of sample volumes in each period.
* **avg**. The average of sample volumes over each period.
* **sum**. The sum of sample volumes over each period.
Alarm
A set of rules that define a monitor and a current state, with
edge-triggered actions associated with target states.
Alarms provide user-oriented Monitoring-as-a-Service and a
general purpose utility for OpenStack. Orchestration auto
scaling is a typical use case. Alarms follow a tristate
model of ``ok``, ``alarm``, and ``insufficient data``.
For conventional threshold-oriented alarms, a static
threshold value and comparison operator govern state transitions.
The comparison operator compares a selected meter statistic against
an evaluation window of configurable length into the recent past.
This example uses the :command:`openstack` client to create an auto-scaling
stack and the :command:`ceilometer` client to measure resources.
#. Create an auto-scaling stack by running the following command.
The ``-f`` option specifies the name of the stack template
file, and the ``-P`` option specifies the ``KeyName``
parameter as ``heat_key``:
.. code-block:: console
$ openstack stack create --template cfn/F17/AutoScalingCeilometer.yaml \
--parameter "KeyName=heat_key" mystack
#. List the heat resources that were created:
.. code-block:: console
$ openstack stack resource list mystack
+---------------+--------------------------------------+------------------+-----------------+---------------------+
| resource_name | physical_resource_id | resource_type | resource_status | updated_time |
+---------------+--------------------------------------+------------------+-----------------+---------------------+
| server | 1b3a7c13-42be-4999-a2a1-8fbefd00062b | OS::Nova::Server | CREATE_COMPLETE | 2013-10-02T05:53:41Z |
| ... | ... | ... | ... | ... |
+---------------+--------------------------------------+------------------+-----------------+---------------------+
#. List the alarms that are set:
.. code-block:: console
$ ceilometer alarm-list
+--------------------------------------+------------------------------+-------------------+---------+------------+----------------------------------+
| Alarm ID | Name | State | Enabled | Continuous | Alarm condition |
+--------------------------------------+------------------------------+-------------------+---------+------------+----------------------------------+
| 4f896b40-0859-460b-9c6a-b0d329814496 | as-CPUAlarmLow-i6qqgkf2fubs | insufficient data | True | False | cpu_util &lt; 15.0 during 1x 60s |
| 75d8ecf7-afc5-4bdc-95ff-19ed9ba22920 | as-CPUAlarmHigh-sf4muyfruy5m | insufficient data | True | False | cpu_util &gt; 50.0 during 1x 60s |
+--------------------------------------+------------------------------+-------------------+---------+------------+----------------------------------+
#. List the meters that are set:
.. code-block:: console
$ ceilometer meter-list
+-------------+------------+----------+--------------------------------------+----------------------------------+----------------------------------+
| Name | Type | Unit | Resource ID | User ID | Project ID |
+-------------+------------+----------+--------------------------------------+----------------------------------+----------------------------------+
| cpu | cumulative | ns | 3965b41b-81b0-4386-bea5-6ec37c8841c1 | d1a2996d3b1f4e0e8645ba9650308011 | bf03bf32e3884d489004ac995ff7a61c |
| cpu | cumulative | ns | 62520a83-73c7-4084-be54-275fe770ef2c | d1a2996d3b1f4e0e8645ba9650308011 | bf03bf32e3884d489004ac995ff7a61c |
| cpu_util | gauge | % | 3965b41b-81b0-4386-bea5-6ec37c8841c1 | d1a2996d3b1f4e0e8645ba9650308011 | bf03bf32e3884d489004ac995ff7a61c |
+-------------+------------+----------+--------------------------------------+----------------------------------+----------------------------------+
#. List samples:
.. code-block:: console
$ ceilometer sample-list -m cpu_util
+--------------------------------------+----------+-------+---------------+------+---------------------+
| Resource ID | Name | Type | Volume | Unit | Timestamp |
+--------------------------------------+----------+-------+---------------+------+---------------------+
| 3965b41b-81b0-4386-bea5-6ec37c8841c1 | cpu_util | gauge | 3.98333333333 | % | 2013-10-02T10:50:12 |
+--------------------------------------+----------+-------+---------------+------+---------------------+
#. View statistics:
.. code-block:: console
$ ceilometer statistics -m cpu_util
+--------+---------------------+---------------------+-------+---------------+---------------+---------------+---------------+----------+---------------------+---------------------+
| Period | Period Start | Period End | Count | Min | Max | Sum | Avg | Duration | Duration Start | Duration End |
+--------+---------------------+---------------------+-------+---------------+---------------+---------------+---------------+----------+---------------------+---------------------+
| 0 | 2013-10-02T10:50:12 | 2013-10-02T10:50:12 | 1 | 3.98333333333 | 3.98333333333 | 3.98333333333 | 3.98333333333 | 0.0 | 2013-10-02T10:50:12 | 2013-10-02T10:50:12 |
+--------+---------------------+---------------------+-------+---------------+---------------+---------------+---------------+----------+---------------------+---------------------+

120
doc/user-guide/source/cli-change-the-size-of-your-server.rst
View File

@ -1,120 +0,0 @@
==============================
Change the size of your server
==============================
Change the size of a server by changing its flavor.
#. Show information about your server, including its size, which is shown
as the value of the flavor property:
.. code-block:: console
$ openstack server show myCirrosServer
+--------------------------------------+----------------------------------------------------------+
| Field | Value |
+--------------------------------------+----------------------------------------------------------+
| OS-DCF:diskConfig | AUTO |
| OS-EXT-AZ:availability_zone | nova |
| OS-EXT-SRV-ATTR:host | node-7.domain.tld |
| OS-EXT-SRV-ATTR:hypervisor_hostname | node-7.domain.tld |
| OS-EXT-SRV-ATTR:instance_name | instance-000000f3 |
| OS-EXT-STS:power_state | 1 |
| OS-EXT-STS:task_state | None |
| OS-EXT-STS:vm_state | active |
| OS-SRV-USG:launched_at | 2016-10-26T01:13:15.000000 |
| OS-SRV-USG:terminated_at | None |
| accessIPv4 | |
| accessIPv6 | |
| addresses | admin_internal_net=192.168.111.139 |
| config_drive | True |
| created | 2016-10-26T01:12:38Z |
| flavor | m1.small (2) |
| hostId | d815539ce1a8fad3d597c3438c13f1229d3a2ed66d1a75447845a2f3 |
| id | 67bc9a9a-5928-47c4-852c-3631fef2a7e8 |
| image | cirros-test (dc5ec4b8-5851-4be8-98aa-df7a9b8f538f) |
| key_name | None |
| name | myCirrosServer |
| os-extended-volumes:volumes_attached | [] |
| progress | 0 |
| project_id | c08367f25666480f9860c6a0122dfcc4 |
| properties | |
| security_groups | [{u'name': u'default'}] |
| status | ACTIVE |
| updated | 2016-10-26T01:13:00Z |
| user_id | 0209430e30924bf9b5d8869990234e44 |
+--------------------------------------+----------------------------------------------------------+
The size (flavor) of the server is ``m1.small (2)``.
#. List the available flavors with the following command:
.. 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 |
+-----+-----------+-------+------+-----------+-------+-----------+
#. To resize the server, use the :command:`openstack server resize` command and
add the server ID or name and the new flavor. For example:
.. code-block:: console
$ openstack server resize --flavor 4 myCirrosServer
.. note::
By default, the :command:`openstack server resize` command gives
the guest operating
system a chance to perform a controlled shutdown before the instance
is powered off and the instance is resized.
The shutdown behavior is configured by the
``shutdown_timeout`` parameter that can be set in the
``nova.conf`` file. Its value stands for the overall
period (in seconds) a guest operating system is allowed
to complete the shutdown. The default timeout is 60 seconds.
See `Description of Compute configuration options
<https://docs.openstack.org/ocata/config-reference/compute/config-options.html>`_
for details.
The timeout value can be overridden on a per image basis
by means of ``os_shutdown_timeout`` that is an image metadata
setting allowing different types of operating systems to specify
how much time they need to shut down cleanly.
#. Show the status for your server.
.. code-block:: console
$ openstack server list
+----------------------+----------------+--------+-----------------------------------------+
| ID | Name | Status | Networks |
+----------------------+----------------+--------+-----------------------------------------+
| 67bc9a9a-5928-47c... | myCirrosServer | RESIZE | admin_internal_net=192.168.111.139 |
+----------------------+----------------+--------+-----------------------------------------+
When the resize completes, the status becomes VERIFY\_RESIZE.
#. Confirm the resize,for example:
.. code-block:: console
$ openstack server resize --confirm 67bc9a9a-5928-47c4-852c-3631fef2a7e8
The server status becomes ACTIVE.
#. If the resize fails or does not work as expected, you can revert the
resize. For example:
.. code-block:: console
$ openstack server resize --revert 67bc9a9a-5928-47c4-852c-3631fef2a7e8
The server status becomes ACTIVE.

400
doc/user-guide/source/cli-cheat-sheet.rst
View File

@ -1,400 +0,0 @@
============================================
OpenStack command-line interface cheat sheet
============================================
Here is a list of common commands for reference.
Identity (keystone)
~~~~~~~~~~~~~~~~~~~
List all users
.. code-block:: console
$ openstack user list
List Identity service catalog
.. code-block:: console
$ openstack catalog list
Images (glance)
~~~~~~~~~~~~~~~
List images you can access
.. code-block:: console
$ openstack image list
Delete specified image
.. code-block:: console
$ openstack image delete IMAGE
Describe a specific image
.. code-block:: console
$ openstack image show IMAGE
Update image
.. code-block:: console
$ openstack image set IMAGE
Upload kernel image
.. code-block:: console
$ openstack image create "cirros-threepart-kernel" \
--disk-format aki --container-format aki --public \
--file ~/images/cirros-0.3.5-x86_64-kernel
Upload RAM image
.. code-block:: console
$ openstack image create "cirros-threepart-ramdisk" \
--disk-format ari --container-format ari --public \
--file ~/images/cirros-0.3.5-x86_64-initramfs
Upload three-part image
.. code-block:: console
$ openstack image create "cirros-threepart" --disk-format ami \
--container-format ami --public \
--property kernel_id=$KID-property ramdisk_id=$RID \
--file ~/images/cirros-0.3.5-x86_64-rootfs.img
Register raw image
.. code-block:: console
$ openstack image create "cirros-raw" --disk-format raw \
--container-format bare --public \
--file ~/images/cirros-0.3.5-x86_64-disk.img
Compute (nova)
~~~~~~~~~~~~~~
List instances, check status of instance
.. code-block:: console
$ openstack server list
List images
.. code-block:: console
$ openstack image list
Create a flavor named m1.tiny
.. code-block:: console
$ openstack flavor create --ram 512 --disk 1 --vcpus 1 m1.tiny
List flavors
.. code-block:: console
$ openstack flavor list
Boot an instance using flavor and image names (if names are unique)
.. code-block:: console
$ openstack server create --image IMAGE --flavor FLAVOR INSTANCE_NAME
$ openstack server create --image cirros-0.3.5-x86_64-uec --flavor m1.tiny \
MyFirstInstance
Log in to the instance (from Linux)
.. note::
The :command:`ip` command is available only on Linux. Using :command:`ip netns` provides your
environment a copy of the network stack with its own routes, firewall
rules, and network devices for better troubleshooting.
.. code-block:: console
# ip netns
# ip netns exec NETNS_NAME ssh USER@SERVER
# ip netns exec qdhcp-6021a3b4-8587-4f9c-8064-0103885dfba2 \
ssh cirros@10.0.0.2
.. note::
In CirrOS, the password for user ``cirros`` is ``cubswin:)``.
For any other operating system, use SSH keys.
Log in to the instance with a public IP address (from Mac)
.. code-block:: console
$ ssh cloud-user@128.107.37.150
Show details of instance
.. code-block:: console
$ openstack server show NAME
$ openstack server show MyFirstInstance
View console log of instance
.. code-block:: console
$ openstack console log show MyFirstInstance
Set metadata on an instance
.. code-block:: console
$ nova meta volumeTwoImage set newmeta='my meta data'
Create an instance snapshot
.. code-block:: console
$ openstack image create volumeTwoImage snapshotOfVolumeImage
$ openstack image show snapshotOfVolumeImage
Pause, suspend, stop, rescue, resize, rebuild, reboot an instance
-----------------------------------------------------------------
Pause
.. code-block:: console
$ openstack server pause NAME
$ openstack server pause volumeTwoImage
Unpause
.. code-block:: console
$ openstack server unpause NAME
Suspend
.. code-block:: console
$ openstack server suspend NAME
Unsuspend
.. code-block:: console
$ openstack server resume NAME
Stop
.. code-block:: console
$ openstack server stop NAME
Start
.. code-block:: console
$ openstack server start NAME
Rescue
.. code-block:: console
$ openstack server rescue NAME
$ openstack server rescue NAME --rescue_image_ref RESCUE_IMAGE
Resize
.. code-block:: console
$ openstack server resize NAME FLAVOR
$ openstack server resize my-pem-server m1.small
$ openstack server resize --confirm my-pem-server1
Rebuild
.. code-block:: console
$ openstack server rebuild NAME IMAGE
$ openstack server rebuild newtinny cirros-qcow2
Reboot
.. code-block:: console
$ openstack server reboot NAME
$ openstack server reboot newtinny
Inject user data and files into an instance
.. code-block:: console
$ openstack server create --user-data FILE INSTANCE
$ openstack server create --user-data userdata.txt --image cirros-qcow2 \
--flavor m1.tiny MyUserdataInstance2
To validate that the file was injected, use ssh to connect to the instance,
and look in ``/var/lib/cloud`` for the file.
Inject a keypair into an instance and access the instance with that
keypair
Create keypair
.. code-block:: console
$ openstack keypair create test > test.pem
$ chmod 600 test.pem
Start an instance (boot)
.. code-block:: console
$ openstack server create --image cirros-0.3.5-x86_64 --flavor m1.small \
--key-name test MyFirstServer
Use ssh to connect to the instance
.. code-block:: console
# ip netns exec qdhcp-98f09f1e-64c4-4301-a897-5067ee6d544f \
ssh -i test.pem cirros@10.0.0.4
Manage security groups
Add rules to default security group allowing ping and SSH between
instances in the default security group
.. code-block:: console
$ openstack security group rule create default \
--remote-group default --protocol icmp
$ openstack security group rule create default \
--remote-group default --dst-port 22
Networking (neutron)
~~~~~~~~~~~~~~~~~~~~
Create network
.. code-block:: console
$ openstack network create NETWORK_NAME
Create a subnet
.. code-block:: console
$ openstack subnet create --subnet-pool SUBNET --network NETWORK SUBNET_NAME
$ openstack subnet create --subnet-pool 10.0.0.0/29 --network net1 subnet1
Block Storage (cinder)
~~~~~~~~~~~~~~~~~~~~~~
Used to manage volumes and volume snapshots that attach to instances.
Create a new volume
.. code-block:: console
$ openstack volume create --size SIZE_IN_GB NAME
$ openstack volume create --size 1 MyFirstVolume
Boot an instance and attach to volume
.. code-block:: console
$ openstack server create --image cirros-qcow2 --flavor m1.tiny MyVolumeInstance
List all volumes, noticing the volume status
.. code-block:: console
$ openstack volume list
Attach a volume to an instance after the instance is active, and the
volume is available
.. code-block:: console
$ openstack server add volume INSTANCE_ID VOLUME_ID
$ openstack server add volume MyVolumeInstance 573e024d-5235-49ce-8332-be1576d323f8
.. note::
On the Xen Hypervisor it is possible to provide a specific device name instead of
automatic allocation. For example:
.. code-block:: console
$ openstack server add volume --device /dev/vdb MyVolumeInstance 573e024d..1576d323f8
This is not currently possible when using non-Xen hypervisors with OpenStack.
Manage volumes after login into the instance
List storage devices
.. code-block:: console
# fdisk -l
Make filesystem on volume
.. code-block:: console
# mkfs.ext3 /dev/vdb
Create a mountpoint
.. code-block:: console
# mkdir /myspace
Mount the volume at the mountpoint
.. code-block:: console
# mount /dev/vdb /myspace
Create a file on the volume
.. code-block:: console
# touch /myspace/helloworld.txt
# ls /myspace
Unmount the volume
.. code-block:: console
# umount /myspace
Object Storage (swift)
~~~~~~~~~~~~~~~~~~~~~~
Display information for the account, container, or object
.. code-block:: console
$ swift stat
$ swift stat ACCOUNT
$ swift stat CONTAINER
$ swift stat OBJECT
List containers
.. code-block:: console
$ swift list

315
doc/user-guide/source/cli-config-drive.rst
View File

@ -1,315 +0,0 @@
=======================================
Store metadata on a configuration drive
=======================================
You can configure OpenStack to write metadata to a special configuration drive
that attaches to the instance when it boots. The instance can mount this drive
and read files from it to get information that is normally available through
the `metadata service <https://docs.openstack.org/admin-guide/compute-networking-nova.html#metadata-service>`__.
This metadata is different from the user data.
One use case for using the configuration drive is to pass a networking
configuration when you do not use DHCP to assign IP addresses to
instances. For example, you might pass the IP address configuration for
the instance through the configuration drive, which the instance can
mount and access before you configure the network settings for the
instance.
Any modern guest operating system that is capable of mounting an ISO
9660 or VFAT file system can use the configuration drive.
Requirements and guidelines
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To use the configuration drive, you must follow the following
requirements for the compute host and image.
**Compute host requirements**
- The following hypervisors support the configuration drive: libvirt,
XenServer, Hyper-V, and VMware.
Also, the Bare Metal service supports the configuration drive.
- To use configuration drive with libvirt, XenServer, or VMware, you
must first install the genisoimage package on each compute host.
Otherwise, instances do not boot properly.
Use the ``mkisofs_cmd`` flag to set the path where you install the
genisoimage program. If genisoimage is in same path as the
``nova-compute`` service, you do not need to set this flag.
- To use configuration drive with Hyper-V, you must set the
``mkisofs_cmd`` value to the full path to an ``mkisofs.exe``
installation. Additionally, you must set the ``qemu_img_cmd`` value
in the ``hyperv`` configuration section to the full path to an
:command:`qemu-img` command installation.
- To use configuration drive with the Bare Metal service,
you do not need to prepare anything because the Bare Metal
service treats the configuration drive properly.
**Image requirements**
- An image built with a recent version of the cloud-init package can
automatically access metadata passed through the configuration drive.
The following table lists the references for cloud-init versions mapped
to a particular operating system:
.. list-table::
:widths: 50 50
:header-rows: 1
* - Operating system
- Reference for cloud-init version
* - Ubuntu
- http://packages.ubuntu.com/search?keywords=cloud-init
* - Fedora (RHEL)
- https://www.rpmfind.net/linux/rpm2html/search.php?query=cloud-init
* - openSUSE (SLE)
- http://software.opensuse.org/download.html?project=Cloud%3ATools&package=cloud-init
- If an image does not have the cloud-init package installed, you must
customize the image to run a script that mounts the configuration
drive on boot, reads the data from the drive, and takes appropriate
action such as adding the public key to an account. You can read more
details about how data is organized on the configuration drive.
- If you use Xen with a configuration drive, use the
``xenapi_disable_agent`` configuration parameter to disable the
agent.
**Guidelines**
- Do not rely on the presence of the EC2 metadata in the configuration
drive, because this content might be removed in a future release. For
example, do not rely on files in the ``ec2`` directory.
- When you create images that access configuration drive data and
multiple directories are under the ``openstack`` directory, always
select the highest API version by date that your consumer supports.
For example, if your guest image supports the 2012-03-05, 2012-08-05,
and 2013-04-13 versions, try 2013-04-13 first and fall back to a
previous version if 2013-04-13 is not present.
Enable and access the configuration drive
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. To enable the configuration drive, pass the ``--config-drive true``
parameter to the :command:`openstack server create` command.
The following example enables the configuration drive and passes user
data, two files, and two key/value metadata pairs, all of which are
accessible from the configuration drive:
.. code-block:: console
$ openstack server create --config-drive true --image my-image-name \
--flavor 1 --key-name mykey --user-data ./my-user-data.txt \
--file /etc/network/interfaces=/home/myuser/instance-interfaces \
--file known_hosts=/home/myuser/.ssh/known_hosts \
--property role=webservers --property essential=false MYINSTANCE
You can also configure the Compute service to always create a
configuration drive by setting the following option in the
``/etc/nova/nova.conf`` file:
.. code-block:: console
force_config_drive = true
.. note::
If a user passes the ``--config-drive true`` flag to the :command:`nova
boot` command, an administrator cannot disable the configuration
drive.
#. If your guest operating system supports accessing disk by label, you
can mount the configuration drive as the
``/dev/disk/by-label/configurationDriveVolumeLabel`` device. In the
following example, the configuration drive has the ``config-2``
volume label:
.. code-block:: console
# mkdir -p /mnt/config
# mount /dev/disk/by-label/config-2 /mnt/config
.. note::
Ensure that you use at least version 0.3.1 of CirrOS for
configuration drive support.
If your guest operating system does not use ``udev``, the
``/dev/disk/by-label`` directory is not present.
You can use the :command:`blkid` command to identify the block device that
corresponds to the configuration drive. For example, when you boot
the CirrOS image with the ``m1.tiny`` flavor, the device is
``/dev/vdb``:
.. code-block:: console
# blkid -t LABEL="config-2" -odevice
.. code-block:: console
/dev/vdb
Once identified, you can mount the device:
.. code-block:: console
# mkdir -p /mnt/config
# mount /dev/vdb /mnt/config
Configuration drive contents
----------------------------
In this example, the contents of the configuration drive are as follows::
ec2/2009-04-04/meta-data.json
ec2/2009-04-04/user-data
ec2/latest/meta-data.json
ec2/latest/user-data
openstack/2012-08-10/meta_data.json
openstack/2012-08-10/user_data
openstack/content
openstack/content/0000
openstack/content/0001
openstack/latest/meta_data.json
openstack/latest/user_data
The files that appear on the configuration drive depend on the arguments
that you pass to the :command:`openstack server create` command.
OpenStack metadata format
-------------------------
The following example shows the contents of the
``openstack/2012-08-10/meta_data.json`` and
``openstack/latest/meta_data.json`` files. These files are identical.
The file contents are formatted for readability.
.. code-block:: json
{
"availability_zone": "nova",
"files": [
{
"content_path": "/content/0000",
"path": "/etc/network/interfaces"
},
{
"content_path": "/content/0001",
"path": "known_hosts"
}
],
"hostname": "test.novalocal",
"launch_index": 0,
"name": "test",
"meta": {
"role": "webservers",
"essential": "false"
},
"public_keys": {
"mykey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
},
"uuid": "83679162-1378-4288-a2d4-70e13ec132aa"
}
Note the effect of the
``--file /etc/network/interfaces=/home/myuser/instance-interfaces``
argument that was passed to the :command:`openstack server create` command.
The contents of this file are contained in the ``openstack/content/0000``
file on the configuration drive, and the path is specified as
``/etc/network/interfaces`` in the ``meta_data.json`` file.
EC2 metadata format
-------------------
The following example shows the contents of the
``ec2/2009-04-04/meta-data.json`` and the ``ec2/latest/meta-data.json``
files. These files are identical. The file contents are formatted to
improve readability.
.. code-block:: json
{
"ami-id": "ami-00000001",
"ami-launch-index": 0,
"ami-manifest-path": "FIXME",
"block-device-mapping": {
"ami": "sda1",
"ephemeral0": "sda2",
"root": "/dev/sda1",
"swap": "sda3"
},
"hostname": "test.novalocal",
"instance-action": "none",
"instance-id": "i-00000001",
"instance-type": "m1.tiny",
"kernel-id": "aki-00000002",
"local-hostname": "test.novalocal",
"local-ipv4": null,
"placement": {
"availability-zone": "nova"
},
"public-hostname": "test.novalocal",
"public-ipv4": "",
"public-keys": {
"0": {
"openssh-key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
}
},
"ramdisk-id": "ari-00000003",
"reservation-id": "r-7lfps8wj",
"security-groups": [
"default"
]
}
User data
---------
The ``openstack/2012-08-10/user_data``, ``openstack/latest/user_data``,
``ec2/2009-04-04/user-data``, and ``ec2/latest/user-data`` file are
present only if the ``--user-data`` flag and the contents of the user
data file are passed to the :command:`openstack server create` command.
Configuration drive format
--------------------------
The default format of the configuration drive as an ISO 9660 file
system. To explicitly specify the ISO 9660 format, add the following
line to the ``/etc/nova/nova.conf`` file:
.. code-block:: console
config_drive_format=iso9660
By default, you cannot attach the configuration drive image as a CD
drive instead of as a disk drive. To attach a CD drive, add the
following line to the ``/etc/nova/nova.conf`` file:
.. code-block:: console
config_drive_cdrom=true
For legacy reasons, you can configure the configuration drive to use
VFAT format instead of ISO 9660. It is unlikely that you would require
VFAT format because ISO 9660 is widely supported across operating
systems. However, to use the VFAT format, add the following line to the
``/etc/nova/nova.conf`` file:
.. code-block:: console
config_drive_format=vfat
If you choose VFAT, the configuration drive is 64 MB.
.. note::
In current version (Liberty) of OpenStack Compute, live migration with
``config_drive`` on local disk is forbidden due to the bug in libvirt
of copying a read-only disk. However, if we use VFAT as the format of
``config_drive``, the function of live migration works well.

313
doc/user-guide/source/cli-create-and-manage-networks.rst
View File

@ -1,313 +0,0 @@
==========================
Create and manage networks
==========================
Before you run commands, `set environment variables using the OpenStack RC file
<https://docs.openstack.org/user-guide/common/cli-set-environment-variables-using-openstack-rc.html>`_.
Create networks
~~~~~~~~~~~~~~~
#. List the extensions of the system:
.. code-block:: console
$ openstack extension list -c Alias -c Name --network
+------------------------------------------+---------------------------+
| Name | Alias |
+------------------------------------------+---------------------------+
| Default Subnetpools | default-subnetpools |
| Network IP Availability | network-ip-availability |
| Auto Allocated Topology Services | auto-allocated-topology |
| Neutron L3 Configurable external gateway | ext-gw-mode |
| Address scope | address-scope |
| Neutron Extra Route | extraroute |
+------------------------------------------+---------------------------+
#. Create a network:
.. code-block:: console
$ openstack network create net1
Created a new network:
+---------------------------+--------------------------------------+
| Field | Value |
+---------------------------+--------------------------------------+
| admin_state_up | UP |
| availability_zone_hints | |
| availability_zones | |
| created_at | 2016-12-21T08:32:54Z |
| description | |
| headers | |
| id | 180620e3-9eae-4ba7-9739-c5847966e1f0 |
| ipv4_address_scope | None |
| ipv6_address_scope | None |
| mtu | 1450 |
| name | net1 |
| port_security_enabled | True |
| project_id | c961a8f6d3654657885226378ade8220 |
| provider:network_type | vxlan |
| provider:physical_network | None |
| provider:segmentation_id | 14 |
| revision_number | 3 |
| router:external | Internal |
| shared | False |
| status | ACTIVE |
| subnets | |
| tags | [] |
| updated_at | 2016-12-21T08:32:54Z |
+---------------------------+--------------------------------------+
.. note::
Some fields of the created network are invisible to non-admin users.
#. Create a network with specified provider network type.
.. code-block:: console
$ openstack network create net2 --provider-network-type vxlan
Created a new network:
+---------------------------+--------------------------------------+
| Field | Value |
+---------------------------+--------------------------------------+
| admin_state_up | UP |
| availability_zone_hints | |
| availability_zones | |
| created_at | 2016-12-21T08:33:34Z |
| description | |
| headers | |
| id | c0a563d5-ef7d-46b3-b30d-6b9d4138b6cf |
| ipv4_address_scope | None |
| ipv6_address_scope | None |
| mtu | 1450 |
| name | net2 |
| port_security_enabled | True |
| project_id | c961a8f6d3654657885226378ade8220 |
| provider:network_type | vxlan |
| provider:physical_network | None |
| provider:segmentation_id | 87 |
| revision_number | 3 |
| router:external | Internal |
| shared | False |
| status | ACTIVE |
| subnets | |
| tags | [] |
| updated_at | 2016-12-21T08:33:34Z |
+---------------------------+--------------------------------------+
Create subnets
~~~~~~~~~~~~~~
Create a subnet:
.. code-block:: console
$ openstack subnet create subnet1 --network net1
--subnet-range 192.0.2.0/24
+-------------------+--------------------------------------+
| Field | Value |
+-------------------+--------------------------------------+
| allocation_pools | 192.0.2.2-192.0.2.254 |
| cidr | 192.0.2.0/24 |
| created_at | 2016-12-22T18:47:52Z |
| description | |
| dns_nameservers | |
| enable_dhcp | True |
| gateway_ip | 192.0.2.1 |
| headers | |
| host_routes | |
| id | a394689c-f547-4834-9778-3e0bb22130dc |
| ip_version | 4 |
| ipv6_address_mode | None |
| ipv6_ra_mode | None |
| name | subnet1 |
| network_id | 180620e3-9eae-4ba7-9739-c5847966e1f0 |
| project_id | c961a8f6d3654657885226378ade8220 |
| revision_number | 2 |
| service_types | |
| subnetpool_id | None |
| updated_at | 2016-12-22T18:47:52Z |
+-------------------+--------------------------------------+
The ``subnet-create`` command has the following positional and optional
parameters:
- The name or ID of the network to which the subnet belongs.
In this example, ``net1`` is a positional argument that specifies the
network name.
- The CIDR of the subnet.
In this example, ``192.0.2.0/24`` is a positional argument that
specifies the CIDR.
- The subnet name, which is optional.
In this example, ``--name subnet1`` specifies the name of the
subnet.
For information and examples on more advanced use of neutron's
``subnet`` subcommand, see the `OpenStack Administrator
Guide <https://docs.openstack.org/admin-guide/networking-use.html#advanced-networking-operations>`__.
Create routers
~~~~~~~~~~~~~~
#. Create a router:
.. code-block:: console
$ openstack router create router1
+-------------------------+--------------------------------------+
| Field | Value |
+-------------------------+--------------------------------------+
| admin_state_up | UP |
| availability_zone_hints | |
| availability_zones | |
| created_at | 2016-12-22T18:48:57Z |
| description | |
| distributed | True |
| external_gateway_info | null |
| flavor_id | None |
| ha | False |
| headers | |
| id | e25a24ee-3458-45c7-b16e-edf49092aab7 |
| name | router1 |
| project_id | e17431afc0524e0690484889a04b7fa0 |
| revision_number | 1 |
| routes | |
| status | ACTIVE |
| updated_at | 2016-12-22T18:48:57Z |
+-------------------------+--------------------------------------+
Take note of the unique router identifier returned, this will be
required in subsequent steps.
#. Link the router to the external provider network:
.. code-block:: console
$ openstack router set ROUTER --external-gateway NETWORK
Replace ROUTER with the unique identifier of the router, replace NETWORK
with the unique identifier of the external provider network.
#. Link the router to the subnet:
.. code-block:: console
$ openstack router add subnet ROUTER SUBNET
Replace ROUTER with the unique identifier of the router, replace SUBNET
with the unique identifier of the subnet.
Create ports
~~~~~~~~~~~~
#. Create a port with specified IP address:
.. code-block:: console
$ openstack port create --network net1 --fixed-ip subnet=subnet1,ip-address=192.0.2.40 port1
+-----------------------+-----------------------------------------+
| Field | Value |
+-----------------------+-----------------------------------------+
| admin_state_up | UP |
| allowed_address_pairs | |
| binding_host_id | |
| binding_profile | |
| binding_vif_details | |
| binding_vif_type | unbound |
| binding_vnic_type | normal |
| created_at | 2016-12-22T18:54:43Z |
| description | |
| device_id | |
| device_owner | |
| extra_dhcp_opts | |
| fixed_ips | ip_address='192.0.2.40', subnet_id='a |
| | 394689c-f547-4834-9778-3e0bb22130dc' |
| headers | |
| id | 031ddba8-3e3f-4c3c-ae26-7776905eb24f |
| mac_address | fa:16:3e:df:3d:c7 |
| name | port1 |
| network_id | 180620e3-9eae-4ba7-9739-c5847966e1f0 |
| port_security_enabled | True |
| project_id | c961a8f6d3654657885226378ade8220 |
| revision_number | 5 |
| security_groups | 84abb9eb-dc59-40c1-802c-4e173c345b6a |
| status | DOWN |
| updated_at | 2016-12-22T18:54:44Z |
+-----------------------+-----------------------------------------+
In the previous command, ``net1`` is the network name, which is a
positional argument. ``--fixed-ip subnet<subnet>,ip-address=192.0.2.40`` is
an option which specifies the port's fixed IP address we wanted.
.. note::
When creating a port, you can specify any unallocated IP in the
subnet even if the address is not in a pre-defined pool of allocated
IP addresses (set by your cloud provider).
#. Create a port without specified IP address:
.. code-block:: console
$ openstack port create port2 --network net1
+-----------------------+-----------------------------------------+
| Field | Value |
+-----------------------+-----------------------------------------+
| admin_state_up | UP |
| allowed_address_pairs | |
| binding_host_id | |
| binding_profile | |
| binding_vif_details | |
| binding_vif_type | unbound |
| binding_vnic_type | normal |
| created_at | 2016-12-22T18:56:06Z |
| description | |
| device_id | |
| device_owner | |
| extra_dhcp_opts | |
| fixed_ips | ip_address='192.0.2.10', subnet_id='a |
| | 394689c-f547-4834-9778-3e0bb22130dc' |
| headers | |
| id | eac47fcd-07ac-42dd-9993-5b36ac1f201b |
| mac_address | fa:16:3e:96:ae:6e |
| name | port2 |
| network_id | 180620e3-9eae-4ba7-9739-c5847966e1f0 |
| port_security_enabled | True |
| project_id | c961a8f6d3654657885226378ade8220 |
| revision_number | 5 |
| security_groups | 84abb9eb-dc59-40c1-802c-4e173c345b6a |
| status | DOWN |
| updated_at | 2016-12-22T18:56:06Z |
+-----------------------+-----------------------------------------+
.. note::
Note that the system allocates one IP address if you do not specify
an IP address in the :command:`openstack port create` command.
.. note::
You can specify a MAC address with ``--mac-address MAC_ADDRESS``.
If you specify an invalid MAC address, including ``00:00:00:00:00:00``
or ``ff:ff:ff:ff:ff:ff``, you will get an error.
#. Query ports with specified fixed IP addresses:
.. code-block:: console
$ neutron port-list --fixed-ips ip_address=192.0.2.2 \
ip_address=192.0.2.40
+----------------+------+-------------------+-------------------------------------------------+
| id | name | mac_address | fixed_ips |
+----------------+------+-------------------+-------------------------------------------------+
| baf13412-26... | | fa:16:3e:f6:ec:c7 | {"subnet_id"... ..."ip_address": "192.0.2.2"} |
| f7a08fe4-e7... | | fa:16:3e:97:e0:fc | {"subnet_id"... ..."ip_address": "192.0.2.40"} |
+----------------+------+-------------------+-------------------------------------------------+

157
doc/user-guide/source/cli-create-and-manage-stacks.rst
View File

@ -1,157 +0,0 @@
========================
Create and manage stacks
========================
The Orchestration service enables you to orchestrate multiple composite
cloud applications. This service supports use of both the Amazon Web
Services (AWS) CloudFormation template format through both a Query API
that is compatible with CloudFormation and the native OpenStack
:term:`Heat Orchestration Template (HOT)` format through a REST API.
These flexible template languages enable application developers to
describe and automate the deployment of infrastructure, services, and
applications. The templates enable creation of most OpenStack resource
types, such as instances, floating IP addresses, volumes, security
groups, and users. The resources, once created, are referred to as
stacks.
The template languages are described in the `Template
Guide <https://docs.openstack.org/developer/heat/template_guide/index.html>`__
in the `Heat developer
documentation <https://docs.openstack.org/developer/heat/>`__.
Create a stack from an example template file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- To create a stack, or template, from an `example template
file <https://git.openstack.org/cgit/openstack/heat-templates>`__, run
the following command:
.. code-block:: console
$ openstack stack create --template server_console.yaml \
--parameter "image=cirros" MYSTACK
The ``--parameter`` values that you specify depend on the parameters
that are defined in the template. If a website hosts the template
file, you can also specify the URL with the ``--template`` parameter.
The command returns the following output:
.. code-block:: console
+---------------------+----------------------------------------------------------------+
| Field | Value |
+---------------------+----------------------------------------------------------------+
| id | 70b9feca-8f99-418e-b2f1-cc38d61b3ffb |
| stack_name | MYSTACK |
| description | The heat template is used to demo the 'console_urls' attribute |
| | of OS::Nova::Server. |
| | |
| creation_time | 2016-06-08T09:54:15 |
| updated_time | None |
| stack_status | CREATE_IN_PROGRESS |
| stack_status_reason | |
+---------------------+----------------------------------------------------------------+
- You can also use the ``--dry-run`` option with the
:command:`openstack stack create` command to validate a
template file without creating a stack from it.
If validation fails, the response returns an error message.
Get information about stacks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To explore the state and history of a particular stack, you can run a
number of commands.
- To see which stacks are visible to the current user, run the
following command:
.. code-block:: console
$ openstack stack list
+--------------------------------------+------------+-----------------+---------------------+--------------+
| ID | Stack Name | Stack Status | Creation Time | Updated Time |
+--------------------------------------+------------+-----------------+---------------------+--------------+
| 70b9feca-8f99-418e-b2f1-cc38d61b3ffb | MYSTACK | CREATE_COMPLETE | 2016-06-08T09:54:15 | None |
+--------------------------------------+------------+-----------------+---------------------+--------------+
- To show the details of a stack, run the following command:
.. code-block:: console
$ openstack stack show MYSTACK
- A stack consists of a collection of resources. To list the resources
and their status, run the following command:
.. code-block:: console
$ openstack stack resource list MYSTACK
+---------------+--------------------------------------+------------------+-----------------+---------------------+
| resource_name | physical_resource_id | resource_type | resource_status | updated_time |
+---------------+--------------------------------------+------------------+-----------------+---------------------+
| server | 1b3a7c13-42be-4999-a2a1-8fbefd00062b | OS::Nova::Server | CREATE_COMPLETE | 2016-06-08T09:54:15 |
+---------------+--------------------------------------+------------------+-----------------+---------------------+
- To show the details for a specific resource in a stack, run the
following command:
.. code-block:: console
$ openstack stack resource show MYSTACK server
- Some resources have associated metadata which can change throughout
the lifecycle of a resource. Show the metadata by running the
following command:
.. code-block:: console
$ openstack stack resource metadata MYSTACK server
- A series of events is generated during the lifecycle of a stack. To
display lifecycle events, run the following command:
.. code-block:: console
$ openstack stack event list MYSTACK
2016-06-08 09:54:15 [MYSTACK]: CREATE_IN_PROGRESS Stack CREATE started
2016-06-08 09:54:15 [server]: CREATE_IN_PROGRESS state changed
2016-06-08 09:54:41 [server]: CREATE_COMPLETE state changed
2016-06-08 09:54:41 [MYSTACK]: CREATE_COMPLETE Stack CREATE completed successfully
- To show the details for a particular event, run the following
command:
.. code-block:: console
$ openstack stack event show MYSTACK server EVENT
Update a stack
~~~~~~~~~~~~~~
To update an existing stack from a modified template file, run a command
like the following command:
.. code-block:: console
$ openstack stack update --template server_console.yaml \
--parameter "image=ubuntu" MYSTACK
+---------------------+----------------------------------------------------------------+
| Field | Value |
+---------------------+----------------------------------------------------------------+
| id | 267a459a-a8cd-4d3e-b5a1-8c08e945764f |
| stack_name | mystack |
| description | The heat template is used to demo the 'console_urls' attribute |
| | of OS::Nova::Server. |
| | |
| creation_time | 2016-06-08T09:54:15 |
| updated_time | 2016-06-08T10:41:18 |
| stack_status | UPDATE_IN_PROGRESS |
| stack_status_reason | Stack UPDATE started |
+---------------------+----------------------------------------------------------------+
Some resources are updated in-place, while others are replaced with new
resources.

43
doc/user-guide/source/cli-delete-an-instance.rst
View File

@ -1,43 +0,0 @@
==================
Delete an instance
==================
When you no longer need an instance, you can delete it.
#. List all instances:
.. code-block:: console
$ openstack server list
+-------------+----------------------+--------+------------+-------------+------------------+------------+
| 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 | ubuntu |
| d7efd3e4... | newServer | ERROR | None | NOSTATE | | centos |
+-------------+----------------------+--------+------------+-------------+------------------+------------+
#. Run the :command:`openstack server delete` command to delete the instance.
The following example shows deletion of the ``newServer`` instance, which
is in ``ERROR`` state:
.. code-block:: console
$ openstack server delete newServer
The command does not notify that your server was deleted.
#. To verify that the server was deleted, run the
:command:`openstack server list` command:
.. code-block:: console
$ openstack server list
+-------------+----------------------+--------+------------+-------------+------------------+------------+
| 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 | ubuntu |
+-------------+----------------------+--------+------------+-------------+------------------+------------+
The deleted instance does not appear in the list.

168
doc/user-guide/source/cli-launch-instances.rst
View File

@ -1,168 +0,0 @@
================
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:`cli-manage-ip-addresses`.
After you gather the parameters that you need to launch an instance,
you can launch it from an :doc:`image<cli-nova-launch-instance-from-image>`
or a :doc:`volume<cli-nova-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
cli-nova-launch-instance-from-image.rst
cli-nova-launch-instance-from-volume.rst
cli-nova-launch-instance-using-ISO-image.rst

176
doc/user-guide/source/cli-manage-bare-metal-nodes.rst
View File

@ -1,176 +0,0 @@
=======================
Manage bare-metal nodes
=======================
The bare-metal driver for OpenStack Compute manages provisioning of
physical hardware by using common cloud APIs and tools such as
Orchestration (Heat). The use case for this driver is for single project
clouds such as a high-performance computing cluster, or for deploying
OpenStack itself.
If you use the bare-metal driver, you must create a network interface
and add it to a bare-metal node. Then, you can launch an instance from a
bare-metal image.
You can list and delete bare-metal nodes. When you delete a node, any
associated network interfaces are removed. You can list and remove
network interfaces that are associated with a bare-metal node.
Commands
~~~~~~~~
The following commands can be used to manage bare-metal nodes.
``baremetal-interface-add``
Adds a network interface to a bare-metal node.
``baremetal-interface-list``
Lists network interfaces associated with a bare-metal node.
``baremetal-interface-remove``
Removes a network interface from a bare-metal node.
``baremetal-node-create``
Creates a bare-metal node.
``baremetal-node-delete``
Removes a bare-metal node and any associated interfaces.
``baremetal-node-list``
Lists available bare-metal nodes.
``baremetal-node-show``
Shows information about a bare-metal node.
Create a bare-metal node
~~~~~~~~~~~~~~~~~~~~~~~~
When you create a bare-metal node, your PM address, user name, and
password should match the information in your hardware's BIOS/IPMI
configuration.
.. code-block:: console
$ nova baremetal-node-create --pm_address PM_ADDRESS --pm_user PM_USERNAME \
--pm_password PM_PASSWORD $(hostname -f) 1 512 10 aa:bb:cc:dd:ee:ff
The following example shows the command and results from creating a node
with the PM address ``1.2.3.4``, the PM user name ipmi, and password
``ipmi``.
.. code-block:: console
$ nova baremetal-node-create --pm_address 1.2.3.4 --pm_user ipmi \
--pm_password ipmi $(hostname -f) 1 512 10 aa:bb:cc:dd:ee:ff
+------------------+-------------------+
| Property | Value |
+------------------+-------------------+
| instance_uuid | None |
| pm_address | 1.2.3.4 |
| interfaces | [] |
| prov_vlan_id | None |
| cpus | 1 |
| memory_mb | 512 |
| prov_mac_address | aa:bb:cc:dd:ee:ff |
| service_host | ubuntu |
| local_gb | 10 |
| id | 1 |
| pm_user | ipmi |
| terminal_port | None |
+------------------+-------------------+
Add a network interface to the node
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For each NIC on the node, you must create an interface, specifying the
interface's MAC address.
.. code-block:: console
$ nova baremetal-interface-add 1 aa:bb:cc:dd:ee:ff
+-------------+-------------------+
| Property | Value |
+-------------+-------------------+
| datapath_id | 0 |
| id | 1 |
| port_no | 0 |
| address | aa:bb:cc:dd:ee:ff |
+-------------+-------------------+
Launch an instance from a bare-metal image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A bare-metal instance is an instance created directly on a physical
machine, without any virtualization layer running underneath it. Nova
retains power control via IPMI. In some situations, Nova may retain
network control via Neutron and OpenFlow.
.. code-block:: console
$ openstack server create --image my-baremetal-image --flavor \
my-baremetal-flavor test
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | BUILD |
| id | cc302a8f-cd81-484b-89a8-b75eb3911b1b |
+-----------------------------+--------------------------------------+
... wait for instance to become active ...
.. note::
Set the ``--availability-zone`` parameter to specify which zone or
node to use to start the server. Separate the zone from the host
name with a comma. For example:
.. code-block:: console
$ openstack server create --availability-zone zone:HOST,NODE
``host`` is optional for the ``--availability-zone`` parameter. You
can simply specify ``zone:,node``, still including the comma.
List bare-metal nodes and interfaces
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :command:`nova baremetal-node-list` command to view all bare-metal
nodes and interfaces. When a node is in use, its status includes the
UUID of the instance that runs on it:
.. code-block:: console
$ nova baremetal-node-list
+----+--------+------+-----------+---------+-------------------+------+------------+-------------+-------------+---------------+
| ID | Host | CPUs | Memory_MB | Disk_GB | MAC Address | VLAN | PM Address | PM Username | PM Password | Terminal Port |
+----+--------+------+-----------+---------+-------------------+------+------------+-------------+-------------+---------------+
| 1 | ubuntu | 1 | 512 | 10 | aa:bb:cc:dd:ee:ff | None | 1.2.3.4 | ipmi | | None |
+----+--------+------+-----------+---------+-------------------+------+------------+-------------+-------------+---------------+
Show details for a bare-metal node
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the :command:`nova baremetal-node-show` command to view the details for a
bare-metal node:
.. code-block:: console
$ nova baremetal-node-show 1
+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
| instance_uuid | cc302a8f-cd81-484b-89a8-b75eb3911b1b |
| pm_address | 1.2.3.4 |
| interfaces | [{u'datapath_id': u'0', u'id': 1, |
| | u'port_no': 0, |
| | u'address': u'aa:bb:cc:dd:ee:ff'}] |
| prov_vlan_id | None |
| cpus | 1 |
| memory_mb | 512 |
| prov_mac_address | aa:bb:cc:dd:ee:ff |
| service_host | ubuntu |
| local_gb | 10 |
| id | 1 |
| pm_user | ipmi |
| terminal_port | None |
+------------------+--------------------------------------+

120
doc/user-guide/source/cli-manage-images-curl.rst
View File

@ -1,120 +0,0 @@
========================
Manage images using cURL
========================
This section is intended to provide a series of commands a typical
client of the API might use to create and modify an image.
These commands assume the implementation of the v2 Image API using
the Identity Service for authentication and authorization. The
X-Auth-Token header is used to provide the authentication token issued by
the Identity Service.
The strings ``$OS_IMAGE_URL`` and ``$OS_AUTH_TOKEN`` represent variables
defined in the client's environment. ``$OS_IMAGE_URL`` is the full path
to your image service endpoint, for example, ``http://example.com``.
``$OS_AUTH_TOKEN`` represents an auth token generated by the
Identity Service, for example, ``6583fb17c27b48b4b4a6033fe9cc0fe0``.
Create an image
~~~~~~~~~~~~~~~
.. code-block:: console
$ curl -i -X POST -H "X-Auth-Token: $OS_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Ubuntu 14.04", \
"tags": ["ubuntu", "14.04", "trusty"]}' \
$OS_IMAGE_URL/v2/images
HTTP/1.1 201 Created
Content-Length: 451
Content-Type: application/json; charset=UTF-8
Location: http://example.com:9292/v2/images
/7b97f37c-899d-44e8-aaa0-543edbc4eaad
Date: Fri, 11 Mar 2016 12:25:32 GMT
{
"id": "7b97f37c-899d-44e8-aaa0-543edbc4eaad",
"name": "Ubuntu 14.04",
"status": "queued",
"visibility": "private",
"protected": false,
"tags": ["ubuntu", "14.04", "trusty"],
"created_at": "2016-03-11T12:25:32Z",
"updated_at": "2016-03-11T12:25:32Z",
"file": "/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad/file",
"self": "/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad",
"schema": "/v2/schemas/image"
}
Update the image
~~~~~~~~~~~~~~~~
.. code-block:: console
$ curl -i -X PATCH -H "X-Auth-Token: $OS_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '[{"op": "add", "path": "/login-user", "value": "root"}]' \
$OS_IMAGE_URL/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad
HTTP/1.1 200 OK
Content-Length: 477
Content-Type: application/json; charset=UTF-8
Date: Fri, 11 Mar 2016 12:44:56 GMT
{
"id": "7b97f37c-899d-44e8-aaa0-543edbc4eaad",
"name": "Ubuntu 14.04",
"status": "queued",
"visibility": "private",
"protected": false,
"tags": ["ubuntu", "14.04", "trusty"],
"login_user": "root",
"created_at": "2016-03-11T12:25:32Z",
"updated_at": "2016-03-11T12:44:56Z",
"file": "/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad/file",
"self": "/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad",
"schema": "/v2/schemas/image"
}
Upload binary image data
~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: console
$ curl -i -X PUT -H "X-Auth-Token: $OS_AUTH_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @/home/glance/ubuntu-14.04.qcow2 \
$OS_IMAGE_URL/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad/file
HTTP/1.1 100 Continue
HTTP/1.1 201 Created
Content-Length: 0
Date: Fri, 11 Mar 2016 12:51:02 GMT
Download binary image data
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: console
$ curl -i -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" \
$OS_IMAGE_URL/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad/file
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Md5: 912ec803b2ce49e4a541068d495ab570
Transfer-Encoding: chunked
Date: Fri, 11 Mar 2016 12:57:41 GMT
Delete an image
~~~~~~~~~~~~~~~
.. code-block:: console
$ curl -i -X DELETE -H "X-Auth-Token: $OS_AUTH_TOKEN" \
$OS_IMAGE_URL/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad
HTTP/1.1 204 No Content
Content-Length: 0
Date: Fri, 11 Mar 2016 12:59:11 GMT

25
doc/user-guide/source/cli-manage-instances-hosts.rst
View File

@ -1,25 +0,0 @@
==========================
Manage instances and hosts
==========================
Instances are virtual machines that run inside the cloud on physical
compute nodes. The Compute service manages instances. A host is the node
on which a group of instances resides.
This section describes how to perform the different tasks involved in
instance management, such as adding floating IP addresses, stopping and
starting instances, and terminating instances. This section also
discusses node management tasks.
.. toctree::
:maxdepth: 2
cli-manage-ip-addresses.rst
cli-change-the-size-of-your-server.rst
cli-stop-and-start-an-instance.rst
cli-search-instance-with-ip-address.rst
cli-reboot-an-instance.rst
cli-delete-an-instance.rst
cli-access-instance-through-a-console.rst
cli-manage-bare-metal-nodes.rst

249
doc/user-guide/source/cli-manage-ip-addresses.rst
View File

@ -1,249 +0,0 @@
===================
Manage IP addresses
===================
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.
Create an external network
~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Create an external network named ``public``:
.. code-block:: console
$ openstack network create public --external
+---------------------------+--------------------------------------+
| Field | Value |
+---------------------------+--------------------------------------+
| admin_state_up | UP |
| availability_zone_hints | |
| availability_zones | |
| created_at | 2017-05-18T05:06:06Z |
| description | |
| dns_domain | None |
| id | 5a6c74b9-5659-4b9e-951e-85ffca212139 |
| ipv4_address_scope | None |
| ipv6_address_scope | None |
| is_default | False |
| mtu | 1450 |
| name | public |
| port_security_enabled | False |
| project_id | b3abf186ac64462e85741315376e9ca7 |
| provider:network_type | vxlan |
| provider:physical_network | None |
| provider:segmentation_id | 9 |
| qos_policy_id | None |
| revision_number | 3 |
| router:external | External |
| segments | None |
| shared | False |
| status | ACTIVE |
| subnets | |
| updated_at | 2017-05-18T05:06:06Z |
+---------------------------+--------------------------------------+
#. Create a subnet of the ``public`` external network:
.. code-block:: console
$ openstack subnet create --network public --subnet-range 172.24.4.0/24 public_subnet
+-------------------------+--------------------------------------+
| Field | Value |
+-------------------------+--------------------------------------+
| allocation_pools | 172.24.4.2-172.24.4.254 |
| cidr | 172.24.4.0/24 |
| created_at | 2017-05-18T05:16:46Z |
| description | |
| dns_nameservers | |
| enable_dhcp | True |
| gateway_ip | 172.24.4.1 |
| host_routes | |
| id | f61a73b3-6097-48ff-b7ef-98da203e6b18 |
| ip_version | 4 |
| ipv6_address_mode | None |
| ipv6_ra_mode | None |
| name | public_subnet |
| network_id | 5a6c74b9-5659-4b9e-951e-85ffca212139 |
| project_id | b3abf186ac64462e85741315376e9ca7 |
| revision_number | 2 |
| segment_id | None |
| service_types | |
| subnetpool_id | None |
| updated_at | 2017-05-18T05:16:46Z |
| use_default_subnet_pool | None |
+-------------------------+--------------------------------------+
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.
This command is only available in ``nova-network``. If you use the OpenStack
Networking service, run the following command to list external networks:
.. code-block:: console
$ openstack network list --external
+--------------------------------------+-------------+--------------------------------------+
| ID | Name | Subnets |
+--------------------------------------+-------------+--------------------------------------+
| 5a6c74b9-5659-4b9e-951e-85ffca212139 | public | f61a73b3-6097-48ff-b7ef-98da203e6b18 |
| 9839a22d-33b7-4173-9708-985f091bb892 | public1 | 19f1fbb4-f411-4465-8ed9-b641c7fc73d0 |
+--------------------------------------+-------------+--------------------------------------+
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 | 2017-03-30T12:35:25Z |
| description | |
| fixed_ip_address | None |
| floating_ip_address | 172.24.4.230 |
| floating_network_id | c213f520-aade-42eb-8bf1-6826505d74bb |
| id | 1e777f9e-4fc8-4df8-be6f-89f5caba3c0f |
| name | None |
| port_id | None |
| project_id | b3abf186ac64462e85741315376e9ca7 |
| revision_number | 1 |
| router_id | None |
| status | DOWN |
| updated_at | 2017-03-30T12:35:25Z |
+---------------------+--------------------------------------+
#. 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.

630
doc/user-guide/source/cli-manage-shares.rst
View File

@ -1,630 +0,0 @@
.. _share:
=============
Manage shares
=============
A share is provided by file storage. You can give access to a share to
instances. To create and manage shares, you use ``manila`` client commands.
Create a share network
~~~~~~~~~~~~~~~~~~~~~~
#. Create a share network.
.. code-block:: console
$ manila share-network-create \
--name mysharenetwork \
--description "My Manila network" \
--neutron-net-id dca0efc7-523d-43ef-9ded-af404a02b055 \
--neutron-subnet-id 29ecfbd5-a9be-467e-8b4a-3415d1f82888
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| name | mysharenetwork |
| segmentation_id | None |
| created_at | 2016-03-24T14:13:02.888816 |
| neutron_subnet_id | 29ecfbd5-a9be-467e-8b4a-3415d1f82888 |
| updated_at | None |
| network_type | None |
| neutron_net_id | dca0efc7-523d-43ef-9ded-af404a02b055 |
| ip_version | None |
| nova_net_id | None |
| cidr | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| description | My Manila network |
+-------------------+--------------------------------------+
#. List share networks.
.. code-block:: console
$ manila share-network-list
+--------------------------------------+----------------+
| id | name |
+--------------------------------------+----------------+
| c895fe26-92be-4152-9e6c-f2ad230efb13 | mysharenetwork |
+--------------------------------------+----------------+
Create a share
~~~~~~~~~~~~~~
#. Create a share.
.. code-block:: console
$ manila create NFS 1 \
--name myshare \
--description "My Manila share" \
--share-network mysharenetwork \
--share-type default
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | creating |
| share_type_name | default |
| description | My Manila share |
| availability_zone | None |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| share_server_id | None |
| host | |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 |
| size | 1 |
| name | myshare |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-24T14:15:34.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+--------------------------------------+
#. Show a share.
.. code-block:: console
$ manila show myshare
+-----------------------------+---------------------------------------------------------------+
| Property | Value |
+-----------------------------+---------------------------------------------------------------+
| status | available |
| share_type_name | default |
| description | My Manila share |
| availability_zone | nova |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| export_locations | |
| | path = 10.254.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | preferred = False |
| | is_admin_only = False |
| | id = b6bd76ce-12a2-42a9-a30a-8a43b503867d |
| | share_instance_id = e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | path = 10.0.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | preferred = False |
| | is_admin_only = True |
| | id = 6921e862-88bc-49a5-a2df-efeed9acd583 |
| | share_instance_id = e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 |
| host | nosb-devstack@london#LONDON |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 |
| size | 1 |
| name | myshare |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-24T14:15:34.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+---------------------------------------------------------------+
#. List shares.
.. code-block:: console
$ manila list
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+-----------------------------+-------------------+
| ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+-----------------------------+-------------------+
| 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 | myshare | 1 | NFS | available | False | default | nosb-devstack@london#LONDON | nova |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+-----------------------------+-------------------+
#. List share export locations.
.. code-block:: console
$ manila share-export-location-list myshare
+--------------------------------------+--------------------------------------------------------+-----------+
| ID | Path | Preferred |
+--------------------------------------+--------------------------------------------------------+-----------+
| 6921e862-88bc-49a5-a2df-efeed9acd583 | 10.0.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d | False |
| b6bd76ce-12a2-42a9-a30a-8a43b503867d | 10.254.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d | False |
+--------------------------------------+--------------------------------------------------------+-----------+
Allow read-write access
~~~~~~~~~~~~~~~~~~~~~~~
#. Allow access.
.. code-block:: console
$ manila access-allow myshare ip 10.0.0.0/24
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
| share_id | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 |
| access_type | ip |
| access_to | 10.0.0.0/24 |
| access_level | rw |
| state | new |
| id | 0c8470ca-0d77-490c-9e71-29e1f453bf97 |
+--------------+--------------------------------------+
#. List access.
.. code-block:: console
$ manila access-list myshare
+--------------------------------------+-------------+-------------+--------------+--------+
| id | access_type | access_to | access_level | state |
+--------------------------------------+-------------+-------------+--------------+--------+
| 0c8470ca-0d77-490c-9e71-29e1f453bf97 | ip | 10.0.0.0/24 | rw | active |
+--------------------------------------+-------------+-------------+--------------+--------+
The access is created.
Allow read-only access
~~~~~~~~~~~~~~~~~~~~~~
#. Allow access.
.. code-block:: console
$ manila access-allow myshare ip 20.0.0.0/24 --access-level ro
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
| share_id | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 |
| access_type | ip |
| access_to | 20.0.0.0/24 |
| access_level | ro |
| state | new |
| id | f151ad17-654d-40ce-ba5d-98a5df67aadc |
+--------------+--------------------------------------+
#. List access.
.. code-block:: console
$ manila access-list myshare
+--------------------------------------+-------------+-------------+--------------+--------+
| id | access_type | access_to | access_level | state |
+--------------------------------------+-------------+-------------+--------------+--------+
| 0c8470ca-0d77-490c-9e71-29e1f453bf97 | ip | 10.0.0.0/24 | rw | active |
| f151ad17-654d-40ce-ba5d-98a5df67aadc | ip | 20.0.0.0/24 | ro | active |
+--------------------------------------+-------------+-------------+--------------+--------+
The access is created.
Deny access
~~~~~~~~~~~
#. Deny access.
.. code-block:: console
$ manila access-deny myshare 0c8470ca-0d77-490c-9e71-29e1f453bf97
$ manila access-deny myshare f151ad17-654d-40ce-ba5d-98a5df67aadc
#. List access.
.. code-block:: console
$ manila access-list myshare
+----+-------------+-----------+--------------+-------+
| id | access type | access to | access level | state |
+----+-------------+-----------+--------------+-------+
+----+-------------+-----------+--------------+-------+
The access is removed.
Create snapshot
~~~~~~~~~~~~~~~
#. Create a snapshot.
.. code-block:: console
$ manila snapshot-create --name mysnapshot --description "My Manila snapshot" myshare
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| status | creating |
| share_id | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 |
| description | My Manila snapshot |
| created_at | 2016-03-24T14:39:58.232844 |
| share_proto | NFS |
| provider_location | None |
| id | e744ca47-0931-4e81-9d9f-2ead7d7c1640 |
| size | 1 |
| share_size | 1 |
| name | mysnapshot |
+-------------------+--------------------------------------+
#. List snapshots.
.. code-block:: console
$ manila snapshot-list
+--------------------------------------+--------------------------------------+-----------+------------+------------+
| ID | Share ID | Status | Name | Share Size |
+--------------------------------------+--------------------------------------+-----------+------------+------------+
| e744ca47-0931-4e81-9d9f-2ead7d7c1640 | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 | available | mysnapshot | 1 |
+--------------------------------------+--------------------------------------+-----------+------------+------------+
Create share from snapshot
~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Create a share from a snapshot.
.. code-block:: console
$ manila create NFS 1 \
--snapshot-id e744ca47-0931-4e81-9d9f-2ead7d7c1640 \
--share-network mysharenetwork \
--name mysharefromsnap
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | creating |
| share_type_name | default |
| description | None |
| availability_zone | nova |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| share_server_id | None |
| host | nosb-devstack@london#LONDON |
| access_rules_status | active |
| snapshot_id | e744ca47-0931-4e81-9d9f-2ead7d7c1640 |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | e73ebcd3-4764-44f0-9b42-fab5cf34a58b |
| size | 1 |
| name | mysharefromsnap |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-24T14:41:36.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+--------------------------------------+
#. List shares.
.. code-block:: console
$ manila list
+--------------------------------------+-----------------+------+-------------+-----------+-----------+-----------------+-----------------------------+-------------------+
| ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone |
+--------------------------------------+-----------------+------+-------------+-----------+-----------+-----------------+-----------------------------+-------------------+
| 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 | myshare | 1 | NFS | available | False | default | nosb-devstack@london#LONDON | nova |
| e73ebcd3-4764-44f0-9b42-fab5cf34a58b | mysharefromsnap | 1 | NFS | available | False | default | nosb-devstack@london#LONDON | nova |
+--------------------------------------+-----------------+------+-------------+-----------+-----------+-----------------+-----------------------------+-------------------+
#. Show the share created from snapshot.
.. code-block:: console
$ manila show mysharefromsnap
+-----------------------------+---------------------------------------------------------------+
| Property | Value |
+-----------------------------+---------------------------------------------------------------+
| status | available |
| share_type_name | default |
| description | None |
| availability_zone | nova |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| export_locations | |
| | path = 10.254.0.3:/share-4c00cb49-51d9-478e-abc1-d1853efaf6d3 |
| | preferred = False |
| | is_admin_only = False |
| | id = 5419fb40-04b9-4a52-b08e-19aa1ce13a5c |
| | share_instance_id = 4c00cb49-51d9-478e-abc1-d1853efaf6d3 |
| | path = 10.0.0.3:/share-4c00cb49-51d9-478e-abc1-d1853efaf6d3 |
| | preferred = False |
| | is_admin_only = True |
| | id = 26f55e4c-6edc-4e55-8c55-c62b7db1aa9f |
| | share_instance_id = 4c00cb49-51d9-478e-abc1-d1853efaf6d3 |
| share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 |
| host | nosb-devstack@london#LONDON |
| access_rules_status | active |
| snapshot_id | e744ca47-0931-4e81-9d9f-2ead7d7c1640 |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | e73ebcd3-4764-44f0-9b42-fab5cf34a58b |
| size | 1 |
| name | mysharefromsnap |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-24T14:41:36.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+---------------------------------------------------------------+
Delete share
~~~~~~~~~~~~
#. Delete a share.
.. code-block:: console
$ manila delete mysharefromsnap
#. List shares.
.. code-block:: console
$ manila list
+--------------------------------------+-----------------+------+-------------+-----------+-----------+-----------------+-----------------------------+-------------------+
| ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone |
+--------------------------------------+-----------------+------+-------------+-----------+-----------+-----------------+-----------------------------+-------------------+
| 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 | myshare | 1 | NFS | available | False | default | nosb-devstack@london#LONDON | nova |
| e73ebcd3-4764-44f0-9b42-fab5cf34a58b | mysharefromsnap | 1 | NFS | deleting | False | default | nosb-devstack@london#LONDON | nova |
+--------------------------------------+-----------------+------+-------------+-----------+-----------+-----------------+-----------------------------+-------------------+
The share is being deleted.
Delete snapshot
~~~~~~~~~~~~~~~
#. List snapshots before deleting.
.. code-block:: console
$ manila snapshot-list
+--------------------------------------+--------------------------------------+-----------+------------+------------+
| ID | Share ID | Status | Name | Share Size |
+--------------------------------------+--------------------------------------+-----------+------------+------------+
| e744ca47-0931-4e81-9d9f-2ead7d7c1640 | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 | available | mysnapshot | 1 |
+--------------------------------------+--------------------------------------+-----------+------------+------------+
#. Delete a snapshot.
.. code-block:: console
$ manila snapshot-delete mysnapshot
#. List snapshots after deleting.
.. code-block:: console
$ manila snapshot-list
+----+----------+--------+------+------------+
| ID | Share ID | Status | Name | Share Size |
+----+----------+--------+------+------------+
+----+----------+--------+------+------------+
The snapshot is deleted.
Extend share
~~~~~~~~~~~~
#. Extend share.
.. code-block:: console
$ manila extend myshare 2
#. Show the share while it is being extended.
.. code-block:: console
$ manila show myshare
+-----------------------------+---------------------------------------------------------------+
| Property | Value |
+-----------------------------+---------------------------------------------------------------+
| status | extending |
| share_type_name | default |
| description | My Manila share |
| availability_zone | nova |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| export_locations | |
| | path = 10.254.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | preferred = False |
| | is_admin_only = False |
| | id = b6bd76ce-12a2-42a9-a30a-8a43b503867d |
| | share_instance_id = e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | path = 10.0.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | preferred = False |
| | is_admin_only = True |
| | id = 6921e862-88bc-49a5-a2df-efeed9acd583 |
| | share_instance_id = e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 |
| host | nosb-devstack@london#LONDON |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 |
| size | 1 |
| name | myshare |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-24T14:15:34.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+---------------------------------------------------------------+
#. Show the share after it is extended.
.. code-block:: console
$ manila show myshare
+-----------------------------+---------------------------------------------------------------+
| Property | Value |
+-----------------------------+---------------------------------------------------------------+
| status | available |
| share_type_name | default |
| description | My Manila share |
| availability_zone | nova |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| export_locations | |
| | path = 10.254.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | preferred = False |
| | is_admin_only = False |
| | id = b6bd76ce-12a2-42a9-a30a-8a43b503867d |
| | share_instance_id = e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | path = 10.0.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | preferred = False |
| | is_admin_only = True |
| | id = 6921e862-88bc-49a5-a2df-efeed9acd583 |
| | share_instance_id = e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 |
| host | nosb-devstack@london#LONDON |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 |
| size | 2 |
| name | myshare |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-24T14:15:34.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+---------------------------------------------------------------+
Shrink share
~~~~~~~~~~~~
#. Shrink a share.
.. code-block:: console
$ manila shrink myshare 1
#. Show the share while it is being shrunk.
.. code-block:: console
$ manila show myshare
+-----------------------------+---------------------------------------------------------------+
| Property | Value |
+-----------------------------+---------------------------------------------------------------+
| status | shrinking |
| share_type_name | default |
| description | My Manila share |
| availability_zone | nova |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| export_locations | |
| | path = 10.254.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | preferred = False |
| | is_admin_only = False |
| | id = b6bd76ce-12a2-42a9-a30a-8a43b503867d |
| | share_instance_id = e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | path = 10.0.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | preferred = False |
| | is_admin_only = True |
| | id = 6921e862-88bc-49a5-a2df-efeed9acd583 |
| | share_instance_id = e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 |
| host | nosb-devstack@london#LONDON |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 |
| size | 2 |
| name | myshare |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-24T14:15:34.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+---------------------------------------------------------------+
#. Show the share after it is being shrunk.
.. code-block:: console
$ manila show myshare
+-----------------------------+---------------------------------------------------------------+
| Property | Value |
+-----------------------------+---------------------------------------------------------------+
| status | available |
| share_type_name | default |
| description | My Manila share |
| availability_zone | nova |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| export_locations | |
| | path = 10.254.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | preferred = False |
| | is_admin_only = False |
| | id = b6bd76ce-12a2-42a9-a30a-8a43b503867d |
| | share_instance_id = e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | path = 10.0.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| | preferred = False |
| | is_admin_only = True |
| | id = 6921e862-88bc-49a5-a2df-efeed9acd583 |
| | share_instance_id = e1c2d35e-fe67-4028-ad7a-45f668732b1d |
| share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 |
| host | nosb-devstack@london#LONDON |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 8d8b854b-ec32-43f1-acc0-1b2efa7c3400 |
| size | 1 |
| name | myshare |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-24T14:15:34.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+---------------------------------------------------------------+

217
doc/user-guide/source/cli-nova-configure-access-security-for-instances.rst
View File

@ -1,217 +0,0 @@
===========================================
Configure access and security for instances
===========================================
When you launch a virtual machine, you can inject a *key pair*, which
provides SSH access to your instance. For this to work, the image must
contain the ``cloud-init`` package.
You can create at least one key pair for each project. You can use the key
pair for multiple instances that belong to that project. If you generate
a key pair with an external tool, you can import it into OpenStack.
.. note::
A key pair belongs to an individual user, not to a project.
To share a key pair across multiple users, each user
needs to import that key pair.
If an image uses a static root password or a static key set (neither is
recommended), you must not provide a key pair when you launch the
instance.
A *security group* is a named collection of network access rules that
are use to limit the types of traffic that have access to instances.
When you launch an instance, you can assign one or more security groups
to it. If you do not create security groups, new instances are
automatically assigned to the default security group, unless you
explicitly specify a different security group.
The associated *rules* in each security group control the traffic to
instances in the group. Any incoming traffic that is not matched by a
rule is denied access by default. You can add rules to or remove rules
from a security group, and you can modify rules for the default and any
other security group.
You can modify the rules in a security group to allow access to
instances through different ports and protocols. For example, you can
modify rules to allow access to instances through SSH, to ping
instances, or to allow UDP traffic; for example, for a DNS server
running on an instance. You specify the following parameters for rules:
- **Source of traffic**. Enable traffic to instances from either IP
addresses inside the cloud from other group members or from all IP
addresses.
- **Protocol**. Choose TCP for SSH, ICMP for pings, or UDP.
- **Destination port on virtual machine**. Define a port range. To open
a single port only, enter the same value twice. ICMP does not support
ports; instead, you enter values to define the codes and types of
ICMP traffic to be allowed.
Rules are automatically enforced as soon as you create or modify them.
.. 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. Additionally, security groups will
automatically drop DHCP responses coming from instances.
You can also assign a floating IP address to a running instance to
make it accessible from outside the cloud. See
:doc:`cli-manage-ip-addresses`.
Add a key pair
~~~~~~~~~~~~~~
You can generate a key pair or upload an existing public key.
#. To generate a key pair, run the following command.
.. code-block:: console
$ openstack keypair create KEY_NAME > MY_KEY.pem
This command generates a key pair with the name that you specify for
KEY\_NAME, writes the private key to the ``.pem`` file that you specify,
and registers the public key to the Nova database.
#. To set the permissions of the ``.pem`` file so that only you can read
and write to it, run the following command.
.. code-block:: console
$ chmod 600 MY_KEY.pem
Import a key pair
~~~~~~~~~~~~~~~~~
#. If you have already generated a key pair and the public key is located
at ``~/.ssh/id_rsa.pub``, run the following command to upload the public
key.
.. code-block:: console
$ openstack keypair create --public-key ~/.ssh/id_rsa.pub KEY_NAME
This command registers the public key at the Nova database and names the
key pair the name that you specify for ``KEY_NAME``.
#. To ensure that the key pair has been successfully imported, list key
pairs as follows:
.. code-block:: console
$ openstack keypair list
Create and manage security groups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. To list the security groups for the current project, including
descriptions, enter the following command:
.. code-block:: console
$ openstack security group list
#. To create a security group with a specified name and description, enter
the following command:
.. code-block:: console
$ openstack security group create SECURITY_GROUP_NAME --description GROUP_DESCRIPTION
#. To delete a specified group, enter the following command:
.. code-block:: console
$ openstack security group delete SECURITY_GROUP_NAME
.. note::
You cannot delete the default security group for a project. Also,
you cannot delete a security group that is assigned to a running
instance.
Create and manage security group rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Modify security group rules with the :command:`openstack security group rule`
commands. Before you begin, source the OpenStack RC file. For details,
see :doc:`../common/cli-set-environment-variables-using-openstack-rc`.
#. To list the rules for a security group, run the following command:
.. code-block:: console
$ openstack security group rule list SECURITY_GROUP_NAME
#. To allow SSH access to the instances, choose one of the following
options:
- Allow access from all IP addresses, specified as IP subnet ``0.0.0.0/0``
in CIDR notation:
.. code-block:: console
$ openstack security group rule create SECURITY_GROUP_NAME \
--protocol tcp --dst-port 22:22 --remote-ip 0.0.0.0/0
- Allow access only from IP addresses from other security groups
(source groups) to access the specified port:
.. code-block:: console
$ openstack security group rule create SECURITY_GROUP_NAME \
--protocol tcp --dst-port 22:22 --remote-group SOURCE_GROUP_NAME
#. To allow pinging of the instances, choose one of the following options:
- Allow pinging from all IP addresses, specified as IP subnet
``0.0.0.0/0`` in CIDR notation.
.. code-block:: console
$ openstack security group rule create --protocol icmp \
SECURITY_GROUP_NAME
This allows access to all codes and all types of ICMP traffic.
- Allow only members of other security groups (source groups) to ping
instances.
.. code-block:: console
$ openstack security group rule create --protocol icmp \
--remote-group SOURCE_GROUP_NAME SECURITY_GROUP
#. To allow access through a UDP port, such as allowing access to a DNS
server that runs on a VM, choose one of the following options:
- Allow UDP access from IP addresses, specified as IP subnet
``0.0.0.0/0`` in CIDR notation.
.. code-block:: console
$ openstack security group rule create --protocol udp \
--dst-port 53:53 SECURITY_GROUP
- Allow only IP addresses from other security groups (source groups) to
access the specified port.
.. code-block:: console
$ openstack security group rule create --protocol udp \
--dst-port 53:53 --remote-group SOURCE_GROUP_NAME SECURITY_GROUP
Delete a security group rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To delete a security group rule, specify the ID of the rule.
.. code-block:: console
$ openstack security group rule delete RULE_ID

143
doc/user-guide/source/cli-nova-launch-instance-from-image.rst
View File

@ -1,143 +0,0 @@
================================
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/user-guide/source/cli-nova-launch-instance-from-volume.rst
View File

@ -1,335 +0,0 @@
================================
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-mapping``
- :ref:`Boot_instance_from_image_and_attach_non-bootable_volume`
* - Create a volume from an image and boot an instance from that
volume.
- ``--volume``
- :ref:`Create_volume_from_image_and_boot_instance`
* - Boot from an existing source volume or snapshot.
- ``--volume``
- :ref:`Create_volume_from_image_and_boot_instance`
.. note::
To attach a volume to a running instance, see
:ref:`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 | 2017-06-10T13:45:19.588269 |
| description | None |
| encrypted | False |
| id | e77b30a9-2c1b-4f3a-b161-e09685296a83 |
| migration_status | None |
| multiattach | False |
| name | my-volume |
| properties | |
| replication_status | disabled |
| size | 8 |
| snapshot_id | None |
| source_volid | None |
| status | creating |
| type | lvmdriver-1 |
| updated_at | None |
| user_id | 07a3f50419714d90b55edb6505b7cc1d |
+---------------------+--------------------------------------+
#. List volumes.
.. code-block:: console
$ openstack volume list
+--------------------------------------+--------------+-----------+------+-------------+
| ID | Display Name | Status | Size | Attached to |
+--------------------------------------+--------------+-----------+------+-------------+
| e77b30a9-2c1b-4f3a-b161-e09685296a83 | my-volume | available | 8 | |
+--------------------------------------+--------------+-----------+------+-------------+
#. Boot an instance from an image and attach the empty volume to the
instance, use the ``--block-device-mapping`` parameter.
For example:
.. code-block:: console
$ openstack server create --flavor FLAVOR --image IMAGE \
--block-device-mapping DEV-NAME=ID:TYPE:SIZE:DELETE_ON_TERMINATE \
NAME
The parameters are:
- ``--flavor``
The flavor ID or name.
- ``--image``
The image ID or name.
- ``--block-device-mapping``
DEV-NAME=ID:TYPE:SIZE:DELETE_ON_TERMINATE
**DEV-NAME**
The device name to attch the volume when the instance is booted.
**ID**
The ID of the source object.
**TYPE**
Which type object to create the volume.
``volume`` chooses volume to create. ``snapshot`` chooses snapshot
to create.
**SIZE**
The size(GB) of the volume that is created.
**DELETE_ON_TERMINATE**
What to do with the volume when the instance is terminated.
``false`` does not delete the volume. ``true`` deletes the
volume.
- ``NAME``. The name for the server.
.. code-block:: console
$ openstack server create --flavor 2 --image c76cf108-1760-45aa-8559-28176f2c0530 \
--block-device-mapping \
myVolumeAttach=e77b30a9-2c1b-4f3a-b161-e09685296a83:volume:8:false \
myInstanceWithVolume
+--------------------------------------+--------------------------------------------+
| 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 | instance-00000004 |
| 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 | UAwJJ7FZWxmA |
| config_drive | |
| created | 2017-06-10T13:50:47Z |
| flavor | m1.small (2) |
| hostId | |
| id | 555cf3e2-9ba3-46bf-9aa5-0a0c73d5b538 |
| image | cirros-0.3.5-x86_64-uec (c76cf108-1760-... |
| key_name | None |
| name | InstanceWithVolume |
| os-extended-volumes:volumes_attached | [{u'id': u'e77b30a9-2c1b-4f3a-b161-e096... |
| progress | 0 |
| project_id | ff903e4825c74f8dbc1aea6432e4f2fd |
| properties | |
| security_groups | [{u'name': u'default'}] |
| status | BUILD |
| updated | 2017-06-10T13:50:48Z |
| user_id | 07a3f50419714d90b55edb6505b7cc1d |
+--------------------------------------+--------------------------------------------+
.. _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 |
+-----------------+---------------------------------+--------+
| dfcd8407-486... | Fedora-x86_64-20-20131211.1-sda | active |
| c76cf108-176... | cirros-0.3.5-x86_64-uec | active |
| 02d6b27f-40b... | cirros-0.3.5-x86_64-uec-kernel | active |
| 47b90a42-8f4... | 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 dfcd8407-4865-4d82-93f3-7fef323a5951
+------------------+------------------------------------------------------+
| Field | Value |
+------------------+------------------------------------------------------+
| checksum | eb9139e4942121f22bbc2afc0400b2a4 |
| container_format | bare |
| created_at | 2017-06-10T06:46:26Z |
| disk_format | qcow2 |
| file | /v2/images/dfcd8407-4865-4d82-93f3-7fef323a5951/file |
| id | dfcd8407-4865-4d82-93f3-7fef323a5951 |
| min_disk | 0 |
| min_ram | 0 |
| name | Fedora-x86_64-20-20131211.1-sda |
| owner | 5ed8a204e27d462a8709bc8ec491e873 |
| protected | False |
| schema | /v2/schemas/image |
| size | 25165824 |
| status | active |
| tags | |
| updated_at | 2017-06-10T13:36:55Z |
| 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.
#. 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,
use the ``--volume`` parameter. The volume is not
deleted when the instance is terminated.
.. code-block:: console
$ openstack server create --flavor 2 --volume VOLUME_ID \
myInstanceFromVolume
+--------------------------------------+----------------------------------+
| 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 | instance-00000005 |
| 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 | dizZcBMnWH8i |
| config_drive | |
| created | 2017-06-10T14:15:10Z |
| flavor | m1.small (2) |
| hostId | |
| id | 7074c21a-22b3-4e91-9ea1-6a22c... |
| image | |
| key_name | None |
| name | myInstanceFromVolume |
| os-extended-volumes:volumes_attached | [{u'id': u'3da01e5a-7d81-4a34... |
| progress | 0 |
| project_id | ff903e4825c74f8dbc1aea6432e4f2fd |
| properties | |
| security_groups | [{u'name': u'default'}] |
| status | BUILD |
| updated | 2017-06-10T14:15:11Z |
| user_id | 07a3f50419714d90b55edb6505b7cc1d |
+--------------------------------------+----------------------------------+
#. 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 |
+---------------------+-----------------+--------+------+---------------------------------+
| 3da01e5a-7d81-4a34- | bootable_volume | in-use | 2 | Attached to myInstanceFromVolume|
| a182-1958d10f7758 | | | | on /dev/vda |
+---------------------+-----------------+--------+------+---------------------------------+
.. _Attach_swap_or_ephemeral_disk_to_an_instance:
Attach swap or ephemeral disk to an instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To attach swap or ephemeral disk to an instance, you need create new
flavor first. This procedure shows you how to boot an instance with
a 512 MB swap disk and 2 GB ephemeral disk.
#. Create a new flavor.
.. code-block:: console
$ openstack flavor create --vcpus 1 --ram 64 --disk 1 \
--swap 512 --ephemeral 2 my_flavor
.. note::
The flavor defines the maximum swap and ephemeral disk size. You
cannot exceed these maximum values.
#. Create a server with 512 MB swap disk and 2 GB ephemeral disk.
.. code-block:: console
$ openstack server create --image IMAGE_ID --flavor \
my_flavor NAME

147
doc/user-guide/source/cli-nova-launch-instance-using-ISO-image.rst
View File

@ -1,147 +0,0 @@
==================================
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.

19
doc/user-guide/source/cli-provide-user-data-to-instances.rst
View File

@ -1,19 +0,0 @@
==============================
Provide user data to instances
==============================
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 :term:`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 which handles early initialization of a cloud
instance.
You can place user data in a local file and pass it through the
``--user-data <user-data-file>`` parameter at instance creation.
.. code-block:: console
$ openstack server create --image ubuntu-cloudimage --flavor 1 \
--user-data mydata.file VM_INSTANCE

75
doc/user-guide/source/cli-reboot-an-instance.rst
View File

@ -1,75 +0,0 @@
==================
Reboot an instance
==================
You can soft or hard reboot a running instance. A soft reboot attempts a
graceful shut down and restart of the instance. A hard reboot power
cycles the instance.
By default, when you reboot an instance, it is a soft reboot.
.. code-block:: console
$ openstack server reboot SERVER
To perform a hard reboot, pass the ``--hard`` parameter, as follows:
.. code-block:: console
$ openstack server reboot --hard SERVER
It is also possible to reboot a running instance into rescue mode. For example,
this operation may be required, if a filesystem of an instance becomes
corrupted with prolonged use.
.. note::
Pause, suspend, and stop operations are not allowed when an instance
is running in rescue mode, as triggering these actions causes the
loss of the original instance state, and makes it impossible to
unrescue the instance.
Rescue mode provides a mechanism for access, even if an image renders
the instance inaccessible. By default, it starts an instance from the
initial image attaching the current boot disk as a secondary one.
To perform an instance reboot into rescue mode, run the following
command:
.. code-block:: console
$ openstack server rescue SERVER
.. note::
On running the :command:`openstack server rescue` command,
an instance performs a soft shutdown first. This means that
the guest operating system has a chance to perform
a controlled shutdown before the instance is powered off.
The shutdown behavior is configured by the ``shutdown_timeout``
parameter that can be set in the ``nova.conf`` file.
Its value stands for the overall period (in seconds)
a guest operating system is allowed to complete the shutdown.
The default timeout is 60 seconds. See `Description of
Compute configuration options
<https://docs.openstack.org/ocata/config-reference/compute/config-options.html>`_
for details.
The timeout value can be overridden on a per image basis
by means of ``os_shutdown_timeout`` that is an image metadata
setting allowing different types of operating systems to specify
how much time they need to shut down cleanly.
To restart the instance from the normal boot disk, run the following
command:
.. code-block:: console
$ openstack server unrescue SERVER
If you want to rescue an instance with a specific image, rather than the
default one, use the ``--image`` parameter:
.. code-block:: console
$ nova rescue --image IMAGE_ID SERVER

21
doc/user-guide/source/cli-search-instance-with-ip-address.rst
View File

@ -1,21 +0,0 @@
=======================================
Search for an instance using IP address
=======================================
You can search for an instance using the IP address parameter, ``--ip``,
with the :command:`openstack server list` command.
.. code-block:: console
$ openstack server list --ip IP_ADDRESS
The following example shows the results of a search on ``10.0.0.4``.
.. code-block:: console
$ openstack server list --ip 10.0.0.4
+------------------+----------------------+--------+------------+-------------+------------------+------------+
| ID | Name | Status | Task State | Power State | Networks | Image Name |
+------------------+----------------------+--------+------------+-------------+------------------+------------+
| 8a99547e-7385... | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 | cirros |
+------------------+----------------------+--------+------------+-------------+------------------+------------+

92
doc/user-guide/source/cli-stop-and-start-an-instance.rst
View File

@ -1,92 +0,0 @@
==========================
Stop and start an instance
==========================
Use one of the following methods to stop and start an instance.
Pause and unpause an instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To pause an instance, run the following command:
.. code-block:: console
$ openstack server pause INSTANCE_NAME
This command stores the state of the VM in RAM. A paused instance
continues to run in a frozen state.
To unpause an instance, run the following command:
.. code-block:: console
$ openstack server unpause INSTANCE_NAME
Suspend and resume an instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To initiate a hypervisor-level suspend operation, run the following
command:
.. code-block:: console
$ openstack server suspend INSTANCE_NAME
To resume a suspended instance, run the following command:
.. code-block:: console
$ openstack server resume INSTANCE_NAME
Shelve and unshelve an instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Shelving is useful if you have an instance that you are not using, but
would like retain in your list of servers. For example, you can stop an
instance at the end of a work week, and resume work again at the start
of the next week. All associated data and resources are kept; however,
anything still in memory is not retained. If a shelved instance is no
longer needed, it can also be entirely removed.
You can run the following shelving tasks:
- Shelve an instance - Shuts down the instance, and stores it together
with associated data and resources (a snapshot is taken if not volume
backed). Anything in memory is lost.
.. code-block:: console
$ openstack server shelve SERVERNAME
.. note::
By default, the :command:`openstack server shelve` command gives the guest
operating system a chance to perform a controlled shutdown before the
instance is powered off. The shutdown behavior is configured by the
``shutdown_timeout`` parameter that can be set in the
:file:`nova.conf` file. Its value stands for the overall
period (in seconds) a guest operating system is allowed
to complete the shutdown. The default timeout is 60 seconds.
See `Description of Compute configuration options
<https://docs.openstack.org/ocata/config-reference/compute/config-options.html>`_
for details.
The timeout value can be overridden on a per image basis
by means of ``os_shutdown_timeout`` that is an image metadata
setting allowing different types of operating systems to specify
how much time they need to shut down cleanly.
- Unshelve an instance - Restores the instance.
.. code-block:: console
$ openstack server unshelve SERVERNAME
- Remove a shelved instance - Removes the instance from the server;
data and resource associations are deleted. If an instance is no longer
needed, you can move the instance off the hypervisor in order to minimize
resource usage.
.. code-block:: console
$ nova shelve-offload SERVERNAME

132
doc/user-guide/source/cli-swift-archive-auto-extract.rst
View File

@ -1,132 +0,0 @@
.. _archive-auto-extract:
==========================
Auto-extract archive files
==========================
To discover whether your Object Storage system supports this feature,
see :ref:`discoverability`. Alternatively, check with your service
provider.
Use the auto-extract archive feature to upload a tar archive file.
The Object Storage system extracts files from the archive file and
creates an object.
Auto-extract archive request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To upload an archive file, make a ``PUT`` request. Add the
``extract-archive=format`` query parameter to indicate that you are
uploading a tar archive file instead of normal content.
Valid values for the ``format`` variable are ``tar``, ``tar.gz``, or
``tar.bz2``.
The path you specify in the ``PUT`` request is used for the location of
the object and the prefix for the resulting object names.
In the ``PUT`` request, you can specify the path for:
- An account
- Optionally, a specific container
- Optionally, a specific object prefix
For example, if the first object in the tar archive is
``/home/file1.txt`` and you specify the
``/v1/12345678912345/mybackup/castor/`` path, the operation creates the
``castor/home/file1.txt`` object in the ``mybackup`` container in the
``12345678912345`` account.
Create an archive for auto-extract
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You must use the tar utility to create the tar archive file.
You can upload regular files but you cannot upload other items (for
example, empty directories or symbolic links).
You must UTF-8-encode the member names.
The archive auto-extract feature supports these formats:
- The POSIX.1-1988 Ustar format.
- The GNU tar format. Includes the long name, long link, and sparse
extensions.
- The POSIX.1-2001 pax format.
Use gzip or bzip2 to compress the archive.
Use the ``extract-archive`` query parameter to specify the format.
Valid values for this parameter are ``tar``, ``tar.gz``, or
``tar.bz2``.
Auto-extract archive response
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When Object Storage processes the request, it performs multiple
sub-operations. Even if all sub-operations fail, the operation returns a
201 ``Created`` status. Some sub-operations might succeed while others
fail. Examine the response body to determine the results of each
auto-extract archive sub-operation.
You can set the ``Accept`` request header to one of these values to
define the response format:
``text/plain``
Formats response as plain text. If you omit the ``Accept`` header,
``text/plain`` is the default.
``application/json``
Formats response as JSON.
``application/xml``
Formats response as XML.
``text/xml``
Formats response as XML.
The following auto-extract archive files example shows a ``text/plain``
response body where no failures occurred:
.. code-block:: console
Number Files Created: 10
Errors:
The following auto-extract archive files example shows a ``text/plain``
response where some failures occurred. In this example, the Object
Storage system is configured to reject certain character strings so that
the 400 Bad Request error occurs for any objects that use the restricted
strings.
.. code-block:: console
Number Files Created: 8
Errors:
/v1/12345678912345/mycontainer/home/xx%3Cyy, 400 Bad Request
/v1/12345678912345/mycontainer/../image.gif, 400 Bad Request
The following example shows the failure response in ``application/json``
format.
.. code-block:: json
{
"Number Files Created":1,
"Errors":[
[
"/v1/12345678912345/mycontainer/home/xx%3Cyy",
"400 Bad Request"
],
[
"/v1/12345678912345/mycontainer/../image.gif",
"400 Bad Request"
]
]
}

93
doc/user-guide/source/cli-swift-bulk-delete.rst
View File

@ -1,93 +0,0 @@
.. _bulk-delete:
===========
Bulk delete
===========
To discover whether your Object Storage system supports this feature,
see :ref:`discoverability`. Alternatively, check with your service provider.
With bulk delete, you can delete up to 10,000 objects or containers
(configurable) in one request.
Bulk delete request
~~~~~~~~~~~~~~~~~~~
To perform a bulk delete operation, add the ``bulk-delete`` query
parameter to the path of a ``POST`` or ``DELETE`` operation.
.. note::
The ``DELETE`` operation is supported for backwards compatibility.
The path is the account, such as ``/v1/12345678912345``, that contains
the objects and containers.
In the request body of the ``POST`` or ``DELETE`` operation, list the
objects or containers to be deleted. Separate each name with a newline
character. You can include a maximum of 10,000 items (configurable) in
the list.
In addition, you must:
- UTF-8-encode and then URL-encode the names.
- To indicate an object, specify the container and object name as:
``CONTAINER_NAME``/``OBJECT_NAME``.
- To indicate a container, specify the container name as:
``CONTAINER_NAME``. Make sure that the container is empty. If it
contains objects, Object Storage cannot delete the container.
- Set the ``Content-Type`` request header to ``text/plain``.
Bulk delete response
~~~~~~~~~~~~~~~~~~~~
When Object Storage processes the request, it performs multiple
sub-operations. Even if all sub-operations fail, the operation returns a
200 status. The bulk operation returns a response body that contains
details that indicate which sub-operations have succeeded and failed.
Some sub-operations might succeed while others fail. Examine the
response body to determine the results of each delete sub-operation.
You can set the ``Accept`` request header to one of the following values
to define the response format:
``text/plain``
Formats response as plain text. If you omit the
``Accept`` header, ``text/plain`` is the default.
``application/json``
Formats response as JSON.
``application/xml`` or ``text/xml``
Formats response as XML.
The response body contains the following information:
- The number of files actually deleted.
- The number of not found objects.
- Errors. A list of object names and associated error statuses for the
objects that failed to delete. The format depends on the value that
you set in the ``Accept`` header.
The following bulk delete response is in ``application/xml`` format. In
this example, the ``mycontainer`` container is not empty, so it cannot
be deleted.
.. code-block:: xml
<delete>
<number_deleted>2</number_deleted>
<number_not_found>4</number_not_found>
<errors>
<object>
<name>/v1/12345678912345/mycontainer</name>
<status>409 Conflict</status>
</object>
</errors>
</delete>

53
doc/user-guide/source/cli-swift-create-containers.rst
View File

@ -1,53 +0,0 @@
============================
Create and manage containers
============================
- To create a container, run the following command and replace
``CONTAINER`` with the name of your container.
.. code-block:: console
$ swift post CONTAINER
- To list all containers, run the following command:
.. code-block:: console
$ swift list
- To check the status of containers, run the following command:
.. code-block:: console
$ swift stat
.. code-block:: console
Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
Containers: 2
Objects: 3
Bytes: 268826
Accept-Ranges: bytes
X-Timestamp: 1392683866.17952
Content-Type: text/plain; charset=utf-8
You can also use the :command:`swift stat` command with the ``ACCOUNT`` or
``CONTAINER`` names as parameters.
.. code-block:: console
$ swift stat CONTAINER
.. code-block:: console
Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
Container: storage1
Objects: 2
Bytes: 240221
Read ACL:
Write ACL:
Sync To:
Sync Key:
Accept-Ranges: bytes
X-Timestamp: 1392683866.20180
Content-Type: text/plain; charset=utf-8

49
doc/user-guide/source/cli-swift-discoverability.rst
View File

@ -1,49 +0,0 @@
.. _discoverability:
===============
Discoverability
===============
Your Object Storage system might not enable all features that this
document describes. These features are:
* :ref:`large-object-creation`
* :ref:`archive-auto-extract`
* :ref:`bulk-delete`
* :ref:`static-website`
To discover which features are enabled in your Object Storage system,
use the ``/info`` request.
To use the ``/info`` request, send a ``GET`` request using the ``/info``
path to the Object Store endpoint as shown in this example:
.. code-block:: console
$ curl https://storage.example.com/info
This example shows a truncated response body:
.. code-block:: json
{
"swift":{
"version":"1.11.0"
},
"staticweb":{
},
"tempurl":{
}
}
This output shows that the Object Storage system has enabled the static
website and temporary URL features.
.. note::
In some cases, the ``/info`` request will return an error. This could be
because your service provider has disabled the ``/info`` request
function, or because you are using an older version that does not
support it.

36
doc/user-guide/source/cli-swift-env-vars.rst
View File

@ -1,36 +0,0 @@
.. _env-vars:
==============================================
Environment variables required to run examples
==============================================
To run the cURL command examples for the Object Storage API requests,
set these environment variables:
publicURL
The public URL that is the HTTP endpoint from where you can access
Object Storage. It includes the Object Storage API version number
and your account name. For example,
``https://23.253.72.207/v1/my_account``.
token
The authentication token for Object Storage.
To obtain these values, run the :command:`swift stat -v` command.
As shown in this example, the public URL appears in the ``StorageURL``
field, and the token appears in the ``Auth Token`` field:
.. code-block:: console
StorageURL: https://23.253.72.207/v1/my_account
Auth Token: {token}
Account: my_account
Containers: 2
Objects: 3
Bytes: 47
Meta Book: MobyDick
X-Timestamp: 1389453423.35964
X-Trans-Id: txee55498935404a2caad89-0052dd3b77
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes

103
doc/user-guide/source/cli-swift-large-lists.rst
View File

@ -1,103 +0,0 @@
=================================================
Page through large lists of containers or objects
=================================================
If you have a large number of containers or objects, you can use the
``marker``, ``limit``, and ``end_marker`` parameters to control
how many items are returned in a list and where the list starts or ends.
* marker
When you request a list of containers or objects, Object Storage
returns a maximum of 10,000 names for each request. To get
subsequent names, you must make another request with the
``marker`` parameter. Set the ``marker`` parameter to the name of
the last item returned in the previous list. You must URL-encode the
``marker`` value before you send the HTTP request. Object Storage
returns a maximum of 10,000 names starting after the last item
returned.
* limit
To return fewer than 10,000 names, use the ``limit`` parameter. If
the number of names returned equals the specified ``limit`` (or
10,000 if you omit the ``limit`` parameter), you can assume there
are more names to list. If the number of names in the list is
exactly divisible by the ``limit`` value, the last request has no
content.
* end_marker
Limits the result set to names that are less than the
``end_marker`` parameter value. You must URL-encode the
``end_marker`` value before you send the HTTP request.
To page through a large list of containers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Assume the following list of container names:
.. code-block:: console
apples
bananas
kiwis
oranges
pears
#. Use a ``limit`` of two:
.. code-block:: console
# curl -i $publicURL/?limit=2 -X GET -H "X-Auth-Token: $token"
.. code-block:: console
apples
bananas
Because two container names are returned, there are more names to
list.
#. Make another request with a ``marker`` parameter set to the name of
the last item returned:
.. code-block:: console
# curl -i $publicURL/?limit=2&amp;marker=bananas -X GET -H \
“X-Auth-Token: $token"
.. code-block:: console
kiwis
oranges
Again, two items are returned, and there might be more.
#. Make another request with a ``marker`` of the last item returned:
.. code-block:: console
# curl -i $publicURL/?limit=2&amp;marker=oranges -X GET -H \”
X-Auth-Token: $token"
.. code-block:: console
pears
You receive a one-item response, which is fewer than the ``limit``
number of names. This indicates that this is the end of the list.
#. Use the ``end_marker`` parameter to limit the result set to object
names that are less than the ``end_marker`` parameter value:
.. code-block:: console
# curl -i $publicURL/?end_marker=oranges -X GET -H \”
X-Auth-Token: $token"
.. code-block:: console
apples
bananas
kiwis
You receive a result set of all container names before the
``end-marker`` value.

368
doc/user-guide/source/cli-swift-large-object-creation.rst
View File

@ -1,368 +0,0 @@
.. _large-object-creation:
=============
Large objects
=============
To discover whether your Object Storage system supports this feature, see
:ref:`discoverability` or check with your service provider.
By default, the content of an object cannot be greater than 5 GB.
However, you can use a number of smaller objects to construct a large
object. The large object is comprised of two types of objects:
* ``Segment objects`` store the object content. You can divide your content
into segments and upload each segment into its own segment object. Segment
objects do not have any special features. You create, update, download, and
delete segment objects just as you do with normal objects.
* A ``manifest object`` links the segment objects into one logical large
object. When you download a manifest object, Object Storage concatenates and
returns the contents of the segment objects in the response body. This
behavior extends to the response headers returned by ``GET`` and ``HEAD``
requests. The ``Content-Length`` response header contains the total size of
all segment objects.
Object Storage takes the ``ETag`` value of each segment, concatenates them
together, and returns the MD5 checksum of the result to calculate the
``ETag`` response header value. The manifest object types are:
Static large objects
The manifest object content is an ordered list of the names of
the segment objects in JSON format. See :ref:`static_large_objects`.
Dynamic large objects
The manifest object has no content but it has a
``X-Object-Manifest`` metadata header. The value of this header
is ``CONTAINER/PREFIX``, where ``CONTAINER`` is the name of
the container where the segment objects are stored, and
``PREFIX`` is a string that all segment objects have in common.
See :ref:`dynamic_large_objects`.
.. note::
If you use a manifest object as the source of a ``COPY`` request, the
new object is a normal, and not a segment, object. If the total size of the
source segment objects exceeds 5 GB, the ``COPY`` request fails. However,
you can make a duplicate of the manifest object and this new object can be
larger than 5 GB.
.. _static_large_objects:
Static large objects
~~~~~~~~~~~~~~~~~~~~
To create a static large object, divide your content into pieces and create
(upload) a segment object to contain each piece.
You must record the ``ETag`` response header value that the ``PUT`` operation
returns. Alternatively, you can calculate the MD5 checksum of the segment
before you perform the upload and include this value in the ``ETag`` request
header. This action ensures that the upload cannot corrupt your data.
List the name of each segment object along with its size and MD5
checksum in order.
Create a manifest object. Include the ``?multipart-manifest=put``
query string at the end of the manifest object name to indicate that
this is a manifest object.
The body of the ``PUT`` request on the manifest object comprises a JSON
list where each element contains these attributes:
path
The container and object name in the format:
``CONTAINER_NAME/OBJECT_NAME``.
etag
The MD5 checksum of the content of the segment object. This value
must match the ``ETag`` of that object.
size_bytes
The size of the segment object. This value must match the
``Content-Length`` of that object.
Static large object manifest list
---------------------------------
This example shows three segment objects. You can use several containers
and the object names do not have to conform to a specific pattern, in
contrast to dynamic large objects.
.. code-block:: json
[
{
"path": "mycontainer/objseg1",
"etag": "0228c7926b8b642dfb29554cd1f00963",
"size_bytes": 1468006
},
{
"path": "mycontainer/pseudodir/seg-obj2",
"etag": "5bfc9ea51a00b790717eeb934fb77b9b",
"size_bytes": 1572864
},
{
"path": "other-container/seg-final",
"etag": "b9c3da507d2557c1ddc51f27c54bae51",
"size_bytes": 256
}
]
|
The ``Content-Length`` request header must contain the length of the
JSON content and not the length of the segment objects. However, after the
``PUT`` operation completes, the ``Content-Length`` metadata is set to
the total length of all the object segments. A similar situation applies
to the ``ETag``. If used in the ``PUT`` operation, it must contain the
MD5 checksum of the JSON content. The ``ETag`` metadata value is then
set to be the MD5 checksum of the concatenated ``ETag`` values of the
object segments. You can also set the ``Content-Type`` request header
and custom object metadata.
When the ``PUT`` operation sees the ``?multipart-manifest=put`` query
parameter, it reads the request body and verifies that each segment
object exists and that the sizes and ETags match. If there is a
mismatch, the ``PUT`` operation fails.
If everything matches, the API creates the manifest object and sets the
``X-Static-Large-Object`` metadata to ``true`` to indicate that the manifest is
a static object manifest.
Normally when you perform a ``GET`` operation on the manifest object, the
response body contains the concatenated content of the segment objects. To
download the manifest list, use the ``?multipart-manifest=get`` query
parameter. The list in the response is not formatted the same as the manifest
that you originally used in the ``PUT`` operation.
If you use the ``DELETE`` operation on a manifest object, the manifest
object is deleted. The segment objects are not affected. However, if you
add the ``?multipart-manifest=delete`` query parameter, the segment
objects are deleted and if all are successfully deleted, the manifest
object is also deleted.
To change the manifest, use a ``PUT`` operation with the
``?multipart-manifest=put`` query parameter. This request creates a
manifest object. You can also update the object metadata in the usual
way.
.. _dynamic_large_objects:
Dynamic large objects
~~~~~~~~~~~~~~~~~~~~~
Before you can upload objects that are larger than 5 GB, you must segment
them. You upload the segment objects like you do with any other object and
create a dynamic large manifest object. The manifest object tells Object
Storage how to find the segment objects that comprise the large object. You
can still access each segment individually, but when you retrieve the manifest
object, the API concatenates the segments. You can include any number of
segments in a single large object.
To ensure the download works correctly, you must upload all the object
segments to the same container and prefix each object name so that the
segments sort in correct concatenation order.
You also create and upload a manifest file. The manifest file is a zero-byte
file with the extra ``X-Object-Manifest`` ``CONTAINER/PREFIX`` header. The
``CONTAINER`` is the container the object segments are in and ``PREFIX`` is
the common prefix for all the segments. You must UTF-8-encode and then
URL-encode the container and common prefix in the ``X-Object-Manifest`` header.
It is best to upload all the segments first and then create or update
the manifest. With this method, the full object is not available for
downloading until the upload is complete. Also, you can upload a new set
of segments to a second location and update the manifest to point to
this new location. During the upload of the new segments, the original
manifest is still available to download the first set of segments.
Upload segment of large object request: HTTP
--------------------------------------------
.. code-block:: console
PUT /API_VERSION/ACCOUNT/CONTAINER/OBJECT HTTP/1.1
Host: storage.example.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
X-Object-Meta-PIN: 1234
No response body is returned.
The 2``nn`` response code indicates a successful write. ``nn`` is a value from
00 to 99.
The ``Length Required (411)`` response code indicates that the request does
not include a required ``Content-Length`` or ``Content-Type`` header.
The ``Unprocessable Entity (422)`` response code indicates that the MD5
checksum of the data written to the storage system does NOT match the optional
ETag value.
You can continue to upload segments, like this example shows, before you
upload the manifest.
Upload next segment of large object request: HTTP
-------------------------------------------------
.. code-block:: console
PUT /API_VERSION/ACCOUNT/CONTAINER/OBJECT HTTP/1.1
Host: storage.example.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
X-Object-Meta-PIN: 1234
Next, upload the manifest. This manifest specifies the container where the
object segments reside. Note that if you upload additional segments after you
create the manifest, the concatenated object becomes that much larger but you
do not need to recreate the manifest file for subsequent additional segments.
Upload manifest request: HTTP
-----------------------------
.. code-block:: console
PUT /API_VERSION/ACCOUNT/CONTAINER/OBJECT HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Content-Length: 0
X-Object-Meta-PIN: 1234
X-Object-Manifest: CONTAINER/PREFIX
Upload manifest response: HTTP
------------------------------
.. code-block:: console
[...]
A ``GET`` or ``HEAD`` request on the manifest returns a ``Content-Type``
response header value that is the same as the ``Content-Type`` request header
value in the ``PUT`` request that created the manifest. To change the
``Content- Type``, reissue the ``PUT`` request.
Extra transaction information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use the ``X-Trans-Id-Extra`` request header to include extra
information to help you debug any errors that might occur with large object
upload and other Object Storage transactions.
The Object Storage API appends the first 32 characters of the
``X-Trans-Id-Extra`` request header value to the transaction ID value in the
generated ``X-Trans-Id`` response header. You must UTF-8-encode and then
URL-encode the extra transaction information before you include it in
the ``X-Trans-Id-Extra`` request header.
For example, you can include extra transaction information when you upload
large objects such as images.
When you upload each segment and the manifest, include the same value in the
``X-Trans-Id-Extra`` request header. If an error occurs, you can find all
requests that are related to the large object upload in the Object Storage
logs.
You can also use ``X-Trans-Id-Extra`` strings to help operators debug requests
that fail to receive responses. The operator can search for the extra
information in the logs.
Comparison of static and dynamic large objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
While static and dynamic objects have similar behavior, this table describes
their differences:
.. tabularcolumns:: |p{0.2\textwidth}|p{0.35\textwidth}|p{0.35\textwidth}|
.. list-table::
:header-rows: 1
:widths: 20 25 25
:stub-columns: 1
* - Description
- Static large object
- Dynamic large object
* - End-to-end integrity
- Assured. The list of segments includes the MD5 checksum
(``ETag``) of each segment. You cannot upload the manifest
object if the ``ETag`` in the list differs from the uploaded
segment object. If a segment is somehow lost, an attempt to
download the manifest object results in an error.
- Not guaranteed. The eventual consistency model means that
although you have uploaded a segment object, it might not
appear in the container listing until later. If you download
the manifest before it appears in the container, it does not
form part of the content returned in response to a ``GET``
request.
* - Upload order
- You must upload the segment objects before upload the manifest
object.
- You can upload manifest and segment objects in any order. You
are recommended to upload the manifest object after the
segments in case a premature download of the manifest occurs.
However, this is not enforced.
* - Removal or addition of segment objects
- You cannot add or remove segment objects from the manifest.
However, you can create a completely new manifest object of the
same name with a different manifest list.
- You can upload new segment objects or remove existing segments.
The names must simply match the ``PREFIX`` supplied in
``X-Object-Manifest``.
* - Segment object size and number
- Segment objects must be at least 1 MB in size (by default). The
final segment object can be any size. At most, 1000 segments
are supported (by default).
- Segment objects can be any size.
* - Segment object container name
- The manifest list includes the container name of each object.
Segment objects can be in different containers.
- All segment objects must be in the same container.
* - Manifest object metadata
- The object has ``X-Static-Large-Object`` set to ``true``. You
do not set this metadata directly. Instead the system sets it
when you ``PUT`` a static manifest object.
- The ``X-Object-Manifest`` value is the ``CONTAINER/PREFIX``,
which indicates where the segment objects are located. You
supply this request header in the ``PUT`` operation.
* - Copying the manifest object
- Include the ``?multipart-manifest=get`` query string in the
``COPY`` request. The new object contains the same manifest as
the original. The segment objects are not copied. Instead, both
the original and new manifest objects share the same set of
segment objects.
- The ``COPY`` operation does not create a manifest object. To
duplicate a manifest object, use the ``GET`` operation to read
the value of ``X-Object-Manifest`` and use this value in the
``X-Object-Manifest`` request header in a ``PUT`` operation.
This creates a new manifest object that shares the same set of
segment objects as the original manifest object.
Upload large objects with python-swiftclient
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use ``python-swiftclient`` to easily upload large objects.
* Upload a large file by specifying the segment size with the
``--segment-size`` or ``-S`` arguments:
.. code-block:: console
$ swift upload CONTAINER OBJECT_FILENAME --segment-size <bytes>
This will automatically break the file into the desired segment size
and upload segments to a container named ``<container>_segments``.
* After upload has completed, you can download the large object as a
single file:
.. code-block:: console
$ swift download CONTAINER OBJECT_FILENAME
* Additional large object arguments can be found by using ``--help``:
.. code-block:: console
$ swift upload --help

91
doc/user-guide/source/cli-swift-manage-access-swift.rst
View File

@ -1,91 +0,0 @@
=============
Manage access
=============
- Users have roles on accounts. For example, a user with the admin role
has full access to all containers and objects in an account. You can
set access control lists (ACLs) at the container level and support
lists for read and write access, which you set with the
``X-Container-Read`` and ``X-Container-Write`` headers.
To give a user read access, use the :command:`swift post` command with the
``-r`` parameter. To give a user write access, use the
``-w`` parameter.
- The following are examples of `read` ACLs for containers:
A request with any HTTP referer header can read container contents:
.. code-block:: console
$ swift post CONTAINER -r ".r:*"
A request with any HTTP referer header can read and list container
contents:
.. code-block:: console
$ swift post CONTAINER -r ".r:*,.rlistings"
A list of specific HTTP referer headers permitted to read container
contents:
.. code-block:: console
$ swift post CONTAINER -r \
".r:openstack.example.com,.r:swift.example.com,.r:storage.example.com"
A list of specific HTTP referer headers denied read access:
.. code-block:: console
$ swift post CONTAINER -r \
".r:*,.r:-openstack.example.com,.r:-swift.example.com,.r:-storage.example.com"
All users residing in project1 can read container contents:
.. code-block:: console
$ swift post CONTAINER -r "project1:*"
User1 from project1 can read container contents:
.. code-block:: console
$ swift post CONTAINER -r "project1:user1"
A list of specific users and projects permitted to read container contents:
.. code-block:: console
$ swift post CONTAINER -r \
"project1:user1,project1:user2,project3:*,project4:user1"
- The following are examples of `write` ACLs for containers:
All users residing in project1 can write to the container:
.. code-block:: console
$ swift post CONTAINER -w "project1:*"
User1 from project1 can write to the container:
.. code-block:: console
$ swift post CONTAINER -w "project1:user1"
A list of specific users and projects permitted to write to the container:
.. code-block:: console
$ swift post CONTAINER -w \
"project1:user1,project1:user2,project3:*,project4:user1"
.. note::
To successfully write to a container, a user must have read privileges
(in addition to write) on the container. For all aforementioned
read/write ACL examples, one can replace the project/user name with
project/user UUID, i.e. ``<project_uuid>:<user_uuid>``. If using multiple
keystone domains, UUID format is required.

52
doc/user-guide/source/cli-swift-manage-objects.rst
View File

@ -1,52 +0,0 @@
==============
Manage objects
==============
- To upload an object to a container, run the following command:
.. code-block:: console
$ swift upload CONTAINER OBJECT_FILENAME
To upload an object in chunks, for larger than 5GB files, run the following
command:
.. code-block:: console
$ swift upload -S CHUNK_SIZE CONTAINER OBJECT_FILENAME
.. important::
Uploading objects in chunks is mandatory if uploading an object larger
than 5GB.
- To check the status of the object, run the following command:
.. code-block:: console
$ swift stat CONTAINER OBJECT_FILENAME
.. code-block:: console
Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
Container: storage1
Object: images
Content Type: application/octet-stream
Content Length: 211616
Last Modified: Tue, 18 Feb 2014 00:40:36 GMT
ETag: 82169623d55158f70a0d720f238ec3ef
Meta Orig-Filename: images.jpg
Accept-Ranges: bytes
X-Timestamp: 1392684036.33306
- To list the objects in a container, run the following command:
.. code-block:: console
$ swift list CONTAINER
- To download an object from a container, run the following command:
.. code-block:: console
$ swift download CONTAINER OBJECT_FILENAME

151
doc/user-guide/source/cli-swift-pseudo-hierarchical-folders-directories.rst
View File

@ -1,151 +0,0 @@
===========================================
Pseudo-hierarchical folders and directories
===========================================
Although you cannot nest directories in OpenStack Object Storage, you
can simulate a hierarchical structure within a single container by
adding forward slash characters (``/``) in the object name. To navigate
the pseudo-directory structure, you can use the ``delimiter`` query
parameter. This example shows you how to use pseudo-hierarchical folders
and directories.
.. note::
In this example, the objects reside in a container called ``backups``.
Within that container, the objects are organized in a pseudo-directory
called ``photos``. The container name is not displayed in the example,
but it is a part of the object URLs. For instance, the URL of the
picture ``me.jpg`` is
``https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg``.
List pseudo-hierarchical folders request: HTTP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To display a list of all the objects in the storage container, use
``GET`` without a ``delimiter`` or ``prefix``.
.. code-block:: console
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups
The system returns status code 2xx (between 200 and 299, inclusive) and
the requested list of the objects.
.. code-block:: console
photos/animals/cats/persian.jpg
photos/animals/cats/siamese.jpg
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg
photos/me.jpg
photos/plants/fern.jpg
photos/plants/rose.jpg
Use the delimiter parameter to limit the displayed results. To use
``delimiter`` with pseudo-directories, you must use the parameter slash
(``/``).
.. code-block:: console
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups?delimiter=/
The system returns status code 2xx (between 200 and 299, inclusive) and
the requested matching objects. Because you use the slash, only the
pseudo-directory ``photos/`` displays. The returned values from a slash
``delimiter`` query are not real objects. The value will refer to
a real object if it does not end with a slash. The pseudo-directories
have no content-type, rather, each pseudo-directory has
its own ``subdir`` entry in the response of JSON and XML results.
For example:
.. code-block:: JSON
[
{
"subdir": "photos/"
}
]
[
{
"subdir": "photos/animals/"
},
{
"hash": "b249a153f8f38b51e92916bbc6ea57ad",
"last_modified": "2015-12-03T17:31:28.187370",
"bytes": 2906,
"name": "photos/me.jpg",
"content_type": "image/jpeg"
},
{
"subdir": "photos/plants/"
}
]
.. code-block:: XML
<?xml version="1.0" encoding="UTF-8"?>
<container name="backups">
<subdir name="photos/">
<name>photos/</name>
</subdir>
</container>
<?xml version="1.0" encoding="UTF-8"?>
<container name="backups">
<subdir name="photos/animals/">
<name>photos/animals/</name>
</subdir>
<object>
<name>photos/me.jpg</name>
<hash>b249a153f8f38b51e92916bbc6ea57ad</hash>
<bytes>2906</bytes>
<content_type>image/jpeg</content_type>
<last_modified>2015-12-03T17:31:28.187370</last_modified>
</object>
<subdir name="photos/plants/">
<name>photos/plants/</name>
</subdir>
</container>
Use the ``prefix`` and ``delimiter`` parameters to view the objects
inside a pseudo-directory, including further nested pseudo-directories.
.. code-block:: console
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups?prefix=photos/&delimiter=/
The system returns status code 2xx (between 200 and 299, inclusive) and
the objects and pseudo-directories within the top level
pseudo-directory.
.. code-block:: console
photos/animals/
photos/me.jpg
photos/plants/
You can create an unlimited number of nested pseudo-directories. To
navigate through them, use a longer ``prefix`` parameter coupled with
the ``delimiter`` parameter. In this sample output, there is a
pseudo-directory called ``dogs`` within the pseudo-directory
``animals``. To navigate directly to the files contained within
``dogs``, enter the following command:
.. code-block:: console
$ curl -X GET -i -H "X-Auth-Token: $token" \
$publicurl/v1/AccountString/backups?prefix=photos/animals/dogs/&delimiter=/
The system returns status code 2xx (between 200 and 299, inclusive) and
the objects and pseudo-directories within the nested pseudo-directory.
.. code-block:: console
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg

124
doc/user-guide/source/cli-swift-serialized-response-formats.rst
View File

@ -1,124 +0,0 @@
===========================
Serialized response formats
===========================
By default, the Object Storage API uses a ``text/plain`` response
format. In addition, both JSON and XML data serialization response
formats are supported.
.. note::
To run the cURL command examples, you must export environment variables. For more
information, see the section :ref:`env-vars`.
To define the response format, use one of these methods:
+-------------------+-------------------------------------------------------+
|Method |Description |
+===================+=======================================================+
|format= ``format`` |Append this parameter to the URL for a ``GET`` request,|
|query parameter |where ``format`` is ``json`` or ``xml``. |
+-------------------+-------------------------------------------------------+
|``Accept`` request |Include this header in the ``GET`` request. |
|header |The valid header values are: |
| | |
| |text/plain |
| | Plain text response format. The default. |
| |application/jsontext |
| | JSON data serialization response format. |
| |application/xml |
| | XML data serialization response format. |
| |text/xml |
| | XML data serialization response format. |
+-------------------+-------------------------------------------------------+
Example 1. JSON example with format query parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For example, this request uses the ``format`` query parameter to ask
for a JSON response:
.. code-block:: console
$ curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token"
.. code-block:: console
HTTP/1.1 200 OK
Content-Length: 96
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT
Object Storage lists container names with additional information in JSON
format:
.. code-block:: json
[
{
"count":0,
"bytes":0,
"name":"janeausten"
},
{
"count":1,
"bytes":14,
"name":"marktwain"
}
]
Example 2. XML example with Accept header
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This request uses the ``Accept`` request header to ask for an XML
response:
.. code-block:: console
$ curl -i $publicURL -X GET -H "X-Auth-Token: $token" -H \
”Accept: application/xml; charset=utf-8"
.. code-block:: console
HTTP/1.1 200 OK
Content-Length: 263
X-Account-Object-Count: 3
X-Account-Meta-Book: MobyDick
X-Timestamp: 1389453423.35964
X-Account-Bytes-Used: 47
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: txf0b4c9727c3e491694019-0052e03420
Date: Wed, 22 Jan 2014 21:12:00 GMT
Object Storage lists container names with additional information in XML
format:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<account name="AUTH_73f0aa26640f4971864919d0eb0f0880">
<container>
<name>janeausten</name>
<count>2</count>
<bytes>33</bytes>
</container>
<container>
<name>marktwain</name>
<count>1</count>
<bytes>14</bytes>
</container>
</account>
The remainder of the examples in this guide use standard, non-serialized
responses. However, all ``GET`` requests that perform list operations
accept the ``format`` query parameter or ``Accept`` request header.

48
doc/user-guide/source/cli-swift-set-object-expiration.rst
View File

@ -1,48 +0,0 @@
=================
Object expiration
=================
You can schedule Object Storage (swift) objects to expire by setting the
``X-Delete-At`` or ``X-Delete-After`` header. Once the object is deleted,
swift will no longer serve the object and it will be deleted from the cluster
shortly thereafter.
* Set an object to expire at an absolute time (in Unix time). You
can get the current Unix time by running ``date +'%s'``.
.. code-block:: console
$ swift post CONTAINER OBJECT_FILENAME -H "X-Delete-At:UNIX_TIME"
Verify the ``X-Delete-At`` header has posted to the object:
.. code-block:: console
$ swift stat CONTAINER OBJECT_FILENAME
* Set an object to expire after a relative amount of time (in seconds):
.. code-block:: console
$ swift post CONTAINER OBJECT_FILENAME -H "X-Delete-After:SECONDS"
The ``X-Delete-After`` header will be converted to ``X-Delete-At``.
Verify the ``X-Delete-At`` header has posted to the object:
.. code-block:: console
$ swift stat CONTAINER OBJECT_FILENAME
If you no longer want to expire the object, you can remove the
``X-Delete-At`` header:
.. code-block:: console
$ swift post CONTAINER OBJECT_FILENAME -H "X-Remove-Delete-At:"
.. note::
In order for object expiration to work properly, the
``swift-object-expirer`` daemon will need access to all backend
servers in the cluster. The daemon does not need access to the
proxy-server or public network.

217
doc/user-guide/source/cli-swift-set-object-versions.rst
View File

@ -1,217 +0,0 @@
=================
Object versioning
=================
You can store multiple versions of your content so that you can recover
from unintended overwrites. Object versioning is an easy way to
implement version control, which you can use with any type of content.
.. note::
You cannot version a large-object manifest file, but the large-object
manifest file can point to versioned segments.
We strongly recommend that you put non-current objects in a different
container than the container where current object versions reside.
To enable and use object versioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. To enable object versioning, ask your cloud provider to set the
``allow_versions`` option to ``TRUE`` in the container configuration
file.
#. Create an ``archive`` container to store older versions of objects:
.. code-block:: console
$ curl -i $publicURL/archive -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
.. code-block:: console
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx46f8c29050834d88b8d7e-0052e1859d
Date: Thu, 23 Jan 2014 21:11:57 GMT
#. Create a ``current`` container to store current versions of objects.
Include the ``X-Versions-Location`` header. This header defines the
container that holds the non-current versions of your objects. You
must UTF-8-encode and then URL-encode the container name before you
include it in the ``X-Versions-Location`` header. This header enables
object versioning for all objects in the ``current`` container.
Changes to objects in the ``current`` container automatically create
non-current versions in the ``archive`` container.
.. code-block:: console
$ curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H \
”X-Auth-Token: $token" -H "X-Versions-Location: archive"
.. code-block:: console
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txb91810fb717347d09eec8-0052e18997
Date: Thu, 23 Jan 2014 21:28:55 GMT
#. Create the first version of an object in the ``current`` container:
.. code-block:: console
$ curl -i $publicURL/current/my_object --data-binary 1 -X PUT -H \
”Content-Length: 0" -H "X-Auth-Token: $token"
.. code-block:: console
HTTP/1.1 201 Created
Last-Modified: Thu, 23 Jan 2014 21:31:22 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx5992d536a4bd4fec973aa-0052e18a2a
Date: Thu, 23 Jan 2014 21:31:22 GMT
Nothing is written to the non-current version container when you
initially ``PUT`` an object in the ``current`` container. However,
subsequent ``PUT`` requests that edit an object trigger the creation
of a version of that object in the ``archive`` container.
These non-current versions are named as follows:
.. code-block:: console
<length><object_name><timestamp>
Where ``length`` is the 3-character, zero-padded hexadecimal
character length of the object, ``<object_name>`` is the object name,
and ``<timestamp>`` is the time when the object was initially created
as a current version.
#. Create a second version of the object in the ``current`` container:
.. code-block:: console
$ curl -i $publicURL/current/my_object --data-binary 2 -X PUT -H \
“Content-Length: 0" -H "X-Auth-Token: $token"
.. code-block:: console
HTTP/1.1 201 Created
Last-Modified: Thu, 23 Jan 2014 21:41:32 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx468287ce4fc94eada96ec-0052e18c8c
Date: Thu, 23 Jan 2014 21:41:32 GMT
#. Issue a ``GET`` request to a versioned object to get the current
version of the object. You do not have to do any request redirects or
metadata lookups.
List older versions of the object in the ``archive`` container:
.. code-block:: console
$ curl -i $publicURL/archive?prefix=009my_object -X GET -H \
"X-Auth-Token: $token"
.. code-block:: console
HTTP/1.1 200 OK
Content-Length: 30
X-Container-Object-Count: 1
Accept-Ranges: bytes
X-Timestamp: 1390513280.79684
X-Container-Bytes-Used: 0
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx9a441884997542d3a5868-0052e18d8e
Date: Thu, 23 Jan 2014 21:45:50 GMT
009my_object/1390512682.92052
.. note::
A ``POST`` request to a versioned object updates only the metadata
for the object and does not create a new version of the object. New
versions are created only when the content of the object changes.
#. Issue a ``DELETE`` request to a versioned object to remove the
current version of the object and replace it with the next-most
current version in the non-current container.
.. code-block:: console
$ curl -i $publicURL/current/my_object -X DELETE -H \
"X-Auth-Token: $token"
.. code-block:: console
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx006d944e02494e229b8ee-0052e18edd
Date: Thu, 23 Jan 2014 21:51:25 GMT
List objects in the ``archive`` container to show that the archived
object was moved back to the ``current`` container:
.. code-block:: console
$ curl -i $publicURL/archive?prefix=009my_object -X GET -H \
"X-Auth-Token: $token"
.. code-block:: console
HTTP/1.1 204 No Content
Content-Length: 0
X-Container-Object-Count: 0
Accept-Ranges: bytes
X-Timestamp: 1390513280.79684
X-Container-Bytes-Used: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx044f2a05f56f4997af737-0052e18eed
Date: Thu, 23 Jan 2014 21:51:41 GMT
This next-most current version carries with it any metadata last set
on it. If you want to completely remove an object and you have five
versions of it, you must ``DELETE`` it five times.
#. To disable object versioning for the ``current`` container, remove
its ``X-Versions-Location`` metadata header by sending an empty key
value.
.. code-block:: console
$ curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H \
"X-Auth-Token: $token" -H "X-Versions-Location: "
.. code-block:: console
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txe2476de217134549996d0-0052e19038
Date: Thu, 23 Jan 2014 21:57:12 GMT
<html><h1>Accepted</h1><p>The request is accepted for processing.</p></html>
Versioning with python-swiftclient
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can utilize ``python-swiftclient`` to enable object versioning.
* Create an additional container to hold previous versions:
.. code-block:: console
$ swift post CONTAINER_versions
* Enable object versioning on your desired container:
.. code-block:: console
$ swift post CONTAINER -H "X-Versions-Location:CONTAINER-versions"

125
doc/user-guide/source/cli-swift-static-website.rst
View File

@ -1,125 +0,0 @@
.. _static-website:
=====================
Create static website
=====================
To discover whether your Object Storage system supports this feature,
see :ref:`discoverability`. Alternatively, check with your service
provider.
You can use your Object Storage account to create a static website. This
static website is created with Static Web middleware and serves container
data with a specified index file, error file resolution, and optional
file listings. This mode is normally active only for anonymous requests,
which provide no authentication token. To use it with authenticated
requests, set the header ``X-Web-Mode`` to ``TRUE`` on the request.
The Static Web filter must be added to the pipeline in your
``/etc/swift/proxy-server.conf`` file below any authentication
middleware. You must also add a Static Web middleware configuration
section.
See the Cloud Administrator Guide for an example of the `static web configuration syntax <https://docs.openstack.org/ocata/config-reference/object-storage/features.html#static-web-sites>`_.
See the Cloud Administrator Guide for a complete example of the `/etc/swift/proxy-server.conf file <https://docs.openstack.org/ocata/config-reference/object-storage/proxy-server.html#sample-proxy-server-configuration-file>`_
(including static web).
Your publicly readable containers are checked for two headers,
``X-Container-Meta-Web-Index`` and ``X-Container-Meta-Web-Error``. The
``X-Container-Meta-Web-Error`` header is discussed below, in the
section called :ref:`set_error_static_website`.
Use ``X-Container-Meta-Web-Index`` to determine the index file (or
default page served, such as ``index.html``) for your website. When
someone initially enters your site, the ``index.html`` file displays
automatically. If you create sub-directories for your site by creating
pseudo-directories in your container, the index page for each
sub-directory is displayed by default. If your pseudo-directory does not
have a file with the same name as your index file, visits to the
sub-directory return a 404 error.
You also have the option of displaying a list of files in your
pseudo-directory instead of a web page. To do this, set the
``X-Container-Meta-Web-Listings`` header to ``TRUE``. You may add styles
to your file listing by setting ``X-Container-Meta-Web-Listings-CSS``
to a style sheet (for example, ``lists.css``).
Static Web middleware through Object Storage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following sections show how to use Static Web middleware through
Object Storage.
Make container publicly readable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Make the container publicly readable. Once the container is publicly
readable, you can access your objects directly, but you must set the
index file to browse the main site URL and its sub-directories.
.. code-block:: console
$ swift post -r '.r:*,.rlistings' container
Set site index file
^^^^^^^^^^^^^^^^^^^
Set the index file. In this case, ``index.html`` is the default file
displayed when the site appears.
.. code-block:: console
$ swift post -m 'web-index:index.html' container
Enable file listing
^^^^^^^^^^^^^^^^^^^
Turn on file listing. If you do not set the index file, the URL displays
a list of the objects in the container. Instructions on styling the list
with a CSS follow.
.. code-block:: console
$ swift post -m 'web-listings: true' container
Enable CSS for file listing
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Style the file listing using a CSS.
.. code-block:: console
$ swift post -m 'web-listings-css:listings.css' container
.. _set_error_static_website:
Set error pages for static website
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can create and set custom error pages for visitors to your website;
currently, only 401 (Unauthorized) and 404 (Not Found) errors are
supported. To do this, set the metadata header,
``X-Container-Meta-Web-Error``.
Error pages are served with the status code pre-pended to the name of
the error page you set. For instance, if you set
``X-Container-Meta-Web-Error`` to ``error.html``, 401 errors will
display the page ``401error.html``. Similarly, 404 errors will display
``404error.html``. You must have both of these pages created in your
container when you set the ``X-Container-Meta-Web-Error`` metadata, or
your site will display generic error pages.
You only have to set the ``X-Container-Meta-Web-Error`` metadata once
for your entire static website.
Set error pages for static website request
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: console
$ swift post -m 'web-error:error.html' container
Any 2\ ``nn`` response indicates success.

139
doc/user-guide/source/cli-use-snapshots-to-migrate-instances.rst
View File

@ -1,139 +0,0 @@
==================================
Use snapshots to migrate instances
==================================
To use snapshots to migrate instances from OpenStack projects to clouds,
complete these steps.
In the source project:
#. :ref:`Create_a_snapshot_of_the_instance`
#. :ref:`Download_the_snapshot_as_an_image`
In the destination project:
#. :ref:`Import_the_snapshot_to_the_new_environment`
#. :ref:`Boot_a_new_instance_from_the_snapshot`
.. note::
Some cloud providers allow only administrators to perform this task.
.. _Create_a_snapshot_of_the_instance:
Create a snapshot of the instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Shut down the source VM before you take the snapshot to ensure that all
data is flushed to disk. If necessary, list the instances to view the
instance name:
.. code-block:: console
$ openstack server list
+--------------------------------------+------------+--------+------------------------------+------------+
| ID | Name | Status | Networks | Image Name |
+--------------------------------------+------------+--------+------------------------------+------------+
| c41f3074-c82a-4837-8673-fa7e9fea7e11 | myInstance | ACTIVE | private=10.0.0.3 | cirros |
+--------------------------------------+------------+--------+------------------------------+------------+
#. Use the :command:`openstack server stop` command to shut down the instance:
.. code-block:: console
$ openstack server stop myInstance
#. Use the :command:`openstack server list` command to confirm that the
instance shows a ``SHUTOFF`` status:
.. code-block:: console
$ openstack server list
+--------------------------------------+------------+---------+------------------+------------+
| ID | Name | Status | Networks | Image Name |
+--------------------------------------+------------+---------+------------------+------------+
| c41f3074-c82a-4837-8673-fa7e9fea7e11 | myInstance | SHUTOFF | private=10.0.0.3 | cirros |
+--------------------------------------+------------+---------+------------------+------------+
#. Use the :command:`openstack server image create` command to take a snapshot:
.. code-block:: console
$ openstack server image create myInstance --name myInstanceSnapshot
The above command creates the image ``myInstance`` by taking a snapshot
of a running server.
#. Use the :command:`openstack image list` command to check the status
until the status is ``active``:
.. code-block:: console
$ openstack image list
+--------------------------------------+---------------------------------+--------+
| ID | Name | Status |
+--------------------------------------+---------------------------------+--------+
| 657ebb01-6fae-47dc-986a-e49c4dd8c433 | cirros-0.3.5-x86_64-uec | active |
| 72074c6d-bf52-4a56-a61c-02a17bf3819b | cirros-0.3.5-x86_64-uec-kernel | active |
| 3c5e5f06-637b-413e-90f6-ca7ed015ec9e | cirros-0.3.5-x86_64-uec-ramdisk | active |
| f30b204e-1ce6-40e7-b8d9-b353d4d84e7d | myInstanceSnapshot | active |
+--------------------------------------+---------------------------------+--------+
.. _Download_the_snapshot_as_an_image:
Download the snapshot as an image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Get the image ID:
.. code-block:: console
$ openstack image list
+-------------------+-------------------+--------+
| ID | Name | Status |
+-------------------+-------------------+--------+
| f30b204e-1ce6... | myInstanceSnapshot| active |
+-------------------+-------------------+--------+
#. Download the snapshot by using the image ID that was returned in the
previous step:
.. code-block:: console
$ openstack image save --file snapshot.raw f30b204e-1ce6-40e7-b8d9-b353d4d84e7d
.. note::
The :command:`openstack image save` command requires the image ID or
the image name.
Check there is sufficient space on the destination file system for
the image file.
#. Make the image available to the new environment, either through HTTP or
direct upload to a machine (``scp``).
.. _Import_the_snapshot_to_the_new_environment:
Import the snapshot to the new environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the new project or cloud environment, import the snapshot:
.. code-block:: console
$ openstack image create NEW_IMAGE_NAME \
--container-format bare --disk-format qcow2 --file IMAGE_URL
.. _Boot_a_new_instance_from_the_snapshot:
Boot a new instance from the snapshot
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the new project or cloud environment, use the snapshot to create the
new instance:
.. code-block:: console
$ openstack server create --flavor m1.tiny --image myInstanceSnapshot myNewInstance

27
doc/user-guide/source/cli.rst
View File

@ -1,27 +0,0 @@
==============================
OpenStack command-line clients
==============================
.. toctree::
:maxdepth: 2
common/cli-overview.rst
common/cli-install-openstack-command-line-clients.rst
common/cli-discover-version-number-for-a-client.rst
common/cli-set-environment-variables-using-openstack-rc.rst
common/cli-manage-images.rst
cli-manage-images-curl.rst
common/cli-manage-volumes.rst
cli-manage-shares.rst
cli-nova-configure-access-security-for-instances.rst
cli-launch-instances.rst
cli-manage-instances-hosts.rst
cli-provide-user-data-to-instances.rst
cli-use-snapshots-to-migrate-instances.rst
cli-config-drive.rst
cli-create-and-manage-networks.rst
managing-openstack-object-storage-with-swift-cli.rst
cli-create-and-manage-stacks.rst
cli-ceilometer.rst
trove-manage-db.rst
database-module-usage.rst

1
doc/user-guide/source/common
View File

@ -1 +0,0 @@
../../common

307
doc/user-guide/source/conf.py
View File

@ -1,307 +0,0 @@
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import os
# import sys
import openstackdocstheme
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['openstackdocstheme']
# Add any paths that contain templates here, relative to this directory.
# templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
repository_name = "openstack/openstack-manuals"
bug_project = 'openstack-manuals'
project = u'End User Guide'
bug_tag = u'user-guide'
copyright = u'2015-2017, OpenStack contributors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '15.0'
# The full version, including alpha/beta/rc tags.
release = '15.0.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['common/nova*', 'common/get-started-*']
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'openstackdocs'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = [openstackdocstheme.get_html_theme_path()]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = []
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
# So that we can enable "log-a-bug" links from each output HTML page, this
# variable must be set to a format that includes year, month, day, hours and
# minutes.
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
html_use_index = False
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
html_show_sourcelink = False
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'user-guide'
# If true, publish source files
html_copy_source = False
# -- Options for linkcheck ------------------------------------------------
linkcheck_ignore = [r'https://build.opensuse.org']
# -- Options for LaTeX output ---------------------------------------------
pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
openstack_logo = openstackdocstheme.get_openstack_logo_path()
latex_custom_template = r"""
\newcommand{\openstacklogo}{%s}
\usepackage{%s}
""" % (openstack_logo, pdf_theme_path)
latex_engine = 'xelatex'
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
'pointsize': '11pt',
#Default figure align
'figure_align': 'H',
# Not to generate blank page after chapter
'classoptions': ',openany',
# Additional stuff for the LaTeX preamble.
'preamble': latex_custom_template,
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'UserGuide.tex', u'User Guide',
u'OpenStack contributors', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'userguide', u'User Guide',
[u'OpenStack contributors'], 1)
]
# If true, show URL addresses after external links.
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'UserGuide', u'User Guide',
u'OpenStack contributors', 'UserGuide',
'This guide shows OpenStack end users how to create and manage resources '
'in an OpenStack cloud with the OpenStack dashboard and OpenStack client '
'commands.', 'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
# texinfo_appendices = []
# If false, no module index is generated.
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False
# -- Options for Internationalization output ------------------------------
locale_dirs = ['locale/']
# -- Options for PDF output --------------------------------------------------
pdf_documents = [
('index', u'UserGuides', u'End User Guide', u'OpenStack contributors')
]

224
doc/user-guide/source/configure-access-and-security-for-instances.rst
View File

@ -1,224 +0,0 @@
===========================================
Configure access and security for instances
===========================================
Before you launch an instance, you should add security group rules to
enable users to ping and use SSH to connect to the instance. Security
groups are sets of IP filter rules that define networking access and are
applied to all instances within a project. To do so, you either add
rules to the default security group :ref:`security_groups_add_rule`
or add a new security group with rules.
Key pairs are SSH credentials that are injected into an instance when it
is launched. To use key pair injection, the image that the instance is
based on must contain the ``cloud-init`` package. Each project should
have at least one key pair. For more information, see the section
:ref:`keypair_add`.
If you have generated a key pair with an external tool, you can import
it into OpenStack. The key pair can be used for multiple instances that
belong to a project. For more information, see the section
:ref:`dashboard_import_keypair`.
.. note::
A key pair belongs to an individual user, not to a project.
To share a key pair across multiple users, each user
needs to import that key pair.
When an instance is created in OpenStack, it is automatically assigned a
fixed IP address in the network to which the instance is assigned. This
IP address is permanently associated with the instance until the
instance is terminated. However, in addition to the fixed IP address, a
floating IP address can also be attached to an instance. Unlike fixed IP
addresses, floating IP addresses are able to have their associations
modified at any time, regardless of the state of the instances involved.
.. _security_groups_add_rule:
Add a rule to the default security group
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This procedure enables SSH and ICMP (ping) access to instances. The
rules apply to all instances within a given project, and should be set
for every project unless there is a reason to prohibit SSH or ICMP
access to the instances.
This procedure can be adjusted as necessary to add additional security
group rules to a project, if your cloud requires them.
.. note::
When adding a rule, you must specify the protocol used with the
destination port or source port.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Access & Security` category. The
:guilabel:`Security Groups` tab shows the security groups that are
available for this project.
#. Select the default security group and click :guilabel:`Manage Rules`.
#. To allow SSH access, click :guilabel:`Add Rule`.
#. In the :guilabel:`Add Rule` dialog box, enter the following values:
* **Rule**: ``SSH``
* **Remote**: ``CIDR``
* **CIDR**: ``0.0.0.0/0``
.. note::
To accept requests from a particular range of IP
addresses, specify the IP address block in the
:guilabel:`CIDR` box.
#. Click :guilabel:`Add`.
Instances will now have SSH port 22 open for requests from any IP
address.
#. To add an ICMP rule, click :guilabel:`Add Rule`.
#. In the :guilabel:`Add Rule` dialog box, enter the following values:
* **Rule**: ``All ICMP``
* **Direction**: ``Ingress``
* **Remote**: ``CIDR``
* **CIDR**: ``0.0.0.0/0``
#. Click :guilabel:`Add`.
Instances will now accept all incoming ICMP packets.
.. _keypair_add:
Add a key pair
~~~~~~~~~~~~~~
Create at least one key pair for each project.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Access & Security` category.
#. Click the :guilabel:`Key Pairs` tab, which shows the key pairs that
are available for this project.
#. Click :guilabel:`Create Key Pair`.
#. In the :guilabel:`Create Key Pair` dialog box, enter a name for your
key pair, and click :guilabel:`Create Key Pair`.
#. Respond to the prompt to download the key pair.
.. _dashboard_import_keypair:
Import a key pair
~~~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Access & Security` category.
#. Click the :guilabel:`Key Pairs` tab, which shows the key pairs that
are available for this project.
#. Click :guilabel:`Import Key Pair`.
#. In the :guilabel:`Import Key Pair` dialog box, enter the name of your
key pair, copy the public key into the :guilabel:`Public Key` box,
and then click :guilabel:`Import Key Pair`.
#. Save the ``*.pem`` file locally.
#. To change its permissions so that only you can read and write to the
file, run the following command:
.. code-block:: console
$ chmod 0600 yourPrivateKey.pem
.. note::
If you are using the Dashboard from a Windows computer, use PuTTYgen
to load the ``*.pem`` file and convert and save it as ``*.ppk``. For
more information see the `WinSCP web page for
PuTTYgen <http://winscp.net/eng/docs/ui_puttygen>`__.
#. To make the key pair known to SSH, run the :command:`ssh-add` command.
.. code-block:: console
$ ssh-add yourPrivateKey.pem
The Compute database registers the public key of the key pair.
The Dashboard lists the key pair on the :guilabel:`Access & Security` tab.
Allocate a floating IP address to an instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When an instance is created in OpenStack, it is automatically assigned a
fixed IP address in the network to which the instance is assigned. This
IP address is permanently associated with the instance until the
instance is terminated.
However, in addition to the fixed IP address, a floating IP address can
also be attached to an instance. Unlike fixed IP addresses, floating IP
addresses can have their associations modified at any time, regardless
of the state of the instances involved. This procedure details the
reservation of a floating IP address from an existing pool of addresses
and the association of that address with a specific instance.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Access & Security` category.
#. Click the :guilabel:`Floating IPs` tab, which shows the floating IP
addresses allocated to instances.
#. Click :guilabel:`Allocate IP To Project`.
#. Choose the pool from which to pick the IP address.
#. Click :guilabel:`Allocate IP`.
#. In the :guilabel:`Floating IPs` list, click :guilabel:`Associate`.
#. In the :guilabel:`Manage Floating IP Associations` dialog box,
choose the following options:
- The :guilabel:`IP Address` field is filled automatically,
but you can add a new IP address by clicking the
:guilabel:`+` button.
- In the :guilabel:`Port to be associated` field, select a port
from the list.
The list shows all the instances with their fixed IP addresses.
#. Click :guilabel:`Associate`.
.. note::
To disassociate an IP address from an instance, click the
:guilabel:`Disassociate` button.
To release the floating IP address back into the floating IP pool, click
the :guilabel:`Release Floating IP` option in the :guilabel:`Actions` column.

176
doc/user-guide/source/create-db.rst
View File

@ -1,176 +0,0 @@
.. _create_db:
============================
Create and access a database
============================
Assume that you have installed the Database service and populated your
data store with images for the type and versions of databases that you
want, and that you can create and access a database.
This example shows you how to create and access a MySQL 5.5 database.
Create and access a database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. **Determine which flavor to use for your database**
When you create a database instance, you must specify a nova flavor.
The flavor indicates various characteristics of the instance, such as
RAM and root volume size. You will need to create or
obtain new nova flavors that work for databases.
The first step is to list flavors by using the
:command:`openstack flavor list` command.
.. code-block:: console
$ openstack flavor list
Now take a look at the minimum requirements for various database
instances:
+--------------------+--------------------+--------------------+--------------------+
| Database | RAM (MB) | Disk (GB) | VCPUs |
+====================+====================+====================+====================+
| MySQL | 512 | 5 | 1 |
+--------------------+--------------------+--------------------+--------------------+
| Cassandra | 2048 | 5 | 1 |
+--------------------+--------------------+--------------------+--------------------+
| MongoDB | 1024 | 5 | 1 |
+--------------------+--------------------+--------------------+--------------------+
| Redis | 512 | 5 | 1 |
+--------------------+--------------------+--------------------+--------------------+
- If you have a custom flavor that meets the needs of the database
that you want to create, proceed to
:ref:`Step 2 <create-database-instance>` and use that flavor.
- If your environment does not have a suitable flavor, an
administrative user must create a custom flavor by using the
:command:`openstack flavor create` command.
**MySQL example.** This example creates a flavor that you can use
with a MySQL database. This example has the following attributes:
- Flavor name: ``mysql_minimum``
- Flavor ID: You must use an ID that is not already in use. In this
example, IDs 1 through 5 are in use, so use ID ``6``.
- RAM: ``512``
- Root volume size in GB: ``5``
- Virtual CPUs: ``1``
.. code-block:: console
$ openstack flavor create mysql-minimum --id 6 --ram 512 --disk 5 --vcpus 1
+----------------------------+---------------+
| Field | Value |
+----------------------------+---------------+
| OS-FLV-DISABLED:disabled | False |
| OS-FLV-EXT-DATA:ephemeral | 0 |
| disk | 5 |
| id | 6 |
| name | mysql-minimum |
| os-flavor-access:is_public | True |
| properties | |
| ram | 512 |
| rxtx_factor | 1.0 |
| swap | |
| vcpus | 1 |
+----------------------------+---------------+
.. _create-database-instance:
#. **Create a database instance**
This example creates a database instance with the following
characteristics:
- Name of the instance: ``mysql_instance_1``
- Database flavor: ``6``
In addition, this command specifies these options for the instance:
- A volume size of ``5`` (5 GB).
- The ``myDB`` database.
- The database is based on the ``mysql`` data store and the
``mysql-5.5`` datastore\_version.
- The ``userA`` user with the ``password`` password.
.. code-block:: console
$ trove create mysql_instance_1 6 --size 5 --databases myDB \
--users userA:password --datastore_version mysql-5.5 \
--datastore mysql
+-------------------+---------------------------------------------------------------------------------------t-----------------------------------------------------------------------------------------------------------------+
| Property | Value |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| created | 2014-05-29T21:26:21 |
| datastore | {u'version': u'mysql-5.5', u'type': u'mysql'} |
| datastore_version | mysql-5.5 |
| flavor | {u'id': u'6', u'links': [{u'href': u'https://controller:8779/v1.0/46d0bc4fc32e4b9e8520f8fc62199f58/flavors/6', u'rel': u'self'}, {u'href': u'https://controller:8779/flavors/6', u'rel': u'bookmark'}]} |
| id | 5599dad6-731e-44df-bb60-488da3da9cfe |
| name | mysql_instance_1 |
| status | BUILD |
| updated | 2014-05-29T21:26:21 |
| volume | {u'size': 5} |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
#. **Get the IP address of the database instance**
First, use the :command:`trove list` command to list all instances and
their IDs:
.. code-block:: console
$ trove list
+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+
| 5599dad6-731e-44df-bb60-488da3da9cfe | mysql_instance_1 | mysql | mysql-5.5 | BUILD | 6 | 5 |
+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+
This command returns the instance ID of your new instance.
You can now pass in the instance ID with the :command:`trove show` command
to get the IP address of the instance. In this example, replace
``INSTANCE_ID`` with ``5599dad6-731e-44df-bb60-488da3da9cfe``.
.. code-block:: console
$ trove show INSTANCE_ID
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-05-29T21:26:21 |
| datastore | mysql |
| datastore_version | mysql-5.5 |
| flavor | 6 |
| id | 5599dad6-731e-44df-bb60-488da3da9cfe |
| ip | 172.16.200.2 |
| name | mysql_instance_1 |
| status | BUILD |
| updated | 2014-05-29T21:26:54 |
| volume | 5 |
+-------------------+--------------------------------------+
This command returns the IP address of the database instance.
#. **Access the new database**
You can now access the new database you just created (myDB) by using
typical database access commands. In this MySQL example, replace
``IP_ADDRESS`` with ``172.16.200.2``.
.. code-block:: console
$ mysql -u userA -p password -h IP_ADDRESS myDB

146
doc/user-guide/source/dashboard-create-networks.rst
View File

@ -1,146 +0,0 @@
==========================
Create and manage networks
==========================
The OpenStack Networking service provides a scalable system for managing
the network connectivity within an OpenStack cloud deployment. It can
easily and quickly react to changing network needs (for example,
creating and assigning new IP addresses).
Networking in OpenStack is complex. This section provides the basic
instructions for creating a network and a router. For detailed
information about managing networks, refer to the `OpenStack
Administrator
Guide <https://docs.openstack.org/admin-guide/networking.html>`__.
Create a network
~~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Network` tab and
click :guilabel:`Networks` category.
#. Click :guilabel:`Create Network`.
#. In the :guilabel:`Create Network` dialog box, specify the following values.
:guilabel:`Network` tab
:guilabel:`Network Name`: Specify a name to identify the network.
:guilabel:`Shared`: Share the network with other projects. Non admin users
are not allowed to set shared option.
:guilabel:`Admin State`: The state to start the network in.
:guilabel:`Create Subnet`: Select this check box to create a subnet
You do not have to specify a subnet when you create a network, but if
you do not specify a subnet, the network can not be attached to an instance.
:guilabel:`Subnet` tab
:guilabel:`Subnet Name`: Specify a name for the subnet.
:guilabel:`Network Address`: Specify the IP address for the subnet.
:guilabel:`IP Version`: Select IPv4 or IPv6.
:guilabel:`Gateway IP`: Specify an IP address for a specific gateway. This
parameter is optional.
:guilabel:`Disable Gateway`: Select this check box to disable a gateway IP
address.
:guilabel:`Subnet Details` tab
:guilabel:`Enable DHCP`: Select this check box to enable DHCP.
:guilabel:`Allocation Pools`: Specify IP address pools.
:guilabel:`DNS Name Servers`: Specify a name for the DNS server.
:guilabel:`Host Routes`: Specify the IP address of host routes.
#. Click :guilabel:`Create`.
The dashboard shows the network on the :guilabel:`Networks` tab.
Create a router
~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Network` tab and
click :guilabel:`Routers` category.
#. Click :guilabel:`Create Router`.
#. In the :guilabel:`Create Router` dialog box, specify a name for the router
and :guilabel:`External Network`, and click :guilabel:`Create Router`.
The new router is now displayed in the :guilabel:`Routers` tab.
#. To connect a private network to the newly created router, perform the
following steps:
A) On the :guilabel:`Routers` tab, click the name of the router.
B) On the :guilabel:`Router Details` page, click the :guilabel:`Interfaces`
tab, then click :guilabel:`Add Interface`.
C) In the :guilabel:`Add Interface` dialog box, select a :guilabel:`Subnet`.
Optionally, in the :guilabel:`Add Interface` dialog box, set an
:guilabel:`IP Address` for the router interface for the selected subnet.
If you choose not to set the :guilabel:`IP Address` value, then by
default OpenStack Networking uses the first host IP address in the
subnet.
The :guilabel:`Router Name` and :guilabel:`Router ID` fields are
automatically updated.
#. Click :guilabel:`Add Interface`.
You have successfully created the router. You can view the new topology
from the :guilabel:`Network Topology` tab.
Create a port
~~~~~~~~~~~~~
.. warning::
Creating and managing ports requires administrator privileges.
Contact an administrator before adding or changing ports.
#. Log in to the dashboard.
#. Select the appropriate project from the drop-down menu at the top left.
#. On the :guilabel:`Admin` tab, click :guilabel:`Networks` category.
#. Click on the :guilabel:`Network Name` of the network in which the port
has to be created.
#. In the :guilabel:`Create Port` dialog box, specify the following values.
:guilabel:`Name`: Specify name to identify the port.
:guilabel:`Device ID`: Device ID attached to the port.
:guilabel:`Device Owner`: Device owner attached to the port.
:guilabel:`Binding Host`: The ID of the host where the port is allocated.
:guilabel:`Binding VNIC Type`: Select the VNIC type that is bound to the
neutron port.
#. Click :guilabel:`Create Port`.
The new port is now displayed in the :guilabel:`Ports` list.

216
doc/user-guide/source/dashboard-databases.rst
View File

@ -1,216 +0,0 @@
===========================
Create and manage databases
===========================
The Database service provides scalable and reliable cloud provisioning
functionality for both relational and non-relational database engines.
Users can quickly and easily use database features without the burden of
handling complex administrative tasks.
.. _dashboard_create_db_instance:
Create a database instance
~~~~~~~~~~~~~~~~~~~~~~~~~~
**Prerequisites.** Before you create a database instance, you need to
configure a default datastore and make sure you have an appropriate
flavor for the type of database instance you want.
#. **Configure a default datastore.**
Because the dashboard does not let you choose a specific datastore to
use with an instance, you need to configure a default datastore. The
dashboard then uses the default datastore to create the instance.
#. Add the following line to ``/etc/trove/trove.conf``:
.. code-block:: console
default_datastore = DATASTORE_NAME
Replace ``DATASTORE_NAME`` with the name that the administrative
user set when issuing the :command:`trove-manage` command to create the
datastore. You can use the trove :command:`datastore-list` command to
display the datastores that are available in your environment.
For example, if your MySQL data store name is set to ``mysql``,
your entry would look like this:
.. code-block:: console
default_datastore = mysql
#. Restart Database services on the controller node:
.. code-block:: console
# service trove-api restart
# service trove-taskmanager restart
# service trove-conductor restart
#. **Verify flavor.**
Make sure an appropriate flavor exists for the type of
database instance you want.
**Create database instance.** Once you have configured a default
datastore and verified that you have an appropriate flavor, you can
create a database instance.
#. Log in to the dashboard.
#. From the CURRENT PROJECT on the :guilabel:`Project` tab, select the
appropriate project.
#. On the :guilabel:`Project` tab, open the :guilabel:`Database` tab and
click :guilabel:`Instances` category. This lists the instances that
already exist in your environment.
#. Click :guilabel:`Launch Instance`.
#. In the :guilabel:`Launch Database` dialog box, specify the following values.
Details
:guilabel:`Database Name`: Specify a name for the database instance.
:guilabel:`Flavor`: Select an appropriate flavor for the instance.
:guilabel:`Volume Size`: Select a volume size. Volume size is expressed in
GB.
:guilabel:`Initialize Databases`: Initial Database
Optionally provide a comma separated list of databases to create, for
example:
``database1``, ``database2``, ``database3``
:guilabel:`Initial Admin User`: Create an initial admin user. This user will
have access to all the databases you create.
:guilabel:`Password`: Specify a password associated with the initial admin
user you just named.
:guilabel:`Host`: Optionally, allow the user to connect only from this host.
If you do not specify a host, this user will be allowed to connect from
anywhere.
#. Click the :guilabel:`Launch` button. The new database instance appears in
the databases list.
Backup and restore a database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use Database services to backup a database and store the backup
artifact in the Object Storage service. Later on, if the original
database is damaged, you can use the backup artifact to restore the
database. The restore process creates a database instance.
This example shows you how to back up and restore a MySQL database.
To backup the database instance
-------------------------------
#. Log in to the dashboard.
#. From the CURRENT PROJECT on the :guilabel:`Project` tab, select the
appropriate project.
#. On the :guilabel:`Project` tab, open the :guilabel:`Database` tab and
click :guilabel:`Instances` category. This displays the existing
instances in your system.
#. Click :guilabel:`Create Backup`.
#. In the :guilabel:`Backup Database` dialog box, specify the following
values:
Name
Specify a name for the backup.
Database Instance
Select the instance you want to back up.
#. Click :guilabel:`Backup`. The new backup appears in the backup list.
To restore a database instance
------------------------------
Now assume that your original database instance is damaged and you
need to restore it. You do the restore by using your backup to create
a new database instance.
#. Log in to the dashboard.
#. From the CURRENT PROJECT on the :guilabel:`Project` tab, select the
appropriate project.
#. On the :guilabel:`Project` tab, open the :guilabel:`Database` tab and
click :guilabel:`Backups` category. This lists the available backups.
#. Check the backup you want to use and click :guilabel:`Restore Backup`.
#. In the :guilabel:`Launch Database` dialog box, specify the values you
want for the new database instance.
#. Click the :guilabel:`Restore From Database` tab and make sure that this
new instance is based on the correct backup.
#. Click :guilabel:`Launch`.
The new instance appears in the database instances list.
Update a database instance
~~~~~~~~~~~~~~~~~~~~~~~~~~
You can change various characteristics of a database instance,
such as its volume size and flavor.
To change the volume size of an instance
----------------------------------------
#. Log in to the dashboard.
#. From the CURRENT PROJECT on the :guilabel:`Project` tab, select the
appropriate project.
#. On the :guilabel:`Project` tab, open the :guilabel:`Database` tab and
click :guilabel:`Instances` category. This displays the existing
instances in your system.
#. Check the instance you want to work with.
In the :guilabel:`Actions` column, expand the drop down menu
and select :guilabel:`Resize Volume`.
#. In the :guilabel:`Resize Database Volume` dialog box,
fill in the :guilabel:`New Size` field with an integer indicating
the new size you want for the instance. Express the size in GB, and
note that the new size must be larger than the current size.
#. Click :guilabel:`Resize Database Volume`.
To change the flavor of an instance
-----------------------------------
#. Log in to the dashboard.
#. From the CURRENT PROJECT on the :guilabel:`Project` tab, select the
appropriate project.
#. On the :guilabel:`Project` tab, open the :guilabel:`Database` tab and
click :guilabel:`Instances` category. This displays the existing
instances in your system.
#. Check the instance you want to work with. In the
:guilabel:`Actions` column, expand the drop down menu and
select :guilabel:`Resize Instance`.
#. In the :guilabel:`Resize Database Instance` dialog box,
expand the drop down menu in the :guilabel:`New Flavor` field.
Select the new flavor you want for the instance.
#. Click :guilabel:`Resize Database Instance`.

295
doc/user-guide/source/dashboard-launch-instances.rst
View File

@ -1,295 +0,0 @@
===========================
Launch and manage instances
===========================
Instances are virtual machines that run inside the cloud.
You can launch an instance from the following sources:
* Images uploaded to the Image service.
* Image that you have copied to a persistent volume. The instance
launches from the volume, which is provided by the ``cinder-volume``
API through iSCSI.
* Instance snapshot that you took.
Launch an instance
~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Instances` category.
The dashboard shows the instances with its name, its private and
floating IP addresses, size, status, task, power state, and so on.
#. Click :guilabel:`Launch Instance`.
#. In the :guilabel:`Launch Instance` dialog box, specify the following values:
:guilabel:`Details` tab
Instance Name
Assign a name to the virtual machine.
Availability Zone
By default, this value is set to the availability zone given by the
cloud provider (for example, ``us-west`` or ``apac-south``). For some
cases, it could be ``nova``.
.. note::
The name you assign here becomes the initial host name of the server.
If the name is longer than 63 characters, the Compute service
truncates it automatically to ensure dnsmasq works correctly.
After the server is built, if you change the server name in the API
or change the host name directly, the names are not updated in the
dashboard.
Server names are not guaranteed to be unique when created so you
could have two instances with the same host name.
Count
To launch multiple instances, enter a value greater than ``1``. The
default is ``1``.
:guilabel:`Source` tab
Instance Boot Source
Your options are:
Boot from image
If you choose this option, a new field for :guilabel:`Image Name`
displays. You can select the image from the list.
Boot from snapshot
If you choose this option, a new field for :guilabel:`Instance
Snapshot` displays. You can select the snapshot from the list.
Boot from volume
If you choose this option, a new field for :guilabel:`Volume`
displays. You can select the volume from the list.
Boot from image (creates a new volume)
With this option, you can boot from an image and create a volume
by entering the :guilabel:`Device Size` and :guilabel:`Device
Name` for your volume. Click the :guilabel:`Delete Volume on
Instance Delete` option to delete the volume on deleting the
instance.
Boot from volume snapshot (creates a new volume)
Using this option, you can boot from a volume snapshot and create
a new volume by choosing :guilabel:`Volume Snapshot` from a list
and adding a :guilabel:`Device Name` for your volume. Click the
:guilabel:`Delete Volume on Instance Delete` option to delete the
volume on deleting the instance.
Image Name
This field changes based on your previous selection. If you have
chosen to launch an instance using an image, the :guilabel:`Image Name`
field displays. Select the image name from the dropdown list.
Instance Snapshot
This field changes based on your previous selection. If you have
chosen to launch an instance using a snapshot, the
:guilabel:`Instance Snapshot` field displays.
Select the snapshot name from the dropdown list.
Volume
This field changes based on your previous selection. If you have
chosen to launch an instance using a volume, the :guilabel:`Volume`
field displays. Select the volume name from the dropdown list.
If you want to delete the volume on instance delete,
check the :guilabel:`Delete Volume on Instance Delete` option.
:guilabel:`Flavor` tab
Flavor
Specify the size of the instance to launch.
.. note::
The flavor is selected based on the size of the image selected
for launching an instance. For example, while creating an image, if
you have entered the value in the :guilabel:`Minimum RAM (MB)` field
as 2048, then on selecting the image, the default flavor is
``m1.small``.
:guilabel:`Networks` tab
Selected Networks
To add a network to the instance, click the :guilabel:`+` in the
:guilabel:`Available` field.
:guilabel:`Network Ports` tab
Ports
Activate the ports that you want to assign to the instance.
:guilabel:`Security Groups` tab
Security Groups
Activate the security groups that you want to assign to the instance.
Security groups are a kind of cloud firewall that define which
incoming network traffic is forwarded to instances.
If you have not created any security groups, you can assign
only the default security group to the instance.
:guilabel:`Key Pair` tab
Key Pair
Specify a key pair.
If the image uses a static root password or a static key set
(neither is recommended), you do not need to provide a key pair
to launch the instance.
:guilabel:`Configuration` tab
Customization Script Source
Specify a customization script that runs after your instance
launches.
:guilabel:`Metadata` tab
Available Metadata
Add Metadata items to your instance.
#. Click :guilabel:`Launch Instance`.
The instance starts on a compute node in the cloud.
.. note::
If you did not provide a key pair, security groups, or rules, users
can access the instance only from inside the cloud through VNC. Even
pinging the instance is not possible without an ICMP rule configured.
You can also launch an instance from the :guilabel:`Images` or
:guilabel:`Volumes` category when you launch an instance from
an image or a volume respectively.
When you launch an instance from an image, OpenStack creates a local
copy of the image on the compute node where the instance starts.
For details on creating images, see `Creating images
manually <https://docs.openstack.org/image-guide/create-images-manually.html>`_
in the *OpenStack Virtual Machine Image Guide*.
When you launch an instance from a volume, note the following steps:
* To select the volume from which to launch, launch an instance from
an arbitrary image on the volume. The arbitrary image that you select
does not boot. Instead, it is replaced by the image on the volume that
you choose in the next steps.
To boot a Xen image from a volume, the image you launch in must be
the same type, fully virtualized or paravirtualized, as the one on
the volume.
* Select the volume or volume snapshot from which to boot. Enter a
device name. Enter ``vda`` for KVM images or ``xvda`` for Xen images.
.. note::
When running QEMU without support for the hardware virtualization, set
``cpu_mode="none"`` alongside ``virt_type=qemu`` in
``/etc/nova/nova-compute.conf`` to solve the following error:
.. code-block:: console
libvirtError: unsupported configuration: CPU mode 'host-model'
for ``x86_64`` qemu domain on ``x86_64`` host is not supported by hypervisor
Connect to your instance by using SSH
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To use SSH to connect to your instance, use the downloaded keypair
file.
.. note::
The user name is ``ubuntu`` for the Ubuntu cloud images on TryStack.
#. Copy the IP address for your instance.
#. Use the :command:`ssh` command to make a secure connection to the instance.
For example:
.. code-block:: console
$ ssh -i MyKey.pem ubuntu@10.0.0.2
#. At the prompt, type ``yes``.
It is also possible to SSH into an instance without an SSH keypair, if the
administrator has enabled root password injection. For more information
about root password injection, see `Injecting the administrator password
<https://docs.openstack.org/admin-guide/compute-admin-password-injection.html>`_
in the *OpenStack Administrator Guide*.
Track usage for instances
~~~~~~~~~~~~~~~~~~~~~~~~~
You can track usage for instances for each project. You can track costs
per month by showing meters like number of vCPUs, disks, RAM, and
uptime for all your instances.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Overview` category.
#. To query the instance usage for a month, select a month and click
:guilabel:`Submit`.
#. To download a summary, click :guilabel:`Download CSV Summary`.
Create an instance snapshot
~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click the :guilabel:`Instances` category.
#. Select the instance from which to create a snapshot.
#. In the actions column, click :guilabel:`Create Snapshot`.
#. In the :guilabel:`Create Snapshot` dialog box, enter a name for the
snapshot, and click :guilabel:`Create Snapshot`.
The :guilabel:`Images` category shows the instance snapshot.
To launch an instance from the snapshot, select the snapshot and click
:guilabel:`Launch`. Proceed with launching an instance.
Manage an instance
~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Instances` category.
#. Select an instance.
#. In the menu list in the actions column, select the state.
You can resize or rebuild an instance. You can also choose to view
the instance console log, edit instance or the security groups.
Depending on the current state of the instance, you can pause,
resume, suspend, soft or hard reboot, or terminate it.

284
doc/user-guide/source/dashboard-log-in.rst
View File

@ -1,284 +0,0 @@
=======================
Log in to the dashboard
=======================
The dashboard is generally installed on the controller node.
#. Ask the cloud operator for the host name or public IP address from
which you can access the dashboard, and for your user name and
password. If the cloud supports multi-domain model, you also need to
ask for your domain name.
#. Open a web browser that has JavaScript and cookies enabled.
.. note::
To use the Virtual Network Computing (VNC) client for the dashboard,
your browser must support HTML5 Canvas and HTML5 WebSockets. The VNC
client is based on noVNC. For details, see `noVNC: HTML5 VNC
Client <https://github.com/kanaka/noVNC/blob/master/README.md>`__.
For a list of supported browsers, see `Browser
support <https://github.com/kanaka/noVNC/wiki/Browser-support>`__.
#. In the address bar, enter the host name or IP address for the
dashboard, for example, ``https://ipAddressOrHostName/``.
.. note::
If a certificate warning appears when you try to access the URL for
the first time, a self-signed certificate is in use, which is not
considered trustworthy by default. Verify the certificate or add an
exception in the browser to bypass the warning.
#. On the :guilabel:`Log In` page, enter your user name and password, and
click :guilabel:`Sign In`. If the cloud supports multi-domain model, you
also need to enter your domain name.
The top of the window displays your user name. You can also access the
:guilabel:`Settings` tab (:ref:`dashboard-settings-tab`) or sign out
of the dashboard.
The visible tabs and functions in the dashboard depend on the access
permissions, or roles, of the user you are logged in as.
* If you are logged in as an end user, the :guilabel:`Project` tab
(:ref:`dashboard-project-tab`) and :guilabel:`Identity` tab
(:ref:`dashboard-identity-tab`) are displayed.
* If you are logged in as an administrator, the :guilabel:`Project` tab
(:ref:`dashboard-project-tab`) and :guilabel:`Admin` tab
(:ref:`dashboard-admin-tab`) and :guilabel:`Identity` tab
(:ref:`dashboard-identity-tab`) are displayed.
.. note::
Some tabs, such as :guilabel:`Orchestration` and :guilabel:`Firewalls`,
only appear on the dashboard if they are properly configured.
.. _dashboard-project-tab:
OpenStack dashboard — Project tab
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Projects are organizational units in the cloud and are also known as
tenants or accounts. Each user is a member of one or more projects.
Within a project, a user creates and manages instances.
From the :guilabel:`Project` tab, you can view and manage the resources in a
selected project, including instances and images. You can select the project
from the drop-down menu at the top left. If the cloud supports multi-domain
model, you can also select the domain from this menu.
.. figure:: figures/dashboard_project_tab.png
:width: 100%
**Figure: Project tab**
From the :guilabel:`Project` tab, you can access the following categories:
Compute tab
-----------
* :guilabel:`Overview`: View reports for the project.
* :guilabel:`Instances`: View, launch, create a snapshot from, stop, pause,
or reboot instances, or connect to them through VNC.
* :guilabel:`Volumes`: Use the following tabs to complete these tasks:
* :guilabel:`Volumes`: View, create, edit, and delete volumes.
* :guilabel:`Volume Snapshots`: View, create, edit, and delete volume
snapshots.
* :guilabel:`Images`: View images and instance snapshots created by project
users, plus any images that are publicly available. Create, edit, and
delete images, and launch instances from images and snapshots.
* :guilabel:`Access & Security`: Use the following tabs to complete these
tasks:
* :guilabel:`Security Groups`: View, create, edit, and delete security
groups and security group rules.
* :guilabel:`Key Pairs`: View, create, edit, import, and delete key pairs.
* :guilabel:`Floating IPs`: Allocate an IP address to or release it from a
project.
* :guilabel:`API Access`: View API endpoints.
* :guilabel:`Shares`: Use the following tabs to complete these tasks:
* :guilabel:`Shares`: View, create, manage, and delete shares.
* :guilabel:`Snapshots`: View, manage, and delete volume snapshots.
* :guilabel:`Share Networks`: View, manage, and delete share networks.
* :guilabel:`Security Services`: View, manage, and delete security services.
Network tab
-----------
* :guilabel:`Network Topology`: View the network topology.
* :guilabel:`Networks`: Create and manage public and private networks.
* :guilabel:`Routers`: Create and manage routers.
* :guilabel:`Load Balancers`: Create and manage load balancers.
* :guilabel:`Pools`: Add and manage pools.
* :guilabel:`Members`: Add and manage members.
* :guilabel:`Monitors`: Add and manage monitors.
* :guilabel:`Firewalls`: Create and manage firewalls.
* :guilabel:`Firewalls`: Create and manage firewalls.
* :guilabel:`Firewall Policies`: Add and manage firewall policies.
* :guilabel:`Firewall Rules`: Add and manage firewall rules.
Orchestration tab
-----------------
* :guilabel:`Stacks`: Use the REST API to orchestrate multiple composite
cloud applications.
* :guilabel:`Resource Types`: Show a list of all the supported resource
types for HOT templates.
Object Store tab
----------------
* :guilabel:`Containers`: Create and manage containers and objects.
.. _dashboard-admin-tab:
OpenStack dashboard — Admin tab
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Administrative users can use the :guilabel:`Admin` tab to view usage and to
manage instances, volumes, flavors, images, networks, and so on.
.. figure:: figures/dashboard_admin_tab.png
:width: 100%
**Figure: Admin tab**
From the :guilabel:`Admin` tab, you can access the following category
to complete these tasks:
System tab
----------
* :guilabel:`Overview`: View basic reports.
* :guilabel:`Resource Usage`: Use the following tabs to view the following
usages:
* :guilabel:`Usage Report`: View the usage report.
* :guilabel:`Stats`: View the statistics of all resources.
* :guilabel:`Hypervisors`: View the hypervisor summary.
* :guilabel:`Host Aggregates`: View, create, and edit host aggregates.
View the list of availability zones.
* :guilabel:`Instances`: View, pause, resume, suspend, migrate, soft or hard
reboot, and delete running instances that belong to users of some, but not
all, projects. Also, view the log for an instance or access an instance
through VNC.
* :guilabel:`Volumes`: Use the following tabs to complete these tasks:
* :guilabel:`Volumes`: View, create, manage, and delete volumes.
* :guilabel:`Volume Types`: View, create, manage, and delete volume types.
* :guilabel:`Volume Snapshots`: View, manage, and delete volume snapshots.
* :guilabel:`Flavors`: View, create, edit, view extra specifications for,
and delete flavors. A flavor is the size of an instance.
* :guilabel:`Images`: View, create, edit properties for, and delete custom
images.
* :guilabel:`Networks`: View, create, edit properties for, and delete
networks.
* :guilabel:`Routers`: View, create, edit properties for, and delete routers.
* :guilabel:`Defaults`: View default quota values. Quotas are hard-coded in
OpenStack Compute and define the maximum allowable size and number of
resources.
* :guilabel:`Metadata Definitions`: Import namespace and view the metadata
information.
* :guilabel:`System Information`: Use the following tabs to view the service
information:
* :guilabel:`Services`: View a list of the services.
* :guilabel:`Compute Services`: View a list of all Compute services.
* :guilabel:`Block Storage Services`: View a list of all Block Storage
services.
* :guilabel:`Network Agents`: View the network agents.
* :guilabel:`Orchestration Services`: View a list of all Orchestration
services.
* :guilabel:`Shares`: Use the following tabs to complete these tasks:
* :guilabel:`Shares`: View, create, manage, and delete shares.
* :guilabel:`Snapshots`: View, manage, and delete volume snapshots.
* :guilabel:`Share Networks`: View, manage, and delete share networks.
* :guilabel:`Security Services`: View, manage, and delete security services.
* :guilabel:`Share Types`: View, create, manage, and delete share types.
* :guilabel:`Share Servers`: View, manage, and delete share servers.
.. _dashboard-identity-tab:
OpenStack dashboard — Identity tab
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. figure:: figures/dashboard_identity_tab.png
:width: 100%
**Figure:Identity tab**
* :guilabel:`Projects`: View, create, assign users to, remove users from,
and delete projects.
* :guilabel:`Users`: View, create, enable, disable, and delete users.
.. _dashboard-settings-tab:
OpenStack dashboard — Settings tab
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. figure:: figures/dashboard_settings_tab.png
:width: 100%
**Figure:Settings tab**
Click the :guilabel:`Settings` button from the user drop down menu at the
top right of any page, you will see the :guilabel:`Settings` tab.
* :guilabel:`User Settings`: View and manage dashboard settings.
* :guilabel:`Change Password`: Change the password of the user.

181
doc/user-guide/source/dashboard-manage-containers.rst
View File

@ -1,181 +0,0 @@
===================================
Create and manage object containers
===================================
OpenStack Object Storage (swift) is used for redundant, scalable data storage
using clusters of standardized servers to store petabytes of accessible data.
It is a long-term storage system for large amounts of static data which can be
retrieved and updated.
OpenStack Object Storage provides a distributed, API-accessible storage
platform that can be integrated directly into an application or used to
store any type of file, including VM images, backups, archives, or media
files. In the OpenStack dashboard, you can only manage containers and
objects.
In OpenStack Object Storage, containers provide storage for objects in a
manner similar to a Windows folder or Linux file directory, though they
cannot be nested. An object in OpenStack consists of the file to be
stored in the container and any accompanying metadata.
Create a container
~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Object Store` tab and
click :guilabel:`Containers` category.
#. Click :guilabel:`Container`.
#. In the :guilabel:`Create Container` dialog box, enter a name for the
container, and then click :guilabel:`Create`.
You have successfully created a container.
.. note::
To delete a container, click the :guilabel:`More` button and select
:guilabel:`Delete Container`.
Upload an object
~~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Object Store` tab and
click :guilabel:`Containers` category.
#. Select the container in which you want to store your object.
#. Click the :guilabel:`Upload File` icon.
The :guilabel:`Upload File To Container: <name>` dialog box
appears.
``<name>`` is the name of the container to which you are uploading
the object.
#. Enter a name for the object.
#. Browse to and select the file that you want to upload.
#. Click :guilabel:`Upload File`.
You have successfully uploaded an object to the container.
.. note::
To delete an object, click the :guilabel:`More button` and select
:guilabel:`Delete Object`.
Manage an object
~~~~~~~~~~~~~~~~
**To edit an object**
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Object Store` tab and
click :guilabel:`Containers` category.
#. Select the container in which you want to store your object.
#. Click the menu button and choose :guilabel:`Edit` from the dropdown list.
The :guilabel:`Edit Object` dialog box is displayed.
#. Browse to and select the file that you want to upload.
#. Click :guilabel:`Update Object`.
.. note::
To delete an object, click the menu button and select
:guilabel:`Delete Object`.
**To copy an object from one container to another**
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Object Store` tab and
click :guilabel:`Containers` category.
#. Select the container in which you want to store your object.
#. Click the menu button and choose :guilabel:`Copy` from the dropdown list.
#. In the :guilabel:`Copy Object` launch dialog box, enter the following
values:
* :guilabel:`Destination Container`: Choose the destination container from
the list.
* :guilabel:`Path`: Specify a path in which the new copy should be stored
inside of the selected container.
* :guilabel:`Destination object name`: Enter a name for the object in the
new container.
#. Click :guilabel:`Copy Object`.
**To create a metadata-only object without a file**
You can create a new object in container without a file available and
can upload the file later when it is ready. This temporary object acts a
place-holder for a new object, and enables the user to share object
metadata and URL info in advance.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Object Store` tab and
click :guilabel:`Containers` category.
#. Select the container in which you want to store your object.
#. Click :guilabel:`Upload Object`.
The :guilabel:`Upload Object To Container`: ``<name>`` dialog box is
displayed.
``<name>`` is the name of the container to which you are uploading
the object.
#. Enter a name for the object.
#. Click :guilabel:`Update Object`.
**To create a pseudo-folder**
Pseudo-folders are similar to folders in your desktop operating system.
They are virtual collections defined by a common prefix on the object's
name.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Object Store` tab and
click :guilabel:`Containers` category.
#. Select the container in which you want to store your object.
#. Click :guilabel:`Create Pseudo-folder`.
The :guilabel:`Create Pseudo-Folder in Container` ``<name>`` dialog box
is displayed. ``<name>`` is the name of the container to which you
are uploading the object.
#. Enter a name for the pseudo-folder.
A slash (/) character is used as the delimiter for pseudo-folders in
Object Storage.
#. Click :guilabel:`Create`.

144
doc/user-guide/source/dashboard-manage-images.rst
View File

@ -1,144 +0,0 @@
========================
Upload and manage images
========================
A virtual machine image, referred to in this document simply
as an image, is a single file that contains a virtual disk that
has a bootable operating system installed on it. Images are used
to create virtual machine instances within the cloud. For information
about creating image files, see the `OpenStack Virtual Machine
Image Guide <https://docs.openstack.org/image-guide/>`_.
Depending on your role, you may have permission to upload and manage
virtual machine images. Operators might restrict the upload and
management of images to cloud administrators or operators only. If you
have the appropriate privileges, you can use the dashboard to upload and
manage images in the admin project.
.. note::
You can also use the :command:`openstack` and :command:`glance`
command-line clients or the Image service to manage images.
For more information see :doc:`../common/cli-manage-images`.
Upload an image
~~~~~~~~~~~~~~~
Follow this procedure to upload an image to a project:
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Images` category.
#. Click :guilabel:`Create Image`.
The :guilabel:`Create An Image` dialog box appears.
.. figure:: figures/create_image.png
**Dashboard — Create Image**
#. Enter the following values:
+-------------------------------+---------------------------------+
| :guilabel:`Image Name` | Enter a name for the image. |
+-------------------------------+---------------------------------+
| :guilabel:`Image Description` | Enter a brief description of |
| | the image. |
+-------------------------------+---------------------------------+
| :guilabel:`Image Source` | Choose the image source from |
| | the dropdown list. Your choices |
| | are :guilabel:`Image Location` |
| | and :guilabel:`Image File`. |
+-------------------------------+---------------------------------+
| :guilabel:`Image File` or | Based on your selection for |
| :guilabel:`Image Location` | :guilabel:`Image Source`, you |
| | either enter the location URL |
| | of the image in the |
| | :guilabel:`Image Location` |
| | field, or browse for the image |
| | file on your file system and |
| | add it. |
+-------------------------------+---------------------------------+
| :guilabel:`Format` | Select the image format (for |
| | example, QCOW2) for the image. |
+-------------------------------+---------------------------------+
| :guilabel:`Architecture` | Specify the architecture. For |
| | example, ``i386`` for a 32-bit |
| | architecture or ``x86_64`` for |
| | a 64-bit architecture. |
+-------------------------------+---------------------------------+
| :guilabel:`Minimum Disk (GB)` | Leave this field empty. |
+-------------------------------+---------------------------------+
| :guilabel:`Minimum RAM (MB)` | Leave this field empty. |
+-------------------------------+---------------------------------+
| :guilabel:`Copy Data` | Specify this option to copy |
| | image data to the Image service.|
+-------------------------------+---------------------------------+
| :guilabel:`Visibility` | The access permission for the |
| | image. |
| | ``Public`` or ``Private``. |
+-------------------------------+---------------------------------+
| :guilabel:`Protected` | Select this check box to ensure |
| | that only users with |
| | permissions can delete the |
| | image. ``Yes`` or ``No``. |
+-------------------------------+---------------------------------+
| :guilabel:`Image Metadata` | Specify this option to add |
| | resource metadata. The glance |
| | Metadata Catalog provides a list|
| | of metadata image definitions. |
| | (Note: Not all cloud providers |
| | enable this feature.) |
+-------------------------------+---------------------------------+
#. Click :guilabel:`Create Image`.
The image is queued to be uploaded. It might take some time before
the status changes from Queued to Active.
Update an image
~~~~~~~~~~~~~~~
Follow this procedure to update an existing image.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. Select the image that you want to edit.
#. In the :guilabel:`Actions` column, click the menu button and then
select :guilabel:`Edit Image` from the list.
#. In the :guilabel:`Edit Image` dialog box, you can perform various
actions. For example:
* Change the name of the image.
* Select the :guilabel:`Public` check box to make the image public.
* Clear the :guilabel:`Public` check box to make the image private.
#. Click :guilabel:`Edit Image`.
Delete an image
~~~~~~~~~~~~~~~
Deletion of images is permanent and **cannot** be reversed. Only users
with the appropriate permissions can delete images.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Images` category.
#. Select the images that you want to delete.
#. Click :guilabel:`Delete Images`.
#. In the :guilabel:`Confirm Delete Images` dialog box, click
:guilabel:`Delete Images` to confirm the deletion.

85
doc/user-guide/source/dashboard-manage-lbaasv2.rst
View File

@ -1,85 +0,0 @@
=================================
View and manage load balancers v2
=================================
Load-Balancer-as-a-Service (LBaaS) enables networking to distribute incoming
requests evenly among designated instances. This distribution ensures that
the workload is shared predictably among instances and enables more effective
use of system resources. Use one of these load-balancing methods to distribute
incoming requests:
* Round robin: Rotates requests evenly between multiple instances.
* Source IP: Requests from a unique source IP address are consistently
directed to the same instance.
* Least connections: Allocates requests to the instance with the
least number of active connections.
As an end user, you can create and manage load balancers and related
objects for users in various projects. You can also delete load balancers
and related objects.
LBaaS v2 has several new concepts to understand:
Load balancer
The load balancer occupies a neutron network port and
has an IP address assigned from a subnet.
Listener
Each port that listens for traffic on a particular load balancer is
configured separately and tied to the load balancer. Multiple listeners can
be associated with the same load balancer.
Pool
A pool is a group of hosts that sits behind the load balancer and
serves traffic through the load balancer.
Member
Members are the actual IP addresses that receive traffic from
the load balancer. Members are associated with pools.
Health monitor
Members may go offline from time to time and health monitors
diverts traffic away from members that are not responding properly.
Health monitors are associated with pools.
View existing load balancers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Log in to the OpenStack dashboard.
#. On the :guilabel:`Project` tab, open the
:guilabel:`Network` tab, and click the
:guilabel:`Load Balancers` category.
This view shows the list of existing load balancers. To view details
of any of the load balancers, click on the specific load balancer.
Create a load balancer
~~~~~~~~~~~~~~~~~~~~~~
#. Log in to the OpenStack dashboard.
#. On the :guilabel:`Project` tab, open the
:guilabel:`Network` tab, and click the
:guilabel:`Load Balancers` category.
#. Click the :guilabel:`Create Load Balancer` button.
Use the concepts described in the overview section to fill in
the necessary information about the load balancer you want to create.
Keep in mind, the health checks routinely run against each instance
within a target load balancer and the result of the health check is
used to determine if the instance receives new connections.
.. note::
A message indicates whether the action succeeded.
Delete a load balancer
~~~~~~~~~~~~~~~~~~~~~~
#. Select the load balancer you want to delete
and click the :guilabel:`Delete Load Balancer` button.
To be deleted successfully, a load balancer must not
have any listeners or pools associated with
it. The delete action is also available in the
:guilabel:`Actions` column for the individual load balancers.

242
doc/user-guide/source/dashboard-manage-shares.rst
View File

@ -1,242 +0,0 @@
=========================
Create and manage shares
=========================
Shares are file storage that you provide access to instances. You can allow
access to a share to a running instance or deny access to a share and allow
access to it to another instance at any time. You can also delete a share.
You can create snapshot from a share if the driver supports it. Only
administrative users can create share types.
Create a share
~~~~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, and click :guilabel:`Shares`.
#. Click :guilabel:`Create Share`.
In the dialog box that opens, enter or select the following values.
:guilabel:`Share Name`: Specify a name for the share.
:guilabel:`Description`: Optionally, provide a brief description for the
share.
:guilabel:`Share Type`: Choose a share type.
:guilabel:`Size (GB)`: The size of the share in gibibytes (GiB).
:guilabel:`Share Protocol`: Select NFS, CIFS, GlusterFS, or HDFS.
:guilabel:`Share Network`: Choose a share network.
:guilabel:`Metadata`: Enter metadata for the share creation if needed.
#. Click :guilabel:`Create Share`.
The dashboard shows the share on the :guilabel:`Shares` tab.
Delete a share
~~~~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, and click :guilabel:`Shares`.
#. Select the check boxes for the shares that you want to delete.
#. Click :guilabel:`Delete Shares` and confirm your choice.
A message indicates whether the action was successful.
Allow access
~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, and click :guilabel:`Shares`.
#. Go to the share that you want to allow access and choose
:guilabel:`Manage Rules` from Actions.
#. Click :guilabel:`Add rule`.
:guilabel:`Access Type`: Choose ip, user, or cert.
:guilabel:`Access Level`: Choose read-write or read-only.
:guilabel:`Access To`: Fill in Access To field.
#. Click :guilabel:`Add Rule`.
A message indicates whether the action was successful.
Deny access
~~~~~~~~~~~
#. Log in to the dashboard, choose a project, and click :guilabel:`Shares`.
#. Go to the share that you want to deny access and choose
:guilabel:`Manage Rules` from Actions.
#. Choose the rule you want to delete.
#. Click :guilabel:`Delete rule` and confirm your choice.
A message indicates whether the action was successful.
Edit share metadata
~~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, and click :guilabel:`Shares`.
#. Go to the share that you want to edit and choose
:guilabel:`Edit Share Metadata` from Actions.
#. :guilabel:`Metadata`: To add share metadata, use key=value. To unset
metadata, use key.
#. Click :guilabel:`Edit Share Metadata`.
A message indicates whether the action was successful.
Edit share
~~~~~~~~~~
#. Log in to the dashboard, choose a project, and click :guilabel:`Shares`.
#. Go to the share that you want to edit and choose :guilabel:`Edit Share` from
Actions.
#. :guilabel:`Share Name`: Enter a new share name.
#. :guilabel:`Description`: Enter a new description.
#. Click :guilabel:`Edit Share`.
A message indicates whether the action was successful.
Extend share
~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, and click :guilabel:`Shares`.
#. Go to the share that you want to edit and choose :guilabel:`Extend Share`
from Actions.
#. :guilabel:`New Size (GB)`: Enter new size.
#. Click :guilabel:`Extend Share`.
A message indicates whether the action was successful.
Create share network
~~~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, click :guilabel:`Shares`,
and click :guilabel:`Share Networks`.
#. Click :guilabel:`Create Share Network`.
In the dialog box that opens, enter or select the following values.
:guilabel:`Name`: Specify a name for the share network.
:guilabel:`Description`: Optionally, provide a brief description for the
share network.
:guilabel:`Neutron Net`: Choose a neutron network.
:guilabel:`Neutron Subnet`: Choose a neutron subnet.
#. Click :guilabel:`Create Share Network`.
The dashboard shows the share network on the :guilabel:`Share Networks` tab.
Delete a share network
~~~~~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, click :guilabel:`Shares`, and
click :guilabel:`Share Networks`.
#. Select the check boxes for the share networks that you want to delete.
#. Click :guilabel:`Delete Share Networks` and confirm your choice.
A message indicates whether the action was successful.
Edit share network
~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, click :guilabel:`Shares`, and
click :guilabel:`Share Networks`.
#. Go to the share network that you want to edit and choose
:guilabel:`Edit Share Network` from Actions.
#. :guilabel:`Name`: Enter a new share network name.
#. :guilabel:`Description`: Enter a new description.
#. Click :guilabel:`Edit Share Network`.
A message indicates whether the action was successful.
Create security service
~~~~~~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, click :guilabel:`Shares`,
and click :guilabel:`Security Services`.
#. Click :guilabel:`Create Security Service`.
In the dialog box that opens, enter or select the following values.
:guilabel:`Name`: Specify a name for the security service.
:guilabel:`DNS IP`: Enter the DNS IP address.
:guilabel:`Server`: Enter the server name.
:guilabel:`Domain`: Enter the domain name.
:guilabel:`User`: Enter the user name.
:guilabel:`Password`: Enter the password.
:guilabel:`Confirm Password`: Enter the password again to confirm.
:guilabel:`Type`: Choose the type from Active Directory, LDAP, or Kerberos.
:guilabel:`Description`: Optionally, provide a brief description for the
security service.
#. Click :guilabel:`Create Security Service`.
The dashboard shows the security service on the :guilabel:`Security Services`
tab.
Delete a security service
~~~~~~~~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, click :guilabel:`Shares`, and
click :guilabel:`Security Services`.
#. Select the check boxes for the security services that you want to delete.
#. Click :guilabel:`Delete Security Services` and confirm your choice.
A message indicates whether the action was successful.
Edit security service
~~~~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard, choose a project, click :guilabel:`Shares`,
and click :guilabel:`Security Services`.
#. Go to the security service that you want to edit and choose
:guilabel:`Edit Security Service` from Actions.
#. :guilabel:`Name`: Enter a new security service name.
#. :guilabel:`Description`: Enter a new description.
#. Click :guilabel:`Edit Security Service`.
A message indicates whether the action was successful.

177
doc/user-guide/source/dashboard-manage-volumes.rst
View File

@ -1,177 +0,0 @@
=========================
Create and manage volumes
=========================
Volumes are block storage devices that you attach to instances to enable
persistent storage. You can attach a volume to a running instance or
detach a volume and attach it to another instance at any time. You can
also create a snapshot from or delete a volume. Only administrative
users can create volume types.
Create a volume
~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Volumes` category.
#. Click :guilabel:`Create Volume`.
In the dialog box that opens, enter or select the following values.
:guilabel:`Volume Name`: Specify a name for the volume.
:guilabel:`Description`: Optionally, provide a brief description for the
volume.
:guilabel:`Volume Source`: Select one of the following options:
* No source, empty volume: Creates an empty volume. An empty volume does
not contain a file system or a partition table.
* Snapshot: If you choose this option, a new field for
:guilabel:`Use snapshot as a source` displays. You can select the
snapshot from the list.
* Image: If you choose this option, a new field for :guilabel:`Use image
as a source` displays. You can select the image from the list.
* Volume: If you choose this option, a new field for
:guilabel:`Use volume as a source` displays. You can select the volume
from the list. Options to use a snapshot or a volume as the source for a
volume are displayed only if there are existing snapshots or volumes.
:guilabel:`Type`: Leave this field blank.
:guilabel:`Size (GB)`: The size of the volume in gibibytes (GiB).
:guilabel:`Availability Zone`: Select the Availability Zone from the list.
By default, this value is set to the availability zone given by the cloud
provider (for example, ``us-west`` or ``apac-south``). For some cases,
it could be ``nova``.
#. Click :guilabel:`Create Volume`.
The dashboard shows the volume on the :guilabel:`Volumes` tab.
.. _attach_a_volume_to_an_instance_dash:
Attach a volume to an instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After you create one or more volumes, you can attach them to instances.
You can attach a volume to one instance at a time.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Volumes` category.
#. Select the volume to add to an instance and click
:guilabel:`Manage Attachments`.
#. In the :guilabel:`Manage Volume Attachments` dialog box, select an instance.
#. Enter the name of the device from which the volume is accessible by
the instance.
.. note::
The actual device name might differ from the volume name because
of hypervisor settings.
#. Click :guilabel:`Attach Volume`.
The dashboard shows the instance to which the volume is now attached
and the device name.
You can view the status of a volume in the Volumes tab of the dashboard.
The volume is either Available or In-Use.
Now you can log in to the instance and mount, format, and use the disk.
Detach a volume from an instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click the :guilabel:`Volumes` category.
#. Select the volume and click :guilabel:`Manage Attachments`.
#. Click :guilabel:`Detach Volume` and confirm your changes.
A message indicates whether the action was successful.
Create a snapshot from a volume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Volumes` category.
#. Select a volume from which to create a snapshot.
#. In the :guilabel:`Actions` column, click :guilabel:`Create Snapshot`.
#. In the dialog box that opens, enter a snapshot name and a brief
description.
#. Confirm your changes.
The dashboard shows the new volume snapshot in Volume Snapshots tab.
Edit a volume
~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Volumes` category.
#. Select the volume that you want to edit.
#. In the :guilabel:`Actions` column, click :guilabel:`Edit Volume`.
#. In the :guilabel:`Edit Volume` dialog box, update the name and description
of the volume.
#. Click :guilabel:`Edit Volume`.
.. note::
You can extend a volume by using the :guilabel:`Extend Volume`
option available in the :guilabel:`More` dropdown list and entering the
new value for volume size.
Delete a volume
~~~~~~~~~~~~~~~
When you delete an instance, the data in its attached volumes is not
deleted.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Compute` tab and
click :guilabel:`Volumes` category.
#. Select the check boxes for the volumes that you want to delete.
#. Click :guilabel:`Delete Volumes` and confirm your choice.
A message indicates whether the action was successful.

151
doc/user-guide/source/dashboard-stacks.rst
View File

@ -1,151 +0,0 @@
========================
Launch and manage stacks
========================
OpenStack Orchestration is a service that you can use to
orchestrate multiple composite cloud applications. This
service supports the use of both the Amazon Web Services (AWS)
CloudFormation template format through both a Query API that
is compatible with CloudFormation and the native OpenStack
:term:`Heat Orchestration Template (HOT)` format through a REST API.
These flexible template languages enable application
developers to describe and automate the deployment of
infrastructure, services, and applications. The templates
enable creation of most OpenStack resource types, such as
instances, floating IP addresses, volumes, security groups,
and users. Once created, the resources are referred to as
stacks.
The template languages are described in the `Template Guide
<https://docs.openstack.org/developer/heat/template_guide/index.
html>`_ in the `Heat developer documentation <http://docs.
openstack.org/developer/heat/>`_.
Launch a stack
~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Orchestration` tab and
click :guilabel:`Stacks` category.
#. Click :guilabel:`Launch Stack`.
#. In the :guilabel:`Select Template` dialog box, specify the
following values:
+---------------------------------------+-------------------------------+
| :guilabel:`Template Source` | Choose the source of the |
| | template from the list. |
+---------------------------------------+-------------------------------+
| :guilabel:`Template URL/File/Data` | Depending on the source that |
| | you select, enter the URL, |
| | browse to the file location, |
| | or directly include the |
| | template. |
+---------------------------------------+-------------------------------+
| :guilabel:`Environment Source` | Choose the source of the |
| | environment from the list. |
| | The environment files contain |
| | additional settings for the |
| | stack. |
+---------------------------------------+-------------------------------+
| :guilabel:`Environment File/Data` | Depending on the source that |
| | you select, browse to the |
| | file location, directly |
| | include the environment |
+---------------------------------------+-------------------------------+
#. Click :guilabel:`Next`.
#. In the :guilabel:`Launch Stack` dialog box, specify the
following values:
+---------------------------------+---------------------------------+
| :guilabel:`Stack Name` | Enter a name to identify |
| | the stack. |
+---------------------------------+---------------------------------+
| :guilabel:`Creation Timeout` | Specify the number of minutes |
| :guilabel:`(minutes)` | that can elapse before the |
| | launch of the stack times out. |
+---------------------------------+---------------------------------+
| :guilabel:`Rollback On Failure` | Select this check box if you |
| | want the service to roll back |
| | changes if the stack fails to |
| | launch. |
+---------------------------------+---------------------------------+
| :guilabel:`Password for user` | Specify the password that |
| :guilabel:`"demo"` | the default user uses when the |
| | stack is created. |
+---------------------------------+---------------------------------+
| :guilabel:`DBUsername` | Specify the name of the |
| | database user. |
+---------------------------------+---------------------------------+
| :guilabel:`LinuxDistribution` | Specify the Linux distribution |
| | that is used in the stack. |
+---------------------------------+---------------------------------+
| :guilabel:`DBRootPassword` | Specify the root password for |
| | the database. |
+---------------------------------+---------------------------------+
| :guilabel:`KeyName` | Specify the name of the key pair|
| | to use to log in to the stack. |
+---------------------------------+---------------------------------+
| :guilabel:`DBName` | Specify the name of the |
| | database. |
+---------------------------------+---------------------------------+
| :guilabel:`DBPassword` | Specify the password of the |
| | database. |
+---------------------------------+---------------------------------+
| :guilabel:`InstanceType` | Specify the flavor for the |
| | instance. |
+---------------------------------+---------------------------------+
#. Click :guilabel:`Launch` to create a stack. The :guilabel:`Stacks`
tab shows the stack.
After the stack is created, click on the stack name to see the
following details:
Topology
The topology of the stack.
Overview
The parameters and details of the stack.
Resources
The resources used by the stack.
Events
The events related to the stack.
Template
The template for the stack.
Manage a stack
~~~~~~~~~~~~~~
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Orchestration` tab and
click :guilabel:`Stacks` category.
#. Select the stack that you want to update.
#. Click :guilabel:`Change Stack Template`.
#. In the :guilabel:`Select Template` dialog box, select the
new template source or environment source.
#. Click :guilabel:`Next`.
The :guilabel:`Update Stack Parameters` window appears.
#. Enter new values for any parameters that you want to update.
#. Click :guilabel:`Update`.
Delete a stack
~~~~~~~~~~~~~~
When you delete a stack, you cannot undo this action.
#. Log in to the dashboard.
#. Select the appropriate project from the drop down menu at the top left.
#. On the :guilabel:`Project` tab, open the :guilabel:`Orchestration` tab and
click :guilabel:`Stacks` category.
#. Select the stack that you want to delete.
#. Click :guilabel:`Delete Stack`.
#. In the confirmation dialog box, click :guilabel:`Delete Stack`
to confirm the deletion.

25
doc/user-guide/source/dashboard.rst
View File

@ -1,25 +0,0 @@
===================
OpenStack dashboard
===================
As a cloud end user, you can use the OpenStack dashboard to provision
your own resources within the limits set by administrators. You can
modify the examples provided in this section to create other types and
sizes of server instances.
.. toctree::
:maxdepth: 2
dashboard-log-in.rst
dashboard-manage-images.rst
configure-access-and-security-for-instances.rst
dashboard-launch-instances.rst
dashboard-create-networks.rst
dashboard-manage-containers.rst
dashboard-manage-volumes.rst
dashboard-manage-shares.rst
dashboard-stacks.rst
dashboard-databases.rst
dashboard-manage-lbaasv2.rst

409
doc/user-guide/source/database-module-usage.rst
View File

@ -1,409 +0,0 @@
.. _database_module_usage:
=====================================
Create and use modules for a database
=====================================
To continue with this document, we recommend that you have installed
the Database service and populated your data store with images for the
type and versions of databases that you want, and that you can create
and access a database.
This example shows you how to create and apply modules to a MySQL 5.6
database and redis 3.2.6 database cluster.
Create and apply a module to a mysql database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. **Create the module file and trove module**
If you wish to apply a module, you must create the module first
and register it with the trove service. A user can not directly
apply a module to a trove instance.
The module created here is a demo module called ping. It is the
basic type made for testing purposes. To create it, it is as
simple as the following :command: ``echo`` command:
.. code-block:: console
$ echo "message=Module.V1" > ping1.dat
You can create a test module and mysql database with the module
applied by doing the following:
.. code-block:: console
$ trove module-create mymod ping ping1.dat --live_update \
--datastore mysql
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| apply_order | 5 |
| auto_apply | False |
| created | 2017-06-02T17:06:21 |
| datastore | all |
| datastore_id | None |
| datastore_version | all |
| datastore_version_id | None |
| description | None |
| id | 0065a8ed-0668-4db5-a4ad-d88d0a166388 |
| instance_count | 2 |
| is_admin | True |
| live_update | True |
| md5 | 7f700cc7b99606615f8b51946f6d3228 |
| name | mymod |
| priority_apply | False |
| tenant | eac1e46e5f7840e39012aff46a92073a |
| tenant_id | eac1e46e5f7840e39012aff46a92073a |
| type | ping |
| updated | 2017-06-02T17:06:21 |
| visible | True |
+----------------------+--------------------------------------+
$ trove create myinst 15 --size 1 --module mymod --datastore mysql
+-------------------------+--------------------------------------+
| Property | Value |
+-------------------------+--------------------------------------+
| created | 2017-06-02T17:22:24 |
| datastore | mysql |
| datastore_version | 5.6 |
| encrypted_rpc_messaging | True |
| flavor | 15 |
| id | 6221b30c-8292-4378-b624-c7e9b0f8ba9e |
| name | myinst |
| region | RegionOne |
| server_id | None |
| status | BUILD |
| tenant_id | eac1e46e5f7840e39012aff46a92073a |
| updated | 2017-06-02T17:22:24 |
| volume | 1 |
| volume_id | None |
+-------------------------+--------------------------------------+
.. _show_and_list_modules:
#. **Show and list modules**
You can view the modules on your instance by doing the following:
.. code-block:: console
$ trove module-query myinst
+-------+------+-----------+---------+--------+-----------+------------------------+------------------------+
| Name | Type | Datastore | Version | Status | Message | Created | Updated |
+-------+------+-----------+---------+--------+-----------+------------------------+------------------------+
| mymod | ping | all | all | OK | Module.V1 | 2017-06-02 17:23:40.50 | 2017-06-02 17:23:40.50 |
+-------+------+-----------+---------+--------+-----------+------------------------+------------------------+
You can count the instances each module is applied to by doing the
following:
.. code-block:: console
$ trove module-instance-count mymod
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | True | 1 |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
You can list the instances that have a particular module applied
by doing the following:
.. code-block:: console
$ trove module-instances mymod
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+-----------+----------------------------------+
| ID | Name | Datastore | Datastore Version | Status | Flavor ID | Size | Region | Tenant ID |
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+-----------+----------------------------------+
| 6221b30c-8292-4378-b624-c7e9b0f8ba9e | myinst | mysql | 5.6 | ACTIVE | 15 | 1 | RegionOne | eac1e46e5f7840e39012aff46a92073a |
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+-----------+----------------------------------+
Updating and creating a second module for a redis cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To update a module you should have another file ready to update the
module with:
.. code-block:: console
$ echo "message=Module.V2" > ping2.dat
$ trove module-update mymod --file ping2.dat
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| apply_order | 5 |
| auto_apply | False |
| created | 2017-06-02T17:06:21 |
| datastore | all |
| datastore_id | None |
| datastore_version | all |
| datastore_version_id | None |
| description | None |
| id | 0065a8ed-0668-4db5-a4ad-d88d0a166388 |
| is_admin | True |
| live_update | True |
| md5 | ba7c204979c8de54be6efb70a17d40b9 |
| name | mymod |
| priority_apply | False |
| tenant | eac1e46e5f7840e39012aff46a92073a |
| tenant_id | eac1e46e5f7840e39012aff46a92073a |
| type | ping |
| updated | 2017-06-02T17:56:12 |
| visible | True |
+----------------------+--------------------------------------+
Now to show the usage with a redis cluster, create as follows:
.. code-block:: console
$ trove cluster-create myclust redis 3.2.6 \
--instance=flavor=15,volume=1,module=mymod \
--instance=flavor=15,volume=1,module=mymod \
--instance=flavor=15,volume=1,module=mymod
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2017-06-02T18:00:17 |
| datastore | redis |
| datastore_version | 3.2.6 |
| id | e4d91ca6-5980-430c-94d0-bf7abc63f712 |
| instance_count | 3 |
| name | myclust |
| task_description | Building the initial cluster. |
| task_name | BUILDING |
| updated | 2017-06-02T18:00:17 |
+-------------------+--------------------------------------+
The original :command: ``count`` command will show the first instance,
unless the ``--include_clustered`` option is used. You can see the
MD5 from each applied module, and you know that the single instance
one is not current.
.. code-block:: console
$ trove module-instance-count mymod
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
$ trove module-instance-count mymod --include_clustered
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 |
| mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | True | 3 |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
Update the module again. By doing this, it will cause the instances
to report their module is not current.
.. code-block:: console
$ echo "message=Module.V3" > ping3.dat
$ trove module-update mymod --file ping3.dat
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| apply_order | 5 |
| auto_apply | False |
| created | 2017-06-02T17:06:21 |
| datastore | all |
| datastore_id | None |
| datastore_version | all |
| datastore_version_id | None |
| description | None |
| id | 0065a8ed-0668-4db5-a4ad-d88d0a166388 |
| is_admin | True |
| live_update | True |
| md5 | 869744bdd18e306a96c145df562065ab |
| name | mymod |
| priority_apply | False |
| tenant | eac1e46e5f7840e39012aff46a92073a |
| tenant_id | eac1e46e5f7840e39012aff46a92073a |
| type | ping |
| updated | 2017-06-02T18:06:53 |
| visible | True |
+----------------------+--------------------------------------+
$ trove module-instance-count mymod --include_clustered
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 |
| mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | False | 3 |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
To update an instance in a cluster you can use the
:command:`trove module-apply` command:
.. code-block:: console
$ trove cluster-instances myclust
+--------------------------------------+------------------+-----------+------+--------+
| ID | Name | Flavor ID | Size | Status |
+--------------------------------------+------------------+-----------+------+--------+
| 393462d5-906d-4214-af0d-538b7f618b2d | myclust-member-2 | 15 | 1 | ACTIVE |
| a3fc5326-e1b6-456a-a8b1-08ad6bbb2278 | myclust-member-3 | 15 | 1 | ACTIVE |
| cba31d4b-d038-42c2-ab03-56c6c176b49d | myclust-member-1 | 15 | 1 | ACTIVE |
+--------------------------------------+------------------+-----------+------+--------+
$ trove module-apply 393462d5-906d-4214-af0d-538b7f618b2d mymod
+-------+------+-----------+---------+--------+-----------+
| Name | Type | Datastore | Version | Status | Message |
+-------+------+-----------+---------+--------+-----------+
| mymod | ping | all | all | OK | Module.V3 |
+-------+------+-----------+---------+--------+-----------+
$ trove module-instance-count mymod --include_clustered
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 |
| mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | False | 2 |
| mymod | 2017-06-02T18:18:37 | 2017-06-02T18:18:37 | 869744bdd18e306a96c145df562065ab | True | 1 |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
For variety in this example, create one more instance and module:
.. code-block:: console
$ trove create myinst_2 15 --size 1 --module mymod
+-------------------------+--------------------------------------+
| Property | Value |
+-------------------------+--------------------------------------+
| created | 2017-06-02T18:21:56 |
| datastore | redis |
| datastore_version | 3.2.6 |
| encrypted_rpc_messaging | True |
| flavor | 15 |
| id | cdd85d94-13a0-4d90-89eb-9c05523d2ac6 |
| name | myinst_2 |
| region | RegionOne |
| server_id | None |
| status | BUILD |
| tenant_id | eac1e46e5f7840e39012aff46a92073a |
| updated | 2017-06-02T18:21:56 |
| volume | 1 |
| volume_id | None |
+-------------------------+--------------------------------------+
$ echo "message=Module.V4" > ping4.dat
$ trove module-update mymod --file ping4.dat
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| apply_order | 5 |
| auto_apply | False |
| created | 2017-06-02T17:06:21 |
| datastore | all |
| datastore_id | None |
| datastore_version | all |
| datastore_version_id | None |
| description | None |
| id | 0065a8ed-0668-4db5-a4ad-d88d0a166388 |
| is_admin | True |
| live_update | True |
| md5 | 6e2c81c1547d640b4c6e7752ed0e33ab |
| name | mymod |
| priority_apply | False |
| tenant | eac1e46e5f7840e39012aff46a92073a |
| tenant_id | eac1e46e5f7840e39012aff46a92073a |
| type | ping |
| updated | 2017-06-02T18:26:22 |
| visible | True |
+----------------------+--------------------------------------+
Now we have 2 single instances, and 3 cluster instances on various
versions of the module, none current.
.. code-block:: console
$ trove list
+--------------------------------------+----------+-----------+-------------------+--------+-----------+------+-----------+
| ID | Name | Datastore | Datastore Version | Status | Flavor ID | Size | Region |
+--------------------------------------+----------+-----------+-------------------+--------+-----------+------+-----------+
| 6221b30c-8292-4378-b624-c7e9b0f8ba9e | myinst | mysql | 5.6 | ACTIVE | 15 | 1 | RegionOne |
| cdd85d94-13a0-4d90-89eb-9c05523d2ac6 | myinst_2 | redis | 3.2.6 | ACTIVE | 15 | 1 | RegionOne |
+--------------------------------------+----------+-----------+-------------------+--------+-----------+------+-----------+
$ trove module-instance-count mymod --include_clustered
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 |
| mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | False | 2 |
| mymod | 2017-06-02T18:18:37 | 2017-06-02T18:21:57 | 869744bdd18e306a96c145df562065ab | False | 2 |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
When the latest module was created, the ``--include_clustered`` was
not used. Use the :command:`trove module-reapply` command:
.. code-block:: console
$ trove module-reapply mymod --md5=869744bdd18e306a96c145df562065ab --include_clustered
$ trove module-instance-count mymod --include_clustered
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 |
| mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | False | 2 |
| mymod | 2017-06-02T18:38:48 | 2017-06-02T18:38:48 | 6e2c81c1547d640b4c6e7752ed0e33ab | True | 2 |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
Now they are both updated. If the ``--force`` flag is used, it can
reapply to already applied instances. Notice that the only thing that
changes is the minimum and maximum updated date fields.
.. code-block:: console
$ trove module-reapply mymod --md5=6e2c81c1547d640b4c6e7752ed0e33ab --include_clustered --force
$ trove module-instance-count mymod --include_clustered
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 |
| mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | False | 2 |
| mymod | 2017-06-02T18:40:45 | 2017-06-02T18:40:46 | 6e2c81c1547d640b4c6e7752ed0e33ab | True | 2 |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
To bring every instance to the current version, use some of the
optional arguments to control how many instances are updated at the
same time. This is useful to avoid potential network issues, if the
module payload is large. Since we are not using the ``--force`` flag,
the minimum updated date will not change.
.. code-block:: console
$ trove module-reapply mymod --include_clustered --batch_size=1 --delay=3
$ trove module-instance-count mymod --include_clustered
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+
| mymod | 2017-06-02T18:40:45 | 2017-06-02T18:44:10 | 6e2c81c1547d640b4c6e7752ed0e33ab | True | 5 |
+-------------+---------------------+---------------------+----------------------------------+---------+-------+

BIN
doc/user-guide/source/figures/create_image.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 32 KiB

BIN
doc/user-guide/source/figures/dashboard_admin_tab.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 54 KiB

BIN
doc/user-guide/source/figures/dashboard_identity_tab.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 35 KiB

BIN
doc/user-guide/source/figures/dashboard_project_tab.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 72 KiB

BIN
doc/user-guide/source/figures/dashboard_settings_tab.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 39 KiB

10
doc/user-guide/source/hot.rst
View File

@ -1,10 +0,0 @@
=========
HOT Guide
=========
Orchestration is compatible with the CloudFormation template, but you can also
write heat templates to orchestrate cloud resources.
To learn how, refer to the `Template Guide
<https://docs.openstack.org/developer/heat/template_guide/index.html>`__
on the OpenStack developer documentation website.

29
doc/user-guide/source/index.rst
View File

@ -1,29 +0,0 @@
========================
OpenStack End User Guide
========================
Abstract
~~~~~~~~
OpenStack is an open-source cloud computing platform for public and
private clouds. A series of interrelated projects deliver a cloud
infrastructure solution. This guide shows OpenStack end users how to
create and manage resources in an OpenStack cloud with the OpenStack
dashboard and OpenStack client commands.
This guide documents OpenStack Ocata, Newton and Mitaka releases.
Contents
~~~~~~~~
.. toctree::
:maxdepth: 2
common/conventions.rst
intro-user.rst
dashboard.rst
cli.rst
sdk.rst
hot.rst
cli-cheat-sheet.rst
common/appendix.rst

39
doc/user-guide/source/intro-user.rst
View File

@ -1,39 +0,0 @@
=================================
How can I use an OpenStack cloud?
=================================
As an OpenStack cloud end user, you can provision your own resources
within the limits set by cloud administrators.
The examples in this guide show you how to perform tasks by using the
following methods:
* OpenStack dashboard: Use this web-based graphical interface, code named
`horizon <https://git.openstack.org/cgit/openstack/horizon>`__, to view,
create, and manage resources.
* OpenStack command-line clients: Each core OpenStack project has a
command-line client that you can use to run simple commands to view,
create, and manage resources in a cloud and automate tasks by using
scripts.
You can modify these examples for your specific use cases.
In addition to these ways of interacting with a cloud, you can access
the OpenStack APIs directly or indirectly through `cURL <http://curl.haxx.se>`__
commands or open SDKs. You can automate access or build tools to manage
resources and services by using the OpenStack APIs.
To use the OpenStack APIs, it helps to be familiar with HTTP/1.1,
RESTful web services, the OpenStack services, and JSON or XML data
serialization formats.
Who should read this book?
~~~~~~~~~~~~~~~~~~~~~~~~~~
This book is written for anyone who uses virtual machines and cloud
resources to develop software or perform research. You should have
years of experience with Linux-based tool sets and be comfortable
using both GUI and CLI based tools. While this book includes some
information about using Python to create and manage cloud resources,
Python knowledge is not a pre-requisite for reading this book.

10531
doc/user-guide/source/locale/id/LC_MESSAGES/user-guide.po
View File

File diff suppressed because it is too large Load Diff

10229
doc/user-guide/source/locale/ja/LC_MESSAGES/user-guide.po
View File

File diff suppressed because it is too large Load Diff

7748
doc/user-guide/source/locale/zh_CN/LC_MESSAGES/user-guide.po
View File

File diff suppressed because it is too large Load Diff

239
doc/user-guide/source/manage-db-config.rst
View File

@ -1,239 +0,0 @@
=============================
Manage database configuration
=============================
You can manage database configuration tasks by using configuration
groups. Configuration groups let you set configuration options, in bulk,
on one or more databases.
This example assumes you have created a MySQL
database and shows you how to use a
configuration group to configure it. Although this example sets just one
option on one database, you can use these same procedures to set
multiple options on multiple database instances throughout your
environment. This can provide significant time savings in managing your
cloud.
Bulk-configure a database or databases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. **List available options**
First, determine which configuration options you can set. Different
data store versions have different configuration options.
List the names and IDs of all available versions of the ``mysql``
data store:
.. code-block:: console
$ trove datastore-version-list mysql
+--------------------------------------+-----------+
| id | name |
+--------------------------------------+-----------+
| eeb574ce-f49a-48b6-820d-b2959fcd38bb | mysql-5.5 |
+--------------------------------------+-----------+
Pass in the data store version ID with the
:command:`trove configuration-parameter-list` command to get the available
options:
.. code-block:: console
$ trove configuration-parameter-list DATASTORE_VERSION_ID
+--------------------------------+---------+---------+----------------------+------------------+
| name | type | min | max | restart_required |
+--------------------------------+---------+---------+----------------------+------------------+
| auto_increment_increment | integer | 1 | 65535 | False |
| auto_increment_offset | integer | 1 | 65535 | False |
| autocommit | integer | 0 | 1 | False |
| bulk_insert_buffer_size | integer | 0 | 18446744073709547520 | False |
| character_set_client | string | | | False |
| character_set_connection | string | | | False |
| character_set_database | string | | | False |
| character_set_filesystem | string | | | False |
| character_set_results | string | | | False |
| character_set_server | string | | | False |
| collation_connection | string | | | False |
| collation_database | string | | | False |
| collation_server | string | | | False |
| connect_timeout | integer | 1 | 65535 | False |
| expire_logs_days | integer | 1 | 65535 | False |
| innodb_buffer_pool_size | integer | 0 | 68719476736 | True |
| innodb_file_per_table | integer | 0 | 1 | True |
| innodb_flush_log_at_trx_commit | integer | 0 | 2 | False |
| innodb_log_buffer_size | integer | 1048576 | 4294967296 | True |
| innodb_open_files | integer | 10 | 4294967296 | True |
| innodb_thread_concurrency | integer | 0 | 1000 | False |
| interactive_timeout | integer | 1 | 65535 | False |
| join_buffer_size | integer | 0 | 4294967296 | False |
| key_buffer_size | integer | 0 | 4294967296 | False |
| local_infile | integer | 0 | 1 | False |
| max_allowed_packet | integer | 1024 | 1073741824 | False |
| max_connect_errors | integer | 1 | 18446744073709547520 | False |
| max_connections | integer | 1 | 65535 | False |
| max_user_connections | integer | 1 | 100000 | False |
| myisam_sort_buffer_size | integer | 4 | 18446744073709547520 | False |
| server_id | integer | 1 | 100000 | True |
| sort_buffer_size | integer | 32768 | 18446744073709547520 | False |
| sync_binlog | integer | 0 | 18446744073709547520 | False |
| wait_timeout | integer | 1 | 31536000 | False |
+--------------------------------+---------+---------+----------------------+------------------+
In this example, the :command:`trove configuration-parameter-list` command
returns a list of options that work with MySQL 5.5.
#. **Create a configuration group**
A configuration group contains a comma-separated list of key-value
pairs. Each pair consists of a configuration option and its value.
You can create a configuration group by using the
:command:`trove configuration-create` command. The general syntax
for this command is:
.. code-block:: console
$ trove configuration-create NAME VALUES --datastore DATASTORE_NAME
- *NAME*. The name you want to use for this group.
- *VALUES*. The list of key-value pairs.
- *DATASTORE_NAME*. The name of the associated data store.
Set *VALUES* as a JSON dictionary, for example:
.. code-block:: json
{"myFirstKey" : "someString", "mySecondKey" : 1}
This example creates a configuration group called ``group1``.
``group1`` contains just one key and value pair, and this pair sets
the ``sync_binlog`` option to ``1``.
.. code-block:: console
$ trove configuration-create group1 '{"sync_binlog" : 1}' --datastore mysql
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| datastore_version_id | eeb574ce-f49a-48b6-820d-b2959fcd38bb |
| description | None |
| id | 9a9ef3bc-079b-476a-9cbf-85aa64f898a5 |
| name | group1 |
| values | {"sync_binlog": 1} |
+----------------------+--------------------------------------+
#. **Examine your existing configuration**
Before you use the newly-created configuration group, look at how the
``sync_binlog`` option is configured on your database. Replace the
following sample connection values with values that connect to your
database:
.. code-block:: console
$ mysql -u user7 -ppassword -h 172.16.200.2 myDB7
Welcome to the MySQL monitor. Commands end with ; or \g.
...
mysql> show variables like 'sync_binlog';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| sync_binlog | 0 |
+---------------+-------+
As you can see, the ``sync_binlog`` option is currently set to ``0``
for the ``myDB7`` database.
#. **Change the database configuration using a configuration group**
You can change a database's configuration by attaching a
configuration group to a database instance. You do this by using the
:command:`trove configuration-attach` command and passing in the ID of the
database instance and the ID of the configuration group.
Get the ID of the database instance:
.. code-block:: console
$ trove list
+-------------+------------------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+-------------+------------------+-----------+-------------------+--------+-----------+------+
| 26a265dd... | mysql_instance_7 | mysql | mysql-5.5 | ACTIVE | 6 | 5 |
+-------------+------------------+-----------+-------------------+--------+-----------+------+
Get the ID of the configuration group:
.. code-block:: console
$ trove configuration-list
+-------------+--------+-------------+---------------------+
| id | name | description |datastore_version_id |
+-------------+--------+-------------+---------------------+
| 9a9ef3bc... | group1 | None | eeb574ce... |
+-------------+--------+-------------+---------------------+
Attach the configuration group to the database instance:
.. note::
This command syntax pertains only to python-troveclient version
1.0.6 and later. Earlier versions require you to pass in the
configuration group ID as the first argument.
.. code-block:: console
$ trove configuration-attach DB_INSTANCE_ID CONFIG_GROUP_ID
#. **Re-examine the database configuration**
Display the ``sync_binlog`` setting again:
.. code-block:: console
mysql> show variables like 'sync_binlog';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| sync_binlog | 1 |
+---------------+-------+
As you can see, the ``sync_binlog`` option is now set to ``1``, as
specified in the ``group1`` configuration group.
**Conclusion.** Using a configuration group to set a single option on
a single database is obviously a trivial example. However, configuration
groups can provide major efficiencies when you consider that:
- A configuration group can specify a large number of option values.
- You can apply a configuration group to hundreds or thousands of
database instances in your environment.
Used in this way, configuration groups let you modify your database
cloud configuration, on the fly, on a massive scale.
**Maintenance.** There are also a number of useful maintenance
features for working with configuration groups. You can:
- Disassociate a configuration group from a database instance, using
the :command:`trove configuration-detach` command.
- Modify a configuration group on the fly, using the
:command:`trove configuration-patch` command.
- Find out what instances are using a configuration group, using the
:command:`trove configuration-instances` command.
- Delete a configuration group, using the
:command:`trove configuration-delete` command. You might want to
do this if no instances use a group.

32
doc/user-guide/source/managing-openstack-object-storage-with-swift-cli.rst
View File

@ -1,32 +0,0 @@
=============================
Manage objects and containers
=============================
The OpenStack Object Storage service provides the ``swift`` client,
which is a command-line interface (CLI). Use this client to list
objects and containers, upload objects to containers, and download
or delete objects from containers. You can also gather statistics and
update metadata for accounts, containers, and objects.
This client is based on the native swift client library, ``client.py``,
which seamlessly re-authenticates if the current token expires during
processing, retries operations multiple times, and provides a processing
concurrency of 10.
.. toctree::
:maxdepth: 2
cli-swift-create-containers.rst
cli-swift-manage-access-swift.rst
cli-swift-manage-objects.rst
cli-swift-env-vars.rst
cli-swift-set-object-versions.rst
cli-swift-set-object-expiration.rst
cli-swift-serialized-response-formats.rst
cli-swift-large-lists.rst
cli-swift-pseudo-hierarchical-folders-directories.rst
cli-swift-discoverability.rst
cli-swift-large-object-creation.rst
cli-swift-archive-auto-extract.rst
cli-swift-bulk-delete.rst
cli-swift-static-website.rst

38
doc/user-guide/source/sdk-assign-cors-headers.rst
View File

@ -1,38 +0,0 @@
===============================
Assign CORS headers to requests
===============================
:term:`Cross-Origin Resource Sharing (CORS)` is a specification that
defines how browsers and servers communicate across origins by using
HTTP headers, such as those assigned by Object Storage API
requests. The Object Storage API supports the following headers:
- Access-Control-Allow-Credentials
- Access-Control-Allow-Methods
- Access-Control-Allow-Origin
- Access-Control-Expose-Headers
- Access-Control-Max-Age
- Access-Control-Request-Headers
- Access-Control-Request-Method
- Origin
You can only assign these headers to objects. For more information, see
`www.w3.org/TR/access-control/ <http://www.w3.org/TR/access-control/>`__.
This example assigns the file origin to the ``Origin`` header, which
ensures that the file originated from a reputable source.
.. code-block:: console
$ curl -i -X POST -H "Origin: example.com" -H "X-Auth-Token:
48e17715dfce47bb90dc2a336f63493a"
https://storage.example.com/v1/MossoCloudFS_c31366f1-9f1c-40dc-a
b92-6b3f0b5a8c45/ephotos
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
Access-Control-Allow-Origin: example.com
Access-Control-Expose-Headers: cache-control, content-language,
content-type, expires, last-modified, pragma, etag, x-timestamp, x-trans-id
X-Trans-Id: tx979bfe26be6649c489ada-0054cba1d9ord1
Date: Fri, 30 Jan 2015 15:23:05 GMT

23
doc/user-guide/source/sdk-authenticate.rst
View File

@ -1,23 +0,0 @@
.. _sdk_authenticate:
============
Authenticate
============
When using the SDK, you must authenticate against an OpenStack endpoint
before you can use OpenStack services. Because all projects use Keystone
for authentication, the process is the same no matter which service
or library you have decided to use. Each library also has more advanced
and complicated ways to do things, should those be needed.
There are two basic ways to deal with your cloud config and credentials:
- Environment variables via an openrc.sh file
- clouds.yaml config file
The environment variables have been around the longest and are the form
you are most likely to receive from your cloud provider. If you have one
and only one cloud account, they are the most convenient way.
``clouds.yaml`` is a bit newer and was designed to help folks who have
more than one OpenStack cloud that they are using.

532
doc/user-guide/source/sdk-compute-apis.rst
View File

@ -1,532 +0,0 @@
=======
Compute
=======
To use the information in this section, you must be familiar with
OpenStack Compute.
Set environment variables
~~~~~~~~~~~~~~~~~~~~~~~~~
To set up environmental variables and authenticate against Compute API
endpoints, see :ref:`sdk_authenticate`.
.. _get-openstack-credentials:
Get OpenStack credentials (API v2)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This example uses the ``get_nova_credentials_v2`` method:
.. code-block:: python
def get_nova_credentials_v2():
d = {}
d['version'] = '2'
d['username'] = os.environ['OS_USERNAME']
d['api_key'] = os.environ['OS_PASSWORD']
d['auth_url'] = os.environ['OS_AUTH_URL']
d['project_id'] = os.environ['OS_TENANT_NAME']
return d
This code resides in the ``credentials.py`` file, which all samples
import.
Use the ``get_nova_credentials_v2()`` method to populate and get a
dictionary:
.. code-block:: python
credentials = get_nova_credentials_v2()
List servers (API v2)
~~~~~~~~~~~~~~~~~~~~~
The following program lists servers by using the Compute API v2.
#. Import the following modules:
.. code-block:: python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
#. Get Nova credentials. See :ref:`Get OpenStack credentials (API v2)
<get-openstack-credentials>`.
#. Instantiate the ``nova_client`` client object by using the
``credentials`` dictionary object:
.. code-block:: python
nova_client = Client(**credentials)
#. List servers by calling ``servers.list`` on ``nova_client`` object:
.. code-block:: python
print(nova_client.servers.list())
List server code listing example
--------------------------------
.. code-block:: python
#!/usr/bin/env python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
credentials = get_nova_credentials_v2()
nova_client = Client(**credentials)
print(nova_client.servers.list())
Create server (API v2)
~~~~~~~~~~~~~~~~~~~~~~
The following program creates a server (VM) by using the Compute API v2.
#. Import the following modules:
.. code-block:: python
import time
from credentials import get_nova_credentials_v2
from novaclient.client import Client
#. Get OpenStack credentials. See :ref:`Get OpenStack credentials (API v2)
<get-openstack-credentials>`.
#. Instantiate the ``nova_client`` client object by using the
``credentials`` dictionary object:
.. code-block:: python
nova_client = Client(**credentials)
#. Get the flavor and image to use to create a server. This code uses
the ``cirros`` image, the ``m1.tiny`` flavor, and the ``private``
network:
.. code-block:: python
image = nova_client.images.find(name="cirros")
flavor = nova_client.flavors.find(name="m1.tiny")
net = nova_client.networks.find(label="private")
#. To create the server, use the network, image, and flavor:
.. code-block:: python
nics = [{'net-id': net.id}]
instance = nova_client.servers.create(name="vm2", image=image,
flavor=flavor, key_name="keypair-1", nics=nics)
#. Run the "Sleep for five seconds" command, and determine whether
the server/vm was created by calling ``nova_client.servers.list()``:
.. code-block:: python
print("Sleeping for 5s after create command")
time.sleep(5)
print("List of VMs")
print(nova_client.servers.list())
Create server code listing example
----------------------------------
.. code-block:: python
#!/usr/bin/env python
import time
from credentials import get_nova_credentials_v2
from novaclient.client import Client
try:
credentials = get_nova_credentials_v2()
nova_client = Client(**credentials)
image = nova_client.images.find(name="cirros")
flavor = nova_client.flavors.find(name="m1.tiny")
net = nova_client.networks.find(label="private")
nics = [{'net-id': net.id}]
instance = nova_client.servers.create(name="vm2", image=image,
flavor=flavor, key_name="keypair-1", nics=nics)
print("Sleeping for 5s after create command")
time.sleep(5)
print("List of VMs")
print(nova_client.servers.list())
finally:
print("Execution Completed")
Delete server (API v2)
~~~~~~~~~~~~~~~~~~~~~~
The following program deletes a server (VM) by using the Compute API v2.
#. Import the following modules:
.. code-block:: python
import time
from credentials import get_nova_credentials_v2
from novaclient.client import Client
#. Get Nova credentials. See :ref:`Get OpenStack credentials (API v2)
<get-openstack-credentials>`.
#. Instantiate the ``nova_client`` client object by using the
``credentials`` dictionary object:
.. code-block:: python
nova_client = Client(**credentials)
#. Determine whether the ``vm1`` server exists:
a. List servers: ``servers_list``.
b. Iterate over ``servers_list`` and compare name with ``vm1``.
c. If true, set the variable name ``server_exists`` to ``True``
and break from the for loop:
.. code-block:: python
servers_list = nova_client.servers.list()
server_del = "vm1"
server_exists = False
for s in servers_list:
if s.name == server_del:
print("This server %s exists" % server_del)
server_exists = True
break
#. If the server exists, run the ``delete`` method of the
``nova_client.servers`` object:
.. code-block:: python
nova_client.servers.delete(s)
Delete server code example
--------------------------
.. code-block:: python
#!/usr/bin/env python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
credentials = get_nova_credentials_v2()
nova_client = Client(**credentials)
servers_list = nova_client.servers.list()
server_del = "vm1"
server_exists = False
for s in servers_list:
if s.name == server_del:
print("This server %s exists" % server_del)
server_exists = True
break
if not server_exists:
print("server %s does not exist" % server_del)
else:
print("deleting server..........")
nova_client.servers.delete(s)
print("server %s deleted" % server_del)
Update server (API v2)
~~~~~~~~~~~~~~~~~~~~~~
The following program updates the name of a server (VM) by using the
Compute API v2.
#. Import the following modules:
.. code-block:: python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
from utils import print_server
``print_server`` is a method defined in ``utils.py`` and prints the
server details as shown in the code listing below:
.. code-block:: python
def print_server(server):
print("-"*35)
print("server id: %s" % server.id)
print("server name: %s" % server.name)
print("server image: %s" % server.image)
print("server flavor: %s" % server.flavor)
print("server key name: %s" % server.key_name)
print("user_id: %s" % server.user_id)
print("-"*35)
#. Get OpenStack Credentials. See :ref:`Get OpenStack credentials
(API v2) <get-openstack-credentials>`.
#. Instantiate the ``nova_client`` client object by using the
``credentials`` dictionary object:
.. code-block:: python
nova_client = Client(**credentials)
#. Get the server instance using ``server_id`` and print the details by
calling ``print_server`` method:
.. code-block:: python
server_id = '99889c8d-113f-4a7e-970c-77f1916bfe14'
server = nova_client.servers.get(server_id)
n = server.name
print_server(server)
#. Call ``server.update`` on the server object with the new value for
``name`` variable:
.. code-block:: python
server.update(name = n + '1')
#. Get the updated instance of the server:
.. code-block:: python
server_updated = nova_client.servers.get(server_id)
#. Call ``print_server`` again to check the update server details:
.. code-block:: python
print_server(server_updated)
Update server code listing example
----------------------------------
.. code-block:: python
#!/usr/bin/env python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
from utils import print_server
credentials = get_nova_credentials_v2()
nova_client = Client(**credentials)
# Change the server_id specific to your environment
server_id = '99889c8d-113f-4a7e-970c-77f1916bfe14'
server = nova_client.servers.get(server_id)
n = server.name
print_server(server)
server.update(name=n +'1')
server_updated = nova_client.servers.get(server_id)
print_server(server_updated)
List flavors (API v2)
~~~~~~~~~~~~~~~~~~~~~
The following program lists flavors and their details by using the
Compute API v2.
#. Import the following modules:
.. code-block:: python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
from utils import print_flavors
The ``print_flavors`` method is defined in ``utils.py`` and prints the
flavor details:
.. code-block:: python
def print_flavors(flavor_list):
for flavor in flavor_list:
print("-"*35)
print("flavor id : %s" % flavor.id)
print("flavor name : %s" % flavor.name)
print("-"*35)
#. Get OpenStack credentials. :ref:`Get OpenStack credentials
(API v2) <get-openstack-credentials>`.
#. Instantiate the ``nova_client`` client object by using the
``credentials`` dictionary object:
.. code-block:: python
nova_client = Client(**credentials)
#. List flavors by calling ``list()`` on ``nova_client.flavors`` object:
.. code-block:: python
flavors_list = nova_client.flavors.list()
#. Print the flavor details, id and name by calling ``print_flavors``:
.. code-block:: python
print_flavors(flavors_list)
List flavors code listing example
---------------------------------
.. code-block:: python
#!/usr/bin/env python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
from utils import print_flavors
credentials = get_nova_credentials_v2()
nova_client = Client(**credentials)
flavors_list = nova_client.flavors.list()
print_flavors(flavors_list)
List floating IPs (API v2)
~~~~~~~~~~~~~~~~~~~~~~~~~~
The following program lists the floating IPs and their details by using
the Compute API v2.
#. Import the following modules:
.. code-block:: python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
from utils import print_values_ip
The ``print_values_ip`` method is defined in ``utils.py`` and prints the
floating\_ip object details:
.. code-block:: python
def print_values_ip(ip_list):
ip_dict_lisl = []
for ip in ip_list:
print("-"*35)
print("fixed_ip : %s" % ip.fixed_ip)
print("id : %s" % ip.id)
print("instance_id : %s" % ip.instance_id)
print("ip : %s" % ip.ip)
print("pool : %s" % ip.pool)
#. Get OpenStack credentials. See :ref:`Get OpenStack credentials
(API v2) <get-openstack-credentials>`.
#. Instantiate the ``nova_client`` client object by using the
``credentials`` dictionary object:
.. code-block:: python
nova_client = Client(**credentials)
#. List floating IPs by calling ``list()`` on ``nova_client.floating_ips``
object:
.. code-block:: python
ip_list = nova_client.floating_ips.list()
#. Print the floating IP object details by calling ``print_values_ip``:
.. code-block:: python
print_values_ip(ip_list)
List floating IPs code listing example
--------------------------------------
.. code-block:: python
#!/usr/bin/env python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
from utils import print_values_ip
credentials = get_nova_credentials_v2()
nova_client = Client(**credentials)
ip_list = nova_client.floating_ips.list()
print_values_ip(ip_list)
List hosts (API v2)
~~~~~~~~~~~~~~~~~~~
The following program lists the hosts by using the Compute API v2.
#. Import the following modules:
.. code-block:: python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
from utils import print_hosts
The ``print_hosts`` method is defined in ``utils.py`` and prints the
host object details:
.. code-block:: python
def print_hosts(host_list):
for host in host_list:
print("-"*35)
print("host_name : %s" % host.host_name)
print("service : %s" % host.service)
print("zone : %s" % host.zone)
print("-"*35)
#. Get OpenStack credentials. See :ref:`Get OpenStack credentials (API v2)
<get-openstack-credentials>`.
#. Instantiate the ``nova_client`` client object by using the
``credentials`` dictionary object:
.. code-block:: python
nova_client = Client(**credentials)
#. List hosts by calling ``list()`` on ``nova_client.hosts`` object:
.. code-block:: python
host_list = nova_client.hosts.list()
#. Print the host object details by calling ``print_hosts(host_list)``:
.. code-block:: python
print_hosts(host_list)
List hosts code listing example
-------------------------------
.. code-block:: python
#!/usr/bin/env python
from credentials import get_nova_credentials_v2
from novaclient.client import Client
from utils import print_hosts
credentials = get_nova_credentials_v2()
nova_client = Client(**credentials)
host_list = nova_client.hosts.list()
print_hosts(host_list)

179
doc/user-guide/source/sdk-configure-access-security-instances.rst
View File

@ -1,179 +0,0 @@
===========================================
Configure access and security for instances
===========================================
When working with images in the SDK, you will call ``novaclient``
methods.
.. _add-keypair:
Add a keypair
~~~~~~~~~~~~~
To generate a keypair, call the
`novaclient.v1\_1.keypairs.KeypairManager.create <http://docs.
openstack.org/developer/python-novaclient/api/novaclient.v1_1.keypairs
.html#novaclient.v1_1.keypairs.KeypairManager.create>`__ method:
.. code-block:: python
import novaclient.v2.client as nvclient
nova = nvclient.Client(...)
keypair_name = "staging"
keypair = nova.keypairs.create(name=keypair_name)
print keypair.private_key
The Python script output looks something like this:
.. code-block:: console
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA8XkaMqInSPfy0hMfWO+OZRtIgrQAbQkNcaNHmv2GN2G6xZlb\nuBRux5Xk/6SZ
ABaNPm1nRWm/ZDHnxCsFTcAl2LYOQXx3Cl2qKNY4r2di4G48GAkd\n7k5lDP2RgQatUM8npO0CD9PU
...
mmrceYYK08/lQ7JKLmVkdzdQKt77+v1oBBuHiykLfI6h1m77NRDw9r8cV\nzczYeoALifpjTPMkKS8
ECfDCuDn/vc9K1He8CRaJHf8AMLQLM3MN
-----END RSA PRIVATE KEY-----
You typically write the private key to a file to use it later. The
file must be readable and writeable by only the file owner; otherwise,
the SSH client will refuse to read the private key file. The safest way
is to create the file with the appropriate permissions, as shown in the
following example:
.. code-block:: python
import novaclient.v2.client as nvclient
import os
nova = nvclient.Client(...)
keypair_name = "staging"
private_key_filename = "/home/alice/id-staging"
keypair = nova.keypairs.create(name=keypair_name)
# Create a file for writing that can only be read and written by
owner
fp = os.open(private_key_filename, os.O_WRONLY | os.O_CREAT, 0o600)
with os.fdopen(fp, 'w') as f:
f.write(keypair.private_key)
.. _import-keypair:
Import a keypair
~~~~~~~~~~~~~~~~
If you have already generated a keypair with the public key located at
``~/.ssh/id_rsa.pub``, pass the contents of the file to the
`novaclient.v1\_1.keypairs.KeypairManager.create <http://docs.
openstack.org/developer/python-novaclient/api/novaclient.v1_1.keypairs
.html#novaclient.v1_1.keypairs.KeypairManager.create>`__ method to
import the public key to Compute:
.. code-block:: python
import novaclient.v2.client as nvclient
import os.path
with open(os.path.expanduser('~/.ssh/id_rsa.pub')) as f:
public_key = f.read()
nova = nvclient.Client(...)
nova.keypairs.create('mykey', public_key)
.. _list-keypair:
List keypairs
~~~~~~~~~~~~~
To list keypairs, call the
`novaclient.v1\_1.keypairs.KeypairManager.list <https://docs.openstack.
org/developer/python-novaclient/api/novaclient.v1_1.keypairs.html
#novaclient.v1_1.keypairs.KeypairManager.list>`__ method:
.. code-block:: python
import novaclient.v2.client as nvclient
nova = nvclient.Client(...)
keypairs = nova.keypairs.list()
.. _create-manage-security-groups:
Create and manage security groups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To list security groups for the current project, call the
`novaclient.v\_1.security\_groups.SecurityGroupManager.list
<https://docs.openstack.org/developer/python-novaclient/api/novaclient
.v1_1.security_groups.html#novaclient.v1_1.security_groups.
SecurityGroupManager.list>`__ method:
.. code-block:: python
import novaclient.v2.client as nvclient
nova = nvclient.Client(...)
security_groups = nova.security_groups.list()
To create a security group with a specified name and description, call
the `novaclient.v\_1.security\_groups.SecurityGroupManager.create
<https://docs.openstack.org/developer/python-novaclient/api/novaclient.
v1_1.security_groups.html#novaclient.v1_1.security_groups.
SecurityGroupManager.create>`__ method:
.. code-block:: python
import novaclient.v2.client as nvclient
nova = nvclient.Client(...)
nova.security_groups.create(name="web", description="Web servers")
To delete a security group, call the
`novaclient.v\_1.security\_groups.SecurityGroupManager.delete
<https://docs.openstack.org/developer/python-novaclient/api/novaclient.
v1_1.security_groups.html#novaclient.v1_1.security_groups.
SecurityGroupManager.delete>`__ method, passing either a
`novaclient.v1\_1.security\_groups.SecurityGroup
<https://docs.openstack.org/developer/python-novaclient/api/novaclient
.v1_1.security_groups.html#novaclient.v1_1.security_groups.
SecurityGroup>`__ object or group ID as an argument:
.. code-block:: python
import novaclient.v2.client as nvclient
nova = nvclient.Client(...)
group = nova.security_groups.find(name="web")
nova.security_groups.delete(group)
# The following lines would also delete the group:
# nova.security_groups.delete(group.id)
# group.delete()
.. _create-manage-security-group-rules:
Create and manage security group rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Access the security group rules from the ``rules`` attribute of a
`novaclient.v1\_1.security\_groups.SecurityGroup <http://docs.
openstack.org/developer/python-novaclient/api/novaclient.v1_1.security
_groups.html#novaclient.v1_1.security_groups.SecurityGroup>`__ object:
.. code-block:: python
import novaclient.v2.client as nvclient
nova = nvclient.Client(...)
group = nova.security_groups.find(name="web")
print group.rules
To add a rule to a security group, call the
`novaclient.v1\_1.security\_group\_rules.SecurityGroupRuleManager.create
<https://docs.openstack.org/developer/python-novaclient/api/
novaclient.v1_1.security_group_rules.html#novaclient.v1_1.
security_group_rules.SecurityGroupRuleManager.create>`__ method:
.. code-block:: python
import novaclient.v2.client as nvclient
nova = nvclient.Client(...)
group = nova.security_groups.find(name="web")
# Add rules for ICMP, tcp/80 and tcp/443
nova.security_group_rules.create(group.id, ip_protocol="icmp",
from_port=-1, to_port=-1)
nova.security_group_rules.create(group.id, ip_protocol="tcp",
from_port=80, to_port=80)
nova.security_group_rules.create(group.id, ip_protocol="tcp",
from_port=443, to_port=443)

63
doc/user-guide/source/sdk-create-legacy-novaclient.rst
View File

@ -1,63 +0,0 @@
=============================
Create a Legacy Client Object
=============================
All of the legacy client objects can be constructed the same way - the only
difference is the first argument to ``make_client``. The examples will use
``compute`` to get a nova client, but neutron can be accessed instead by
replacing ``compute`` with ``network``.
To use the legacy ``python-novaclient`` with a Compute endpoint, instantiate a
`novaclient.v2.client.Client
<https://docs.openstack.org/developer/python-novaclient/ref/v2/client.html>`__
object using ``os-client-config``:
.. code-block:: python
import os_client_config
nova = os_client_config.make_client(
'compute',
auth_url='https://example.com',
username='example-openstack-user',
password='example-password',
project_name='example-project-name',
region_name='example-region-name')
If you desire a specific micro-version of the Nova API, you can pass that
as the ``version`` parameter:
.. code-block:: python
import os_client_config
nova = os_client_config.make_client(
'compute',
version='2.10',
auth_url='https://example.com',
username='example-openstack-user',
password='example-password',
project_name='example-project-name',
region_name='example-region-name')
If you authenticate against an endpoint that uses a custom
authentication back end, you must provide the name of the plugin in the
``auth_type`` parameter.
For instance, the Rackspace public cloud is an OpenStack deployment that has
an optional custom authentication back end. While normal keystone password
authentication works perfectly well, you may want to use the
custom Rackspace keystoneauth API Key plugin found in
`rackspace-keystoneauth-plugin <https://pypi.python.org/pypi/rackspaceauth>`_.
.. code-block:: python
nova = os_client_config.make_client(
'compute',
auth_type='rackspace_apikey',
auth_url='https://example.com',
username='example-openstack-user',
api_key='example-apikey',
project_name='example-project-name',
region_name='example-region-name')

10
doc/user-guide/source/sdk-install.rst
View File

@ -1,10 +0,0 @@
Installing OpenStack SDK
-------------------------
Each OpenStack project has its own Python library. These libraries are
bundled with the command-line clients. For example, the Python bindings
for the Compute API are bundled with the python-novaclient package.
For details about how to install the clients, see
:doc:`../common/cli-install-openstack-command-line-clients`.

129
doc/user-guide/source/sdk-manage-images.rst
View File

@ -1,129 +0,0 @@
=============
Manage images
=============
When working with images in the SDK, you will call both ``glance`` and
``nova`` methods.
.. _list-images:
List images
~~~~~~~~~~~
To list the available images, call the
``glanceclient.v2.images.Controller.list`` method:
.. code-block:: python
import glanceclient.v2.client as glclient
glance = glclient.Client(...)
images = glance.images.list()
The images method returns a Python generator, as shown in the following
interaction with the Python interpreter:
.. code-block:: python
>>> images = glance.images.list()
>>> images
<generator object list at 0x105e9c2d0>
>>> list(images)
[{u'checksum': u'f8a2eeee2dc65b3d9b6e63678955bd83',
u'container_format': u'ami',
u'created_at': u'2013-10-20T14:28:10Z',
u'disk_format': u'ami',
u'file': u'/v2/images/dbc9b2db-51d7-403d-b680-3f576380b00c/file',
u'id': u'dbc9b2db-51d7-403d-b680-3f576380b00c',
u'kernel_id': u'c002c82e-2cfa-4952-8461-2095b69c18a6',
u'min_disk': 0,
u'min_ram': 0,
u'name': u'cirros-0.3.5-x86_64-uec',
u'protected': False,
u'ramdisk_id': u'4c1c9b4f-3fe9-425a-a1ec-1d8fd90b4db3',
u'schema': u'/v2/schemas/image',
u'size': 25165824,
u'status': u'active',
u'tags': [],
u'updated_at': u'2013-10-20T14:28:11Z',
u'visibility': u'public'},
{u'checksum': u'69c33642f44ca552ba4bb8b66ad97e85',
u'container_format': u'ari',
u'created_at': u'2013-10-20T14:28:09Z',
u'disk_format': u'ari',
u'file': u'/v2/images/4c1c9b4f-3fe9-425a-a1ec-1d8fd90b4db3/file',
u'id': u'4c1c9b4f-3fe9-425a-a1ec-1d8fd90b4db3',
u'min_disk': 0,
u'min_ram': 0,
u'name': u'cirros-0.3.5-x86_64-uec-ramdisk',
u'protected': False,
u'schema': u'/v2/schemas/image',
u'size': 3714968,
u'status': u'active',
u'tags': [],
u'updated_at': u'2013-10-20T14:28:10Z',
u'visibility': u'public'},
{u'checksum': u'c352f4e7121c6eae958bc1570324f17e',
u'container_format': u'aki',
u'created_at': u'2013-10-20T14:28:08Z',
u'disk_format': u'aki',
u'file': u'/v2/images/c002c82e-2cfa-4952-8461-2095b69c18a6/file',
u'id': u'c002c82e-2cfa-4952-8461-2095b69c18a6',
u'min_disk': 0,
u'min_ram': 0,
u'name': u'cirros-0.3.5-x86_64-uec-kernel',
u'protected': False,
u'schema': u'/v2/schemas/image',
u'size': 4955792,
u'status': u'active',
u'tags': [],
u'updated_at': u'2013-10-20T14:28:09Z',
u'visibility': u'public'}]
.. _get-image-id:
Get image by ID
~~~~~~~~~~~~~~~
To retrieve an image object from its ID, call the
``glanceclient.v2.images.Controller.get`` method:
.. code-block:: python
import glanceclient.v2.client as glclient
image_id = 'c002c82e-2cfa-4952-8461-2095b69c18a6'
glance = glclient.Client(...)
image = glance.images.get(image_id)
.. _get-image-name:
Get image by name
~~~~~~~~~~~~~~~~~
The Image service Python bindings do not support the retrieval of an
image object by name. However, the Compute Python bindings enable you to
get an image object by name. To get an image object by name, call the
``novaclient.v2.images.ImageManager.find`` method:
.. code-block:: python
import novaclient.v2.client as nvclient
name = "cirros"
nova = nvclient.Client(...)
image = nova.images.find(name=name)
.. _upload-image:
Upload an image
~~~~~~~~~~~~~~~
To upload an image, call the ``glanceclient.v2.images.ImageManager.create``
method:
.. code-block:: python
import glanceclient.v2.client as glclient
imagefile = "/tmp/myimage.img"
glance = glclient.Client(...)
with open(imagefile) as fimage:
glance.images.create(name="myimage", is_public=False, disk_format="qcow2",
container_format="bare", data=fimage)

611
doc/user-guide/source/sdk-neutron-apis.rst
View File

@ -1,611 +0,0 @@
==========
Networking
==========
To use the information in this section, you should have a general
understanding of OpenStack Networking, OpenStack Compute, and the
integration between the two. You should also have access to a plug-in
that implements the Networking API v2.0.
.. _set-environment-variables:
Set environment variables
~~~~~~~~~~~~~~~~~~~~~~~~~
Make sure that you set the relevant environment variables.
As an example, see the sample shell file that sets these variables to
get credentials:
.. code-block:: bash
export OS_USERNAME="admin"
export OS_PASSWORD="password"
export OS_TENANT_NAME="admin"
export OS_AUTH_URL="http://IPADDRESS/v2.0"
.. _get-credentials:
Get credentials
~~~~~~~~~~~~~~~
The examples in this section use the ``get_credentials`` method:
.. code-block:: python
def get_credentials():
d = {}
d['username'] = os.environ['OS_USERNAME']
d['password'] = os.environ['OS_PASSWORD']
d['auth_url'] = os.environ['OS_AUTH_URL']
d['tenant_name'] = os.environ['OS_TENANT_NAME']
return d
This code resides in the ``credentials.py`` file, which all samples
import.
Use the ``get_credentials()`` method to populate and get a dictionary:
.. code-block:: python
credentials = get_credentials()
.. _get-nova-credentials:
Get Nova credentials
~~~~~~~~~~~~~~~~~~~~
The examples in this section use the ``get_nova_credentials`` method:
.. code-block:: python
def get_nova_credentials():
d = {}
d['username'] = os.environ['OS_USERNAME']
d['api_key'] = os.environ['OS_PASSWORD']
d['auth_url'] = os.environ['OS_AUTH_URL']
d['project_id'] = os.environ['OS_TENANT_NAME']
return d
This code resides in the ``credentials.py`` file, which all samples
import.
Use the ``get_nova_credentials()`` method to populate and get a
dictionary:
.. code-block:: python
nova_credentials = get_nova_credentials()
.. _print-values:
Print values
~~~~~~~~~~~~
The examples in this section use the ``print_values`` and
``print_values_server`` methods:
.. code-block:: python
def print_values(val, type):
if type == 'ports':
val_list = val['ports']
if type == 'networks':
val_list = val['networks']
if type == 'routers':
val_list = val['routers']
for p in val_list:
for k, v in p.items():
print("%s : %s" % (k, v))
print('\n')
def print_values_server(val, server_id, type):
if type == 'ports':
val_list = val['ports']
if type == 'networks':
val_list = val['networks']
for p in val_list:
bool = False
for k, v in p.items():
if k == 'device_id' and v == server_id:
bool = True
if bool:
for k, v in p.items():
print("%s : %s" % (k, v))
print('\n')
This code resides in the ``utils.py`` file, which all samples import.
.. _create-network:
Create network
~~~~~~~~~~~~~~
The following program creates a network:
.. code-block:: python
#!/usr/bin/env python
from neutronclient.v2_0 import client
from credentials import get_credentials
network_name = 'sample_network'
credentials = get_credentials()
neutron = client.Client(**credentials)
try:
body_sample = {'network': {'name': network_name,
'admin_state_up': True}}
netw = neutron.create_network(body=body_sample)
net_dict = netw['network']
network_id = net_dict['id']
print('Network %s created' % network_id)
body_create_subnet = {'subnets': [{'cidr': '192.168.199.0/24',
'ip_version': 4, 'network_id': network_id}]}
subnet = neutron.create_subnet(body=body_create_subnet)
print('Created subnet %s' % subnet)
finally:
print("Execution completed")
.. _list-network:
List networks
~~~~~~~~~~~~~
The following program lists networks:
.. code-block:: python
#!/usr/bin/env python
from neutronclient.v2_0 import client
from credentials import get_credentials
from utils import print_values
credentials = get_credentials()
neutron = client.Client(**credentials)
netw = neutron.list_networks()
print_values(netw, 'networks')
For ``print_values``, see :ref:`Print values <print-values>`.
.. _create-ports:
Create ports
~~~~~~~~~~~~
The following program creates a port:
.. code-block:: python
#!/usr/bin/env python
from neutronclient.v2_0 import client
import novaclient.v2.client as nvclient
from credentials import get_credentials
from credentials import get_nova_credentials
credentials = get_nova_credentials()
nova_client = nvclient.Client(**credentials)
# Replace with server_id and network_id from your environment
server_id = '9a52795a-a70d-49a8-a5d0-5b38d78bd12d'
network_id = 'ce5d204a-93f5-43ef-bd89-3ab99ad09a9a'
server_detail = nova_client.servers.get(server_id)
print(server_detail.id)
if server_detail != None:
credentials = get_credentials()
neutron = client.Client(**credentials)
body_value = {
"port": {
"admin_state_up": True,
"device_id": server_id,
"name": "port1",
"network_id": network_id
}
}
response = neutron.create_port(body=body_value)
print(response)
For ``get_nova_credentials``, see :ref:`Get Nova credentials
<get-nova-credentials>`.
For ``get_credentials``, see :ref:`Get credentials <get-credentials>`.
.. _list-ports:
List ports
~~~~~~~~~~
The following program lists ports:
.. code-block:: python
#!/usr/bin/env python
from neutronclient.v2_0 import client
from credentials import get_credentials
from utils import print_values
credentials = get_credentials()
neutron = client.Client(**credentials)
ports = neutron.list_ports()
print_values(ports, 'ports')
For ``get_credentials`` see :ref:`Get credentials <get-credentials>`.
For ``print_values``, see :ref:`Print values <print-values>`.
.. _list-server-ports:
List server ports
~~~~~~~~~~~~~~~~~
The following program lists the ports for a server:
.. code-block:: python
#!/usr/bin/env python
from neutronclient.v2_0 import client
import novaclient.v2.client as nvclient
from credentials import get_credentials
from credentials import get_nova_credentials
from utils import print_values_server
credentials = get_nova_credentials()
nova_client = nvclient.Client(**credentials)
# change these values according to your environment
server_id = '9a52795a-a70d-49a8-a5d0-5b38d78bd12d'
network_id = 'ce5d204a-93f5-43ef-bd89-3ab99ad09a9a'
server_detail = nova_client.servers.get(server_id)
print(server_detail.id)
if server_detail is not None:
credentials = get_credentials()
neutron = client.Client(**credentials)
ports = neutron.list_ports()
print_values_server(ports, server_id, 'ports')
body_value = {'port': {
'admin_state_up': True,
'device_id': server_id,
'name': 'port1',
'network_id': network_id,
}}
response = neutron.create_port(body=body_value)
print(response)
.. _create-port-add-port-subnet:
Create router and add port to subnet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This example queries OpenStack Networking to create a router and add a
port to a subnet.
#. Import the following modules:
.. code-block:: python
from neutronclient.v2_0 import client
import novaclient.v2.client as nvclient
from credentials import get_credentials
from credentials import get_nova_credentials
from utils import print_values_server
#. Get Nova Credentials. See :ref:'Get Nova credentials
<get-nova-credentials>'.
#. Instantiate the ``nova_client`` client object by using the
``credentials`` dictionary object:
.. code-block:: python
nova_client = nvclient.Client(**credentials)
#. Create a router and add a port to the subnet:
.. code-block:: python
# Replace with network_id from your environment
network_id = '81bf592a-9e3f-4f84-a839-ae87df188dc1'
credentials = get_credentials()
neutron = client.Client(**credentials)
neutron.format = json
request = {'router': {'name': 'router name',
'admin_state_up': True}}
router = neutron.create_router(request)
router_id = router['router']['id']
# for example: '72cf1682-60a8-4890-b0ed-6bad7d9f5466'
router = neutron.show_router(router_id)
print(router)
body_value = {'port': {
'admin_state_up': True,
'device_id': router_id,
'name': 'port1',
'network_id': network_id,
}}
response = neutron.create_port(body=body_value)
print(response)
print("Execution Completed")
Create router: complete code listing example
--------------------------------------------
.. code-block:: python
#!/usr/bin/env python
from neutronclient.v2_0 import client
import novaclient.v2.client as nvclient
from credentials import get_credentials
from credentials import get_nova_credentials
from utils import print_values_server
credentials = get_nova_credentials()
nova_client = nvclient.Client(**credentials)
# Replace with network_id from your environment
network_id = '81bf592a-9e3f-4f84-a839-ae87df188dc1'
try:
credentials = get_credentials()
neutron = client.Client(**credentials)
neutron.format = 'json'
request = {'router': {'name': 'router name',
'admin_state_up': True}}
router = neutron.create_router(request)
router_id = router['router']['id']
# for example: '72cf1682-60a8-4890-b0ed-6bad7d9f5466'
router = neutron.show_router(router_id)
print(router)
body_value = {'port': {
'admin_state_up': True,
'device_id': router_id,
'name': 'port1',
'network_id': network_id,
}}
response = neutron.create_port(body=body_value)
print(response)
finally:
print("Execution completed")
.. _delete-network:
Delete a network
~~~~~~~~~~~~~~~~
This example queries OpenStack Networking to delete a network.
To delete a network:
#. Import the following modules:
.. code-block:: python
from neutronclient.v2_0 import client
from credentials import get_credentials
#. Get credentials. See :ref:`Get Nova credentials <get-nova-credentials>`.
#. Instantiate the ``neutron`` client object by using the ``credentials``
dictionary object:
.. code-block:: python
neutron = client.Client(**credentials)
#. Delete the network:
.. code-block:: python
body_sample = {'network': {'name': network_name,
'admin_state_up': True}}
netw = neutron.create_network(body=body_sample)
net_dict = netw['network']
network_id = net_dict['id']
print('Network %s created' % network_id)
body_create_subnet = {'subnets': [{'cidr': '192.168.199.0/24',
'ip_version': 4, 'network_id': network_id}]}
subnet = neutron.create_subnet(body=body_create_subnet)
print('Created subnet %s' % subnet)
neutron.delete_network(network_id)
print('Deleted Network %s' % network_id)
print("Execution completed")
Delete network: complete code listing example
---------------------------------------------
.. code-block:: python
#!/usr/bin/env python
from neutronclient.v2_0 import client
from credentials import get_credentials
network_name = 'temp_network'
credentials = get_credentials()
neutron = client.Client(**credentials)
try:
body_sample = {'network': {'name': network_name,
'admin_state_up': True}}
netw = neutron.create_network(body=body_sample)
net_dict = netw['network']
network_id = net_dict['id']
print('Network %s created' % network_id)
body_create_subnet = {'subnets': [{'cidr': '192.168.199.0/24',
'ip_version': 4, 'network_id': network_id}]}
subnet = neutron.create_subnet(body=body_create_subnet)
print('Created subnet %s' % subnet)
neutron.delete_network(network_id)
print('Deleted Network %s' % network_id)
finally:
print("Execution Completed")
.. _list-routers:
List routers
~~~~~~~~~~~~
This example queries OpenStack Networking to list all routers.
#. Import the following modules:
.. code-block:: python
from neutronclient.v2_0 import client
from credentials import get_credentials
from utils import print_values
#. Get credentials. See :ref:`Get Nova credentials <get-nova-credentials>`.
#. Instantiate the ``neutron`` client object by using the ``credentials``
dictionary object:
.. code-block:: python
neutron = client.Client(**credentials)
#. List the routers:
.. code-block:: python
routers_list = neutron.list_routers(retrieve_all=True)
print_values(routers_list, 'routers')
print("Execution completed")
For ``print_values``, see :ref:`Print values <print-values>`.
List routers: complete code listing example
-------------------------------------------
.. code-block:: python
#!/usr/bin/env python
from neutronclient.v2_0 import client
from credentials import get_credentials
from utils import print_values
try:
credentials = get_credentials()
neutron = client.Client(**credentials)
routers_list = neutron.list_routers(retrieve_all=True)
print_values(routers_list, 'routers')
finally:
print("Execution completed")
.. _list-security-groups:
List security groups
~~~~~~~~~~~~~~~~~~~~
This example queries OpenStack Networking to list security groups.
#. Import the following modules:
.. code-block:: python
from neutronclient.v2_0 import client
from credentials import get_credentials
from utils import print_values
#. Get credentials. See :ref:`Get credentials <get-credentials>`.
#. Instantiate the ``neutron`` client object by using the ``credentials``
dictionary object:
.. code-block:: python
neutron = client.Client(**credentials)
#. List Security groups
.. code-block:: python
sg = neutron.list_security_groups()
print(sg)
List security groups: complete code listing example
---------------------------------------------------
.. code-block:: python
#!/usr/bin/env python
from neutronclient.v2_0 import client
from credentials import get_credentials
from utils import print_values
credentials = get_credentials()
neutron = client.Client(**credentials)
sg = neutron.list_security_groups()
print(sg)
.. note::
OpenStack Networking security groups are case-sensitive while the
nova-network security groups are case-insensitive.
List subnets
~~~~~~~~~~~~
This example queries OpenStack Networking to list subnets.
#. Import the following modules:
.. code-block:: python
from neutronclient.v2_0 import client
from credentials import get_credentials
from utils import print_values
#. Get credentials. See :ref:'Get credentials <get-credentials>'.
#. Instantiate the ``neutron`` client object by using the ``credentials``
dictionary object:
.. code-block:: python
neutron = client.Client(**credentials)
#. List subnets:
.. code-block:: python
subnets = neutron.list_subnets()
print(subnets)
List subnets: complete code listing example
-------------------------------------------
.. code-block:: python
#!/usr/bin/env python
from neutronclient.v2_0 import client
from credentials import get_credentials
from utils import print_values
credentials = get_credentials()
neutron = client.Client(**credentials)
subnets = neutron.list_subnets()
print(subnets)

60
doc/user-guide/source/sdk-overview.rst
View File

@ -1,60 +0,0 @@
========
Overview
========
OpenStack provides four different options for interacting with its
APIs from Python, each targeting a slightly different user:
- OpenStack SDK
- shade
- Per-project client libraries
- Direct REST calls via keystoneauth
You should also be familiar with:
- RESTful web services
- HTTP/1.1
- JSON and data serialization formats
OpenStack SDK
-------------
The `OpenStack Python Software Development Kit (SDK)
<https://pypi.python.org/pypi/openstacksdk>`_ is used to write Python
automation scripts that create and manage resources in your OpenStack
cloud. The SDK implements Python bindings to the OpenStack API, which
enables you to perform automation tasks in Python by making calls on
Python objects, rather than making REST calls directly.
New users should default to coding against the OpenStack SDK.
shade
-----
`shade <http://pypi.python.org/pypi/shade>`_ is an abstraction library
focused on hiding implementation differences between OpenStack clouds. While
the OpenStack SDK presents a clean object interface to the underlying REST
APIs, shade hides them if doing so is advantageous. If you plan on
running the same Python program against many OpenStack clouds, you may want to
use shade - but if you need to access any features of a cloud that do not have
a cloud-neutral abstraction mapping, you will be unable to do so with shade.
Per-project client libraries
----------------------------
Each OpenStack project produces a client library that wraps its own REST API.
Unless there is no other choice for some reason, the per-project libraries
should be avoided.
Direct REST calls via keystoneauth
----------------------------------
All of OpenStack's APIs are actually REST APIs. The
`keystoneauth <https://docs.openstack.org/developer/keystoneauth>`_ library
provides an object that looks very much like a
`Session <http://docs.python-requests.org/en/master/api/#request-sessions>`_
object from the Python
`requests <http://pypi.python.org/pypi/requests>`_ library that handles all
of the authentication for you. If you are more comfortable just dealing with
REST or if there is a feature implemented in your cloud that has not seen
support in any of the libraries yet, this option is for you.

57
doc/user-guide/source/sdk-schedule-objects-for-deletion.rst
View File

@ -1,57 +0,0 @@
=============================
Schedule objects for deletion
=============================
To determine whether your Object Storage system supports this feature,
see :doc:`managing-openstack-object-storage-with-swift-cli`.
Alternatively, check with your service provider.
Scheduling an object for deletion is helpful for managing objects that
you do not want to permanently store, such as log files, recurring full
backups of a dataset, or documents or images that become outdated at a
specified time.
To schedule an object for deletion, include one of these headers with
the ``PUT`` or ``POST`` request on the object:
X-Delete-At
A UNIX epoch timestamp, in integer form. For example, ``1348691905``
represents ``Wed, 26 Sept 2012 20:38:25 GMT``. It specifies the time you
want the object to expire, no longer be served, and be deleted completely
from the object store.
X-Delete-After
An integer value which specifies the number of seconds from the time of
the request to when you want to delete the object.
This header is converted to a ``X-Delete-At`` header that is set to
the sum of the ``X-Delete-After`` value plus the current time, in
seconds.
.. note::
Use `EpochConverter <http://www.epochconverter.com/>`_ to convert dates to
and from epoch timestamps and for batch conversions.
Use the POST method to assign expiration headers to existing objects
that you want to expire.
In this example, the ``X-Delete-At`` header is assigned a UNIX epoch
timestamp in integer form for ``Mon, 11 Jun 2012 15:38:25 GMT``.
.. code-block:: console
$ curl -i publicURL/marktwain/goodbye -X PUT -H "X-Auth-Token: token" \
-H "X-Delete-At: 1390581073" -H "Content-Length: 14" -H \
"Content-Type: application/octet-stream"
In this example, the ``X-Delete-After`` header is set to 864000 seconds.
The object expires after this time.
.. code-block:: console
PUT /<api version>/<account>/<container>/<object> HTTP/1.1
Host: storage.example.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Content-Type: image/jpeg
X-Delete-After: 864000

17
doc/user-guide/source/sdk.rst
View File

@ -1,17 +0,0 @@
====================
OpenStack Python SDK
====================
.. toctree::
:maxdepth: 2
sdk-overview.rst
sdk-install.rst
sdk-authenticate.rst
sdk-create-legacy-novaclient.rst
sdk-manage-images.rst
sdk-assign-cors-headers.rst
sdk-schedule-objects-for-deletion.rst
sdk-configure-access-security-instances.rst
sdk-neutron-apis.rst
sdk-compute-apis.rst

168
doc/user-guide/source/set-up-clustering.rst
View File

@ -1,168 +0,0 @@
==========================
Set up database clustering
==========================
You can store data across multiple machines by setting up MongoDB
sharded clusters.
Each cluster includes:
- One or more *shards*. Each shard consists of a three member replica
set (three instances organized as a replica set).
- One or more *query routers*. A query router is the machine that your
application actually connects to. This machine is responsible for
communicating with the config server to figure out where the
requested data is stored. It then accesses and returns the data from
the appropriate shard(s).
- One or more *config servers*. Config servers store the metadata that
links requested data with the shard that contains it.
This example shows you how to set up a MongoDB sharded cluster.
.. note::
**Before you begin.** Make sure that:
- The administrative user has registered a MongoDB datastore type and
version.
- The administrative user has created an appropriate :ref:`flavor that
meets the MongoDB minimum requirements <create_db>`.
Set up clustering
~~~~~~~~~~~~~~~~~
#. **Create a cluster**
Create a cluster by using the :command:`trove cluster-create` command. This
command creates a one-shard cluster. Pass in:
- The name of the cluster.
- The name and version of the datastore you want to use.
- The three instances you want to include in the replication set for
the first shard. Specify each instance by using the ``--instance``
argument and the associated flavor ID and volume size. Use the
same flavor ID and volume size for each instance. In this example,
flavor ``7`` is a custom flavor that meets the MongoDB minimum
requirements.
.. code-block:: console
$ trove cluster-create cluster1 mongodb "2.4" \
--instance flavor=7,volume=2 --instance flavor=7,volume=2 \
--instance flavor=7,volume=2
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-08-16T01:46:51 |
| datastore | mongodb |
| datastore_version | 2.4 |
| id | aa6ef0f5-dbef-48cd-8952-573ad881e717 |
| name | cluster1 |
| task_description | Building the initial cluster. |
| task_name | BUILDING |
| updated | 2014-08-16T01:46:51 |
+-------------------+--------------------------------------+
#. **Display cluster information**
Display information about a cluster by using the
:command:`trove cluster-show` command. Pass in the ID of the cluster.
The cluster ID displays when you first create a cluster. (If you need
to find it later on, use the :command:`trove cluster-list` command to list
the names and IDs of all the clusters in your system.)
.. code-block:: console
$ trove cluster-show CLUSTER_ID
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-08-16T01:46:51 |
| datastore | mongodb |
| datastore_version | 2.4 |
| id | aa6ef0f5-dbef-48cd-8952-573ad881e717 |
| ip | 10.0.0.2 |
| name | cluster1 |
| task_description | No tasks for the cluster. |
| task_name | NONE |
| updated | 2014-08-16T01:59:33 |
+-------------------+--------------------------------------+
.. note::
**Your application connects to this IP address.** The :command:`trove cluster-show`
command displays the IP address of the query router.
This is the IP address your application uses to retrieve data from
the database.
#. **List cluster instances**
List the instances in a cluster by using the
:command:`trove cluster-instances` command.
.. code-block:: console
$ trove cluster-instances CLUSTER_ID
+--------------------------------------+----------------+-----------+------+
| ID | Name | Flavor ID | Size |
+--------------------------------------+----------------+-----------+------+
| 45532fc4-661c-4030-8ca4-18f02aa2b337 | cluster1-rs1-1 | 7 | 2 |
| 7458a98d-6f89-4dfd-bb61-5cf1dd65c121 | cluster1-rs1-2 | 7 | 2 |
| b37634fb-e33c-4846-8fe8-cf2b2c95e731 | cluster1-rs1-3 | 7 | 2 |
+--------------------------------------+----------------+-----------+------+
**Naming conventions for replication sets and instances.** Note
that the ``Name`` column displays an instance name that includes the
replication set name. The replication set names and instance names
are automatically generated, following these rules:
- **Replication set name.** This name consists of the cluster
name, followed by the string -rs\ *n*, where *n* is 1 for
the first replication set you create, 2 for the second replication
set, and so on. In this example, the cluster name is ``cluster1``,
and there is only one replication set, so the replication set name
is ``cluster1-rs1``.
- **Instance name.** This name consists of the replication set
name followed by the string -*n*, where *n* is 1 for the
first instance in a replication set, 2 for the second
instance, and so on. In this example, the instance names are
``cluster1-rs1-1``, ``cluster1-rs1-2``, and ``cluster1-rs1-3``.
#. **List clusters**
List all the clusters in your system, using the
:command:`trove cluster-list` command.
.. code-block:: console
$ trove cluster-list
+--------------------------------------+----------+-----------+-------------------+-----------+
| ID | Name | Datastore | Datastore Version | Task Name |
+--------------------------------------+----------+-----------+-------------------+-----------+
| aa6ef0f5-dbef-48cd-8952-573ad881e717 | cluster1 | mongodb | 2.4 | NONE |
| b8829c2a-b03a-49d3-a5b1-21ec974223ee | cluster2 | mongodb | 2.4 | BUILDING |
+--------------------------------------+----------+-----------+-------------------+-----------+
#. **Delete a cluster**
Delete a cluster, using the :command:`trove cluster-delete` command.
.. code-block:: console
$ trove cluster-delete CLUSTER_ID
Query routers and config servers
--------------------------------
Each cluster includes at least one query router and one config server.
Query routers and config servers count against your quota. When you
delete a cluster, the system deletes the associated query router(s) and
config server(s).

109
doc/user-guide/source/set-up-replication.rst
View File

@ -1,109 +0,0 @@
===========================
Set up database replication
===========================
You can create a replica of an existing database instance. When you make
subsequent changes to the original instance, the system automatically
applies those changes to the replica.
- Replicas are read-only.
- When you create a replica, do not specify the ``--users`` or
``--databases`` options.
- You can choose a smaller volume or flavor for a replica than for the
original, but the replica's volume must be big enough to hold the
data snapshot from the original.
This example shows you how to replicate a MySQL database instance.
Set up replication
~~~~~~~~~~~~~~~~~~
#. **Get the instance ID**
Get the ID of the original instance you want to replicate:
.. code-block:: console
$ trove list
+-----------+------------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+-----------+------------+-----------+-------------------+--------+-----------+------+
| 97b...ae6 | base_1 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
+-----------+------------+-----------+-------------------+--------+-----------+------+
#. **Create the replica**
Create a new instance that will be a replica of the original
instance. You do this by passing in the ``--replica_of`` option with
the :command:`trove create` command. This example creates a replica
called ``replica_1``. ``replica_1`` is a replica of the original instance,
``base_1``:
.. code-block:: console
$ trove create replica_1 6 --size=5 --datastore_version mysql-5.5 \
--datastore mysql --replica_of ID_OF_ORIGINAL_INSTANCE
#. **Verify replication status**
Pass in ``replica_1``'s instance ID with the :command:`trove show` command
to verify that the newly created ``replica_1`` instance is a replica
of the original ``base_1``. Note that the ``replica_of`` property is
set to the ID of ``base_1``.
.. code-block:: console
$ trove show INSTANCE_ID_OF_REPLICA_1
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-09-16T11:16:49 |
| datastore | mysql |
| datastore_version | mysql-5.5 |
| flavor | 6 |
| id | 49c6eff6-ef91-4eff-91c0-efbda7e83c38 |
| name | replica_1 |
| replica_of | 97b4b853-80f6-414f-ba6f-c6f455a79ae6 |
| status | BUILD |
| updated | 2014-09-16T11:16:49 |
| volume | 5 |
+-------------------+--------------------------------------+
Now pass in ``base_1``'s instance ID with the :command:`trove show` command
to list the replica(s) associated with the original instance. Note
that the ``replicas`` property is set to the ID of ``replica_1``. If
there are multiple replicas, they appear as a comma-separated list.
.. code-block:: console
$ trove show INSTANCE_ID_OF_BASE_1
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-09-16T11:04:56 |
| datastore | mysql |
| datastore_version | mysql-5.5 |
| flavor | 6 |
| id | 97b4b853-80f6-414f-ba6f-c6f455a79ae6 |
| ip | 172.16.200.2 |
| name | base_1 |
| replicas | 49c6eff6-ef91-4eff-91c0-efbda7e83c38 |
| status | ACTIVE |
| updated | 2014-09-16T11:05:06 |
| volume | 5 |
| volume_used | 0.11 |
+-------------------+--------------------------------------+
#. **Detach the replica**
If the original instance goes down, you can detach the replica. The
replica becomes a standalone database instance. You can then take the
new standalone instance and create a new replica of that instance.
You detach a replica using the :command:`trove detach-replica` command:
.. code-block:: console
$ trove detach-replica INSTANCE_ID_OF_REPLICA

18
doc/user-guide/source/trove-manage-db.rst
View File

@ -1,18 +0,0 @@
===========================
Create and manage databases
===========================
The Database service provides scalable and reliable cloud provisioning
functionality for both relational and non-relational database engines.
Users can quickly and easily use database features without the burden of
handling complex administrative tasks.
.. toctree::
:maxdepth: 1
create-db.rst
backup-db.rst
backup-db-incremental.rst
manage-db-config.rst
set-up-replication.rst
set-up-clustering.rst

7
tools/build-all-rst.sh
View File

@ -28,12 +28,13 @@ done
# PDF targets for Install guides are dealt in build-install-guides-rst.sh
PDF_TARGETS=( 'arch-design'\
'ha-guide' 'image-guide'\
'ops-guide' 'user-guide' )
'ha-guide' \
'image-guide'\
'ops-guide' )
# Note that these guides are only build for master branch
for guide in admin-guide arch-design contributor-guide \
ha-guide image-guide ops-guide user-guide; do
ha-guide image-guide ops-guide; do
if [[ ${PDF_TARGETS[*]} =~ $guide ]]; then
tools/build-rst.sh doc/$guide --build build \
--target $guide $LINKCHECK $PDF_OPTION

2
tools/www-generator.py
View File

@ -79,6 +79,8 @@ _URLS = [
'https://docs.openstack.org/{name}/{series}/configuration/'),
('has_in_tree_api_docs',
'https://docs.openstack.org/{name}/{series}/api/'),
('has_user_guide',
'https://docs.openstack.org/{name}/{series}/user/'),
('has_api_ref',
'https://developer.openstack.org/api-ref/{service_type}/'),
('has_api_guide',

3
www/.htaccess
View File

@ -43,6 +43,9 @@ redirect 301 /networking-guide/ /ocata/networking-guide/
# Redirect old releases content to new location
redirectmatch 301 "^/releases.*$" http://releases.openstack.org$1
# Redirect removed user guide
redirectmatch 301 /user-guide/.*$ /user/
# Redirect changed directory name in the Contributor Guide
redirect 301 /contributor-guide/ui-text-guidelines.html /contributor-guide/ux-ui-guidelines/ui-text-guidelines.html
redirect 301 /contributor-guide/ui-text-guidelines /contributor-guide/ux-ui-guidelines

12
www/project-data/latest.yaml
View File

@ -31,6 +31,7 @@
has_config_ref: true
has_admin_guide: true
type: service
has_user_guide: true
- name: python-glanceclient
service: Image service Python Bindings
type: client
@ -80,10 +81,12 @@
service: BaGPipe backend
type: networking
has_install_guide: true
has_user_guide: true
- name: networking-bgpvpn
service: BGP-MPLS VPN Networking service Plug-in
type: networking
has_install_guide: true
has_user_guide: true
- name: neutron-dynamic-routing
service: Dynamic Routing service Plug-in
type: networking
@ -114,6 +117,7 @@
has_install_guide: true
has_config_ref: true
has_admin_guide: true
has_user_guide: true
type: service
- name: django_openstack_auth
service: pluggable Django authentication backend for authenticating with Keystone
@ -149,6 +153,7 @@
has_api_ref: true
has_admin_guide: true
# has_config_ref: true
has_user_guide: true
type: service
- name: python-ironicclient
service: Bare Metal service Python Bindings
@ -190,6 +195,7 @@
# has_install_guide: true
# has_config_ref: true
has_api_ref: true
has_user_guide: true
type: service
- name: python-designateclient
service: DNS service Python Bindings
@ -318,6 +324,7 @@
has_install_guide: true
has_admin_guide: true
# has_config_ref: true
has_user_guide: true
- name: python-watcherclient
service: Infrastructure Optimization service Python Bindings
type: client
@ -341,6 +348,7 @@
has_install_guide: false
has_api_ref: true
# has_config_ref: true
has_user_guide: true
- name: python-muranoclient
service: Application Catalog service Python Bindings
type: client
@ -352,6 +360,7 @@
type: service
has_install_guide: false
# has_config_ref: true
has_user_guide: true
- name: python-senlinclient
service: Clustering service Python Bindings
type: client
@ -380,6 +389,7 @@
has_install_guide: true
has_api_ref: true
# has_config_ref: true
has_user_guide: true
- name: python-tackerclient
service: NFV Orchestration service Python Bindings
type: client
@ -563,6 +573,7 @@
has_config_ref: true
has_admin_guide: true
type: service
has_user_guide: true
- name: python-octaviaclient
service: Load-balancer service client
type: client
@ -614,6 +625,7 @@
type: client
description: shade client library
has_install_guide: true
has_user_guide: true
- name: solum
service: Software Development Lifecycle Automation service

Some files were not shown because too many files have changed in this diff Show More