openstack/openstack-manuals
Code Issues Proposed changes

Remove DocBook User Guides

Browse Source 
Remove DocBook User Guides and also the moved hot-guide.

Publish RST User Guides instead.
Remove workarounds for old tools.

Change-Id: I3fcc3972452959183c099daaf8226d7734445650
This commit is contained in:
Andreas Jaeger 2015-04-08 16:56:49 +02:00
parent cb45d60cb1
commit fa3477a19d
129 changed files with 20 additions and 55316 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,15 +1,15 @@
# directories to be set up
declare -A DIRECTORIES=(
["fr"]="common glossary user-guide image-guide"
["ja"]="common glossary image-guide install-guide user-guide user-guide-admin"
["fr"]="common glossary image-guide"
["ja"]="common glossary image-guide install-guide"
["pt_BR"]="common install-guide"
["zh_CN"]="common glossary arch-design image-guide install-guide"
)
# books to be built
declare -A BOOKS=(
["fr"]="user-guide image-guide"
["ja"]="image-guide install-guide user-guide user-guide-admin"
["fr"]="image-guide"
["ja"]="image-guide install-guide"
["pt_BR"]="install-guide"
["zh_CN"]="arch-design image-guide install-guide"
)
@ -27,5 +27,4 @@ declare -A SPECIAL_BOOKS
SPECIAL_BOOKS=(
["user-guides"]="RST"
["networking-guide"]="skip"
["hot-guide"]="skip"
)

177
doc/hot-guide/Makefile
View File

@ -1,177 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/HOTTemplatesGuide.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/HOTTemplatesGuide.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/HOTTemplatesGuide"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/HOTTemplatesGuide"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The xml files are in $(BUILDDIR)/xml."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

81
doc/hot-guide/pom.xml
View File

@ -1,81 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>
<groupId>org.openstack.docs</groupId>
<artifactId>parent-pom</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>openstack-hot-guide</artifactId>
<packaging>jar</packaging>
<name>OpenStack HOT templates guide</name>
<properties>
<!-- This is set by Jenkins according to the branch. -->
<release.path.name>local</release.path.name>
<comments.enabled>0</comments.enabled>
</properties>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
<build>
<plugins>
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<!-- version is set in ../pom.xml file -->
<executions>
<execution>
<id>generate-webhelp</id>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<!-- These parameters only apply to webhelp -->
<enableDisqus>0</enableDisqus>
<disqusShortname>os-hot-guide</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
<generateToc>
appendix toc,title
article/appendix nop
article toc,title
book toc,title,figure,table,example,equation
chapter toc
section toc
part toc
preface toc
qandadiv toc
qandaset toc
reference toc,title
set toc,title
</generateToc>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>0</sectionAutolabel>
<formalProcedures>0</formalProcedures>
<tocSectionDepth>1</tocSectionDepth>
<tocChapterDepth>1</tocChapterDepth>
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
<webhelpDirname>hot-guide</webhelpDirname>
<pdfFilenameBase>hot-guide</pdfFilenameBase>
</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
<profileAudience>enduser</profileAudience>
<xincludeSupported>true</xincludeSupported>
<sourceDirectory>.</sourceDirectory>
<includes>
build/docbook/index.xml
</includes>
<branding>openstack</branding>
<canonicalUrlBase>http://docs.openstack.org/hot-guide/content</canonicalUrlBase>
</configuration>
</plugin>
</plugins>
</build>
</project>

507
doc/hot-guide/source/basic_resources.rst
View File

@ -1,507 +0,0 @@
.. _hot_basic_resources:
#########
Instances
#########
.. For consistency let's define a few values to use in the samples:
* image name: ubuntu-trusty-x86_64
* shared/provider network name: "public"
* tenant network and subnet names: "private" and "private-subnet"
Manage instances
================
Create an instance
------------------
Use the :hotref:`OS::Nova::Server` resource to create a Compute instance. The
``flavor`` property is the only mandatory one, but you need to define a boot
source using one of the ``image`` or ``block_device_mapping`` properties.
You also need to define the ``networks`` property to indicate to which networks
your instance must connect if multiple networks are available in your tenant.
The following example creates a simple instance, booted from an image, and
connecting to the ``private`` network:
.. code-block:: yaml
resources:
instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: private
Connect an instance to a network
--------------------------------
Use the ``networks`` property of an :hotref:`OS::Nova::Server` resource to
define which networks an instance should connect to. Define each network as a
YAML map, containing one of the following keys:
``port``
The ID of an existing Networking port. You usually create this port in the
same template using an :hotref:`OS::Neutron::Port` resource. You will be
able to associate a floating IP to this port, and the port to your Compute
instance.
``network``
The name or ID of an existing network. You don't need to create an
:hotref:`OS::Neutron::Port` resource if you use this property, but you will
not be able to associate a floating IP with the instance interface in the
template.
The following example demonstrates the use of the ``port`` and ``network``
properties:
.. code-block:: yaml
resources:
instance_port:
type: OS::Neutron::Port
properties:
network: private
fixed_ips:
- subnet_id: "private-subnet"
instance1:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- port: { get_resource: instance_port }
instance2:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: private
Create and associate security groups to an instance
---------------------------------------------------
Use the :hotref:`OS::Neutron::SecurityGroup` resource to create security
groups.
Define the ``security_groups`` property of the :hotref:`OS::Neutron::Port`
resource to associate security groups to a port, then associate the port to an
instance.
The following example creates a security group allowing inbound connections on
ports 80 and 443 (web server) and associates this security group to an instance
port:
.. code-block:: yaml
resources:
web_secgroup:
type: OS::Neutron::SecurityGroup
properties:
rules:
- protocol: tcp
remote_ip_prefix: 0.0.0.0/0
port_range_min: 80
port_range_max: 80
- protocol: tcp
remote_ip_prefix: 0.0.0.0/0
port_range_min: 443
port_range_max: 443
instance_port:
type: OS::Neutron::Port
properties:
network: private
security_groups:
- default
- { get_resource: web_secgroup }
fixed_ips:
- subnet_id: private-subnet
instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- port: { get_resource: instance_port }
Create and associate a floating IP to an instance
-------------------------------------------------
You can use two sets of resources to create and associate floating IPs to
instances.
OS::Nova resources
~~~~~~~~~~~~~~~~~~
Use the :hotref:`OS::Nova::FloatingIP` resource to create a floating IP, and
the :hotref:`OS::Nova::FloatingIPAssociation` resource to associate the
floating IP to an instance.
The following example creates an instance and a floating IP, and associate the
floating IP to the instance:
.. code-block:: yaml
resources:
floating_ip:
type: OS::Nova::FloatingIP
properties:
pool: public
inst1:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: private
association:
type: OS::Nova::FloatingIPAssociation
properties:
floating_ip: { get_resource: floating_ip }
server_id: { get_resource: instance }
OS::Neutron resources
~~~~~~~~~~~~~~~~~~~~~
.. note::
The Networking service (neutron) must be enabled on your OpenStack
deployment to use these resources.
Use the :hotref:`OS::Neutron::FloatingIP` resource to create a floating IP, and
the :hotref:`OS::Neutron::FloatingIPAssociation` resource to associate the
floating IP to a port:
.. code-block:: yaml
parameters:
net:
description: name of network used to launch instance.
type: string
default: private
resources:
inst1:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: {get_param: net}
floating_ip:
type: OS::Neutron::FloatingIP
properties:
floating_network: public
association:
type: OS::Neutron::FloatingIPAssociation
properties:
floatingip_id: { get_resource: floating_ip }
port_id: {get_attr: [inst1, addresses, {get_param: net}, 0, port]}
You can also create an OS::Neutron::Port and associate that with the server and
the floating IP. However the approach mentioned above will work better
with stack updates.
.. code-block:: yaml
resources:
instance_port:
type: OS::Neutron::Port
properties:
network: private
fixed_ips:
- subnet_id: "private-subnet"
floating_ip:
type: OS::Neutron::FloatingIP
properties:
floating_network: public
association:
type: OS::Neutron::FloatingIPAssociation
properties:
floatingip_id: { get_resource: floating_ip }
port_id: { get_resource: instance_port }
Enable remote access to an instance
-----------------------------------
The ``key_name`` attribute of the :hotref:`OS::Nova::Server` resource defines
the key pair to use to enable SSH remote access:
.. code-block:: yaml
resources:
my_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
key_name: my_key
.. note::
For more information about key pairs, see the `Configure access and
security for instances`_ section of the OpenStack user guide.
.. _`Configure access and security for instances`: http://docs.openstack.org/user-guide/content/cli_configure_instances.html
Create a key pair
-----------------
You can create new key pairs with the :hotref:`OS::Nova::KeyPair` resource. Key
pairs can be imported or created during the stack creation.
If the ``public_key`` property is not specified, the Orchestration module
creates a new key pair. If the ``save_private_key`` property is set to
``true``, the ``private_key`` attribute of the resource holds the private key.
The following example creates a new key pair and uses it as authentication key
for an instance:
.. code-block:: yaml
resources:
my_key:
type: OS::Nova::KeyPair
properties:
save_private_key: true
my_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
key_name: { get_resource: my_key }
outputs:
private_key:
description: Private key
value: { get_attr: [ my_key, private_key ] }
Manage networks
===============
Create a network and a subnet
-----------------------------
.. note::
The Networking service (neutron) must be enabled on your OpenStack
deployment to create and manage networks and subnets. Networks and subnets
cannot be created if your deployment uses legacy networking (nova-network).
Use the :hotref:`OS::Neutron::Net` resource to create a network, and the
:hotref:`OS::Neutron::Subnet` resource to provide a subnet for this network:
.. code-block:: yaml
resources:
new_net:
type: OS::Neutron::Net
new_subnet:
type: OS::Neutron::Subnet
properties:
network_id: { get_resource: new_net }
cidr: "10.8.1.0/24"
dns_nameservers: [ "8.8.8.8", "8.8.4.4" ]
ip_version: 4
Create and manage a router
--------------------------
Use the :hotref:`OS::Neutron::Router` resource to create a router. You can
define its gateway with the ``external_gateway_info`` property:
.. code-block:: yaml
resources:
router1:
type: OS::Neutron::Router
properties:
external_gateway_info: { network: public }
You can connect subnets to routers with the
:hotref:`OS::Neutron::RouterInterface` resource:
.. code-block:: yaml
resources:
subnet1_interface:
type: OS::Neutron::RouterInterface
properties:
router_id: { get_resource: router1 }
subnet: private-subnet
Complete network example
------------------------
The following example creates a network stack:
* A network and an associated subnet.
* A router with an external gateway.
* An interface to the new subnet for the new router.
In this example, the ``public`` network is an existing shared network:
.. code-block:: yaml
resources:
internal_net:
type: OS::Neutron::Net
internal_subnet:
type: OS::Neutron::Subnet
properties:
network_id: { get_resource: internal_net }
cidr: "10.8.1.0/24"
dns_nameservers: [ "8.8.8.8", "8.8.4.4" ]
ip_version: 4
internal_router:
type: OS::Neutron::Router
properties:
external_gateway_info: { network: public }
internal_interface:
type: OS::Neutron::RouterInterface
properties:
router_id: { get_resource: internal_router }
subnet: { get_resource: internal_subnet }
Manage volumes
==============
Create a volume
---------------
Use the :hotref:`OS::Cinder::Volume` resource to create a new Block Storage
volume.
For example:
.. code-block:: yaml
resources:
my_new_volume:
type: OS::Cinder::Volume
properties:
size: 10
The volumes that you create are empty by default. Use the ``image`` property to
create a bootable volume from an existing image:
.. code-block:: yaml
resources:
my_new_bootable_volume:
type: OS::Cinder::Volume
properties:
size: 10
image: ubuntu-trusty-x86_64
You can also create new volumes from another volume, a volume snapshot, or a
volume backup. Use the ``source_volid``, ``snapshot_id`` or ``backup_id``
properties to create a new volume from an existing source.
For example, to create a new volume from a backup:
.. code-block:: yaml
resources:
another_volume:
type: OS::Cinder::Volume
properties:
backup_id: 2fff50ab-1a9c-4d45-ae60-1d054d6bc868
In this example the ``size`` property is not defined because the Block Storage
service uses the size of the backup to define the size of the new volume.
Attach a volume to an instance
------------------------------
Use the :hotref:`OS::Cinder::VolumeAttachment` resource to attach a volume to
an instance.
The following example creates a volume and an instance, and attaches the volume
to the instance:
.. code-block:: yaml
resources:
new_volume:
type: OS::Cinder::Volume
properties:
size: 1
new_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
volume_attachment:
type: OS::Cinder::VolumeAttachment
properties:
volume_id: { get_resource: new_volume }
instance_uuid: { get_resource: new_instance }
Boot an instance from a volume
------------------------------
Use the ``block_device_mapping`` property of the :hotref:`OS::Nova::Server`
resource to define a volume used to boot the instance. This property is a list
of volumes to attach to the instance before its boot.
The following example creates a bootable volume from an image, and uses it to
boot an instance:
.. code-block:: yaml
resources:
bootable_volume:
type: OS::Cinder::Volume
properties:
size: 10
image: ubuntu-trusty-x86_64
instance:
type: OS::Nova::Server
properties:
flavor: m1.small
networks:
- network: private
block_device_mapping:
- device_name: vda
volume_id: { get_resource: bootable_volume }
delete_on_termination: false
.. TODO
A few elements that probably belong here:
- OS::Swift::Container
- OS::Trove::Instance

163
doc/hot-guide/source/composition.rst
View File

@ -1,163 +0,0 @@
.. _composition:
====================
Template composition
====================
When writing complex templates you are encouraged to break up your
template into separate smaller templates. These can then be brought
together using template resources. This is a mechanism to define a resource
using a template, thus composing one logical stack with multiple templates.
Template resources provide a feature similar to the
:hotref:`AWS::CloudFormation::Stack` resource, but also provide a way to:
* Define new resource types and build your own resource library.
* Override the default behaviour of existing resource types.
To achieve this:
* The Orchestration client gets the associated template files and passes them
along in the ``files`` section of the ``POST stacks/`` API request.
* The environment in the Orchestration engine manages the mapping of resource
type to template creation.
* The Orchestration engine translates template parameters into resource
properties.
The following examples illustrate how you can use a custom template to define
new types of resources. These examples use a custom template stored in a
:file:`my_nova.yml` file:
.. code-block:: yaml
heat_template_version: 2014-10-16
parameters:
key_name:
type: string
description: Name of a KeyPair
resources:
server:
type: OS::Nova::Server
properties:
key_name: {get_param: key_name}
flavor: m1.small
image: ubuntu-trusty-x86_64
Use the template filename as type
=================================
The following template defines the :file:`my_nova.yaml` file as value for the
``type`` property of a resource:
.. code-block:: yaml
heat_template_version: 2014-10-16
resources:
my_server:
type: my_nova.yaml
properties:
key_name: my_key
The ``key_name`` argument of the ``my_nova.yaml`` template gets its value from
the ``key_name`` property of the new template.
.. note::
The above reference to ``my_nova.yaml`` assumes it is in the same directory.
You can use any of the following forms:
* Relative path (``my_nova.yaml``)
* Absolute path (``file:///home/user/templates/my_nova.yaml``)
* Http URL (``http://example.com/templates/my_nova.yaml``)
* Https URL (``https://example.com/templates/my_nova.yaml``)
To create the stack run:
.. code-block:: console
$ heat stack-create -f main.yaml stack1
Define a new resource type
==========================
You can associate a name to the ``my_nova.yaml`` template in an environment
file. If the name is already known by the Orchestration module then your new
resource will override the default one.
In the following example a new ``OS::Nova::Server`` resource overrides the
default resource of the same name.
An :file:`env.yaml` environment file holds the definition of the new resource:
.. code-block:: yaml
resource_registry:
"OS::Nova::Server": my_nova.yaml
.. note::
See :ref:`environments` for more detail about environment files.
You can now use the new ``OS::Nova::Server`` in your new template:
.. code-block:: yaml
heat_template_version: 2014-10-16
resources:
my_server:
type: OS::Nova::Server
properties:
key_name: my_key
To create the stack run:
.. code-block:: console
$ heat stack-create -f main.yaml -e env.yaml example-two
Get access to nested attributes
===============================
There are implicit attributes of a template resource. These are
accessible as follows:
.. code-block:: yaml
heat_template_version: 2014-10-16
resources:
my_server:
type: my_nova.yaml
outputs:
test_out:
value: {get_attr: my_server, resource.server, first_address}
Making your template resource more "transparent"
================================================
If you wish to be able to return the ID of one of the inner resources
instead of the nested stack's identifier, you can add the special reserved
output "OS::stack_id" to your template resource.
.. code-block:: yaml
heat_template_version: 2014-10-16
resources:
server:
type: OS::Nova::Server
outputs:
OS::stack_id:
value: {get_resource: server}
Now when you use "get_resource" from the outer template heat
will use the nova server id and not the template resource identifier.

272
doc/hot-guide/source/conf.py
View File

@ -1,272 +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.
# HOT Templates Guide documentation build configuration file, created by
# sphinx-quickstart on Fri Jul 18 15:27:11 2014.
#
# 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
# 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 = ['oslosphinx', 'os_doc_tools.sphinx.hotref']
# 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.
project = u'HOT guide'
copyright = u'2014, OpenStack Doc Team'
# 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 = '0.1'
# The full version, including alpha/beta/rc tags.
release = '0.1'
# 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 = []
# 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 = 'default'
# 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 = []
# 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 = ['_static']
# 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.
# html_last_updated_fmt = '%b %d, %Y'
# 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 = True
# 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 = True
# 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 = 'HOTguidedoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
}
# 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', 'HOTguide.tex', u'HOT guide',
u'OpenStack Doc Team', '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', 'hotguide', u'HOT Guide',
[u'OpenStack Doc Team'], 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', 'HOTguide', u'HOT guide',
u'OpenStack Doc Team', 'HOTguide', 'One line description of project.',
'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/']

127
doc/hot-guide/source/environment.rst
View File

@ -1,127 +0,0 @@
.. _environments:
============
Environments
============
The environment affects the runtime behaviour of a template. It provides a way
to override the resource implementations and a mechanism to place parameters
that the service needs.
To fully understand the runtime behavior you have to consider what plug-ins are
installed on the cloud you're using.
Environment file format
-----------------------
The environment is a yaml text file that contains two main sections:
``parameters``
A map of key/pair values.
``resource_registry``
Definition of custom resources.
Use the :option:`-e` option of the :command:`heat stack-create` command to
create a stack using with the environment defined in such a file.
You can also provide environment parameters as a list of key/value pairs using
the :option:`-P` option of the :command:`heat stack-create` command.
In the following example the environment is read from the :file:`my_env.yaml`
file and an extra parameter is provided using the :option:`-P` option:
.. code-block:: console
$ heat stack-create my_stack -e my_env.yaml -P "param1=val1;param2=val2" -f my_tmpl.yaml
Global and effective environments
---------------------------------
The environment used for a stack is the combination of the environment you
use with the template for the stack, and a global environment that is
determined by your cloud operator. An entry in the user environment takes
precedence over the global environment. OpenStack includes a default global
environment, but you cloud operator can add additional environment entries.
.. TODO:
move this to a heat section in the admin-guide-cloud
The cloud operator can add to the global environment
by putting environment files in a configurable directory wherever
the Orchestration engine runs. The configuration variable is named
"environment_dir" is found in the "[DEFAULT]" section
of "/etc/heat/heat.conf". The default for that directory is
"/etc/heat/environment.d". Its contents are combined in whatever
order the shell delivers them when the service starts up,
which is the time when these files are read.
If the "my_env.yaml" file from the example above had been put in the
"environment_dir" then the user's command line could be this:
::
heat stack-create my_stack -P "some_parm=bla" -f my_tmpl.yaml
Define values for a template arguments
--------------------------------------
You can define values for the template arguments in the ``parameters`` section
of an environment file:
.. code-block:: yaml
parameters:
KeyName: my_keypair
InstanceType: m1.tiny
ImageId: F18-x86_64-cfntools
Create and override resources
-----------------------------
You can create or override resources in the ``resource_registry`` section of an
environment file. The resource you provide in this manner must have an
identifier, and references either other resources IDs or the URL of an existing
template file.
The following example maps the new ``OS::Networking::FloatingIP``
resource to the existing :hotref:`OS::Nova::FloatingIP` resource:
.. code-block:: yaml
resource_registry:
"OS::Networking::FloatingIP": "OS::Nova::FloatingIP"
You can use wildcards to map multiple resources:
.. code-block:: yaml
resource_registry:
"OS::Network*": "OS::Neutron*"
To create or override a resource with a custom resource, create a template file
to define this resource, and provide the URL to the template file in the
environment file:
.. code-block:: yaml
resource_registry:
"AWS::EC2::Instance": file:///path/to/my_instance.yaml
The supported URL scheme are ``file``, ``http`` and ``https``.
.. note::
The template file extension must be ``.yaml`` or ``.template``, or it will
not be treated as a custom template resource.
You can limit the usage of a custom resource to a specific resource of the
template:
.. code-block:: yaml
resource_registry:
resources:
my_db_server:
"OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml

27
doc/hot-guide/source/existing_templates.rst
View File

@ -1,27 +0,0 @@
.. _existing_templates:
================================
Where to find existing templates
================================
There are several repositories where you can find existing HOT templates.
The `OpenStack Heat Templates repository`_ is a collection of example
templates which demonstrates core Heat functionality, related image-building
templates, template-related scripts and conversion tools.
.. _OpenStack Heat Templates Repository: http://git.openstack.org/cgit/openstack/heat-templates/tree/
The `OpenStack TripleO Heat Templates repository`_ contains a variety of
heat templates that are included in the tripleo-heat-templates codebase.
.. _OpenStack TripleO Heat Templates repository: http://git.openstack.org/cgit/openstack/tripleo-heat-templates/tree/
Rackspace has provided a set of Heat templates at the `RCB Ops repository`_
that can be used by cloud operators to launch applications, templates for
building a multi-node OpenStack cluster, as well as templates for CI
development. Heat templates for deployment of Magento, Hadoop, MongoDB,
ELK, Drupal and more can be found here.
.. _RCB Ops repository: http://github.com/rcbops/

35
doc/hot-guide/source/functions.rst
View File

@ -1,35 +0,0 @@
#############
HOT functions
#############
Link between resources
======================
* get_param
* get_resource
* Ref
* Fn::GetAtt / get_attr
String manipulations
====================
* get_file
* list_join
* str_replace
* Fn::Base64
* Fn::Join
* Fn::Split
* Fn::Replace
Lookup structured data
======================
* Fn::FindInMap
* Fn::MemberListToMap
* Fn::Select
Misc
====
* Fn::ResourceFacade / resource_facade
* Fn::GetAZs

234
doc/hot-guide/source/hello_world.rst
View File

@ -1,234 +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.
.. _hello_world:
==================================
Writing a hello world HOT template
==================================
HOT is a new template format meant to replace the CloudFormation-compatible
format (CFN) as the native format supported by the Orchestration module over
time.
This guide is targeted towards template authors and explains how to write
HOT templates based on examples. A detailed specification of HOT can be found
at :ref:`hot_spec`.
This section gives an introduction on how to write HOT templates, starting from
very basic steps and then going into more and more detail by means of examples.
A most basic template
---------------------
The most basic template you can think of contains only a single resource
definition using only predefined properties. For example, the template below
could be used to deploy a single compute instance:
.. code-block:: yaml
heat_template_version: 2013-05-23
description: Simple template to deploy a single compute instance
resources:
my_instance:
type: OS::Nova::Server
properties:
key_name: my_key
image: ubuntu-trusty-x86_64
flavor: m1.small
Each HOT template has to include the ``heat_template_version`` key with value
``2013-05-23``, the current HOT version. While the ``description`` key is
optional, it is good practice to include some useful text that describes what
users can do with the template. In case you want to provide a longer
description that does not fit on a single line, you can provide multi-line text
in YAML, for example:
.. code-block:: yaml
description: >
This is how you can provide a longer description
of your template that goes over several lines.
The ``resources`` section is required and must contain at least one resource
definition. In the above example, a compute instance is defined with fixed
values for the ``key_name``, ``image`` and ``flavor`` properties.
.. note::
All the defined elements (key pair, image, flavor) have to exist in the
OpenStack environment where the template is used.
Input parameters
----------------
Input parameters defined in the ``parameters`` section of a template
allow users to customize a template during deployment. For example, this allows
for providing custom key pair names or image IDs to be used for a deployment.
From a template author's perspective, this helps to make a template more easily
reusable by avoiding hardcoded assumptions.
The following example extends the previous template to provide parameters for
the key pair, image and flavor properties of the resource:
.. code-block:: yaml
heat_template_version: 2013-05-23
description: Simple template to deploy a single compute instance
parameters:
key_name:
type: string
label: Key Name
description: Name of key-pair to be used for compute instance
image_id:
type: string
label: Image ID
description: Image to be used for compute instance
flavor:
type: string
label: Instance Type
description: Type of instance (flavor) to be used
resources:
my_instance:
type: OS::Nova::Server
properties:
key_name: { get_param: key_name }
image: { get_param: image_id }
flavor: { get_param: flavor }
Values for the three parameters must be defined by the template user during the
deployment of a stack. The ``get_param`` intrinsic function retrieves a
user-specified value for a given parameter and uses this value for the
associated resource property.
For more information about intrinsic functions, see
:ref:`hot_spec_intrinsic_functions`.
Providing default values
~~~~~~~~~~~~~~~~~~~~~~~~
You can provide default values for parameters. If a user doesn't define a value
for a parameter, the default value is used during the stack deployment. The
following example defines a default value ``m1.small`` for the
``flavor`` property:
.. code-block:: yaml
parameters:
flavor:
type: string
label: Instance Type
description: Flavor to be used
default: m1.small
.. note::
If a template doesn't define a default value for a parameter, then the user
must define the value, otherwise the stack creation will fail.
Hiding parameters values
~~~~~~~~~~~~~~~~~~~~~~~~~
The values that a user provides when deploying a stack are available in the
stack details and can be accessed by any user in the same tenant. To hide the
value of a parameter, use the ``hidden`` boolean attribute of the parameter:
.. code-block:: yaml
parameters:
database_password:
type: string
label: Database Password
description: Password to be used for database
hidden: true
Restricting user input
~~~~~~~~~~~~~~~~~~~~~~
You can restrict the values of an input parameter to make sure that the user
defines valid data for this parameter. The ``constraints`` property of an input
parameter defines a list of constraints to apply for the parameter.
The following example restricts the ``flavor`` parameter to a list of three
possible values:
.. code-block:: yaml
parameters:
flavor:
type: string
label: Instance Type
description: Type of instance (flavor) to be used
constraints:
- allowed_values: [ m1.medium, m1.large, m1.xlarge ]
description: Value must be one of m1.medium, m1.large or m1.xlarge.
The following example defines multiple constraints for a password definition:
.. code-block:: yaml
parameters:
database_password:
type: string
label: Database Password
description: Password to be used for database
hidden: true
constraints:
- length: { min: 6, max: 8 }
description: Password length must be between 6 and 8 characters.
- allowed_pattern: "[a-zA-Z0-9]+"
description: Password must consist of characters and numbers only.
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
description: Password must start with an uppercase character.
The list of supported constraints is available in the
:ref:`hot_spec_parameters_constraints` section.
.. note::
You can define multiple constraints of the same type. Especially in the
case of allowed patterns this not only allows for keeping regular
expressions simple and maintainable, but also for keeping error messages to
be presented to users precise.
Template outputs
----------------
In addition to template customization through input parameters, you can
provide information about the resources created during the stack deployment to
the users in the ``outputs`` section of a template. In the following example
the output section provides the IP address of the ``my_instance`` resource:
.. code-block:: yaml
outputs:
instance_ip:
description: The IP address of the deployed instance
value: { get_attr: [my_instance, first_address] }
.. note::
Output values are typically resolved using intrinsic function such as
the ``get_attr``. See :ref:`hot_spec_intrinsic_functions` for more information
about intrinsic functions..
See :ref:`hot_spec_outputs` for more information about the ``outputs`` section.

896
doc/hot-guide/source/hot_spec.rst
View File

@ -1,896 +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.
.. _hot_spec:
===============================================
Heat Orchestration Template (HOT) specification
===============================================
------------------
Template structure
------------------
HOT templates are defined in YAML and use the following structure:
.. code-block:: yaml
heat_template_version: 2013-05-23
description:
# description of the template
parameter_groups:
# declaration of input parameter groups and order
parameters:
# declaration of input parameters
resources:
# declaration of template resources
outputs:
# declaration of output parameters
heat_template_version
This key with value ``2013-05-23`` (or a later date) indicates that the
YAML document is a HOT template of the specified version.
description
This optional key gives a description of the template, or
the workload that can be deployed using the template.
parameter_groups
This section specifies how the input parameters should be
grouped and the order to provide the parameters in.
This section is optional.
parameters
This section specifies input parameters that have to
be provided when instantiating the template.
This section is optional.
resources
This section contains the declaration of the resources of the template.
This section with at least one resource must be defined in any HOT
template, or the template would not really do anything when being
instantiated.
outputs
This section specifies output parameters available to users once the
template has been instantiated.
This section is optional.
.. _hot_spec_parameter_groups:
------------------------
Parameter groups section
------------------------
The ``parameter_groups`` section specifies how the input parameters should be
grouped and the order to provide the parameters in. These groups are typically
used to describe expected behavior for downstream user interfaces.
These groups are specified in a list with each group containing a list of
associated parameters. The lists are used to denote the expected order of the
parameters. A parameter can only be included in one group. Use the name of the
parameter to add it to a group. The parameters details are defined in
the ``parameters`` section.
.. code-block:: yaml
parameter_groups:
- label: <human-readable label of parameter group>
description: <description of the parameter group>
parameters:
- <param name>
- <param name>
label
A human-readable label that defines the associated group of parameters.
description
A human-readable description of the parameter group.
parameters
A list of parameters that belong with this parameter group.
param name
The name of a parameter defined in the ``parameters`` section.
.. _hot_spec_parameters:
------------------
Parameters section
------------------
The ``parameters`` section defines input parameters that have to be
provided when instantiating the template. Such parameters are typically used to
customize each deployment, or for binding to environment specifics like certain
images.
Each parameter is specified in a separated nested block with the name of the
parameter defined in the first line and additional attributes such as a type or
a default value defined as nested elements:
.. code-block:: yaml
parameters:
<param name>:
type: <string | number | json | comma_delimited_list | boolean>
label: <human-readable name of the parameter>
description: <description of the parameter>
default: <default value for parameter>
hidden: <true | false>
constraints:
<parameter constraints>
param name
The name of the parameter.
type
The type of the parameter. Supported types
are ``string``, ``number``, ``comma_delimited_list``, ``json`` and
``boolean``.
This attribute is required.
label
A human readable name for the parameter.
This attribute is optional.
description
A human readable description for the parameter.
This attribute is optional.
default
A default value for the parameter. This value is used if the user doesn't
specify his own value during deployment.
This attribute is optional.
hidden
Defines whether the parameters should be hidden when a user requests
information about a stack created from the template. This attribute can be
used to hide passwords specified as parameters.
This attribute is optional and defaults to ``false``.
constraints
A list of constraints to apply. The constraints are validated by the
Orchestration engine when a user deploys a stack. The stack creation fails
if the parameter value doesn't comply to the constraints.
This attribute is optional.
The following example shows a minimalistic definition of two parameters:
.. code-block:: yaml
parameters:
user_name:
type: string
label: User Name
description: User name to be configured for the application
port_number:
type: number
label: Port Number
description: Port number to be configured for the web server
.. note::
The description and the label are optional, but defining these attributes
is good practice to provide useful information about the role of the
parameter to the user.
.. _hot_spec_parameters_constraints:
Parameter constraints
---------------------
The ``constraints`` block of a parameter definition defines
additional validation constraints that apply to the value of the
parameter. The parameter values provided by a user are validated against the
constraints at instantiation time. The constraints are defined as a list with
the following syntax:
.. code-block:: yaml
constraints:
- <constraint type>: <constraint definition>
description: <constraint description>
constraint type
Type of constraint to apply. The set of currently supported constraints is
given below.
constraint definition
The actual constraint, depending on the constraint type. The
concrete syntax for each constraint type is given below.
description
A description of the constraint. The text
is presented to the user when the value he defines violates the constraint.
If omitted, a default validation message is presented to the user.
This attribute is optional.
The following example shows the definition of a string parameter with two
constraints. Note that while the descriptions for each constraint are optional,
it is good practice to provide concrete descriptions to present useful messages
to the user at deployment time.
.. code-block:: yaml
parameters:
user_name:
type: string
label: User Name
description: User name to be configured for the application
constraints:
- length: { min: 6, max: 8 }
description: User name must be between 6 and 8 characters
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
description: User name must start with an uppercase character
.. note::
While the descriptions for each constraint are optional, it is good practice
to provide concrete descriptions so useful messages can be presented to the
user at deployment time.
The following sections list the supported types of parameter constraints, along
with the syntax for each type.
length
~~~~~~
The ``length`` constraint applies to parameters of type ``string``. It defines
a lower and upper limit for the length of the string value.
The syntax of the ``length`` constraint is:
.. code-block:: yaml
length: { min: <lower limit>, max: <upper limit> }
It is possible to define a length constraint with only a lower limit or an
upper limit. However, at least one of ``min`` or ``max`` must be specified.
range
~~~~~
The ``range`` constraint applies to parameters of type ``number``. It defines a
lower and upper limit for the numeric value of the parameter.
The syntax of the ``range`` constraint is:
.. code-block:: yaml
range: { min: <lower limit>, max: <upper limit> }
It is possible to define a range constraint with only a lower limit or an
upper limit. However, at least one of ``min`` or ``max`` must be specified.
The minimum and maximum boundaries are included in the range. For example, the
following range constraint would allow for all numeric values between 0 and 10:
.. code-block:: yaml
range: { min: 0, max: 10 }
allowed_values
~~~~~~~~~~~~~~
The ``allowed_values`` constraint applies to parameters of type ``string`` or
``number``. It specifies a set of possible values for a parameter. At
deployment time, the user-provided value for the respective parameter must
match one of the elements of the list.
The syntax of the ``allowed_values`` constraint is:
.. code-block:: yaml
allowed_values: [ <value>, <value>, ... ]
Alternatively, the following YAML list notation can be used:
.. code-block:: yaml
allowed_values:
- <value>
- <value>
- ...
For example:
.. code-block:: yaml
parameters:
instance_type:
type: string
label: Instance Type
description: Instance type for compute instances
constraints:
- allowed_values:
- m1.small
- m1.medium
- m1.large
allowed_pattern
~~~~~~~~~~~~~~~
The ``allowed_pattern`` constraint applies to parameters of type ``string``.
It specifies a regular expression against which a user-provided parameter value
must evaluate at deployment.
The syntax of the ``allowed_pattern`` constraint is:
.. code-block:: yaml
allowed_pattern: <regular expression>
For example:
.. code-block:: yaml
parameters:
user_name:
type: string
label: User Name
description: User name to be configured for the application
constraints:
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
description: User name must start with an uppercase character
custom_constraint
~~~~~~~~~~~~~~~~~
The ``custom_constraint`` constraint adds an extra step of validation,
generally to check that the specified resource exists in the backend. Custom
constraints get implemented by plug-ins and can provide any kind of advanced
constraint validation logic.
The syntax of the ``custom_constraint`` constraint is:
.. code-block:: yaml
custom_constraint: <name>
The ``name`` attribute specifies the concrete type of custom constraint. It
corresponds to the name under which the respective validation plugin has been
registered in the Orchestration engine.
For example:
.. code-block:: yaml
parameters:
key_name
type: string
description: SSH key pair
constraints:
- custom_constraint: nova.keypair
.. _hot_spec_pseudo_parameters:
Pseudo Parameters
-----------------
In addition to parameters defined by a template author, the Orchestration
module also creates two parameters for every stack that allow referential
access to the stack's name and identifier. These parameters are named
``OS::stack_name`` for the stack name and ``OS::stack_id`` for the stack
identifier. These values are accessible via the ``get_param`` intrinsic
function, just like user-defined parameters.
.. _hot_spec_resources:
-----------------
Resources section
-----------------
The ``resources`` section defines actual resources that make up a stack
deployed from the HOT template (for instance compute instances, networks,
storage volumes).
Each resource is defined as a separate block in the ``resources`` section with
the following syntax:
.. code-block:: yaml
resources:
<resource ID>:
type: <resource type>
properties:
<property name>: <property value>
metadata:
<resource specific metadata>
depends_on: <resource ID or list of ID>
update_policy: <update policy>
deletion_policy: <deletion policy>
resource ID
A resource ID which must be unique within the ``resources`` section of the
template.
type
The resource type, such as ``OS::Nova::Server`` or ``OS::Neutron::Port``.
This attribute is required.
properties
A list of resource-specific properties. The property value can be provided
in place, or via a function (see :ref:`hot_spec_intrinsic_functions`).
This section is optional.
metadata
Resource-specific metadata.
This section is optional.
depends_on
Dependencies of the resource on one or more resources of the template.
See :ref:`hot_spec_resources_dependencies` for details.
This attribute is optional.
update_policy
Update policy for the resource, in the form of a nested dictionary. Whether
update policies are supported and what the exact semantics are depends on
the type of the current resource.
This attribute is optional.
deletion_policy
Deletion policy for the resource. Which type of deletion policy is
supported depends on the type of the current resource.
This attribute is optional.
Depending on the type of resource, the resource block might include more
resource specific data.
All resource types that can be used in CFN templates can also be used in HOT
templates, adapted to the YAML structure as outlined above.
The following example demonstrates the definition of a simple compute resource
with some fixed property values:
.. code-block:: yaml
resources:
my_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: F18-x86_64-cfntools
.. _hot_spec_resources_dependencies:
Resource dependencies
---------------------
The ``depends_on`` attribute of a resource defines a dependency between this
resource and one or more other resources.
If a resource depends on just one other resource, the ID of the other resource
is specified as string of the ``depends_on`` attribute, as shown in the
following example:
.. code-block:: yaml
resources:
server1:
type: OS::Nova::Server
depends_on: server2
server2:
type: OS::Nova::Server
If a resource depends on more than one other resources, the value of the
``depends_on`` attribute is specified as a list of resource IDs, as shown in
the following example:
.. code-block:: yaml
resources:
server1:
type: OS::Nova::Server
depends_on: [ server2, server3 ]
server2:
type: OS::Nova::Server
server3:
type: OS::Nova::Server
.. _hot_spec_outputs:
---------------
Outputs section
---------------
The ``outputs`` section defines output parameters that should be available to
the user once a stack has been created. This would be, for example, parameters
such as IP addresses of deployed instances, or URLs of web applications
deployed as part of a stack.
Each output parameter is defined as a separate block within the outputs section
according to the following syntax:
.. code-block:: yaml
outputs:
<parameter name>:
description: <description>
value: <parameter value>
parameter name
The output parameter name, which must be unique within the ``outputs``
section of a template.
description
A short description of the output parameter.
This attribute is optional.
parameter value
The value of the output parameter. This value is usually resolved by means
of a function. See :ref:`hot_spec_intrinsic_functions` for details about
the functions.
This attribute is required.
The example below shows how the IP address of a compute resource can
be defined as an output parameter:
.. code-block:: yaml
outputs:
instance_ip:
description: IP address of the deployed compute instance
value: { get_attr: [my_instance, first_address] }
.. _hot_spec_intrinsic_functions:
-------------------
Intrinsic functions
-------------------
HOT provides a set of intrinsic functions that can be used inside templates
to perform specific tasks, such as getting the value of a resource attribute at
runtime. The following section describes the role and syntax of the intrinsic
functions.
get_attr
--------
The ``get_attr`` function references an attribute of a
resource. The attribute value is resolved at runtime using the resource
instance created from the respective resource definition.
The syntax of the ``get_attr`` function is:
.. code-block:: yaml
get_attr:
- <resource ID>
- <attribute name>
- <key/index 1> (optional)
- <key/index 2> (optional)
- ...
resource ID
The resource ID for which the attribute needs to be resolved.
The resource ID must exist in the ``resources`` section of the template.
attribute name
The attribute name to be resolved. If the attribute returns a complex data
structure such as a list or a map, then subsequent keys or indexes can be
specified. These additional parameters are used to navigate the data
structure to return the desired value.
The following example demonstrates how to use the ``get_param`` function:
.. code-block:: yaml
resources:
my_instance:
type: OS::Nova::Server
# ...
outputs:
instance_ip:
description: IP address of the deployed compute instance
value: { get_attr: [my_instance, first_address] }
instance_private_ip:
description: Private IP address of the deployed compute instance
value: { get_attr: [my_instance, networks, private, 0] }
In this example, if the networks attribute contained the following data:
.. code-block:: yaml
{"public": ["2001:0db8:0000:0000:0000:ff00:0042:8329", "1.2.3.4"],
"private": ["10.0.0.1"]}
then the value of ``the get_attr`` function would resolve to ``10.0.0.1``
(first item of the ``private`` entry in the ``networks`` map).
get_file
--------
The ``get_file`` function returns the content of a file into the template.
It is generally used as a file inclusion mechanism for files
containing scripts or configuration files.
The syntax of ``the get_file`` function is:
.. code-block:: yaml
get_file: <content key>
The ``content key`` is used to look up the ``files`` dictionary that is
provided in the REST API call. The Orchestration client command
(:command:`heat`) is ``get_file`` aware and will populate the ``files``
dictionary with the actual content of fetched paths and URLs. The
Orchestration client command supports relative paths and will transform these
to the absolute URLs required by the Orchestration API.
.. note::
The ``get_file`` argument must be a static path or URL and not rely on
intrinsic functions like ``get_param``. the Orchestration client does not
process intrinsic functions (they are only processed by the Orchestration
engine).
The example below demonstrates the ``get_file`` function usage with both
relative and absolute URLs:
.. code-block:: yaml
resources:
my_instance:
type: OS::Nova::Server
properties:
# general properties ...
user_data:
get_file: my_instance_user_data.sh
my_other_instance:
type: OS::Nova::Server
properties:
# general properties ...
user_data:
get_file: http://example.com/my_other_instance_user_data.sh
The ``files`` dictionary generated by the Orchestration client during
instantiation of the stack would contain the following keys:
* ``file:///path/to/my_instance_user_data.sh``
* ``http://example.com/my_other_instance_user_data.sh*``
get_param
---------
The ``get_param`` function references an input parameter of a template. It
resolves to the value provided for this input parameter at runtime.
The syntax of the ``get_param`` function is:
.. code-block:: yaml
get_param:
- <parameter name>
- <key/index 1> (optional)
- <key/index 2> (optional)
- ...
parameter name
The parameter name to be resolved. If the parameters returns a complex data
structure such as a list or a map, then subsequent keys or indexes can be
specified. These additional parameters are used to navigate the data
structure to return the desired value.
The following example demonstrates the use of the ``get_param`` function:
.. code-block:: yaml
parameters:
instance_type:
type: string
label: Instance Type
description: Instance type to be used.
server_data:
type: json
resources:
my_instance:
type: OS::Nova::Server
properties:
flavor: { get_param: instance_type}
metadata: { get_param: [ server_data, metadata ] }
key_name: { get_param: [ server_data, keys, 0 ] }
In this example, if the ``instance_type`` and ``server_data`` parameters
contained the following data:
.. code-block:: yaml
{"instance_type": "m1.tiny",
{"server_data": {"metadata": {"foo": "bar"},
"keys": ["a_key","other_key"]}}}
then the value of the property ``flavor`` would resolve to ``m1.tiny``,
``metadata`` would resolve to ``{"foo": "bar"}`` and ``key_name`` would resolve
to ``a_key``.
get_resource
------------
The ``get_resource`` function references another resource within the
same template. At runtime, it is resolved to reference the ID of the referenced
resource, which is resource type specific. For example, a reference to a
floating IP resource returns the respective IP address at runtime. The syntax
of the ``get_resource`` function is:
.. code-block:: yaml
get_resource: <resource ID>
The resource ID of the referenced resource is given as single parameter to the
get_resource function.
For example:
.. code-block:: yaml
resources:
instance_port:
type: OS::Neutron::Port
properties: ...
instance:
type: OS::Nova::Server
properties:
...
networks:
port: { get_resource: instance_port }
list_join
---------
The ``list_join`` function joins a list of strings with the given delimiter.
The syntax of the ``list_join`` function is:
.. code-block:: yaml
list_join:
- <delimiter>
- <list to join>
For example:
.. code-block:: yaml
list_join: [', ', ['one', 'two', 'and three']]
This resolve to the string ``one, two, and three``.
resource_facade
---------------
The ``resource_facade`` function retrieves data in a parent provider template.
A provider template provides a custom definition of a resource, called its
facade. For more information about custom templates, see :ref:`composition`.
The syntax of the ``resource_facade`` function is:
.. code-block:: yaml
resource_facade: <data type>
``data type`` can be one of ``metadata``, ``deletion_policy`` or
``update_policy``.
str_replace
-----------
The ``str_replace`` function dynamically constructs strings by
providing a template string with placeholders and a list of mappings to assign
values to those placeholders at runtime. The placeholders are replaced with
mapping values wherever a mapping key exactly matches a placeholder.
The syntax of the ``str_replace`` function is:
.. code-block:: yaml
str_replace:
template: <template string>
params: <parameter mappings>
template
Defines the template string that contains placeholders which will be
substituted at runtime.
params
Provides parameter mappings in the form of dictionary. Each key refers to a
placeholder used in the ``template`` attribute.
The following example shows a simple use of the ``str_replace`` function in the
outputs section of a template to build a URL for logging into a deployed
application:
.. code-block:: yaml
resources:
my_instance:
type: OS::Nova::Server
# general metadata and properties ...
outputs:
Login_URL:
description: The URL to log into the deployed application
value:
str_replace:
template: http://host/MyApplication
params:
host: { get_attr: [ my_instance, first_address ] }
The following examples show the use of the ``str_replace`` function to build an
instance initialization script:
.. code-block:: yaml
parameters:
DBRootPassword:
type: string
label: Database Password
description: Root password for MySQL
hidden: true
resources:
my_instance:
type: OS::Nova::Server
properties:
# general properties ...
user_data:
str_replace:
template: |
#!/bin/bash
echo "Hello world"
echo "Setting MySQL root password"
mysqladmin -u root password $db_rootpassword
# do more things ...
params:
$db_rootpassword: { get_param: DBRootPassword }

15
doc/hot-guide/source/index.rst
View File

@ -1,15 +0,0 @@
HOT guide
=========
.. toctree::
:maxdepth: 2
hello_world
hot_spec
basic_resources
software_deployment
environment
composition
existing_templates
#advanced_topics
#functions

815
doc/hot-guide/source/software_deployment.rst
View File

@ -1,815 +0,0 @@
.. _hot_software_deployment:
Software configuration
######################
There are a variety of options to configure the software which runs on the
servers in your stack. These can be broadly divided into the following:
* Custom image building
* User-data boot scripts and cloud-init
* Software deployment resources
This section will describe each of these options and provide examples for
using them together in your stacks.
Image building
**************
The first opportunity to influence what software is configured on your servers
is by booting them with a custom-built image. There are a number of reasons
you might want to do this, including:
* **Boot speed** - since the required software is already on the image there
is no need to download and install anything at boot time.
* **Boot reliability** - software downloads can fail for a number of reasons
including transient network failures and inconsistent software repositories.
* **Test verification** - custom built images can be verified in test
environments before being promoted to production.
* **Configuration dependencies** - post-boot configuration may depend on
agents already being installed and enabled
A number of tools are available for building custom images, including:
* diskimage-builder_ image building tools for OpenStack
* imagefactory_ builds images for a variety of operating system/cloud
combinations
Examples in this guide which require custom images will use diskimage-builder_.
User-data boot scripts and cloud-init
*************************************
When booting a server it is possible to specify the contents of the user-data
to be passed to that server. This user-data is made available either from
configured config-drive or from the `Metadata service`_.
How this user-data is consumed depends on the image being booted, but the most
commonly used tool for default cloud images is Cloud-init_.
Whether the image is using Cloud-init_ or not, it should be possible to
specify a shell script in the user_data property and have it be executed by
the server during boot:
.. code-block:: yaml
resources:
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data: |
#!/bin/bash
echo "Running boot script"
# ...
..
**Tip**: debugging these scripts it is often useful to view the boot
log using ``nova console-log <server-id>`` to view the progress of boot
script execution.
Often there is a need to set variable values based on parameters or resources
in the stack. This can be done with the ``str_replace`` intrinsic function:
.. code-block:: yaml
parameters:
foo:
default: bar
resources:
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data:
str_replace:
template: |
#!/bin/bash
echo "Running boot script with $FOO"
# ...
params:
$FOO: {get_param: foo}
..
**Warning**: If a stack-update is performed and there are any changes
at all to the content of user_data then the server will be replaced
(deleted and recreated) so that the modified boot configuration can be
run on a new server.
When these scripts grow it can become difficult to maintain them inside the
template, so the ``get_file`` intrinsic function can be used to maintain the
script in a separate file:
.. code-block:: yaml
parameters:
foo:
default: bar
resources:
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data:
str_replace:
template: {get_file: the_server_boot.sh}
params:
$FOO: {get_param: foo}
..
**Tip**: ``str_replace`` can replace any strings, not just strings
starting with ``$``. However doing this for the above example is useful
because the script file can be executed for testing by passing in
environment variables.
Choosing the user_data_format
=============================
The :hotref:`OS::Nova::Server` user_data_format property determines how the
user_data should be formatted for the server. For the default value
``HEAT_CFNTOOLS``, the user_data is bundled as part of the heat-cfntools
cloud-init boot configuration data. While ``HEAT_CFNTOOLS`` is the default
for ``user_data_format``, it is considered legacy and ``RAW`` or
``SOFTWARE_CONFIG`` will generally be more appropriate.
For ``RAW`` the user_data is passed to Nova unmodified. For a Cloud-init_
enabled image, the following are both valid ``RAW`` user-data:
.. code-block:: yaml
resources:
server_with_boot_script:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: |
#!/bin/bash
echo "Running boot script"
# ...
server_with_cloud_config:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: |
#cloud-config
final_message: "The system is finally up, after $UPTIME seconds"
For ``SOFTWARE_CONFIG`` user_data is bundled as part of the software config
data, and metadata is derived from any associated
`Software deployment resources`_.
Signals and wait conditions
===========================
Often it is necessary to pause further creation of stack resources until the
boot configuration script has notified that it has reached a certain state.
This is usually either to notify that a service is now active, or to pass out
some generated data which is needed by another resource. The resources
:hotref:`OS::Heat::WaitCondition` and :hotref:`OS::Heat::SwiftSignal` both perform
this function using different techniques and tradeoffs.
:hotref:`OS::Heat::WaitCondition` is implemented as a call to the
`Orchestration API`_ resource signal. The token is created using credentials
for a user account which is scoped only to the wait condition handle
resource. This user is created when the handle is created, and is associated
to a project which belongs to the stack, in an identity domain which is
dedicated to the orchestration service.
Sending the signal is a simple HTTP request, as with this example using curl_:
.. code-block:: sh
curl -i -X POST -H 'X-Auth-Token: <token>' \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
'<wait condition URL>' --data-binary '<json containing signal data>'
The JSON containing the signal data is expected to be of the following format:
.. code-block:: json
{
"status": "SUCCESS",
"reason": "The reason which will appear in the 'heat event-list' output",
"data": "Data to be used elsewhere in the template via get_attr",
"id": "Optional unique ID of signal"
}
All of these values are optional, and if not specified will be set to the
following defaults:
.. code-block:: json
{
"status": "SUCCESS",
"reason": "Signal <id> received",
"data": null,
"id": "<sequential number starting from 1 for each signal received>"
}
If ``status`` is set to ``FAILURE`` then the resource (and the stack) will go
into a ``FAILED`` state using the ``reason`` as failure reason.
The following template example uses the convenience attribute ``curl_cli``
which builds a curl command with a valid token:
.. code-block:: yaml
resources:
wait_condition:
type: OS::Heat::WaitCondition
properties:
handle: {get_resource: wait_handle}
# Note, count of 5 vs 6 is due to duplicate signal ID 5 sent below
count: 5
timeout: 300
wait_handle:
type: OS::Heat::WaitConditionHandle
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data:
str_replace:
template: |
#!/bin/sh
# Below are some examples of the various ways signals
# can be sent to the Handle resource
# Simple success signal
wc_notify --data-binary '{"status": "SUCCESS"}'
# Or you optionally can specify any of the additional fields
wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal2"}'
wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal3", "data": "data3"}'
wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal4", "data": "data4"}'
# If you require control of the ID, you can pass it.
# The ID should be unique, unless you intend for duplicate
# signals to overwrite each other. The following two calls
# do the exact same thing, and will be treated as one signal
# (You can prove this by changing count above to 7)
wc_notify --data-binary '{"status": "SUCCESS", "id": "5"}'
wc_notify --data-binary '{"status": "SUCCESS", "id": "5"}'
# Example of sending a failure signal, optionally
# reason, id, and data can be specified as above
# wc_notify --data-binary '{"status": "FAILURE"}'
params:
wc_notify: { get_attr: [wait_handle, curl_cli] }
outputs:
wc_data:
value: { get_attr: [wait_condition, data] }
# this would return the following json
# {"1": null, "2": null, "3": "data3", "4": "data4", "5": null}
wc_data_4:
value: { get_attr: [wait_condition, data, '4'] }
# this would return "data4"
..
:hotref:`OS::Heat::SwiftSignal` is implemented by creating an Object Storage
API temporary URL which is populated with signal data with an HTTP PUT. The
orchestration service will poll this object until the signal data is available.
Object versioning is used to store multiple signals.
Sending the signal is a simple HTTP request, as with this example using curl_:
.. code-block:: sh
curl -i -X PUT '<object URL>' --data-binary '<json containing signal data>'
The above template example only needs to have the ``type`` changed to the
swift signal resources:
.. code-block:: yaml
resources:
signal:
type: OS::Heat::SwiftSignal
properties:
handle: {get_resource: wait_handle}
timeout: 300
signal_handle:
type: OS::Heat::SwiftSignalHandle
# ...
The decision to use :hotref:`OS::Heat::WaitCondition` or
:hotref:`OS::Heat::SwiftSignal` will depend on a few factors:
* :hotref:`OS::Heat::SwiftSignal` depends on the availability of an Object
Storage API
* :hotref:`OS::Heat::WaitCondition` depends on whether the orchestration
service has been configured with a dedicated stack domain (which may depend
on the availability of an Identity V3 API).
* The preference to protect signal URLs with token authentication or a
secret webhook URL.
Software config resources
=========================
Boot configuration scripts can also be managed as their own resources. This
allows configuration to be defined once and run on multiple server resources.
These software-config resources are stored and retrieved via dedicated calls
to the `Orchestration API`_. It is not possible to modify the contents of an
existing software-config resource, so a stack-update which changes any
existing software-config resource will result in API calls to create a new
config and delete the old one.
The resource :hotref:`OS::Heat::SoftwareConfig` is used for storing configs
represented by text scripts, for example:
.. code-block:: yaml
resources:
boot_script:
type: OS::Heat::SoftwareConfig
properties:
group: ungrouped
config: |
#!/bin/bash
echo "Running boot script"
# ...
server_with_boot_script:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: {get_resource: boot_script}
The resource :hotref:`OS::Heat::CloudConfig` allows Cloud-init_ cloud-config to
be represented as template YAML rather than a block string. This allows
intrinsic functions to be included when building the cloud-config. This also
ensures that the cloud-config is valid YAML, although no further checks for
valid cloud-config are done.
.. code-block:: yaml
parameters:
file_content:
type: string
description: The contents of the file /tmp/file
resources:
boot_config:
type: OS::Heat::CloudConfig
properties:
cloud_config:
write_files:
- path: /tmp/file
content: {get_param: file_content}
server_with_cloud_config:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: {get_resource: boot_config}
..
The resource :hotref:`OS::Heat::MultipartMime` allows multiple
:hotref:`OS::Heat::SoftwareConfig` and :hotref:`OS::Heat::CloudConfig`
resources to be combined into a single Cloud-init_ multi-part message:
.. code-block:: yaml
parameters:
file_content:
type: string
description: The contents of the file /tmp/file
other_config:
type: string
description: The ID of a software-config resource created elsewhere
resources:
boot_config:
type: OS::Heat::CloudConfig
properties:
cloud_config:
write_files:
- path: /tmp/file
content: {get_param: file_content}
boot_script:
type: OS::Heat::SoftwareConfig
properties:
group: ungrouped
config: |
#!/bin/bash
echo "Running boot script"
# ...
server_init:
type: OS::Heat::MultipartMime
properties:
parts:
- config: {get_resource: boot_config}
- config: {get_resource: boot_script}
- config: {get_resource: other_config}
server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: {get_resource: server_init}
..
Software deployment resources
*****************************
There are many situations where it is not desirable to replace the server
whenever there is a configuration change. The
:hotref:`OS::Heat::SoftwareDeployment` resource allows any number of software
configurations to be added or removed from a server throughout its life-cycle.
Building custom image for software deployments
==============================================
:hotref:`OS::Heat::SoftwareConfig` resources are used to store software
configuration, and a :hotref:`OS::Heat::SoftwareDeployment` resource is used
to associate a config resource with one server. The ``group`` attribute on
:hotref:`OS::Heat::SoftwareConfig` specifies what tool will consume the
config content.
:hotref:`OS::Heat::SoftwareConfig` has the ability to define a schema of
``inputs`` and which the configuration script supports. Inputs are mapped to
whatever concept the configuration tool has for assigning
variables/parameters.
Likewise, ``outputs`` are mapped to the tool's capability to export structured
data after configuration execution. For tools which do not support this,
outputs can always be written to a known file path for the hook to read.
The :hotref:`OS::Heat::SoftwareDeployment` resource allows values to be
assigned to the config inputs, and the resource remains in an ``IN_PROGRESS``
state until the server signals to heat what (if any) output values were
generated by the config script.
Custom image script
===================
Each of the following examples requires that the servers be booted with a
custom image. The following script uses diskimage-builder to create an image
required in later examples:
.. code-block:: sh
# Clone the required repositories. Some of these are also available
# via pypi or as distro packages.
git clone https://git.openstack.org/openstack/diskimage-builder.git
git clone https://git.openstack.org/openstack/tripleo-image-elements.git
git clone https://git.openstack.org/openstack/heat-templates.git
# Required by diskimage-builder to discover element collections
export ELEMENTS_PATH=tripleo-image-elements/elements:heat-templates/hot/software-config/elements
# The base operating system element(s) provided by the diskimage-builder
# elements collection. Other values which may work include:
# centos7, debian, opensuse, rhel, rhel7, or ubuntu
export BASE_ELEMENTS="fedora selinux-permissive"
# Install and configure the os-collect-config agent to poll the heat service
# for configuration changes to execute
export AGENT_ELEMENTS="os-collect-config os-refresh-config os-apply-config"
# heat-config installs an os-refresh-config script which will invoke the
# appropriate hook to perform configuration. The element heat-config-script
# installs a hook to perform configuration with shell scripts
export DEPLOYMENT_BASE_ELEMENTS="heat-config heat-config-script"
# Install a hook for any other chosen configuration tool(s).
# Elements which install hooks include:
# heat-config-cfn-init, heat-config-puppet, or heat-config-salt
export DEPLOYMENT_TOOL=""
# The name of the qcow2 image to create, and the name of the image
# uploaded to the OpenStack image registry.
export IMAGE_NAME=fedora-software-config
# Create the image
diskimage-builder/bin/disk-image-create vm $BASE_ELEMENTS $AGENT_ELEMENTS \
$DEPLOYMENT_BASE_ELEMENTS $DEPLOYMENT_TOOL -o $IMAGE_NAME.qcow2
# Upload the image, assuming valid credentials are already sourced
glance image-create --disk-format qcow2 --container-format bare \
--name $IMAGE_NAME < $IMAGE_NAME.qcow2
..
Configuring with scripts
========================
The `Custom image script`_ already includes the ``heat-config-script`` element
so the built image will already have the ability to configure using shell
scripts.
Config inputs are mapped to shell environment variables. The script can
communicate outputs to heat by writing to the file
``$heat_outputs_path.<output name>``. See the following example for a script
which expects inputs ``foo``, ``bar`` and generates an output ``result``.
.. code-block:: yaml
resources:
config:
type: OS::Heat::SoftwareConfig
properties:
group: script
inputs:
- name: foo
- name: bar
outputs:
- name: result
config: |
#!/bin/sh -x
echo "Writing to /tmp/$bar"
echo $foo > /tmp/$bar
echo -n "The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action" > $heat_outputs_path.result
echo "Written to /tmp/$bar"
echo "Output to stderr" 1>&2
deployment:
type: OS::Heat::SoftwareDeployment
properties:
config:
get_resource: config
server:
get_resource: server
input_values:
foo: fooooo
bar: baaaaa
server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: SOFTWARE_CONFIG
outputs:
result:
value:
get_attr: [deployment, result]
stdout:
value:
get_attr: [deployment, deploy_stdout]
stderr:
value:
get_attr: [deployment, deploy_stderr]
status_code:
value:
get_attr: [deployment, deploy_status_code]
..
**Tip**: A config resource can be associated with multiple deployment
resources, and each deployment can specify the same or different values
for the ``server`` and ``input_values`` properties.
As can be seen in the ``outputs`` section of the above template, the
``result`` config output value is available as an attribute on the
``deployment`` resource. Likewise the captured stdout, stderr and status_code
are also available as attributes.
Configuring with os-apply-config
================================
The agent toolchain of ``os-collect-config``, ``os-refresh-config`` and
``os-apply-config`` can actually be used on their own to inject heat stack
configuration data into a server running a custom image.
The custom image needs to have the following to use this approach:
* All software dependencies installed
* os-refresh-config_ scripts to be executed on configuration changes
* os-apply-config_ templates to transform the heat-provided config data into
service configuration files
The projects tripleo-image-elements_ and tripleo-heat-templates_ demonstrate
this approach.
Configuring with cfn-init
=========================
Likely the only reason to use the ``cfn-init`` hook is to migrate templates
which contain `AWS::CloudFormation::Init`_ metadata without needing a
complete rewrite of the config metadata. It is included here as it introduces
a number of new concepts.
To use the ``cfn-init`` tool the ``heat-config-cfn-init`` element is required
to be on the built image, so `Custom image script`_ needs to be modified with
the following:
.. code-block:: sh
export DEPLOYMENT_TOOL="heat-config-cfn-init"
..
Configuration data which used to be included in the
``AWS::CloudFormation::Init`` section of resource metadata is instead moved
to the ``config`` property of the config resource, as in the following
example:
.. code-block:: yaml
resources:
config:
type: OS::Heat::StructuredConfig
properties:
group: cfn-init
inputs:
- name: bar
config:
config:
files:
/tmp/foo:
content:
get_input: bar
mode: '000644'
deployment:
type: OS::Heat::StructuredDeployment
properties:
name: 10_deployment
signal_transport: NO_SIGNAL
config:
get_resource: config
server:
get_resource: server
input_values:
bar: baaaaa
other_deployment:
type: OS::Heat::StructuredDeployment
properties:
name: 20_other_deployment
signal_transport: NO_SIGNAL
config:
get_resource: config
server:
get_resource: server
input_values:
bar: barmy
server:
type: OS::Nova::Server
properties:
image: {get_param: image}
flavor: {get_param: flavor}
key_name: {get_param: key_name}
user_data_format: SOFTWARE_CONFIG
..
There are a number of things to note about this template example:
* :hotref:`OS::Heat::StructuredConfig` is like
:hotref:`OS::Heat::SoftwareConfig` except that the ``config`` property
contains structured YAML instead of text script. This is useful for a
number of other configuration tools including ansible, salt and
os-apply-config.
* ``cfn-init`` has no concept of inputs, so ``{get_input: bar}`` acts as a
placeholder which gets replaced with the
:hotref:`OS::Heat::StructuredDeployment` ``input_values`` value when the
deployment resource is created.
* ``cfn-init`` has no concept of outputs, so specifying
``signal_transport: NO_SIGNAL`` will mean that the deployment resource will
immediately go into the ``CREATED`` state instead of waiting for a
completed signal from the server.
* The template has 2 deployment resources deploying the same config with
different ``input_values``. The order these are deployed in on the server
is determined by sorting the values of the ``name`` property for each
resource (10_deployment, 20_other_deployment)
Configuring with puppet
=======================
The puppet_ hook makes it possible to write configuration as puppet manifests
which are deployed and run in a masterless environment.
To specify configuration as puppet manifests the ``heat-config-puppet``
element is required to be on the built image, so `Custom image script`_ needs
to be modified with the following:
.. code-block:: sh
export DEPLOYMENT_TOOL="heat-config-puppet"
..
.. code-block:: yaml
resources:
config:
type: OS::Heat::SoftwareConfig
properties:
group: puppet
inputs:
- name: foo
- name: bar
outputs:
- name: result
config:
get_file: example-puppet-manifest.pp
deployment:
type: OS::Heat::SoftwareDeployment
properties:
config:
get_resource: config
server:
get_resource: server
input_values:
foo: fooooo
bar: baaaaa
server:
type: OS::Nova::Server
properties:
image: {get_param: image}
flavor: {get_param: flavor}
key_name: {get_param: key_name}
user_data_format: SOFTWARE_CONFIG
outputs:
result:
value:
get_attr: [deployment, result]
stdout:
value:
get_attr: [deployment, deploy_stdout]
..
This demonstrates the use of the ``get_file`` function, which will attach the
contents of the file ``example-puppet-manifest.pp``, containing:
.. code-block:: puppet
file { 'barfile':
ensure => file,
mode => '0644',
path => '/tmp/$::bar',
content => '$::foo',
}
file { 'output_result':
ensure => file,
path => '$::heat_outputs_path.result',
mode => '0644',
content => 'The file /tmp/$::bar contains $::foo',
}
..
.. _`AWS::CloudFormation::Init`: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html
.. _diskimage-builder: https://github.com/openstack/diskimage-builder
.. _imagefactory: http://imgfac.org/
.. _`Metadata service`: http://docs.openstack.org/admin-guide-cloud/content/section_metadata-service.html
.. _Cloud-init: http://cloudinit.readthedocs.org/en/latest/
.. _curl: http://curl.haxx.se/
.. _`Orchestration API`: http://developer.openstack.org/api-ref-orchestration-v1.html
.. _os-refresh-config: https://github.com/openstack/os-refresh-config
.. _os-apply-config: https://github.com/openstack/os-apply-config
.. _tripleo-heat-templates: https://github.com/openstack/tripleo-heat-templates
.. _tripleo-image-elements: https://github.com/openstack/tripleo-image-elements
.. _puppet: http://puppetlabs.com/

10
doc/local-files.html
View File

@ -110,16 +110,6 @@
Use the OpenStack dashboard and command-line clients
</h4>
<dl>
<dd>
<a href="user-guide/target/docbkx/webhelp/user-guide/content/index.html">
End User Guide
</a>
</dd>
<dd>
<a href="user-guide-admin/target/docbkx/webhelp/user-guide-admin/content/index.html">
Admin User Guide
</a>
</dd>
<dd>
<a href="cli-reference/target/docbkx/webhelp/cli-reference/content/index.html">
Command-Line Interface Reference

2
doc/pom.xml
View File

@ -18,8 +18,6 @@
<module>hot-reference</module>
<module>image-guide</module>
<module>install-guide</module>
<module>user-guide</module>
<module>user-guide-admin</module>
</modules>
<profiles>
<profile>

112
doc/user-guide-admin/bk-admin-user-guide.xml
View File

@ -1,112 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
]>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="os-admin-user-guide">
<title>OpenStack Admin User Guide</title>
<titleabbrev>Admin User Guide</titleabbrev>
<info>
<author>
<personname>
<firstname/>
<surname/>
</personname>
<affiliation>
<orgname>OpenStack Foundation</orgname>
</affiliation>
</author>
<copyright>
<year>2014</year>
<year>2015</year>
<holder>OpenStack Foundation</holder>
</copyright>
<releaseinfo>current</releaseinfo>
<productname>OpenStack</productname>
<pubdate/>
<legalnotice role="cc-by">
<annotation>
<remark>Copyright details are filled in by the
template.</remark>
</annotation>
</legalnotice>
<abstract>
<para>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 admin users how to create and manage resources in an
OpenStack cloud with the OpenStack dashboard or OpenStack client
commands.</para>
<para>This guide documents OpenStack Juno, OpenStack
Icehouse, and OpenStack Havana releases.</para>
</abstract>
<revhistory>
<revision>
<date>2014-10-15</date>
<revdescription>
<itemizedlist>
<listitem>
<para>For the Juno release, this guide has
been edited for clarity.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2014-04-17</date>
<revdescription>
<itemizedlist>
<listitem>
<para>For the Icehouse release, this guide
has been updated with changes to the
dashboard plus the moving of the
command reference appendix as
indicated below.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2014-01-31</date>
<revdescription>
<itemizedlist>
<listitem>
<para>Remove the command reference appendix. This
information is now in <link
xlink:href="http://docs.openstack.org/cli-reference/content/"
><citetitle>OpenStack Command Line
Interface Reference</citetitle></link>.
</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2013-10-17</date>
<revdescription>
<itemizedlist>
<listitem>
<para>Havana release.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2013-08-31</date>
<revdescription>
<itemizedlist>
<listitem>
<para>First edition of this document.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
</info>
<xi:include href="../common/ch_using_openstack_overview.xml"/>
<xi:include href="ch_dashboard.xml"/>
<xi:include href="ch_cli.xml"/>
<xi:include href="../common/app_support.xml"/>
</book>

39
doc/user-guide-admin/ch_cli.xml
View File

@ -1,39 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="admin_ch_cli">
<info>
<title>OpenStack command-line clients</title>
</info>
<xi:include
href="../common/section_cli_overview.xml"/>
<?hard-pagebreak?>
<xi:include
href="../common/section_cli_version.xml"/>
<?hard-pagebreak?>
<xi:include
href="../common/section_cli_help.xml"/>
<?hard-pagebreak?>
<xi:include
href="section_cli_keystone_manage_projects_users_roles.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_nova_manage_projects_security.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_manage_services.xml"/>
<?hard-pagebreak?>
<xi:include href="../common/section_cli_glance_manage_images.xml"/>
<?hard-pagebreak?>
<xi:include href="../common/section_cli_cinder_manage_volumes.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_nova_manage_flavors.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_admin_manage_environment.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_keystone_set_quotas.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_swift_analyze_log_files.xml"/>
</chapter>

41
doc/user-guide-admin/ch_dashboard.xml
View File

@ -1,41 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="ch_dashboard">
<info>
<title>Dashboard</title>
</info>
<para>As a cloud administrative user, the OpenStack dashboard lets
you create and manage projects, users, images, and flavors.
You can also set quotas and create and manage services. For
information about using the dashboard to perform end user
tasks, see the
<link xlink:href="http://docs.openstack.org/user-guide/content/"
><citetitle>OpenStack End User
Guide</citetitle></link>.</para>
<xi:include href="../common/section_dashboard_access.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_admin_manage_projects_users.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_admin_manage_roles.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_admin_manage_instances.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_admin_manage_volumes.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_admin_manage_images.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_admin_manage_flavors.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_admin_set_quotas.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_admin_manage_resources.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_admin_manage_host_aggregates.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_admin_manage_stacks.xml"/>
</chapter>

BIN
doc/user-guide-admin/figures/cloud_dash_users_list.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 24 KiB

3549
doc/user-guide-admin/locale/ja.po
View File

File diff suppressed because it is too large Load Diff

2628
doc/user-guide-admin/locale/user-guide-admin.pot
View File

File diff suppressed because it is too large Load Diff

84
doc/user-guide-admin/pom.xml
View File

@ -1,84 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>
<groupId>org.openstack.docs</groupId>
<artifactId>parent-pom</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>openstack-user-guide-admin</artifactId>
<packaging>jar</packaging>
<name>OpenStack Admin User Guide</name>
<properties>
<!-- This is set by Jenkins according to the branch. -->
<release.path.name>local</release.path.name>
<comments.enabled>1</comments.enabled>
</properties>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
<build>
<plugins>
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<!-- version is set in ../pom.xml file -->
<executions>
<!-- Configuration for OpenStack End User Guide -->
<execution>
<id>generate-webhelp</id>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<profileAudience>adminuser</profileAudience>
<includes> bk-admin-user-guide.xml</includes>
<generateToc>
appendix toc,title
article/appendix nop
article toc,title
book toc,title,figure,table,example,equation
chapter toc,title
section toc
part toc,title
qandadiv toc
qandaset toc
reference toc,title
set toc,title
</generateToc>
<webhelpDirname>user-guide-admin</webhelpDirname>
<pdfFilenameBase>user-guide-admin</pdfFilenameBase>
</configuration>
</execution>
</executions>
<configuration>
<profileAudience>adminuser</profileAudience>
<chapterAutolabel>1</chapterAutolabel>
<sectionAutolabel>0</sectionAutolabel>
<tocSectionDepth>1</tocSectionDepth>
<formalProcedures>0</formalProcedures>
<highlightSource>false</highlightSource>
<xincludeSupported>true</xincludeSupported>
<showXslMessages>true</showXslMessages>
<sourceDirectory>.</sourceDirectory>
<feedbackEmail>diane.fleming@rackspace.com</feedbackEmail>
<branding>openstack</branding>
<enableDisqus>${comments.enabled}</enableDisqus>
<disqusShortname>os-user-admin-guide</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
<suppressFooterNavigation>0</suppressFooterNavigation>
<formalProcedures>0</formalProcedures>
<sectionAutolabel>0</sectionAutolabel>
<tocSectionDepth>1</tocSectionDepth>
<canonicalUrlBase>http://docs.openstack.org/user-guide-admin/content</canonicalUrlBase>
<glossaryCollection>${basedir}/../glossary/glossary-terms.xml</glossaryCollection>
</configuration>
</plugin>
</plugins>
</build>
</project>

29
doc/user-guide-admin/roadmap.rst
View File

@ -1,29 +0,0 @@
Roadmap for Admin User Guide
----------------------------
This file is stored with the source to offer ideas for what to work on.
Put your name next to a task if you want to work on it and put a WIP
review up on review.openstack.org.
May 20, 2014
To do tasks:
- Add a chapter describing Telemetry tasks (ceilometer); how to monitor usage
Ongoing tasks:
- Ensure it meets conventions and standards
- Continually update with latest OpenStack dashboard (horizon)
information including great descriptions of fields and why you set a
setting
Wishlist tasks:
- Get examples of common tasks from real admins and add to this guide
as how-to: migration of VM from one host to another, quota
management, targeting launch on a particular compute node
- Create flavor example - also refer to from Ops Guide (Anne Gentle todo)
- Migrations examples (Anne Gentle todo)
- Create tenant example with CLI
- Replace all individual client commands (like keystone, nova) with
openstack client commands

17
doc/user-guide-admin/section_cli_admin_manage_environment.xml
View File

@ -1,17 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="section_cli_admin_manage_environment">
<title>Manage the OpenStack environment</title>
<para>This section includes tasks specific to the OpenStack environment.</para>
<xi:include href="section_cli_nova_specify_host.xml"/>
<?hard-pagebreak?>
<xi:include href="../common/section_cli_nova_evacuate.xml"/>
<xi:include href="section_cli_nova_migrate.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_nova_floating_ips.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_admin_manage_stacks.xml"/>
</section>

37
doc/user-guide-admin/section_cli_admin_manage_stacks.xml
View File

@ -1,37 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="section_cli_admin_manage_stacks">
<title>Launch and manage stacks</title>
<para>The Orchestration service provides a template-based orchestration engine
for the OpenStack cloud, which can be used to create and manage cloud
infrastructure resources such as storage, networking, instances, and
applications as a repeatable running environment.
</para>
<para>Templates are used to create stacks, which are collections of resources. For example,
a stack might include instances, floating IPs, volumes, security groups, or users.
The Orchestration service offers access to all OpenStack core services via a single modular template,
with additional orchestration capabilities such as auto-scaling and basic high availability.</para>
<para>For information about the:</para>
<para>
<itemizedlist>
<listitem>
<para>Basic creation and deletion of Orchestration stacks, refer to the
<link xlink:href="http://docs.openstack.org/user-guide/content/dashboard_stacks.html">End User Guide</link>.</para>
</listitem>
<listitem>
<para><systemitem>heat</systemitem> CLI commands, see the <link
xlink:href="http://docs.openstack.org/cli-reference/content/"><citetitle>
OpenStack Command Line Interface Reference</citetitle></link>
</para>
</listitem>
</itemizedlist>
</para>
<para>As an administrator, you can also carry out stack functions on behalf of your users. For
example, to resume, suspend, or delete a stack, run:</para>
<screen><prompt>$</prompt> <userinput>action-resume <replaceable>stackID</replaceable></userinput>
<prompt>$</prompt> <userinput>action-suspend <replaceable>stackID</replaceable></userinput>
<prompt>$</prompt> <userinput>stack-delete <replaceable>stackID</replaceable></userinput></screen>
</section>

140
doc/user-guide-admin/section_cli_cinder_quotas.xml
View File

@ -1,140 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="cli_set_block_storage_quotas">
<title>Manage Block Storage service quotas</title>
<para>As an administrative user, you can update the OpenStack Block
Storage service quotas for a project. You can also update the quota
defaults for a new project.</para>
<para>
<table rules="all">
<caption>Block Storage quotas</caption>
<col width="20%"/>
<col width="80%"/>
<thead>
<tr>
<th>Property name</th>
<th>Defines the number of</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>gigabytes</para>
</td>
<td>
<para>Volume gigabytes allowed for each
tenant.</para>
</td>
</tr>
<tr>
<td>
<para>snapshots</para>
</td>
<td>
<para>Volume snapshots allowed for each
tenant.</para>
</td>
</tr>
<tr>
<td>
<para>volumes</para>
</td>
<td>
<para>Volumes allowed for each tenant.</para>
</td>
</tr>
</tbody>
</table>
</para>
<section xml:id="cli_view_block_storage_quotas">
<title>View Block Storage quotas</title>
<para>Administrative users can view Block Storage
service quotas.</para>
<procedure>
<step>
<para>List the default quotas for all projects:</para>
<screen><prompt>$</prompt> <userinput>cinder quota-defaults <replaceable>TENANT_ID</replaceable></userinput>
<computeroutput>+-----------+-------+
| Property | Value |
+-----------+-------+
| gigabytes | 1000 |
| snapshots | 10 |
| volumes | 10 |
+-----------+-------+</computeroutput></screen>
</step>
<step>
<para>View Block Storage service quotas for a project:</para>
<screen><prompt>$</prompt> <userinput>cinder quota-show <replaceable>TENANT_NAME</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>cinder quota-show tenant01</userinput>
<computeroutput>+-----------+-------+
| Property | Value |
+-----------+-------+
| gigabytes | 1000 |
| snapshots | 10 |
| volumes | 10 |
+-----------+-------+</computeroutput></screen>
</step>
<step>
<para>Show the current usage of a per-tenant quota:</para>
<screen><prompt>$</prompt> <userinput>cinder quota-usage <replaceable>tenantID</replaceable></userinput>
<computeroutput>+-----------+--------+----------+-------+
| Type | In_use | Reserved | Limit |
+-----------+--------+----------+-------+
| gigabytes | 0 | 0 | 1000 |
| snapshots | 0 | 0 | 10 |
| volumes | 0 | 0 | 15 |
+-----------+--------+----------+-------+</computeroutput></screen>
</step>
</procedure>
</section>
<section xml:id="cli_edit_update_block_storage_quotas">
<title>Edit and Update Block Storage service quotas</title>
<para>Administrative users can edit and update Block Storage
service quotas.</para>
<procedure>
<step>
<para>Clear per-tenant quota limits:</para>
<screen><prompt>$</prompt> <userinput>cinder quota-delete <replaceable>tenantID</replaceable></userinput></screen>
</step>
<step>
<para>To update a default value for a new project,
update the property in the <literal>cinder.quota</literal> section of the
<filename>/etc/cinder/cinder.conf</filename>
file. For more information,
see the <link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/ch_configuring-openstack-block-storage.html"
>Block Storage Configuration Reference</link>.</para>
</step>
<step>
<para>To update Block Storage service quotas, place
the tenant ID in a variable:</para>
<screen><prompt>$</prompt> <userinput>tenant=$(keystone tenant-list | awk '/<replaceable>tenantName</replaceable>/ {print $2}')</userinput></screen>
</step>
<step>
<para>Update a particular quota value:</para>
<screen><prompt>$</prompt> <userinput>cinder quota-update --<replaceable>quotaName</replaceable> <replaceable>NewValue</replaceable> <replaceable>tenantID</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>cinder quota-update --volumes 15 $tenant</userinput>
<prompt>$</prompt> <userinput>cinder quota-show tenant01</userinput>
<computeroutput>+-----------+-------+
| Property | Value |
+-----------+-------+
| gigabytes | 1000 |
| snapshots | 10 |
| volumes | 15 |
+-----------+-------+</computeroutput></screen>
</step>
<step>
<para>Clear per-tenant quota limits:</para>
<screen><prompt>$</prompt> <userinput>cinder quota-delete <replaceable>tenantID</replaceable></userinput></screen>
</step>
</procedure>
</section>
</section>

377
doc/user-guide-admin/section_cli_keystone_manage_projects_users_roles.xml
View File

@ -1,377 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="admin_cli_manage_projects_users">
<?dbhtml stop-chunking?>
<title>Manage projects, users, and roles</title>
<para>As a cloud administrator, you manage projects, users, and
roles. Projects are organizational units in the cloud to which
you can assign users. Projects are also known as <emphasis
role="italic">tenants</emphasis> or <emphasis
role="italic">accounts</emphasis>. Users can be members of
one or more projects. Roles define which actions users can
perform. You assign roles to user-project pairs.</para>
<para>You can define actions for OpenStack service roles in the
<filename>/etc/<replaceable>PROJECT</replaceable>/policy.json</filename>
files. For example, define actions for Compute service roles
in the <filename>/etc/nova/policy.json</filename> file.</para>
<para>You can manage projects, users, and roles independently from
each other.</para>
<para>During cloud set up, the operator defines at least one
project, user, and role.</para>
<para>Learn how to add, update, and delete projects and users,
assign users to one or more projects, and change or remove the
assignment. To enable or temporarily disable a project or
user, you update that project or user. You can also change
quotas at the project level.</para>
<para>Before you can delete a user account, you must remove the
user account from its primary project.</para>
<para>Before you can run keystone client commands, you must
download and source an OpenStack RC file. See <link
xlink:href="http://docs.openstack.org/user-guide/content/cli_openrc.html"
>Download and source the OpenStack RC file</link>.</para>
<section xml:id="services">
<title>Services</title>
<para>To look at your service catalog, use these keystone
client commands.</para>
<section xml:id="keystone-service-create">
<title><literal>service-create</literal></title>
<para>Keyword arguments:</para>
<itemizedlist>
<listitem>
<para>Name</para>
</listitem>
<listitem>
<para>Type</para>
</listitem>
<listitem>
<para>Description</para>
</listitem>
</itemizedlist>
<para>Example:</para>
<screen><prompt>$</prompt> <userinput>keystone service-create \
--name nova \
--type compute \
--description &quot;Nova Compute Service&quot;</userinput></screen>
</section>
<section xml:id="keystone-service-list">
<title><literal>service-list</literal></title>
<para>Example:</para>
<screen><prompt>$</prompt> <userinput>keystone service-list</userinput></screen>
</section>
<section xml:id="keystone-service-get">
<title><literal>service-get</literal></title>
<para>Arguments</para>
<itemizedlist>
<listitem>
<para>service_id</para>
</listitem>
</itemizedlist>
<para>Example:</para>
<screen><prompt>$</prompt> <userinput>keystone service-get 08741d8ed88242ca88d1f61484a0fe3b</userinput></screen>
</section>
<section xml:id="keystone-service-delete">
<title><literal>service-delete</literal></title>
<para>Arguments</para>
<itemizedlist>
<listitem>
<para>service_id</para>
</listitem>
</itemizedlist>
<para>Example:</para>
<screen><prompt>$</prompt> <userinput>keystone service-delete 08741d8ed88242ca88d1f61484a0fe3b</userinput></screen>
</section>
<section xml:id="admin_cli_projects">
<title>Create a tenant (project)</title>
<para>A tenant is a group of zero or more users. In nova,
a tenant owns virtual machines. In swift, a tenant
owns containers. In the Dashboard, tenants are
represented as projects. Users can be associated with
more than one tenant. Each tenant and user pairing can
have a role associated with it.</para>
<procedure>
<step>
<para>To list all projects with their ID, name,
and whether they are enabled or
disabled:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-list</userinput></screen>
<screen><computeroutput>+----------------------------------+--------------------+---------+
| id | name | enabled |
+----------------------------------+--------------------+---------+
| f7ac731cc11f40efbc03a9f9e1d1d21f | admin | True |
| c150ab41f0d9443f8874e32e725a4cc8 | alt_demo | True |
| a9debfe41a6d4d09a677da737b907d5e | demo | True |
| 9208739195a34c628c58c95d157917d7 | invisible_to_admin | True |
| 3943a53dc92a49b2827fae94363851e1 | service | True |
| 80cab5e1f02045abad92a2864cfd76cb | test_project | True |
+----------------------------------+--------------------+---------+</computeroutput></screen>
</step>
<step>
<para>Create a project named
<literal>new-project</literal>:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-create --name new-project --description 'my new project'</userinput></screen>
<para>By default, the project is enabled.</para>
<screen><computeroutput>+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| description | my new project |
| enabled | True |
| id | 1a4a0618b306462c9830f876b0bd6af2 |
| name | new-project |
+-------------+----------------------------------+</computeroutput></screen>
<para>Note the ID for the project so you can
update it in the next procedure.</para>
</step>
</procedure>
</section>
<section xml:id="cli_update_project">
<title>Update a project</title>
<para>Specify the project ID to update a project. You can
update the name, description, and enabled status of a
project.</para>
<procedure>
<step>
<para>To temporarily disable a project:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-update <replaceable>PROJECT_ID</replaceable> --enabled false</userinput></screen>
</step>
<step>
<para>To enable a disabled project:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-update <replaceable>PROJECT_ID</replaceable> --enabled true</userinput></screen>
</step>
<step>
<para>To update the name of a project:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-update <replaceable>PROJECT_ID</replaceable> --name project-new</userinput></screen>
</step>
<step>
<para>To verify your changes, show information for
the updated project:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-get <replaceable>PROJECT_ID</replaceable></userinput></screen>
<screen><computeroutput>+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| description | my new project |
| enabled | True |
| id | 1a4a0618b306462c9830f876b0bd6af2 |
| name | project-new |
+-------------+----------------------------------+</computeroutput></screen>
</step>
</procedure>
</section>
<section xml:id="cli_project_delete">
<title>Delete a project</title>
<procedure>
<step>
<para>To delete a project:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-delete <replaceable>PROJECT_ID</replaceable></userinput></screen>
</step>
</procedure>
</section>
<section xml:id="admin_cli_user_accounts">
<title>Create a user</title>
<procedure>
<step>
<para>To list all users:</para>
<screen><prompt>$</prompt> <userinput>keystone user-list</userinput></screen>
<para>The output shows the ID, name, enabled
status, and e-mail address for each
user:</para>
<screen><computeroutput>+----------------------------------+----------+---------+----------------------+
| id | name | enabled | email |
+----------------------------------+----------+---------+----------------------+
| 352b37f5c89144d4ad0534139266d51f | admin | True | admin@example.com |
| 86c0de739bcb4802b8dc786921355813 | demo | True | demo@example.com |
| 32ec34aae8ea432e8af560a1cec0e881 | glance | True | glance@example.com |
| 7047fcb7908e420cb36e13bbd72c972c | nova | True | nova@example.com |
+----------------------------------+----------+---------+----------------------+</computeroutput></screen>
</step>
<step>
<para>To create a user, you must specify a name.
Optionally, you can specify a tenant ID,
password, and email address. It is recommended
that you include the tenant ID and password
because the user cannot log in to the
dashboard without this information.</para>
<para>To create the <literal>new-user</literal>
user:</para>
<screen><prompt>$</prompt> <userinput>keystone user-create --name new-user --tenant_id 1a4a0618b306462c9830f876b0bd6af2 --pass <replaceable>PASSWORD</replaceable></userinput></screen>
<screen><computeroutput>+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| email | |
| enabled | True |
| id | 6e5140962b424cb9814fb172889d3be2 |
| name | new-user |
| tenantId | 1a4a0618b306462c9830f876b0bd6af2 |
+----------+----------------------------------+</computeroutput></screen>
</step>
</procedure>
</section>
<section xml:id="cli_update_user">
<title>Update a user</title>
<para>You can update the name, email address, and enabled
status for a user.</para>
<procedure>
<step>
<para>To temporarily disable a user
account:</para>
<screen><prompt>$</prompt> <userinput>keystone user-update <replaceable>USER_ID</replaceable> --enabled false</userinput></screen>
<para>If you disable a user account, the user
cannot log in to the dashboard. However, data
for the user account is maintained, so you can
enable the user at any time.</para>
</step>
<step>
<para>To enable a disabled user account:</para>
<screen><prompt>$</prompt> <userinput>keystone user-update <replaceable>USER_ID</replaceable> --enabled true</userinput></screen>
</step>
<step>
<para>To change the name and description for a
user account:</para>
<screen><prompt>$</prompt> <userinput>keystone user-update <replaceable>USER_ID</replaceable> --name user-new --email new-user@example.com</userinput></screen>
<screen><computeroutput>User has been updated.</computeroutput></screen>
</step>
</procedure>
</section>
<section xml:id="cli_delete_user">
<title>Delete a user</title>
<procedure>
<step>
<para>To delete a specified user account:</para>
<screen><prompt>$</prompt> <userinput>keystone user-delete <replaceable>USER_ID</replaceable></userinput></screen>
</step>
</procedure>
</section>
<section xml:id="admin_cli_modify_projects">
<title>Create and assign a role</title>
<para>Users can be members of multiple projects. To assign
users to multiple projects, define a role and assign
that role to a user-project pair.</para>
<procedure>
<step>
<para>To list the available roles:</para>
<screen><prompt>$</prompt> <userinput>keystone role-list</userinput></screen>
<screen><computeroutput>+----------------------------------+---------------+
| id | name |
+----------------------------------+---------------+
| 71ccc37d41c8491c975ae72676db687f | Member |
| 149f50a1fe684bfa88dae76a48d26ef7 | ResellerAdmin |
| 9fe2ff9ee4384b1894a90878d3e92bab | _member_ |
| 6ecf391421604da985db2f141e46a7c8 | admin |
| deb4fffd123c4d02a907c2c74559dccf | anotherrole |
+----------------------------------+---------------+</computeroutput></screen>
</step>
<step>
<para>To create the <literal>new-role</literal>
role:</para>
<screen><prompt>$</prompt> <userinput>keystone role-create --name new-role</userinput></screen>
<screen><computeroutput>+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| id | bef1f95537914b1295da6aa038ef4de6 |
| name | new-role |
+----------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>To assign a user to a project, you must
assign the role to a user-project pair. To do
this, you need the user, role, and project
IDs.</para>
<substeps>
<step>
<para>To list users:</para>
<screen><prompt>$</prompt> <userinput>keystone user-list</userinput></screen>
<screen><computeroutput>+----------------------------------+----------+---------+----------------------+
| id | name | enabled | email |
+----------------------------------+----------+---------+----------------------+
| 352b37f5c89144d4ad0534139266d51f | admin | True | admin@example.com |
| 981422ec906d4842b2fc2a8658a5b534 | alt_demo | True | alt_demo@example.com |
| 036e22a764ae497992f5fb8e9fd79896 | cinder | True | cinder@example.com |
| 86c0de739bcb4802b8dc786921355813 | demo | True | demo@example.com |
| 32ec34aae8ea432e8af560a1cec0e881 | glance | True | glance@example.com |
| 7047fcb7908e420cb36e13bbd72c972c | nova | True | nova@example.com |
+----------------------------------+----------+---------+----------------------+</computeroutput></screen>
<para>Note the ID of the user to which you
want to assign the role.</para>
</step>
<step>
<para>To list role IDs:</para>
<screen><prompt>$</prompt> <userinput>keystone role-list</userinput></screen>
<screen><computeroutput>+----------------------------------+---------------+
| id | name |
+----------------------------------+---------------+
| 71ccc37d41c8491c975ae72676db687f | Member |
| 149f50a1fe684bfa88dae76a48d26ef7 | ResellerAdmin |
| 9fe2ff9ee4384b1894a90878d3e92bab | _member_ |
| 6ecf391421604da985db2f141e46a7c8 | admin |
| deb4fffd123c4d02a907c2c74559dccf | anotherrole |
| bef1f95537914b1295da6aa038ef4de6 | new-role |
+----------------------------------+---------------+</computeroutput></screen>
<para>Note the ID of the role that you
want to assign.</para>
</step>
<step>
<para>To list projects:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-list</userinput></screen>
<screen><computeroutput>+----------------------------------+--------------------+---------+
| id | name | enabled |
+----------------------------------+--------------------+---------+
| f7ac731cc11f40efbc03a9f9e1d1d21f | admin | True |
| c150ab41f0d9443f8874e32e725a4cc8 | alt_demo | True |
| a9debfe41a6d4d09a677da737b907d5e | demo | True |
| 9208739195a34c628c58c95d157917d7 | invisible_to_admin | True |
| caa9b4ce7d5c4225aa25d6ff8b35c31f | new-user | True |
| 1a4a0618b306462c9830f876b0bd6af2 | project-new | True |
| 3943a53dc92a49b2827fae94363851e1 | service | True |
| 80cab5e1f02045abad92a2864cfd76cb | test_project | True |
+----------------------------------+--------------------+---------+</computeroutput></screen>
<para>Note the ID of the project to which
you want to assign the role.</para>
</step>
</substeps>
</step>
<step>
<para>Assign a role to a user-project pair. In
this example, you assign the
<literal>new-role</literal> role to the
<literal>demo</literal> and
<literal>test-project</literal>
pair:</para>
<screen><prompt>$</prompt> <userinput>keystone user-role-add --user <replaceable>USER_ID</replaceable> --role <replaceable>ROLE_ID</replaceable> --tenant <replaceable>TENANT_ID</replaceable></userinput></screen>
</step>
<step>
<para>To verify the role assignment:</para>
<screen><prompt>$</prompt> <userinput>keystone user-role-list --user <replaceable>USER_ID</replaceable> --tenant <replaceable>TENANT_ID</replaceable></userinput></screen>
<screen><computeroutput>+----------------------------------+----------+----------------------------------+----------------------------------+
| id | name | user_id | tenant_id |
+----------------------------------+----------+----------------------------------+----------------------------------+
| bef1f95537914b1295da6aa038ef4de6 | new-role | 86c0de739bcb4802b8dc786921355813 | 80cab5e1f02045abad92a2864cfd76cb |
+----------------------------------+----------+----------------------------------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>To get details for a specified role:</para>
<screen><prompt>$</prompt> <userinput>keystone role-get <replaceable>ROLE_ID</replaceable></userinput></screen>
<screen><computeroutput>+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| id | bef1f95537914b1295da6aa038ef4de6 |
| name | new-role |
+----------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>To remove a role from a user-project
pair:</para>
<screen><prompt>$</prompt> <userinput>keystone user-role-remove --user <replaceable>USER_ID</replaceable> --role <replaceable>ROLE_ID</replaceable> --tenant <replaceable>TENANT_ID</replaceable></userinput></screen>
</step>
<step>
<para>To verify the role removal, run the
following command:</para>
<screen><prompt>$</prompt> <userinput>keystone user-role-list --user <replaceable>USER_ID</replaceable> --tenant <replaceable>TENANT_ID</replaceable></userinput></screen>
<para>If the role was removed, the command output
omits the removed role.</para>
</step>
</procedure>
</section>
</section>
</section>

169
doc/user-guide-admin/section_cli_keystone_services.xml
View File

@ -1,169 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="adding-users-tenants-and-roles-with-python-keystoneclient">
<?dbhtml stop-chunking?>
<title>Create and manage services and service users</title>
<para>The Identity Service enables you to define services, as
follows:</para>
<itemizedlist>
<listitem>
<para>Service catalog template. The Identity Service acts
as a service catalog of endpoints for other OpenStack
services. The
<literal>etc/default_catalog.templates</literal>
template file defines the endpoints for services. When
the Identity Service uses a template file back end,
any changes that are made to the endpoints are cached.
These changes do not persist when you restart the
service or reboot the machine.</para>
</listitem>
<listitem>
<para>A SQL back end for the catalog service. When the
Identity Service is online, you must add the services
to the catalog. When you deploy a system for
production, use the SQL back end.</para>
</listitem>
</itemizedlist>
<para>The <literal>auth_token</literal> middleware supports the
use of either a shared secret or users for each
service.</para>
<para>To authenticate users against the Identity Service, you must
create a service user for each OpenStack service. For example,
create a service user for the Compute, Block Storage, and
Networking services.</para>
<para>To configure the OpenStack services with service users,
create a project for all services and create users for each
service. Assign the admin role to each service user and
project pair. This role enables users to validate tokens and
authenticate and authorize other user requests.</para>
<section xml:id="cli_service-create">
<title>Create a service</title>
<procedure>
<step>
<para>List the available services:</para>
<screen><prompt>$</prompt> <userinput>keystone service-list</userinput></screen>
<screen><computeroutput>+----------------------------------+----------+----------+---------------------------+
| id | name | type | description |
+----------------------------------+----------+----------+---------------------------+
| 9816f1faaa7c4842b90fb4821cd09223 | cinder | volume | Cinder Volume Service |
| da8cf9f8546b4a428c43d5e032fe4afc | ec2 | ec2 | EC2 Compatibility Layer |
| 5f105eeb55924b7290c8675ad7e294ae | glance | image | Glance Image Service |
| dcaa566e912e4c0e900dc86804e3dde0 | keystone | identity | Keystone Identity Service |
| 4a715cfbc3664e9ebf388534ff2be76a | nova | compute | Nova Compute Service |
| 6feb2e0b98874d88bee221974770e372 | s3 | s3 | S3 |
+----------------------------------+----------+----------+---------------------------+</computeroutput></screen>
</step>
<step>
<para>To create a service, run this command:</para>
<screen><prompt>$</prompt> <userinput>keystone service-create --name <replaceable>service_name</replaceable> --type <replaceable>service_type</replaceable> --description <replaceable>service_description</replaceable></userinput></screen>
<para>The arguments are:</para>
<itemizedlist>
<listitem>
<para><code><replaceable>service_name</replaceable></code>.
The unique name of the new service.</para>
</listitem>
<listitem>
<para><code><replaceable>service_type</replaceable></code>.
The service type, such as
<code>identity</code>,
<code>compute</code>,
<code>network</code>,
<code>image</code>,
<code>object-store</code> or any other
service identifier string.</para>
</listitem>
<listitem>
<para><code><replaceable>service_description</replaceable></code>.
The description of the service.</para>
</listitem>
</itemizedlist>
<para>For example, to create a
<literal>swift</literal> service of type
<literal>object-store</literal>, run this
command:</para>
<screen><prompt>$</prompt> <userinput>keystone service-create --name swift --type object-store --description "object store service"</userinput></screen>
<screen><computeroutput>+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| description | object store service |
| enabled | True |
| id | 84c23f4b942c44c38b9c42c5e517cd9a |
| name | swift |
| type | object-store |
+-------------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>To get details for a service, run this
command:</para>
<screen><prompt>$</prompt> <userinput>keystone service-get <replaceable>service_ID</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>keystone service-get 84c23f4b942c44c38b9c42c5e517cd9a</userinput></screen>
<screen><computeroutput>+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| description | object store service |
| enabled | True |
| id | 84c23f4b942c44c38b9c42c5e517cd9a |
| name | swift |
| type | object-store |
+-------------+----------------------------------+</computeroutput></screen>
</step>
</procedure>
</section>
<section xml:id="cli_create_service_users">
<title>Create service users</title>
<procedure>
<step>
<para>Create a project for the service users.
Typically, this project is named
<literal>service</literal>, but choose any
name you like:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-create --name service</userinput></screen>
<para>The output shows the ID for the project.</para>
<para>Make a note of this ID. You need it to create
service users and assign roles.</para>
<screen><computeroutput>+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| description | |
| enabled | True |
| id | 3e9f3f5399624b2db548d7f871bd5322 |
| name | service |
+-------------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>Create service users for the relevant services
for your deployment.</para>
</step>
<step>
<para>To assign the admin role to the service
user-project pairs, run this command to get the ID
of the admin role:</para>
<screen><prompt>$</prompt> <userinput>keystone role-list</userinput></screen>
<screen><computeroutput>+----------------------------------+---------------+
| id | name |
+----------------------------------+---------------+
| 71ccc37d41c8491c975ae72676db687f | Member |
| 149f50a1fe684bfa88dae76a48d26ef7 | ResellerAdmin |
| 9fe2ff9ee4384b1894a90878d3e92bab | _member_ |
| 6ecf391421604da985db2f141e46a7c8 | admin |
| deb4fffd123c4d02a907c2c74559dccf | anotherrole |
| bef1f95537914b1295da6aa038ef4de6 | new-role |
+----------------------------------+---------------+</computeroutput></screen>
</step>
<step>
<para>Assign the admin role to the user-project
pair:</para>
<screen><prompt>$</prompt> <userinput>keystone user-role-add --user <replaceable>SERVICE_USER_ID</replaceable> --role <replaceable>ADMIN_ROLE_ID</replaceable> --tenant <replaceable>SERVICE_PROJECT_ID</replaceable></userinput></screen>
</step>
</procedure>
</section>
<section xml:id="cli_delete_service">
<title>Delete a service</title>
<para>To delete a specified service, specify its ID:</para>
<screen><prompt>$</prompt> <userinput>keystone service-delete <replaceable>SERVICE_ID</replaceable></userinput></screen>
</section>
</section>

53
doc/user-guide-admin/section_cli_keystone_set_quotas.xml
View File

@ -1,53 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="cli_set_quotas">
<?dbhtml stop-chunking?>
<title>Manage quotas</title>
<para>To prevent system capacities from being exhausted without
notification, you can set up quotas. Quotas are operational
limits. For example, the number of gigabytes allowed for each
tenant can be controlled so that cloud resources are optimized.
Quotas can be enforced at both the tenant (or project)
and the tenant-user level.</para>
<para>Using the command-line interface, you can manage quotas for
the OpenStack Compute service, the OpenStack Block Storage service,
and the OpenStack Networking service.</para>
<para>The cloud operator typically changes default values because a
tenant requires more than ten volumes or 1&nbsp;TB on a compute
node.
</para>
<note>
<para>To view all tenants (projects), run:
<screen><prompt>$</prompt> <userinput>keystone tenant-list</userinput>
<computeroutput>+----------------------------------+----------+---------+
| id | name | enabled |
+----------------------------------+----------+---------+
| e66d97ac1b704897853412fc8450f7b9 | admin | True |
| bf4a37b885fe46bd86e999e50adad1d3 | services | True |
| 21bd1c7c95234fd28f589b60903606fa | tenant01 | True |
| f599c5cd1cba4125ae3d7caed08e288c | tenant02 | True |
+----------------------------------+----------+---------+</computeroutput></screen>
</para>
<para>To display all current users for a tenant, run:</para>
<para>
<screen><prompt>$</prompt> <userinput>keystone user-list --tenant-id <replaceable>tenantID</replaceable></userinput>
<computeroutput>+----------------------------------+--------+---------+-------+
| id | name | enabled | email |
+----------------------------------+--------+---------+-------+
| ea30aa434ab24a139b0e85125ec8a217 | demo00 | True | |
| 4f8113c1d838467cad0c2f337b3dfded | demo01 | True | |
+----------------------------------+--------+---------+-------+
</computeroutput></screen>
</para>
</note>
<xi:include href="../common/section_cli_nova_quotas.xml"/>
<xi:include href="section_cli_cinder_quotas.xml"/>
<xi:include href="../common/section_cli_neutron-quotas.xml"/>
</section>

12
doc/user-guide-admin/section_cli_manage_services.xml
View File

@ -1,12 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="section_cli_manage_services">
<?dbhtml stop-chunking?>
<title>Manage services</title>
<xi:include href="section_cli_keystone_services.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_nova_services.xml"/>
</section>

109
doc/user-guide-admin/section_cli_nova_floating_ips.xml
View File

@ -1,109 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="manage_ip_addresses">
<title>Manage IP addresses</title>
<para>Each instance has a private, fixed IP address (assigned when launched) and can also have a
public, or floating, 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.</para>
<para>
<itemizedlist>
<listitem>
<para>By default, both administrative and end users can associate floating IP
addresses with projects and instances. You can change user permissions for
managing IP addresses by updating the <filename>/etc/nova/policy.json</filename>
file. For basic floating-IP procedures, refer to the <citetitle>Manage IP
Addresses</citetitle> section in the <link
xlink:href="http://docs.openstack.org/user-guide/content/"
><citetitle>OpenStack End User Guide</citetitle></link>.</para>
</listitem>
<listitem>
<para>For details on creating public networks using OpenStack Networking
(<systemitem>neutron</systemitem>), refer to the <link
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/"
><citetitle>OpenStack Cloud Administrator Guide</citetitle></link>. No
floating IP addresses are created by default in OpenStack Networking.</para>
</listitem>
</itemizedlist>
</para>
<para>As an administrator using legacy networking (<systemitem>nova-network</systemitem>), you
can use the following bulk commands to list, create, and delete ranges of floating IP
addresses. These addresses can then be associated with instances by end users:</para>
<variablelist>
<varlistentry><term>List addresses for all projects</term>
<listitem><para>To list all floating IP addresses for all projects, run:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-bulk-list</userinput>
<computeroutput>+------------+---------------+---------------+--------+-----------+
| project_id | address | instance_uuid | pool | interface |
+------------+---------------+---------------+--------+-----------+
| None | 172.24.4.225 | None | public | eth0 |
| None | 172.24.4.226 | None | public | eth0 |
| None | 172.24.4.227 | None | public | eth0 |
| None | 172.24.4.228 | None | public | eth0 |
| None | 172.24.4.229 | None | public | eth0 |
| None | 172.24.4.230 | None | public | eth0 |
| None | 172.24.4.231 | None | public | eth0 |
| None | 172.24.4.232 | None | public | eth0 |
| None | 172.24.4.233 | None | public | eth0 |
| None | 172.24.4.234 | None | public | eth0 |
| None | 172.24.4.235 | None | public | eth0 |
| None | 172.24.4.236 | None | public | eth0 |
| None | 172.24.4.237 | None | public | eth0 |
| None | 172.24.4.238 | None | public | eth0 |
| None | 192.168.253.1 | None | test | eth0 |
| None | 192.168.253.2 | None | test | eth0 |
| None | 192.168.253.3 | None | test | eth0 |
| None | 192.168.253.4 | None | test | eth0 |
| None | 192.168.253.5 | None | test | eth0 |
| None | 192.168.253.6 | None | test | eth0 |
+------------+---------------+---------------+--------+-----------+</computeroutput></screen></listitem>
</varlistentry>
<varlistentry><term>Bulk create floating IP addresses</term>
<listitem><para>To create a range of floating IP addresses, run:</para>
<para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-bulk-create [--pool <replaceable>POOL_NAME</replaceable>] [--interface <replaceable>INTERFACE</replaceable>] <replaceable>RANGE_TO_CREATE</replaceable></userinput></screen>
</para>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-bulk-create --pool test 192.168.1.56/29</userinput></screen>
<para>By default, <command>floating-ip-bulk-create</command> uses the
<systemitem>public</systemitem> pool and <systemitem>eth0</systemitem>
interface values.</para>
<para>
<note>
<para>You should use a range of free IP addresses that is correct for your
network. If you are not sure, at least try to avoid the DHCP address
range:</para>
<para>
<itemizedlist>
<listitem>
<para>Pick a small range (/29 gives an 8 address range, 6 of
which will be usable)</para>
</listitem>
<listitem>
<para>Use <command>nmap</command> to check a range's
availability. For example, 192.168.1.56/29 represents a
small range of addresses (192.168.1.56-63, with 57-62
usable), and you could run the command <command>nmap -sn
192.168.1.56/29</command> to check whether the entire
range is currently unused.</para>
</listitem>
</itemizedlist>
</para>
</note>
</para>
</listitem>
</varlistentry>
<varlistentry><term>Bulk delete floating IP addresses</term>
<listitem><para>To delete a range of floating IP addresses, run:</para>
<para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-bulk-delete <replaceable>RANGE_TO_DELETE</replaceable></userinput></screen>
</para>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-bulk-delete 192.168.1.56/29</userinput></screen>
</listitem>
</varlistentry>
</variablelist>
</section>

32
doc/user-guide-admin/section_cli_nova_host_servers_migrate.xml
View File

@ -1,32 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nova_cli_host_servers_migrate">
<title>Migrate all instances to another compute host</title>
<para>When you want to move all instances from one compute host to
another, you can use the <command>nova
host-servers-migrate</command> command. The difference
between this command and the <command>nova evacuate</command>
command is that you can specify the host when evacuating. Also
when evacuating, you must configure shared storage on the
target host so that user data is preserved on the server disk.
See <link xlink:href="http://docs.openstack.org/user-guide/content/nova_cli_evacuate.html">Evacuate instances</link>.</para>
<procedure xml:id="migrate_host">
<step>
<para>To list the host you want to migrate, run:</para>
<screen><prompt>$</prompt> <userinput>nova service-list</userinput></screen>
</step>
<step>
<para>After selecting a host from the list, run this
command:
<screen><prompt>$</prompt> <userinput>nova host-servers-migrate <replaceable>HOST_NAME</replaceable></userinput></screen></para>
<para>Where <replaceable>HOST_NAME</replaceable> is the
name of the host you want the servers to go to.</para>
<para>All instances are booted from a new host while preserving
their current configurations, including ID, name, UUID, IP
address, and so on.</para>
</step>
</procedure>
</section>

225
doc/user-guide-admin/section_cli_nova_manage_flavors.xml
View File

@ -1,225 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="cli_manage_flavors">
<?dbhtml stop-chunking?>
<title>Manage flavors</title>
<para>In OpenStack, flavors define the compute, memory, and
storage capacity of nova computing instances. To put it
simply, a flavor is an available hardware configuration for a
server. It defines the <quote>size</quote> of a virtual server
that can be launched.</para>
<note>
<para>Flavors can also determine on which compute host a flavor
can be used to launch an instance. For information
about customizing flavors, refer to the <link
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/"
><citetitle>OpenStack Cloud Administrator Guide</citetitle></link>.</para></note>
<para>A flavor consists of the following parameters:</para>
<variablelist>
<varlistentry>
<term>Flavor ID</term>
<listitem>
<para>Automatically generated by OpenStack. For
private flavors, a value from 1 to 255.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Name</term>
<listitem>
<para>Name for the new flavor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>VCPUs</term>
<listitem>
<para>Number of virtual CPUs to use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Memory MB</term>
<listitem>
<para>Amount of RAM to use (in megabytes).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Root Disk GB</term>
<listitem>
<para>Amount of disk space (in gigabytes) to use for
the root (/) partition.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Ephemeral Disk GB</term>
<listitem>
<para>Amount of disk space (in gigabytes) to use for
the ephemeral partition. If unspecified, the value
is 0 by default.</para>
<para>Ephemeral disks offer machine local disk storage
linked to the life cycle of a VM instance. When a
VM is terminated, all data on the ephemeral disk
is lost. Ephemeral disks are not included in any
snapshots.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Swap</term>
<listitem>
<para>Amount of swap space (in megabytes) to use. If
unspecified, the value is 0 by default.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The default flavors are:</para>
<informaltable rules="all" width="50%">
<col width="30%"/>
<col width="20%"/>
<col width="25%"/>
<col width="25%"/>
<thead>
<tr>
<th>Flavor</th>
<th>VCPUs</th>
<th>Disk (in GB)</th>
<th>RAM (in MB)</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>m1.tiny</para>
</td>
<td>
<para>1</para>
</td>
<td>
<para>1</para>
</td>
<td>
<para>512</para>
</td>
</tr>
<tr>
<td>
<para>m1.small</para>
</td>
<td>
<para>1</para>
</td>
<td>
<para>20</para>
</td>
<td>
<para>2048</para>
</td>
</tr>
<tr>
<td>
<para>m1.medium</para>
</td>
<td>
<para>2</para>
</td>
<td>
<para>40</para>
</td>
<td>
<para>4096</para>
</td>
</tr>
<tr>
<td>
<para>m1.large</para>
</td>
<td>
<para>4</para>
</td>
<td>
<para>80</para>
</td>
<td>
<para>8192</para>
</td>
</tr>
<tr>
<td>
<para>m1.xlarge</para>
</td>
<td>
<para>8</para>
</td>
<td>
<para>160</para>
</td>
<td>
<para>16384</para>
</td>
</tr>
</tbody>
</informaltable>
<para>You can create and manage flavors with the nova
<command>flavor-*</command> commands provided by the
<filename>python-novaclient</filename> package.</para>
<section xml:id="cli_create_flavor">
<title>Create a flavor</title>
<procedure>
<step>
<para>List flavors to show the ID and name, the amount
of memory, the amount of disk space for the root
partition and for the ephemeral partition, the
swap, and the number of virtual CPUs for each
flavor.</para>
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput></screen>
</step>
<step>
<para>To create a flavor, specify a name, ID, RAM
size, disk size, and the number of VCPUs for the
flavor, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova flavor-create <replaceable>FLAVOR_NAME</replaceable> <replaceable>FLAVOR_ID</replaceable> <replaceable>RAM_IN_MB ROOT_DISK_IN_GB</replaceable> <replaceable>NUMBER_OF_VCPUS</replaceable></userinput></screen>
<note>
<para>The flavor ID is a number from 1 to 255 and
cannot contain special characters or
spaces.</para>
</note>
<para>Here is an example with additional optional
parameters filled in that creates a public "extra
tiny" flavor that automatically gets an ID
assigned, with 256 MB memory, no disk space, and
one VCPU. The rxtx-factor indicates the slice of
bandwidth that the instances with this flavor can
use (through the Virtual Interface (vif) creation
in the hypervisor).</para>
<screen><prompt>$</prompt> <userinput>nova flavor-create --is-public true m1.extra_tiny auto 256 0 1 --rxtx-factor .1</userinput></screen>
<para>If an individual user or group of users needs a custom
flavor that you do not want other tenants to have access to,
you can change the flavor's access to make it a private flavor.
See <link
xlink:href="http://docs.openstack.org/openstack-ops/content/private-flavors.html">
Private Flavors in the OpenStack Operations Guide
</link>.</para>
<para>For a list of optional parameters, run this
command:</para>
<screen><prompt>$</prompt> <userinput>nova help flavor-create</userinput></screen>
</step>
<step>
<para>After you create a flavor, assign it to a
project by specifying the flavor name or ID and
the tenant ID:</para>
<screen><prompt>$</prompt> <userinput>nova flavor-access-add <replaceable>FLAVOR</replaceable> <replaceable>TENANT_ID</replaceable></userinput></screen>
</step>
</procedure>
</section>
<section xml:id="cli_delete_flavor">
<title>Delete a flavor</title>
<procedure>
<step>
<para>Delete a specified flavor, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova flavor-delete <replaceable>FLAVOR_ID</replaceable></userinput></screen>
</step>
</procedure>
</section>
</section>

203
doc/user-guide-admin/section_cli_nova_manage_projects_security.xml
View File

@ -1,203 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nova_cli_manage_projects_security">
<?dbhtml stop-chunking?>
<title>Manage project security</title>
<para>Security groups are sets of IP filter rules that are applied
to all project instances, which define networking access
to the instance. Group rules are project specific; project
members can edit the default rules for their group and add new
rule sets.</para>
<para>All projects have a "default" security group which is
applied to any instance that has no other defined security
group. Unless you change the default, this security group
denies all incoming traffic and allows only outgoing traffic
to your instance.</para>
<note>
<para>For information about updating rules using the
dashboard, see <xref
linkend="dashboard_manage_projects_security"/>.</para>
</note>
<para>You can use the <code>allow_same_net_traffic</code> option
in the <filename>/etc/nova/nova.conf</filename> file to
globally control whether the rules apply to hosts which
share a network.</para>
<para>If set to:</para>
<itemizedlist>
<listitem>
<para><code>True</code> (default), hosts on the same
subnet are not filtered and are allowed to pass all
types of traffic between them. On a flat network, this
allows all instances from all projects unfiltered
communication. With VLAN networking, this allows
access between instances within the same project. You
can also simulate this setting by configuring the
default security group to allow all traffic from the
subnet.</para>
</listitem>
<listitem>
<para><code>False</code>, security groups are enforced for
all connections.</para>
</listitem>
</itemizedlist>
<para>Additionally, the number of maximum rules per security group
is controlled by the <code>security_group_rules</code> and the
number of allowed security groups per project is controlled by
the <code>security_groups</code> quota (see <xref
linkend="cli_set_quotas"/>).</para>
<procedure>
<title>List and view current security groups</title>
<para>From the command line you can get a list of security
groups for the project, using the nova
command:</para>
<step>
<para>Ensure your system variables are set for the user
and tenant for which you are checking security group
rules for. For example:</para>
<programlisting language="bash">export OS_USERNAME=demo00
export OS_TENANT_NAME=tenant01</programlisting>
</step>
<step>
<para>Output security groups, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list</userinput>
<computeroutput>+---------+-------------+
| Name | Description |
+---------+-------------+
| default | default |
| open | all ports |
+---------+-------------+</computeroutput></screen>
</step>
<step>
<para>View the details of a group, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules <replaceable>groupName</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules open</userinput>
<computeroutput>+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+
| icmp | -1 | 255 | 0.0.0.0/0 | |
| tcp | 1 | 65535 | 0.0.0.0/0 | |
| udp | 1 | 65535 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+ </computeroutput></screen>
<para>These rules are allow type rules as the default is
deny. The first column is the IP protocol (one of
icmp, tcp, or udp). The second and third columns
specify the affected port range. The third column
specifies the IP range in CIDR format. This example
shows the full port range for all protocols allowed
from all IPs.</para>
</step>
</procedure>
<procedure>
<title>Create a security group</title>
<para>When adding a new security group, you should pick a
descriptive but brief name. This name shows up in brief
descriptions of the instances that use it where the longer
description field often does not. For example, seeing that
an instance is using security group "http" is much easier
to understand than "bobs_group" or "secgrp1".</para>
<step>
<para>Ensure your system variables are set for the user
and tenant for which you are checking security group
rules for.</para>
</step>
<step>
<para>Add the new security group, as follows:</para>
<para>
<screen><prompt>$</prompt> <userinput>nova secgroup-create <replaceable>Group Name Description</replaceable></userinput></screen>
</para>
<para>For example:</para>
<para>
<screen><prompt>$</prompt> <userinput>nova secgroup-create global_http "Allows Web traffic anywhere on the Internet."</userinput>
<computeroutput>+--------------------------------------+-------------+----------------------------------------------+
| Id | Name | Description |
+--------------------------------------+-------------+----------------------------------------------+
| 1578a08c-5139-4f3e-9012-86bd9dd9f23b | global_http | Allows Web traffic anywhere on the Internet. |
+--------------------------------------+-------------+----------------------------------------------+</computeroutput></screen>
</para>
</step>
<step>
<para>Add a new group rule, as follows:</para>
<para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule <replaceable>secGroupName ip-protocol from-port to-port CIDR</replaceable></userinput></screen>
</para>
<para>The arguments are positional, and the "from-port"
and "to-port" arguments specify the local port range
connections are allowed to access, not the source and
destination ports of the connection. For
example:</para>
<para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule global_http tcp 80 80 0.0.0.0/0</userinput>
<computeroutput>+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+
| tcp | 80 | 80 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+</computeroutput></screen>
</para>
<para>You can create complex rule sets by creating
additional rules. For example, if you want to pass
both HTTP and HTTPS traffic, run:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule global_http tcp 443 443 0.0.0.0/0</userinput>
<computeroutput>+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+
| tcp | 443 | 443 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+</computeroutput></screen>
<para>Despite only outputting the newly added rule, this
operation is additive (both rules are created and
enforced).</para>
</step>
<step>
<para>View all rules for the new security group, as
follows:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules global_http</userinput>
<computeroutput>+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+
| tcp | 80 | 80 | 0.0.0.0/0 | |
| tcp | 443 | 443 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+</computeroutput></screen>
</step>
</procedure>
<procedure>
<title>Delete a security group</title>
<step>
<para>Ensure your system variables are set for the user
and tenant for which you are deleting a security
group for.</para>
</step>
<step>
<para>Delete the new security group, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-delete <replaceable>GroupName</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-delete global_http</userinput></screen>
</step>
</procedure>
<procedure>
<title>Create security group rules for a cluster of
instances</title>
<para>Source Groups are a special, dynamic way of defining the
CIDR of allowed sources. The user specifies a Source Group
(Security Group name), and all the users' other Instances
using the specified Source Group are selected dynamically.
This alleviates the need for individual rules to allow
each new member of the cluster.</para>
<step>
<para>Make sure to set the system variables for the user
and tenant for which you are deleting a security
group for.</para>
</step>
<step>
<para>Add a source group, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule <replaceable>secGroupName source-group ip-protocol from-port to-port</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule cluster global_http tcp 22 22</userinput></screen>
<para>The <code>cluster</code> rule allows ssh access from
any other instance that uses the
<code>global_http</code> group.</para>
</step>
</procedure>
</section>

75
doc/user-guide-admin/section_cli_nova_migrate.xml
View File

@ -1,75 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nova_cli_migrate_single">
<title>Migrate single instance to another compute host</title>
<para>When you want to move an instance from one compute host to another,
you can use the <command>nova migrate</command> command. The scheduler
chooses the destination compute host based on its settings. This process
does not assume that the instance has shared storage available on the
target host.</para>
<procedure xml:id="migrate_single">
<step>
<para>To list the VMs you want to migrate, run:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput></screen>
</step>
<step>
<para>After selecting a VM from the list, run this command where
<replaceable>VM_ID</replaceable> is set to the ID in the list
returned in the previous step:</para>
<screen><prompt>$</prompt> <userinput>nova show <replaceable>VM_ID</replaceable></userinput></screen>
</step>
<step>
<para>Now, use the <command>nova migrate</command> command:</para>
<screen><prompt>$</prompt> <userinput>nova migrate <replaceable>VM_ID</replaceable></userinput></screen>
</step>
<step performance="optional">
<para>To migrate of an instance and watch the status, use this
example script:</para>
<programlisting language="bash">#!/bin/bash
# Provide usage
usage() {
echo "Usage: $0 VM_ID"
exit 1
}
[[ $# -eq 0 ]] &amp;&amp; usage
# Migrate the VM to an alternate hypervisor
echo -n "Migrating instance to alternate host"
$VM_ID=$1
nova migrate $VM_ID
VM_OUTPUT=`nova show $VM_ID`
VM_STATUS=`echo "$VM_OUTPUT" | grep status | awk '{print $4}'`
while [[ "$VM_STATUS" != "VERIFY_RESIZE" ]]; do
echo -n "."
sleep 2
VM_OUTPUT=`nova show $VM_ID`
VM_STATUS=`echo "$VM_OUTPUT" | grep status | awk '{print $4}'`
done
nova resize-confirm $VM_ID
echo " instance migrated and resized."
echo;
# Show the details for the VM
echo "Updated instance details:"
nova show $VM_ID
# Pause to allow users to examine VM details
read -p "Pausing, press &lt;enter&gt; to exit."</programlisting>
<note>
<para>If you see this error, it means you are either trying the
command with the wrong credentials, such as a non-admin
user, or the <filename>policy.json</filename> file prevents
migration for your user.
<screen><computeroutput>ERROR (Forbidden): Policy doesn't allow compute_extension:admin_actions:migrate to be performed. (HTTP 403)</computeroutput></screen></para>
</note>
<para>The instance is booted from a new host, but preserves its
configuration including its ID, name, any metadata, IP address,
and other properties.</para>
</step>
</procedure>
</section>

73
doc/user-guide-admin/section_cli_nova_services.xml
View File

@ -1,73 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nova-manage-services">
<title>Manage Compute services</title>
<para>You can enable and disable Compute services. The following
examples disable and enable the <systemitem class="service"
>nova-compute</systemitem> service.</para>
<procedure>
<step>
<para>List the Compute services:</para>
<screen><prompt>$</prompt> <userinput>nova service-list</userinput>
<computeroutput>+------------------+----------+----------+---------+-------+----------------------------+-----------------+
| Binary | Host | Zone | Status | State | Updated_at | Disabled Reason |
+------------------+----------+----------+---------+-------+----------------------------+-----------------+
| nova-conductor | devstack | internal | enabled | up | 2013-10-16T00:56:08.000000 | None |
| nova-cert | devstack | internal | enabled | up | 2013-10-16T00:56:09.000000 | None |
| nova-compute | devstack | nova | enabled | up | 2013-10-16T00:56:07.000000 | None |
| nova-network | devstack | internal | enabled | up | 2013-10-16T00:56:06.000000 | None |
| nova-scheduler | devstack | internal | enabled | up | 2013-10-16T00:56:04.000000 | None |
| nova-consoleauth | devstack | internal | enabled | up | 2013-10-16T00:56:07.000000 | None |
+------------------+----------+----------+---------+-------+----------------------------+-----------------+</computeroutput></screen>
</step>
<step>
<para>Disable a nova service:</para>
<screen><prompt>$</prompt> <userinput>nova service-disable localhost.localdomain nova-compute --reason 'trial log'</userinput>
<computeroutput>+----------+--------------+----------+-------------------+
| Host | Binary | Status | Disabled Reason |
+----------+--------------+----------+-------------------+
| devstack | nova-compute | disabled | Trial log |
+----------+--------------+----------+-------------------+</computeroutput></screen>
</step>
<step>
<para>Check the service list:</para>
<screen><prompt>$</prompt> <userinput>nova service-list</userinput>
<computeroutput>+------------------+----------+----------+---------+-------+----------------------------+------------------+
| Binary | Host | Zone | Status | State | Updated_at | Disabled Reason |
+------------------+----------+----------+---------+-------+----------------------------+------------------+
| nova-conductor | devstack | internal | enabled | up | 2013-10-16T00:56:48.000000 | None |
| nova-cert | devstack | internal | enabled | up | 2013-10-16T00:56:49.000000 | None |
| nova-compute | devstack | nova | disabled | up | 2013-10-16T00:56:47.000000 | Trial log |
| nova-network | devstack | internal | enabled | up | 2013-10-16T00:56:51.000000 | None |
| nova-scheduler | devstack | internal | enabled | up | 2013-10-16T00:56:44.000000 | None |
| nova-consoleauth | devstack | internal | enabled | up | 2013-10-16T00:56:47.000000 | None |
+------------------+----------+----------+---------+-------+----------------------------+-----------------+</computeroutput></screen>
</step>
<step>
<para>Enable the service:</para>
<screen><prompt>$</prompt> <userinput>nova service-enable localhost.localdomain nova-compute</userinput>
<computeroutput>+----------+--------------+---------+
| Host | Binary | Status |
+----------+--------------+---------+
| devstack | nova-compute | enabled |
+----------+--------------+---------+</computeroutput></screen>
</step>
<step>
<para>Check the service list:</para>
<screen><prompt>$</prompt> <userinput>nova service-list</userinput>
<computeroutput>+------------------+----------+----------+---------+-------+----------------------------+-----------------+
| Binary | Host | Zone | Status | State | Updated_at | Disabled Reason |
+------------------+----------+----------+---------+-------+----------------------------+-----------------+
| nova-conductor | devstack | internal | enabled | up | 2013-10-16T00:57:08.000000 | None |
| nova-cert | devstack | internal | enabled | up | 2013-10-16T00:57:09.000000 | None |
| nova-compute | devstack | nova | enabled | up | 2013-10-16T00:57:07.000000 | None |
| nova-network | devstack | internal | enabled | up | 2013-10-16T00:57:11.000000 | None |
| nova-scheduler | devstack | internal | enabled | up | 2013-10-16T00:57:14.000000 | None |
| nova-consoleauth | devstack | internal | enabled | up | 2013-10-16T00:57:07.000000 | None |
+------------------+----------+----------+---------+-------+----------------------------+-----------------+</computeroutput></screen>
</step>
</procedure>
</section>

41
doc/user-guide-admin/section_cli_nova_specify_host.xml
View File

@ -1,41 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="specify-host-to-boot-instances-on">
<title>Select hosts where instances are launched</title>
<para>With the appropriate permissions, you can select which
host instances are launched on and which roles can boot instances
on this host.</para>
<procedure>
<step>
<para>To select the host where instances are launched, use
the <literal>--availability_zone
<replaceable>zone</replaceable>:<replaceable>host</replaceable></literal>
parameter on the <command>nova boot</command> command, </para>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>nova boot --image &lt;uuid&gt; --flavor m1.tiny --key_name test --availability-zone nova:server2</userinput></screen>
</step>
<step>
<para>To specify which roles can launch an instance on a
specified host, enable the
<literal>create:forced_host</literal> option in
the <filename>policy.json</filename> file. By default,
this option is enabled for only the admin role.</para>
</step>
<step>
<para>To view the list of valid compute hosts, use the
<command>nova hypervisor-list</command> command,
as follows:</para>
<screen><prompt>$</prompt> <userinput>nova hypervisor-list</userinput>
<computeroutput>+----+---------------------+
| ID | Hypervisor hostname |
+----+---------------------+
| 1 | server2 |
| 2 | server3 |
| 3 | server4 |
+----+---------------------+</computeroutput></screen>
</step>
</procedure>
</section>

154
doc/user-guide-admin/section_cli_swift_analyze_log_files.xml
View File

@ -1,154 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="analyzing-log-files-with-swift-cli">
<title>Analyze log files</title>
<para>Use the swift command-line client to analyze log files.</para>
<para>The swift client is simple to use, scalable, and flexible.</para><para>Use the swift client <option>-o</option> or
<option>-output</option> option to get short answers to
questions about logs,</para>
<para>You can use the <parameter>-o</parameter> or <parameter>--output</parameter> option with a
single object download to redirect the command output to a
specific file or to STDOUT (<literal>-</literal>). The ability
to redirect the output to STDOUT enables you to pipe
(<literal>|</literal>) data without saving it to disk
first.</para>
<section xml:id="swift_file_analysis"><title>Upload and analyze log files</title><procedure>
<step>
<para>This example assumes that
<filename>logtest</filename> directory
contains the following log files:</para>
<example><title>Example files</title> <screen>2010-11-16-21_access.log
2010-11-16-22_access.log
2010-11-15-21_access.log
2010-11-15-22_access.log</screen></example>
<para>Each file uses the following line format:</para>
<example><title>Log line format</title><screen><computeroutput>Nov 15 21:53:52 lucid64 proxy-server - 127.0.0.1 15/Nov/2010/22/53/52 DELETE /v1/AUTH_cd4f57824deb4248a533f2c28bf156d3/2eefc05599d44df38a7f18b0b42ffedd HTTP/1.0 204 - \
- test%3Atester%2CAUTH_tkcdab3c6296e249d7b7e2454ee57266ff - - - txaba5984c-aac7-460e-b04b-afc43f0c6571 - 0.0432</computeroutput></screen></example>
</step><step>
<para>Change into the <filename class="directory"
>logtest</filename> directory:</para>
<screen><prompt>$</prompt> <userinput>cd logtest</userinput></screen></step>
<step>
<para>Upload the log files into the <filename>logtest</filename>
container:</para>
<screen><prompt>$</prompt> <userinput>swift -A http://swift-auth.com:11000/v1.0 -U test:tester -K testing upload logtest *.log</userinput></screen>
<screen><computeroutput>2010-11-16-21_access.log
2010-11-16-22_access.log
2010-11-15-21_access.log
2010-11-15-22_access.log</computeroutput></screen></step><step>
<para>Get statistics for the account:</para>
<screen><prompt>$</prompt> <userinput>swift -A http://swift-auth.com:11000/v1.0 -U test:tester -K testing -q stat</userinput></screen>
<screen><computeroutput>Account: AUTH_cd4f57824deb4248a533f2c28bf156d3
Containers: 1
Objects: 4
Bytes: 5888268</computeroutput></screen></step>
<step><para>Get statistics for the logtest container:</para>
<screen><prompt>$</prompt> <userinput>swift -A http://swift-auth.com:11000/v1.0 -U test:tester -K testing stat logtest</userinput> </screen>
<screen><computeroutput>Account: AUTH_cd4f57824deb4248a533f2c28bf156d3
Container: logtest
Objects: 4
Bytes: 5864468
Read ACL:
Write ACL:</computeroutput></screen></step>
<step><para>List all objects in the logtest container:</para>
<screen><prompt>$</prompt> <userinput>swift -A http:///swift-auth.com:11000/v1.0 -U test:tester -K testing list logtest</userinput></screen>
<screen><computeroutput>2010-11-15-21_access.log
2010-11-15-22_access.log
2010-11-16-21_access.log
2010-11-16-22_access.log</computeroutput></screen></step></procedure></section>
<section xml:id="swift_upload_files"><title>Download and analyze an object</title>
<procedure>
<para>This example uses the <option>-o</option>
option and a hyphen (<literal>-</literal>) to get
information about an object.</para>
<para>Use the swift <command>download</command> command to
download the object. On this command, stream the
output to <command>awk</command> to break down
requests by return code and the date <literal>2200 on
November 16th, 2010</literal>.</para>
<para>Using the log line format, find the request type in
column 9 and the return code in column 12.</para>
<para>After <command>awk</command> processes the output,
it pipes it to <command>sort</command> and
<command>uniq -c</command> to sum up the number of
occurrences for each request type and return code
combination.</para>
<step>
<para>Download an object:</para>
<screen><prompt>$</prompt> <userinput>swift -A http://swift-auth.com:11000/v1.0 -U test:tester -K testing \
download -o - logtest 2010-11-16-22_access.log | awk '{ print $9"-"$12}' | sort | uniq -c</userinput> </screen>
<screen><computeroutput>805 DELETE-204
12 DELETE-404
2 DELETE-409
723 GET-200
142 GET-204
74 GET-206
80 GET-304
34 GET-401
5 GET-403
18 GET-404
166 GET-412
2 GET-416
50 HEAD-200
17 HEAD-204
20 HEAD-401
8 HEAD-404
30 POST-202
25 POST-204
22 POST-400
6 POST-404
842 PUT-201
2 PUT-202
32 PUT-400
4 PUT-403
4 PUT-404
2 PUT-411
6 PUT-412
6 PUT-413
2 PUT-422
8 PUT-499</computeroutput></screen></step>
<step><para>Discover how many PUT requests are in each log file.</para>
<para>Use a bash for loop with awk and swift with
the <parameter>-o</parameter> or <parameter>--output</parameter> option and a
hyphen (<literal>-</literal>) to discover how many
PUT requests are in each log file.</para>
<para>Run the swift <command>list</command> command to
list objects in the logtest container. Then, for
each item in the list, run the swift
<command>download -o -</command> command. Pipe
the output into grep to filter the PUT requests.
Finally, pipe into <command>wc -l</command> to
count the lines.</para>
<screen><prompt>$</prompt> <userinput>for f in `swift -A http://swift-auth.com:11000/v1.0 -U test:tester -K testing list logtest` ; \
do echo -ne "PUTS - " ; swift -A http://swift-auth.com:11000/v1.0 -U test:tester -K testing download -o - logtest $f | grep PUT | wc -l ; \
done</userinput></screen>
<screen><computeroutput>2010-11-15-21_access.log - PUTS - 402
2010-11-15-22_access.log - PUTS - 1091
2010-11-16-21_access.log - PUTS - 892
2010-11-16-22_access.log - PUTS - 910</computeroutput></screen>
</step><step>
<para>List the object names that begin with a specified
string.</para>
<para>Run the swift <command>list -p 2010-11-15</command>
command to list objects in the logtest container
that begin with the <literal>2010-11-15</literal>
string.</para>
<para>For each item in the list, run the swift
<command>download -o -</command> command.</para>
<para>Pipe the output to <command>grep</command> and
<command>wc</command>. Use the
<command>echo</command> command to display the
object name.</para>
<screen><prompt>$</prompt> <userinput>for f in `swift -A http://swift-auth.com:11000/v1.0 -U test:tester -K testing list -p 2010-11-15 logtest` ; \
do echo -ne "$f - PUTS - " ; swift -A http://127.0.0.1:11000/v1.0 -U test:tester \
-K testing download -o - logtest $f | grep PUT | wc -l ; \
done</userinput></screen>
<screen><computeroutput>2010-11-15-21_access.log - PUTS - 402
2010-11-15-22_access.log - PUTS - 910</computeroutput></screen></step></procedure>
</section>
</section>

282
doc/user-guide-admin/section_dashboard_admin_manage_flavors.xml
View File

@ -1,282 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_manage_flavors">
<?dbhtml stop-chunking?>
<title>Manage flavors</title>
<para>In OpenStack, a flavor defines the compute, memory, and storage
capacity of a virtual server, also known as an instance. As an
administrative user, you can create, edit, and delete flavors..</para>
<para>The following table lists the default flavors.</para>
<informaltable rules="all" width="50%">
<col width="30%"/>
<col width="20%"/>
<col width="25%"/>
<col width="25%"/>
<thead>
<tr>
<th>Flavor</th>
<th>VCPUs</th>
<th>Disk (in GB)</th>
<th>RAM (in MB)</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>m1.tiny</para>
</td>
<td>
<para>1</para>
</td>
<td>
<para>1</para>
</td>
<td>
<para>512</para>
</td>
</tr>
<tr>
<td>
<para>m1.small</para>
</td>
<td>
<para>1</para>
</td>
<td>
<para>20</para>
</td>
<td>
<para>2048</para>
</td>
</tr>
<tr>
<td>
<para>m1.medium</para>
</td>
<td>
<para>2</para>
</td>
<td>
<para>40</para>
</td>
<td>
<para>4096</para>
</td>
</tr>
<tr>
<td>
<para>m1.large</para>
</td>
<td>
<para>4</para>
</td>
<td>
<para>80</para>
</td>
<td>
<para>8192</para>
</td>
</tr>
<tr>
<td>
<para>m1.xlarge</para>
</td>
<td>
<para>8</para>
</td>
<td>
<para>160</para>
</td>
<td>
<para>16384</para>
</td>
</tr>
</tbody>
</informaltable>
<section xml:id="dashboard_create_flavors">
<title>Create flavors</title>
<procedure>
<step>
<para>Log in to the dashboard.</para>
<para>Choose the <guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guilabel>System Panel</guilabel> and click the
<guilabel>Flavors</guilabel> category.</para>
</step>
<step>
<para>Click <guibutton>Create
Flavor</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Create Flavor</guilabel>
window, enter or select the parameters for the flavor.</para>
<informaltable rules="all" width="75%">
<col width="25%"/>
<col width="75%"/>
<thead>
<tr>
<th colspan="2" align="center">
<guilabel>Flavor Info</guilabel> tab</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para><guilabel>Name</guilabel></para>
</td>
<td>
<para>Enter the flavor name.</para>
</td>
</tr>
<tr>
<td>
<para>
<guilabel>ID</guilabel>
</para>
</td>
<td>
<para>OpenStack generates the flavor ID.</para>
</td>
</tr>
<tr>
<td>
<para><guilabel>VCPUs</guilabel></para>
</td>
<td>
<para>Enter the number of virtual CPUs
to use.</para>
</td>
</tr>
<tr>
<td>
<para><guilabel>RAM MB</guilabel></para>
</td>
<td>
<para>Enter the amount of RAM to use,
in megabytes.</para>
</td>
</tr>
<tr>
<td>
<para><guilabel>Root Disk GB</guilabel></para>
</td>
<td>
<para>Enter the mount of disk space in
gigabytes to use for the root (/)
partition.</para>
</td>
</tr>
<tr>
<td>
<para><guilabel>Ephemeral Disk GB</guilabel></para>
</td>
<td>
<para>Enter the amount of disk space
in gigabytes to use for the
ephemeral partition. If
unspecified, the value is 0 by
default.</para>
<para>Ephemeral disks offer machine
local disk storage linked to the
life cycle of a VM instance. When a
VM is terminated, all data on the
ephemeral disk is lost. Ephemeral
disks are not included in any
snapshots.</para>
</td>
</tr>
<tr>
<td>
<para><guilabel>Swap Disk MB</guilabel></para>
</td>
<td>
<para>Enter the amount of swap space
(in megabytes) to use. If
unspecified, the default is 0.
</para>
</td>
</tr>
</tbody>
</informaltable>
</step>
<step>
<para>In the <guilabel>Flavor Access</guilabel> tab, you can
control access to the flavor by moving projects from the
<guilabel>All Projects</guilabel> column to the <guilabel>Selected
Projects</guilabel> column.</para>
<para>Only projects in the <guilabel>Selected Projects</guilabel>
column can use the flavor. If there are no projects in the
right column, all projects can use the flavor.</para>
</step>
<step>
<para>Click <guibutton>Create
Flavor</guibutton>.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_update_flavors">
<title>Update flavors</title>
<procedure>
<step>
<para>Log in to the dashboard.</para>
<para>Choose the <guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guilabel>System Panel</guilabel> and click the
<guilabel>Flavors</guilabel> category.</para>
</step>
<step>
<para>Select the flavor that you want to edit. Click
<guibutton>Edit Flavor</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Edit Flavor</guilabel> window,
you can change the flavor name, VCPUs, RAM, root
disk, ephemeral disk, and swap disk
values.</para>
</step>
<step>
<para>Click <guibutton>Save</guibutton>.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_delete_flavors">
<title>Delete flavors</title>
<procedure>
<step>
<para>Log in to the dashboard.</para>
<para>Choose the <guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guilabel>System Panel</guilabel> and click the
<guilabel>Flavors</guilabel> category.</para>
</step>
<step>
<para>Select the flavors that you want to
delete.</para>
</step>
<step>
<para>Click <guibutton>Delete
Flavors</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Confirm Delete
Flavors</guilabel> window, click
<guibutton>Delete Flavors</guibutton> to
confirm the deletion. You cannot undo this
action.</para>
</step>
</procedure>
</section>
</section>

111
doc/user-guide-admin/section_dashboard_admin_manage_host_aggregates.xml
View File

@ -1,111 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_manage_host_aggregates">
<?dbhtml stop-chunking?>
<title>Create and manage host aggregates</title>
<para>Host aggregates enable administrative users to assign
key-value pairs to groups of machines.</para>
<para>Each node can have multiple aggregates and each aggregate can
have multiple key-value pairs. You can assign the same key-value
pair to multiple aggregates.</para>
<para>The scheduler uses this information to make scheduling
decisions. For information, see <link xlink:href="http://docs.openstack.org/trunk/config-reference/content/section_compute-scheduler.html"><citetitle>Scheduling</citetitle></link>.</para>
<procedure>
<title>To create a host aggregate</title>
<step>
<para>Log in to the dashboard.</para>
<para>Choose the <guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guilabel>System Panel</guilabel> and click the
<guilabel>Host Aggregates</guilabel> category.</para>
</step>
<step>
<para>Click <guibutton>Create Host Aggregate</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Create Host Aggregate</guilabel> dialog
box, enter or select the following values on the
<guilabel>Host Aggregate Info</guilabel> tab:</para>
<itemizedlist>
<listitem>
<para><guilabel>Name</guilabel>: The host aggregate
name.</para>
</listitem>
<listitem>
<para><guilabel>Availability Zone</guilabel>: The cloud
provider defines the default availability zone, such as
<literal>us-west</literal>,
<literal>apac-south</literal>, or
<literal>nova</literal>. You can target the host
aggregate, as follows:</para>
<itemizedlist>
<listitem>
<para>When the host aggregate is exposed as an
availability zone, select the availability zone when
you launch an instance.</para>
</listitem>
<listitem>
<para>When the host aggregate is not exposed as an
availability zone, select a flavor and its extra specs
to target the host aggregate.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</step>
<step>
<para>Assign hosts to the aggregate on the <guilabel>Host within
Aggregate</guilabel> tab.</para>
<para>To assign a host to the aggregate, click
<guilabel>+</guilabel> for the host. The host moves from the
<guilabel>All available hosts</guilabel> list to the
<guilabel>Selected hosts</guilabel> list.</para>
</step>
</procedure>
<para>You can add one host to one or more aggregates. To add a host
to an existing aggregate, edit the aggregate.</para>
<procedure>
<title>To manage host and aggregates</title>
<step>
<para>Choose the <guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guilabel>System Panel</guilabel> and click the <guilabel>
Host Aggregates</guilabel> category.</para>
<itemizedlist>
<listitem>
<para>To edit host aggregates, select the host aggregate that
you want to edit. Click <guibutton>Edit Host
Aggregate</guibutton>.</para>
<para>In the <guilabel>Edit Host Aggregate</guilabel> dialog
box, you can change the name and availability zone for the
aggregate.</para>
</listitem>
<listitem>
<para>To manage hosts, locate the host aggregate that you want
to edit in the table. Click <guibutton>More</guibutton>
and select <guilabel>Manage Hosts</guilabel>.</para>
<para>In the <guilabel>Add/Remove Hosts to
Aggregate</guilabel> dialog box, click
<guilabel>+</guilabel> to assign a host to the
aggregate. Click <guilabel>-</guilabel> to remove a host
that is assigned to an aggregate.</para>
</listitem>
<listitem>
<para>To delete host aggregates, locate the host aggregate that
you want to edit in the table. Click
<guibutton>More</guibutton> and select <guilabel>Delete
Host Aggregate</guilabel>.</para>
</listitem>
</itemizedlist>
</step>
</procedure>
</section>

160
doc/user-guide-admin/section_dashboard_admin_manage_images.xml
View File

@ -1,160 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_manage_images">
<?dbhtml stop-chunking?>
<title>Create and manage images</title>
<para>As an administrative user, you can create and manage images
for the projects to which you belong. You can also create and
manage images for users in all projects to which you have
access.</para>
<para>To create and manage images in specified projects as an end
user, see the <link
xlink:href="http://docs.openstack.org/user-guide/content/"
><citetitle>OpenStack End User
Guide</citetitle></link>.</para>
<para>To create and manage images as an administrator for other
users, use the following procedures.</para>
<section xml:id="dashboard_create_images">
<title>Create images</title>
<para>For details about image creation, see the <link
xlink:href="http://docs.openstack.org/image-guide/content/"
><citetitle>Virtual Machine Image
Guide</citetitle></link>.</para>
<procedure>
<step>
<para>Log in to the dashboard.</para>
<para>Choose the <guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guilabel>System Panel</guilabel> and click the
<guilabel>Images</guilabel> category. The images that you
can administer for cloud users appear on this page.</para>
</step>
<step>
<para>Click <guibutton>Create Image</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Create An Image</guilabel> window,
enter or select the following values:</para>
<informaltable rules="all" width="50%">
<col width="25%"/>
<col width="75%"/>
<tbody>
<tr>
<td><para><guilabel>Name</guilabel></para></td>
<td><para>Enter a name for the image.</para></td>
</tr>
<tr>
<td><para><guilabel>Description</guilabel></para></td>
<td><para>Enter a brief description about the
image.</para></td>
</tr>
<tr>
<td><para><guilabel>Image Source</guilabel></para></td>
<td><para>Choose the image source from the dropdown list. Your
choices are <guilabel>Image Location</guilabel> and
<guilabel>Image File</guilabel>.</para></td>
</tr>
<tr>
<td><para><guilabel>Image File</guilabel> or <guilabel>Image
Location</guilabel></para></td>
<td>
<para>Based on your selection, there is an <guilabel>Image File
</guilabel> or <guilabel>Image Location</guilabel> field. You
can include the location URL or browse for the image file on
your file system and add it.</para></td>
</tr>
<tr>
<td><para><guilabel>Format</guilabel></para></td>
<td><para>Select the image format.</para></td>
</tr>
<tr>
<td><para><guilabel>Minimum Disk (GB)</guilabel> and
<guilabel>Minimum RAM (MB)</guilabel></para></td>
<td><para>Leave these fields empty.</para>
</td>
</tr>
<tr>
<td><para><guilabel>Public</guilabel></para></td>
<td><para>Select this option to make the image public to
all users.</para></td>
</tr><tr>
<td><para><guilabel>Protected</guilabel></para></td>
<td><para>Select this option to ensure that only users with
permissions can delete it.</para></td>
</tr>
</tbody>
</informaltable>
</step>
<step>
<para>Click <guibutton>Create Image</guibutton>.</para>
<para>The image is queued to be uploaded. It might take
several minutes before the status changes from
<literal>Queued</literal> to
<literal>Active</literal>.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_update_images">
<title>Update images</title>
<procedure>
<step>
<para>Log in to the dashboard.</para>
<para>Choose the <guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guilabel>System Panel</guilabel> and click the
<guilabel>Images</guilabel> category.</para>
</step>
<step>
<para>Select the image that you want to edit. Click
<guilabel>Edit</guilabel>.</para>
</step>
<step>
<para>In the <guilabel>Update Image</guilabel> window, you can
change the image name.</para>
<para>Select the <guilabel>Public</guilabel> check box to make
the image public. Clear this check box to make the image
private. You cannot change the kernel ID, RAM disk ID, or
architecture attributes for an image.</para>
</step>
<step>
<para>Click <guibutton>Update Image</guibutton>.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_delete_images">
<title>Delete images</title>
<procedure>
<step>
<para>Log in to the dashboard.</para>
<para>Choose the <guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guilabel>System Panel</guilabel> and click the
<guilabel>Images</guilabel> category.</para>
</step>
<step>
<para>Select the images that you want to delete.</para>
</step>
<step>
<para>Click <guibutton>Delete Images</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Confirm Delete Image</guilabel> window,
click <guibutton>Delete Images</guibutton> to confirm the
deletion.</para>
<para>You cannot undo this action.</para>
</step>
</procedure>
</section>
</section>

130
doc/user-guide-admin/section_dashboard_admin_manage_instances.xml
View File

@ -1,130 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_manage_instances">
<?dbhtml stop-chunking?>
<title>Manage instances</title>
<para>As an administrative user, you can manage instances for
users in various projects. You can view, terminate, edit,
perform a soft or hard reboot, create a snapshot from, and
migrate instances. You can also view the logs for instances or
launch a VNC console for an instance.</para>
<para>For information about using the dashboard to launch
instances as an end user, see the <link
xlink:href="http://docs.openstack.org/user-guide/content/"
><citetitle>OpenStack End User
Guide</citetitle></link>.</para>
<section xml:id="dashboard_instance_snapshots">
<title>Create instance snapshots</title>
<procedure>
<step>
<para>Log in to the dashboard and choose the
<guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, click the
<guilabel>Instances</guilabel>
category.</para>
</step>
<step>
<para>Select an instance to create a snapshot from it.
From the <guilabel>Actions</guilabel> drop-down
list, select <guilabel>Create
Snapshot</guilabel>.</para>
</step>
<step>
<para>In the <guilabel>Create Snapshot</guilabel>
window, enter a name for the snapshot. Click
<guibutton>Create Snapshot</guibutton>. The
dashboard shows the instance snapshot in the
<guilabel>Images &amp; Snapshots</guilabel>
category.</para>
</step>
<step>
<para>To launch an instance from the snapshot, select
the snapshot and click
<guibutton>Launch</guibutton>. For information
about launching instances, see the <link
xlink:href="http://docs.openstack.org/user-guide/content/"
><citetitle>OpenStack End User
Guide</citetitle></link>.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_control_instance_states">
<title>Control the state of an instance</title>
<procedure>
<step>
<para>Log in to the dashboard and choose the
<guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, click the
<guilabel>Instances</guilabel>
category.</para>
</step>
<step>
<para>Select the instance for which you want to change
the state.</para>
</step>
<step>
<para>In the <guilabel>More</guilabel> drop-down list
in the <guilabel>Actions</guilabel> column, select
the state.</para>
<para>Depending on the current state of the instance,
you can choose to pause, un-pause, suspend,
resume, soft or hard reboot, or terminate an
instance (items in red are disabled).</para>
<figure>
<title>Dashboard&mdash;Instance Actions</title>
<mediaobject>
<imageobject>
<imagedata
fileref="../common/figures/change_instance_state.png"
format="PNG" contentwidth="4in"/>
</imageobject>
</mediaobject>
</figure>
</step>
</procedure>
</section>
<section xml:id="dashboard_track_usage">
<title>Track usage</title>
<para>Use the <guilabel>Overview</guilabel> category to track
usage of instances for each project.</para>
<para>You can track costs per month by showing metrics like
number of VCPUs, disks, RAM, and uptime of all your
instances.</para>
<procedure>
<step>
<para>Log in to the dashboard and choose the
<guilabel>admin</guilabel> project from the
<guilabel>CURRENT PROJECT</guilabel> drop-down
list.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, click the
<guilabel>Instances</guilabel>
category.</para>
</step>
<step>
<para>Select a month and click
<guibutton>Submit</guibutton> to query the
instance usage for that month.</para>
</step>
<step>
<para>Click <guibutton>Download CSV
Summary</guibutton> to download a CSV
summary.</para>
</step>
</procedure>
</section>
</section>

274
doc/user-guide-admin/section_dashboard_admin_manage_projects_security.xml
View File

@ -1,274 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_manage_projects_security">
<?dbhtml stop-chunking?>
<title>Manage project security</title>
<para>Security groups are sets of IP filter rules that define networking
access and are applied to all instances within a project. Group rules
are project-specific; project members can edit the default rules for
their group and add new rule sets.</para>
<para>All projects have a default security group that is applied to any
instance that has no other defined security group. When unmodified, the
default security group denies all incoming traffic and allows only
outgoing traffic to your instance. A common use case is to edit the
default security group to permit SSH access and ICMP access, so that
users can log into and ping instances.</para>
<note>
<para>For information about updating global controls on the
command line, see <xref
linkend="nova_cli_manage_projects_security"/>.</para>
</note>
<section xml:id="create_security_group">
<title>Create a security group</title>
<procedure>
<step>
<para>Log in to the dashboard as a project member.</para>
</step>
<step>
<para>Select a project from the drop-down menu at the top of the screen.</para>
</step>
<step>
<para>On the <guilabel>Project</guilabel> tab, click the
<guimenuitem>Access &amp; Security</guimenuitem>
category.</para>
</step>
<step>
<para>On the <guilabel>Security Groups</guilabel> tab,
click <guibutton>Create Security
Group</guibutton>.</para>
</step>
<step>
<para>Provide a name and appropriate description for
the group, and click <guibutton>Create Security
Group</guibutton>. By default, the new rule
provides outgoing access rules for the
group.</para>
</step>
</procedure>
</section>
<section xml:id="add_security_group_rules">
<title>Add a security group rule</title>
<procedure>
<step>
<para>Log in to the dashboard as a project member.</para>
</step>
<step>
<para>Select a project from the drop-down menu at the top of the
screen.</para>
</step>
<step>
<para>On the <guilabel>Project</guilabel> tab, click the
<guimenuitem>Access &amp; Security</guimenuitem>
category.</para>
</step>
<step>
<para>On the <guilabel>Security Groups</guilabel> tab, click
<guibutton>Manage rules</guibutton> for the appropriate
security group.</para>
</step>
<step>
<para>To add a rule, click <guibutton>Add Rule</guibutton>. Set
the attributes for the rule, and click
<guibutton>Add</guibutton>.</para>
<para>The following attributes can be configured:</para>
<variablelist wordsize="10">
<varlistentry>
<term>Rule</term>
<listitem>
<para>The rule protocol type. Valid types are:<itemizedlist>
<listitem>
<para><guilabel>Custom TCP
Rule</guilabel>.Typically used to
exchange data between systems, and for
end-user communication.</para>
</listitem>
<listitem>
<para><guilabel>Custom UDP
Rule</guilabel>. Typically used to
exchange data between systems,
particularly at the application
level.</para>
</listitem>
<listitem>
<para><guilabel>Custom ICMP
Rule</guilabel>. Typically used by
network devices (for example, routers)
to send error or monitoring
messages.</para>
</listitem>
<listitem>
<para><guilabel>Other
Protocol</guilabel>: Enables you to
manually specify another rule protocol,
if it is not included in the
list.</para>
</listitem>
<listitem>
<para>Other standard IP protocols,
including: All ICMP, All TCP, All UDP,
DNS, HTTP, HTTPS, IMAP, IMAPS, LDAP, MS
SQL, MYSQL, POP3, POP3S, RDP, SMTP,
SMTPS, and SSH.</para>
</listitem>
</itemizedlist></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Direction</term>
<listitem>
<para>The direction of network traffic to which the
rule applies: <guilabel>Ingress</guilabel>
(inbound) or <guilabel>Egress</guilabel>
(outbound). This option is available only when
<guilabel>Custom TCP Rule</guilabel>,
<guilabel>Custom UDP Rule</guilabel>,
<guilabel>Custom ICMP Rule</guilabel>,
<guilabel>All ICMP</guilabel>, <guilabel>All
TCP</guilabel>, <guilabel>All
UDP</guilabel>, or <guilabel>Other
Protocol</guilabel> is selected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Open Port</term>
<listitem>
<para>The <guilabel>Port</guilabel> or
<guilabel>Port Range</guilabel> to open for
the rule. This option is available only when
<guilabel>Custom TCP Rule</guilabel> or
<guilabel>Custom UDP Rule</guilabel> is
selected.</para>
<itemizedlist>
<listitem>
<para>For a range of ports, enter port
values in the <guilabel>From
Port</guilabel> and <guilabel>To
Port</guilabel> fields.</para>
</listitem>
<listitem>
<para>For a single port, enter the port
value in the <guilabel>Port</guilabel>
field.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Type</term>
<listitem>
<para>Specifies the ICMP message that is being
passed. This option is available only when
<guilabel>Custom ICMP Rule</guilabel> is
selected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Code</term>
<listitem>
<para>For ICMP rules, specifies the ICMP subtype
code, which provides further information about
the <guilabel>Type</guilabel> message. This
option is available only when <guilabel>Custom
ICMP Rule</guilabel> is selected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>IP Protocol</term>
<listitem>
<para>For <guilabel>Other Protocol</guilabel> rules,
specifies the IP protocol to be used for the
rule. Specify the protocol as an integer. See
<link
xlink:href="http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml"
>http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml</link>.
This option is available only when
<guilabel>Other Protocol</guilabel> is
selected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Remote</term>
<listitem>
<para>The source of the traffic
for this rule:</para>
<itemizedlist>
<listitem>
<para><guilabel>CIDR</guilabel> (Classless
Inter-Domain Routing). When selected,
access is limited only to IP addresses
within the specified block. When
selected, enter the CIDR in the
<guilabel>CIDR</guilabel> field.</para>
</listitem>
<listitem>
<para><guilabel>Security Group</guilabel>.
When selected, any instance in the
selected security group can access any
other group instance. When selected,
choose the <guilabel>Security
Group</guilabel> and the <guilabel>Ether
Type</guilabel>, which can be either
<guilabel>IPv4</guilabel> or
<guilabel>IPv6</guilabel>.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</step>
</procedure>
</section>
<section xml:id="delete_security_group_rule">
<title>Delete a security group rule</title>
<procedure>
<step>
<para>Log in to the dashboard as a project member.</para>
</step>
<step>
<para>Select a project from the drop-down menu at the top of the
screen.</para>
</step>
<step>
<para>On the <guilabel>Project</guilabel> tab, click the
<guimenuitem>Access &amp; Security</guimenuitem>
category.</para>
</step>
<step>
<para>On the <guilabel>Security Groups</guilabel> tab, click
<guibutton>Manage rules</guibutton> for the appropriate
security group.</para>
</step>
<step>
<para>To delete a rule, select the rule and click
<guibutton>Delete Rule</guibutton> and confirm that you
want to delete the rule.</para>
</step>
</procedure>
</section>
<section xml:id="delete_security_group">
<title>Delete a security group</title>
<procedure>
<step>
<para>Log in to the dashboard as a project member.</para>
</step>
<step>
<para>Select a project from the drop-down menu at the top of the
screen.</para>
</step>
<step>
<para>On the <guilabel>Project</guilabel> tab, click the
<guimenuitem>Access &amp; Security</guimenuitem>
category.</para>
</step>
<step>
<para>On the <guilabel>Security Groups</guilabel> tab, select
the appropriate group, and click <guibutton>Delete Security
Group</guibutton> and confirm that you want to delete
the group.</para>
</step>
</procedure>
</section>
</section>

316
doc/user-guide-admin/section_dashboard_admin_manage_projects_users.xml
View File

@ -1,316 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_manage_projects_users">
<?dbhtml stop-chunking?>
<title>Manage projects and users</title>
<para>As an OpenStack cloud administrator, you manage both
projects and users, which can be managed independently from
each other. Projects, also known as <emphasis role="italic"
>tenants</emphasis> or <emphasis role="italic"
>accounts</emphasis>, are organizational units in the
cloud to which you can assign users. Users also have roles
that determine their level of access to the project, and may
have different roles in different projects.</para>
<para>When the cloud is initially created, the operator defines at
least one project, user, and role.</para>
<para>As an administrator, you can create additional projects and users as
needed. This section documents the following project and user
administration tasks:</para>
<itemizedlist>
<listitem>
<para>Adding, updating, and deleting projects and
users.</para>
</listitem>
<listitem>
<para>Assigning users to one or more projects, and changing or
removing the assignment.</para>
</listitem>
<listitem>
<para>Enabling or temporarily disabling a project or
user.</para>
</listitem>
</itemizedlist>
<para>You can also change quotas at the project level. For information, see
<xref linkend="dashboard_set_quotas"/>.</para>
<section xml:id="dashboard_create_project">
<title>Create a project</title>
<procedure>
<step>
<para>Log in to the dashboard and choose the
<guilabel>admin</guilabel> project from the
<guilabel>CURRENT PROJECT</guilabel> drop-down
list at the top of the screen.</para>
</step>
<step>
<para>In the <guilabel>Admin</guilabel> tab, open the
<guilabel>Identity Panel</guilabel> and click
on <guilabel>Projects</guilabel>.</para>
</step>
<step>
<para>Click <guibutton>Create
Project</guibutton>.</para>
</step>
<step>
<para>On the <guilabel>Project Info</guilabel> tab in
the <guilabel>Create Project</guilabel> window,
enter a name and description for the project. By
default, the project is enabled. See <xref
linkend="disable_project"/>.</para>
</step>
<step>
<para>On the <guilabel>Project Members</guilabel> tab,
add members to the project.</para>
</step>
<step>
<para>On the <guilabel>Quota</guilabel> tab, edit
quota values. For information about quotas, see
<xref linkend="dashboard_set_quotas"/>.</para>
</step>
<step>
<para>Click <guibutton>Create
Project</guibutton>.</para>
<para>The <guilabel>Projects</guilabel> list shows the
project, including its assigned ID.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_update_project">
<title>Update a project</title>
<para>You can update a project to change its name or
description, and enable or temporarily disable it.</para>
<procedure>
<step>
<para>In the <guilabel>Admin</guilabel> tab, open the
<guilabel>Identity Panel</guilabel> and click
on <guilabel>Projects</guilabel>.</para>
</step>
<step>
<para>Select the project that you want to update.</para>
</step>
<step>
<para>In the <guilabel>More</guilabel> drop-down list,
click <guilabel>Edit Project</guilabel>.</para>
</step>
<step>
<para>In the <guilabel>Edit Project</guilabel> window,
you can update a project to change its name or
description, and enable or temporarily disable
it.</para>
<para>By default, the project is enabled. To
temporarily disable it, clear the
<guilabel>Enabled</guilabel> check box. To
enable a disabled project, select the
<guilabel>Enabled</guilabel> check box.</para>
</step>
<step>
<para>Click <guibutton>Save</guibutton>.</para>
</step>
</procedure>
<section xml:id="disable_project">
<title>Consequences of disabling projects</title>
<para>When you disable a project, it has the following
consequences:</para>
<itemizedlist>
<listitem>
<para>In the dashboard, users can no longer access the
project from the <guilabel>CURRENT
PROJECT</guilabel> drop-down list on the
<guilabel>Project</guilabel> tab.</para>
</listitem>
<listitem>
<para>Users who are members of only the disabled
project can no longer log in.</para>
</listitem>
<listitem>
<para>You cannot launch instances for a disabled
project. Instances that are already running are
not automatically terminated though&mdash;you must stop
them manually.</para>
</listitem>
<listitem>
<para>The data for a disabled project is maintained so
that you can enable the project again at any
time.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="dashboard_user_assignments">
<title>Modify user assignments for a project</title>
<para>When you create users, you must assign them to a primary
project as described in <xref
linkend="dashboard_create_user"/>. You can assign
users to additional projects or update and remove
assignments.</para>
<procedure>
<step>
<para>In the <guilabel>Admin</guilabel> tab, open the
<guilabel>Identity Panel</guilabel> and click
on <guilabel>Projects</guilabel>.</para>
</step>
<step>
<para>Click the <guilabel>Modify Users</guilabel>
button for the project that you want to
modify.</para>
<para>The <guilabel>Edit Project</guilabel> window
shows the following lists of users:</para>
<itemizedlist>
<listitem>
<para><guilabel>All Users</guilabel>. Users
that are available to be assigned to the
current project.</para>
</listitem>
<listitem>
<para><guilabel>Project Members</guilabel>.
Users that are assigned to the current
project.</para>
</listitem>
</itemizedlist>
<figure xml:id="cloud_dash_users_list">
<title>Edit the users list</title>
<mediaobject>
<imageobject>
<imagedata
fileref="figures/cloud_dash_users_list.png"
format="PNG" contentwidth="6in" width="6in"
/>
</imageobject>
</mediaobject>
</figure>
</step>
<step>
<para>To assign a user to the current project, click
<guibutton>+</guibutton> for the user.</para>
<para>The user moves from the <guilabel>All
Users</guilabel> list to the <guilabel>Project
Members</guilabel> list.</para>
</step>
<step>
<para>To remove a user from the current project, click
the <guibutton>-</guibutton> button for the
user.</para>
<para>The user moves from the <guilabel>Project
Members</guilabel> list to the <guilabel>All
Users</guilabel> list.</para>
</step>
<step>
<para>Click <guibutton>Save</guibutton>.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_delete_project">
<title>Delete projects</title>
<procedure>
<step>
<para>On the <guilabel>Admin</guilabel> tab, click the
<guilabel>Projects</guilabel> category.</para>
</step>
<step>
<para>Select the projects that you want to delete.</para>
</step>
<step>
<para>Click <guibutton>Delete Projects</guibutton> to
confirm the deletion.</para>
<warning>
<para>You cannot undo the delete action.</para>
</warning>
</step>
</procedure>
</section>
<section xml:id="dashboard_create_user">
<title>Create a user account</title>
<para>When you create a user account, you must assign the account to a
primary project. You also have the option of assigning the account
to additional projects. Before you can delete a user account, you
must remove the user account from its primary project.</para>
<procedure>
<step>
<para>Log in to the dashboard and choose the
<guilabel>admin</guilabel> project from the
<guilabel>CURRENT PROJECT</guilabel> drop-down
list at the top of the screen.</para>
</step>
<step>
<para>In the <guilabel>Admin</guilabel> tab, open the
<guilabel>Identity Panel</guilabel> and click
on <guilabel>Users</guilabel>.</para>
</step>
<step>
<para>Click <guibutton>Create User</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Create User</guilabel> window,
enter a user name, email, and preliminary password
for the user. Confirm the password.</para>
<para>Select a project from the <guilabel>Primary
Project</guilabel> drop-down list.</para>
<para>Choose a role for the user from the
<guilabel>Role</guilabel> drop-down list.
Default is <literal>Member</literal>.</para>
</step>
<step>
<para>Click <guibutton>Create User</guibutton> to
confirm your changes.</para>
<para>Respond to the prompt to remember the password
for the user.</para>
<para>The dashboard assigns an ID to the user, and the
user appears in the <guilabel>Users</guilabel>
category.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_disable_user">
<title>Disable or enable a user</title>
<para>When you disable a user account, the user can no longer log in.
However, the data for the user is maintained so that you can enable
the user again at any time.</para>
<procedure>
<step>
<para>In the <guilabel>Admin</guilabel> tab, open the
<guilabel>Identity Panel</guilabel> and click
on <guilabel>Users</guilabel>.</para>
</step>
<step>
<para>Locate the user that you want to disable or
enable in the Users list.</para>
</step>
<step>
<para>In the <guilabel>More</guilabel> drop-down list,
select <guilabel>Disable User</guilabel> or
<guilabel>Enable User</guilabel>.</para>
<para>In the <guilabel>Enabled</guilabel> column, the
enabled value updates to either
<literal>True</literal> or
<literal>False</literal>.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_delete_user">
<title>Delete users</title>
<procedure>
<step>
<para>On the <guilabel>Admin</guilabel> tab, select
the <guilabel>Users</guilabel> category.</para>
</step>
<step>
<para>Select the users that you want to delete.</para>
</step>
<step>
<para>Click <guilabel>Delete Users</guilabel>.</para>
</step>
<step>
<para>In the <guilabel>Confirm Delete Users</guilabel>
window, click <guibutton>Delete Users</guibutton>
to confirm the deletion.</para>
</step>
</procedure>
</section>
<xi:include href="section_dashboard_admin_manage_projects_security.xml"/>
</section>

10
doc/user-guide-admin/section_dashboard_admin_manage_resources.xml
View File

@ -1,10 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="section_dashboard_admin_manage_resources">
<title>View cloud resources</title>
<xi:include href="section_dashboard_admin_manage_services.xml"/>
<xi:include href="section_dashboard_admin_view_cloud_resources.xml"/>
</section>

93
doc/user-guide-admin/section_dashboard_admin_manage_roles.xml
View File

@ -1,93 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="section_dashboard_admin_manage_roles">
<?dbhtml stop-chunking?>
<title>Create and manage roles</title>
<para>A role is a personality that a user assumes to perform a specific set
of operations. A role includes a set of rights and privileges. A user
assuming that role inherits those rights and privileges.</para>
<note>
<para>OpenStack Identity service defines a user's role on a project but it
is completely up to the individual service to define what that role means.
This is referred to as the service's policy. To get details about what the
privileges for each role are, refer to the <filename>policy.json</filename>
file available for each service in the
<filename>/etc/<replaceable>SERVICE</replaceable>/policy.json</filename>
file. For example, the policy defined for OpenStack Identity service is
defined in the <filename>/etc/keystone/policy.json</filename> file.
</para>
</note>
<section xml:id="create_role">
<title>Create a role</title>
<procedure>
<step>
<para>Log in to the dashboard and choose the <guilabel>admin</guilabel>
project from the <guilabel>CURRENT PROJECT</guilabel> drop-down list.
</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, click the <guilabel>Roles
</guilabel> category.
</para>
</step>
<step>
<para>Click the <guibutton>Create Role</guibutton> button.</para>
<para>In the <guilabel>Create Role</guilabel> window, enter a
name for the role.</para>
</step>
<step>
<para>Click the <guibutton>Create Role</guibutton> button to confirm
your changes.</para>
</step>
</procedure>
</section>
<section xml:id="edit_role">
<title>Edit a role</title>
<procedure>
<step>
<para>Log in to the dashboard and choose the <guilabel>admin</guilabel>
project from the <guilabel>CURRENT PROJECT</guilabel> drop-down list.
</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, click the <guilabel>Roles
</guilabel> category.
</para>
</step>
<step>
<para>Click the <guibutton>Edit</guibutton> button.</para>
<para>In the <guilabel>Update Role</guilabel> window, enter a new
name for the role.</para>
</step>
<step>
<para>Click the <guibutton>Update Role</guibutton> button to confirm
your changes.
</para>
</step>
</procedure>
<note>
<para>Using the dashboard, you can edit only the name assigned to a role.</para>
</note>
</section>
<section xml:id="delete_role">
<title>Delete a role</title>
<procedure>
<step>
<para>Log in to the dashboard and choose the <guilabel>admin</guilabel>
project from the <guilabel>CURRENT PROJECT</guilabel> drop-down list.
</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, click the <guilabel>Roles
</guilabel> category.</para>
</step>
<step>
<para>Select the role you want to delete and click the <guibutton>Delete
Roles</guibutton> button.</para>
</step>
</procedure>
</section>
</section>

56
doc/user-guide-admin/section_dashboard_admin_manage_services.xml
View File

@ -1,56 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_view_services">
<title>View services information</title>
<para>As an administrative user, you can view information for
OpenStack services.</para>
<procedure>
<step>
<para>Log in to the OpenStack dashboard and choose the
<guilabel>admin</guilabel> project from the drop-down list
at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, click the
<guilabel>System Info</guilabel> category.</para>
<para>View the following information on these tabs:<itemizedlist>
<listitem>
<para><guilabel>Services</guilabel>: Displays the internal
name and the public OpenStack name for each service, the
host on which the service runs, and whether or not the
service is enabled.</para>
</listitem>
<listitem>
<para><guilabel>Compute Services</guilabel>: Displays
information specific to the Compute Service. Both host
and zone are listed for each service, as well as its
activation status.</para>
</listitem>
<listitem>
<para><guilabel>Network Agents</guilabel>: Displays the
network agents active within the cluster, such as L3 and
DHCP agents, and the status of each agent.</para>
</listitem>
<listitem>
<para><guilabel>Default Quotas</guilabel>: Displays the
quotas that have been configured for the cluster.</para>
</listitem>
<listitem>
<para><guilabel>Availability Zones</guilabel>: Displays
the availability zones that have been configured for the
cluster. It is only available when multiple availability
zones have been defined.</para>
</listitem>
<listitem>
<para><guilabel>Host Aggregates</guilabel>: Displays the
host aggregates that have been defined for the cluster.
It is only available when multiple host aggregates have
been defined.</para>
</listitem>
</itemizedlist></para>
</step>
</procedure>
</section>

31
doc/user-guide-admin/section_dashboard_admin_manage_stacks.xml
View File

@ -1,31 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="section_dashboard_admin_manage_stacks">
<title>Launch and manage stacks</title>
<para>The Orchestration service provides a template-based orchestration engine
for the OpenStack cloud, which can be used to create and manage cloud
infrastructure resources such as storage, networking, instances, and
applications as a repeatable running environment.
</para>
<para>Templates are used to create stacks, which are collections of resources. For example,
a stack might include instances, floating IPs, volumes, security groups, or users.
The Orchestration service offers access to all OpenStack core services via a single modular template,
with additional orchestration capabilities such as auto-scaling and basic high availability.</para>
<para>For information about:</para>
<para>
<itemizedlist>
<listitem>
<para>Administrative tasks on the command line, see <xref linkend="section_cli_admin_manage_stacks"/>.
<note><para>There are no administration-specific tasks that can be done through the dashboard.</para></note></para>
</listitem>
<listitem>
<para>The basic creation and deletion of Orchestration stacks, refer to the <link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_stacks.html"
>End User Guide</link>.</para>
</listitem>
</itemizedlist>
</para>
</section>

114
doc/user-guide-admin/section_dashboard_admin_manage_volumes.xml
View File

@ -1,114 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_manage_volumes">
<?dbhtml stop-chunking?>
<title>Manage volumes and volume types</title>
<para>Volumes are the Block Storage devices that you attach to
instances to enable persistent storage. Users can attach a
volume to a running instance or detach a volume and attach it
to another instance at any time. For information about using
the dashboard to create and manage volumes as an end user, see
the <link
xlink:href="http://docs.openstack.org/user-guide/content/"
><citetitle>OpenStack End User
Guide</citetitle></link>.</para>
<para>As an administrative user, you can manage volumes and volume types for users in various
projects. You can create and delete volume types, and you can view and delete
volumes.</para>
<section xml:id="dashboard_create_volume_types">
<title>Create a volume type</title>
<procedure>
<step>
<para>Log in to the dashboard and choose the
<guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guibutton>System Panel</guibutton> and click
the <guilabel>Volumes</guilabel> category.</para>
</step>
<step>
<para>Click <guibutton>Create Volume
Type</guibutton>.</para>
<para>In the <guilabel>Create Volume Type</guilabel>
window, enter a name for the volume type.</para>
</step>
<step>
<para>Click <guibutton>Create Volume Type</guibutton>
to confirm your changes.</para>
<para>A message indicates whether the action
succeeded.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_delete_volume_types">
<title>Delete volume types</title>
<para>When you delete a volume type, volumes of that type are
not deleted.</para>
<procedure>
<step>
<para>Log in to the dashboard and choose the
<guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guibutton>System Panel</guibutton> and click
the <guilabel>Volumes</guilabel> category.</para>
</step>
<step>
<para>Select the volume type or types that you want to
delete.</para>
</step>
<step>
<para>Click <guibutton>Delete Volume
Types</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Confirm Delete Volume
Types</guilabel> window, click
<guibutton>Delete Volume Types</guibutton> to
confirm the action.</para>
<para>A message indicates whether the action
succeeded.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_delete_volume">
<title>Delete volumes</title>
<para>When you delete an instance, the data of its attached
volumes is not destroyed.</para>
<procedure>
<step>
<para>Log in to the dashboard and choose the
<guilabel>admin</guilabel> project from the
drop-down list at the top of the page.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, open the
<guibutton>System Panel</guibutton> and click
the <guilabel>Volumes</guilabel> category.</para>
</step>
<step>
<para>Select the volume or volumes that you want to
delete.</para>
</step>
<step>
<para>Click <guibutton>Delete
Volumes</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Confirm Delete
Volumes</guilabel> window, click
<guibutton>Delete Volumes</guibutton> to
confirm the action.</para>
<para>A message indicates whether the action
succeeded.</para>
</step>
</procedure>
</section>
</section>

198
doc/user-guide-admin/section_dashboard_admin_set_quotas.xml
View File

@ -1,198 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_set_quotas">
<?dbhtml stop-chunking?>
<title>View and manage quotas</title>
<para>To prevent system capacities from being exhausted without notification,
you can set up quotas. Quotas are operational limits. For example, the
number of gigabytes allowed for each tenant can be controlled so that
cloud resources are optimized. Quotas can be enforced at both the tenant
(or project) and the tenant-user level.</para>
<para>Typically, you change quotas when a project needs more than ten
volumes or 1&nbsp;TB on a compute node.</para>
<para>Using the Dashboard, you can view default Compute and Block Storage
quotas for new tenants, as well as update quotas for existing tenants.</para>
<note>
<para>Using the command-line interface, you can manage quotas for the
OpenStack Compute service, the OpenStack Block Storage service, and
the OpenStack Networking service (see <xref linkend="cli_set_quotas"/>).
Additionally, you can update Compute service quotas for
tenant users.</para>
</note>
<para>The following table describes the Compute and Block Storage
service quotas:</para>
<table rules="all" width="50%" xml:id="compute_quotas">
<caption>Quota Descriptions</caption>
<col width="30%"/>
<col width="50%"/>
<col width="20%"/>
<thead>
<tr>
<th>Quota Name</th>
<th>Defines the number of</th>
<th>Service</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>Gigabytes</para>
</td>
<td>
<para>Volume gigabytes allowed for each project.</para>
</td>
<td>Block Storage</td>
</tr>
<tr>
<td>
<para>Instances</para>
</td>
<td>
<para>Instances allowed for each project.</para>
</td>
<td>Compute</td>
</tr>
<tr>
<td>
<para>Injected Files</para>
</td>
<td>
<para>Injected files allowed for each project.</para>
</td>
<td>Compute</td>
</tr>
<tr>
<td>
<para>Injected File Content Bytes</para>
</td>
<td>
<para>Content bytes allowed for each injected file.</para>
</td>
<td>Compute</td>
</tr>
<tr>
<td>
<para>Keypairs</para>
</td>
<td>
<para>Number of keypairs.</para>
</td>
<td>Compute</td>
</tr>
<tr>
<td>
<para>Metadata Items</para>
</td>
<td>
<para>Metadata items allowed for each instance.</para>
</td>
<td>Compute</td>
</tr>
<tr>
<td>
<para>RAM (MB)</para>
</td>
<td>
<para>RAM megabytes allowed for each instance.</para>
</td>
<td>Compute</td>
</tr>
<tr>
<td>
<para>Security Groups</para>
</td>
<td>
<para>Security groups allowed for each project.</para>
</td>
<td>Compute</td>
</tr>
<tr>
<td>
<para>Security Group Rules</para>
</td>
<td>
<para>Rules allowed for each security group.</para>
</td>
<td>Compute</td>
</tr>
<tr>
<td>
<para>Snapshots</para>
</td>
<td>
<para>Volume snapshots allowed for each project.</para>
</td>
<td>Block Storage</td>
</tr>
<tr>
<td>
<para>VCPUs</para>
</td>
<td>
<para>Instance cores allowed for each project.</para>
</td>
<td>Compute</td>
</tr>
<tr>
<td>
<para>Volumes</para>
</td>
<td>
<para>Volumes allowed for each project.</para>
</td>
<td>Block Storage</td>
</tr>
</tbody>
</table>
<section xml:id="dashboard_view_quotas_procedure">
<title>View default project quotas</title>
<procedure>
<step>
<para>Log in to the OpenStack dashboard.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, click the
<guilabel>Defaults</guilabel> category.</para>
</step>
<step>
<para>The default quota values are displayed.</para>
</step>
</procedure>
<note>
<para>You can sort the table by clicking on either the <guilabel>Quota Name</guilabel> or <guilabel>Limit</guilabel> column headers.</para>
</note>
</section>
<section xml:id="dashboard_update_project_quotas">
<title>Update project quotas</title>
<procedure>
<step>
<para>Log in to the OpenStack dashboard.</para>
</step>
<step>
<para>On the <guilabel>Admin</guilabel> tab, click the
<guilabel>Defaults</guilabel> category.</para>
</step>
<step>
<para>Click the <guibutton>Update Defaults</guibutton> button.</para>
</step>
<step>
<para>In the <guilabel>Update Default Quotas</guilabel> window, you can edit the default quota values.</para>
</step>
<step>
<para>Click the <guibutton>Update Defaults</guibutton> button.</para>
</step>
</procedure>
<note>
<para>The dashboard does not show all possible project quotas.
To view and update the quotas for a service, use its
command-line client. See <xref linkend="cli_set_quotas"/>.</para>
</note>
</section>
</section>

48
doc/user-guide-admin/section_dashboard_admin_view_cloud_resources.xml
View File

@ -1,48 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="section_ceilometer_dashboard">
<title>View cloud usage statistics</title>
<para>The Telemetry module provides user-level usage data for OpenStack-based clouds,
which can be used for customer billing, system monitoring, or alerts. Data can be
collected by notifications sent by existing OpenStack components (for example,
usage events emitted from Compute) or by polling the infrastructure (for example,
libvirt).
</para>
<note><para>You can only view metering statistics on the dashboard (available only to administrators). The Telemetry service
must be set up and administered through the <command>ceilometer</command> command-line
interface (CLI).
</para>
<para>For basic administration information, refer to the "Measure Cloud Resources" chapter in the
<citetitle>OpenStack End User Guide</citetitle>.</para></note>
<section xml:id="dashboard_view_resource_stats">
<title>View resource statistics</title>
<procedure>
<step>
<para>Log in to the OpenStack dashboard as a user with Admin privileges.</para>
</step>
<step><para>On the <guilabel>Admin</guilabel> tab, click the
<guilabel>Resource Usage</guilabel> category.</para>
</step>
<step>
<para>Click the:
<itemizedlist>
<listitem><para><guilabel>Global Disk Usage</guilabel> tab to view disk usage per tenant (project).</para></listitem>
<listitem><para><guilabel>Global Network Traffic Usage</guilabel> tab to view ingress or egress usage per tenant
(project).</para></listitem>
<listitem><para><guilabel>Global Object Storage Usage</guilabel> tab to view incoming and outgoing storage bytes per tenant (project).</para></listitem>
<listitem><para><guilabel>Global Network Usage</guilabel> tab to view duration and creation requests for
networks, subnets, routers, ports, and floating IPs, per tenant
(project).</para></listitem>
<listitem><para><guilabel>Stats</guilabel> tab to view a multi-series line chart with user-defined metrics.
You group by project, define the value type (min, max, avg, or sum),
and specify the time period (or even use a calendar to define a date
range).</para></listitem>
</itemizedlist>
</para>
</step>
</procedure>
</section>
</section>

515
doc/user-guide/app_cheat_sheet.xml
View File

@ -1,515 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="app_cheat_sheet">
<?dbhtml stop-chunking?>
<title>OpenStack command-line interface cheat sheet</title>
<para>
The following tables give a quick reference of the most used
command-line commands.
</para>
<table rules="all" width="100%">
<caption>Identity (keystone)</caption>
<col width="30%"/>
<col width="70%"/>
<thead>
<tr>
<th>Description</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>List all users</td>
<td>
<screen><prompt>$</prompt> <userinput>keystone user-list</userinput></screen>
</td>
</tr>
<tr>
<td>List Identity service catalog</td>
<td>
<screen><prompt>$</prompt> <userinput>keystone catalog</userinput></screen>
</td>
</tr>
<tr>
<td>List all services in service catalog</td>
<td>
<screen><prompt>$</prompt> <userinput>keystone service-list</userinput></screen>
</td>
</tr>
<tr>
<td>Create new user</td>
<td>
<screen><prompt>$</prompt> <userinput>keystone user-create --name <replaceable>NAME</replaceable> --tenant-id <replaceable>TENANT</replaceable> \
--pass <replaceable>PASSWORD</replaceable> --email <replaceable>EMAIL</replaceable> --enabled <replaceable>BOOL</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Create new tenant</td>
<td>
<screen><prompt>$</prompt> <userinput>keystone tenant-create --name <replaceable>NAME</replaceable> --description "<replaceable>DESCRIPTION</replaceable>" \
--enabled BOOL</userinput></screen>
</td>
</tr>
</tbody>
</table>
<table rules="all" width="100%">
<caption>Image service (glance)</caption>
<col width="30%"/>
<col width="70%"/>
<thead>
<tr>
<th>Description</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>List images you can access</td>
<td>
<screen><prompt>$</prompt> <userinput>glance image-list</userinput></screen>
</td>
</tr>
<tr>
<td>Delete specified image</td>
<td>
<screen><prompt>$</prompt> <userinput>glance image-delete <replaceable>IMAGE</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Describe a specific image</td>
<td>
<screen><prompt>$</prompt> <userinput>glance image-show <replaceable>IMAGE</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Update image</td>
<td>
<screen><prompt>$</prompt> <userinput>glance image-update <replaceable>IMAGE</replaceable></userinput></screen>
</td>
</tr>
<tr>
<th colspan="2">Manage images</th>
</tr>
<tr>
<td>Kernel image</td>
<td>
<screen><prompt>$</prompt> <userinput>glance image-create --name "cirros-threepart-kernel" \
--disk-format aki --container-format aki --is-public False \
--file ~/images/cirros-0.3.1~pre4-x86_64-vmlinuz</userinput></screen>
</td>
</tr>
<tr>
<td>RAM image</td>
<td>
<screen><prompt>$</prompt> <userinput>glance image-create --name "cirros-threepart-ramdisk" \
--disk-format ari --container-format ari --is-public False \
--file ~/images/cirros-0.3.1~pre4-x86_64-initrd</userinput></screen>
</td>
</tr>
<tr>
<td>Three-part image</td>
<td>
<screen><prompt>$</prompt> <userinput>glance image-create --name "cirros-threepart" --disk-format ami \
--container-format ami --is-public False \
--property kernel_id=$KID-property ramdisk_id=$RID \
--file ~/images/cirros-0.3.1~pre4-x86_64-blank.img</userinput></screen>
</td>
</tr>
<tr>
<td>Register raw image</td>
<td>
<screen><prompt>$</prompt> <userinput>glance image-create --name "cirros-qcow2" --disk-format qcow2 \
--container-format bare --is-public False \
--file ~/images/cirros-0.3.1~pre4-x86_64-disk.img</userinput></screen>
</td>
</tr>
</tbody>
</table>
<table rules="all" width="100%">
<caption>Compute (nova)</caption>
<col width="30%"/>
<col width="70%"/>
<thead>
<tr>
<th>Description</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>List instances, notice status of instance</td>
<td>
<screen><prompt>$</prompt> <userinput>nova list</userinput></screen>
</td>
</tr>
<tr>
<td>List images</td>
<td>
<screen><prompt>$</prompt> <userinput>nova image-list</userinput></screen>
</td>
</tr>
<tr>
<td>List flavors</td>
<td>
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput></screen>
</td>
</tr>
<tr>
<td>Boot an instance using flavor and image names (if names are unique)</td>
<td>
<screen><prompt>$</prompt> <userinput>nova boot --image <replaceable>IMAGE</replaceable> --flavor <replaceable>FLAVOR</replaceable> <replaceable>INSTANCE_NAME</replaceable></userinput>
<prompt>$</prompt> <userinput>nova boot --image cirros-0.3.1-x86_64-uec --flavor m1.tiny \
MyFirstInstance</userinput></screen>
</td>
</tr>
<tr>
<td>Login to instance</td>
<td>
<screen><prompt>#</prompt> <userinput>ip netns</userinput>
<prompt>#</prompt> <userinput>ip netns exec <replaceable>NETNS_NAME</replaceable> ssh <replaceable>USER</replaceable>@<replaceable>SERVER</replaceable></userinput>
<prompt>#</prompt> <userinput>ip netns exec qdhcp-6021a3b4-8587-4f9c-8064-0103885dfba2 \
ssh cirros@10.0.0.2</userinput></screen>
<para>Note, in CirrOS the password for user
<literal>cirros</literal> is "cubswin:)" without the
quotes.</para>
</td>
</tr>
<tr>
<td>Show details of instance</td>
<td>
<screen><prompt>$</prompt> <userinput>nova show <replaceable>NAME</replaceable></userinput>
<prompt>$</prompt> <userinput>nova show MyFirstInstance</userinput></screen>
</td>
</tr>
<tr>
<td>View console log of instance</td>
<td>
<screen><prompt>$</prompt> <userinput>nova console-log MyFirstInstance</userinput></screen>
</td>
</tr>
<tr>
<td>Set metadata on an instance</td>
<td>
<screen><prompt>$</prompt> <userinput>nova meta volumeTwoImage set newmeta='my meta data'</userinput></screen>
</td>
</tr>
<tr>
<td>Create an instance snapshot</td>
<td>
<screen><prompt>$</prompt> <userinput>nova image-create volumeTwoImage snapshotOfVolumeImage</userinput>
<prompt>$</prompt> <userinput>nova image-show snapshotOfVolumeImage</userinput></screen>
</td>
</tr>
<tr>
<th colspan="2">Pause, suspend, stop, rescue, resize, rebuild, reboot an instance</th>
</tr>
<tr>
<td>Pause</td>
<td>
<screen><prompt>$</prompt> <userinput>nova pause <replaceable>NAME</replaceable></userinput>
<prompt>$</prompt> <userinput>nova pause volumeTwoImage</userinput></screen>
</td>
</tr>
<tr>
<td>Unpause</td>
<td>
<screen><prompt>$</prompt> <userinput>nova unpause <replaceable>NAME</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Suspend</td>
<td>
<screen><prompt>$</prompt> <userinput>nova suspend <replaceable>NAME</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Unsuspend</td>
<td>
<screen><prompt>$</prompt> <userinput>nova resume <replaceable>NAME</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Stop</td>
<td>
<screen><prompt>$</prompt> <userinput>nova stop <replaceable>NAME</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Start</td>
<td>
<screen><prompt>$</prompt> <userinput>nova start <replaceable>NAME</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Rescue</td>
<td>
<screen><prompt>$</prompt> <userinput>nova rescue <replaceable>NAME</replaceable></userinput>
<prompt>$</prompt> <userinput>nova rescue <replaceable>NAME</replaceable> --rescue_image_ref <replaceable>RESCUE_IMAGE</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Resize</td>
<td>
<screen><prompt>$</prompt> <userinput>nova resize <replaceable>NAME</replaceable> <replaceable>FLAVOR</replaceable></userinput>
<prompt>$</prompt> <userinput>nova resize my-pem-server m1.small</userinput>
<prompt>$</prompt> <userinput>nova resize-confirm my-pem-server1</userinput></screen>
</td>
</tr>
<tr>
<td>Rebuild</td>
<td>
<screen><prompt>$</prompt> <userinput>nova rebuild <replaceable>NAME</replaceable> <replaceable>IMAGE</replaceable></userinput>
<prompt>$</prompt> <userinput>nova rebuild newtinny cirros-qcow2</userinput></screen>
</td>
</tr>
<tr>
<td>Reboot</td>
<td>
<screen><prompt>$</prompt> <userinput>nova reboot <replaceable>NAME</replaceable></userinput>
<prompt>$</prompt> <userinput>nova reboot newtinny</userinput></screen>
</td>
</tr>
<tr>
<td>Inject user data and files into an instance</td>
<td>
<screen><prompt>$</prompt> <userinput>nova boot --user-data <replaceable>FILE</replaceable> <replaceable>INSTANCE</replaceable></userinput>
<prompt>$</prompt> <userinput>nova boot --user-data userdata.txt --image cirros-qcow2 \
--flavor m1.tiny MyUserdataInstance2</userinput></screen>
<para>To validate that the file is there, ssh into the
instance, and look in <filename>/var/lib/cloud</filename>
for the file.</para>
</td>
</tr>
<tr>
<th colspan="2">Inject a keypair into an instance and access
the instance with that keypair</th>
</tr>
<tr>
<td>Create keypair</td>
<td>
<screen><prompt>$</prompt> <userinput>nova keypair-add test > test.pem</userinput>
<prompt>$</prompt> <userinput>chmod 600 test.pem</userinput></screen>
</td>
</tr>
<tr>
<td>Boot</td>
<td>
<screen><prompt>$</prompt> <userinput>nova boot --image cirros-0.3.0-x86_64 --flavor m1.small \
--key_name test MyFirstServer</userinput></screen>
</td>
</tr>
<tr>
<td>Use ssh to connect to the instance</td>
<td>
<screen><prompt>#</prompt> <userinput>ip netns exec qdhcp-98f09f1e-64c4-4301-a897-5067ee6d544f \
ssh -i test.pem cirros@10.0.0.4</userinput></screen>
</td>
</tr>
<tr>
<th colspan="2">Manage security groups</th>
</tr>
<tr>
<td>Add rules to default security group allowing ping and
SSH between instances in the default security group</td>
<td>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule default default icmp -1 -1</userinput>
<prompt>$</prompt> <userinput>nova secgroup-add-group-rule default default tcp 22 22</userinput></screen></td>
</tr>
</tbody>
</table>
<table rules="all" width="100%">
<caption>Networking (neutron)</caption>
<col width="30%"/>
<col width="70%"/>
<thead>
<tr>
<th>Description</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>Create network</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron net-create <replaceable>NAME</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Create a subnet</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron subnet-create <replaceable>NETWORK_NAME</replaceable> <replaceable>CIDR</replaceable></userinput>
<prompt>$</prompt> <userinput>neutron subnet-create my-network 10.0.0.0/29</userinput></screen>
</td>
</tr>
<tr>
<td>List network and subnet</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron net-list</userinput>
<prompt>$</prompt> <userinput>neutron subnet-list</userinput></screen>
</td>
</tr>
<tr>
<td>Examine details of network and subnet</td>
<td>
<screen><prompt>$</prompt> <userinput>neutron net-show <replaceable>ID_OR_NAME_OF_NETWORK</replaceable></userinput>
<prompt>$</prompt> <userinput>neutron subnet-show <replaceable>ID_OR_NAME_OF_NETWORK</replaceable></userinput></screen>
</td>
</tr>
</tbody>
</table>
<table rules="all" width="100%">
<caption>Block Storage (cinder)</caption>
<col width="30%"/>
<col width="70%"/>
<thead>
<tr>
<th>Description</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<th colspan="2">Manage volumes and volume snapshots</th>
</tr>
<tr>
<td>Create a new volume</td>
<td>
<screen><prompt>$</prompt> <userinput>cinder create <replaceable>SIZE_IN_GB</replaceable> --display-name <replaceable>NAME</replaceable></userinput>
<prompt>$</prompt> <userinput>cinder create 1 --display-name MyFirstVolume</userinput></screen>
</td>
</tr>
<tr>
<td>Boot an instance and attach to volume</td>
<td>
<screen><prompt>$</prompt> <userinput>nova boot --image cirros-qcow2 --flavor m1.tiny MyVolumeInstance</userinput></screen>
</td>
</tr>
<tr>
<td>List volumes, notice status of volume</td>
<td>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
</td>
</tr>
<tr>
<td>Attach volume to instance after instance is active, and
volume is available</td>
<td>
<screen><prompt>$</prompt> <userinput>nova volume-attach <replaceable>INSTANCE_ID</replaceable> <replaceable>VOLUME_ID</replaceable> auto</userinput>
<prompt>$</prompt> <userinput>nova volume-attach MyVolumeInstance /dev/vdb auto</userinput></screen>
</td>
</tr>
<tr>
<th colspan="2">Manage volumes after login into the instance</th>
</tr>
<tr>
<td>List storage devices</td>
<td>
<screen><prompt>#</prompt> <userinput>fdisk -l</userinput></screen>
</td>
</tr>
<tr>
<td>Make filesystem on volume</td>
<td>
<screen><prompt>#</prompt> <userinput>mkfs.ext3 /dev/vdb</userinput></screen>
</td>
</tr>
<tr>
<td>Create a mountpoint</td>
<td>
<screen><prompt>#</prompt> <userinput>mkdir /myspace</userinput></screen>
</td>
</tr>
<tr>
<td>Mount the volume at the mountpoint</td>
<td>
<screen><prompt>#</prompt> <userinput>mount /dev/vdb /myspace</userinput></screen>
</td>
</tr>
<tr>
<td>Create a file on the volume</td>
<td>
<screen><prompt>#</prompt> <userinput>touch /myspace/helloworld.txt</userinput>
<prompt>#</prompt> <userinput>ls /myspace</userinput></screen>
</td>
</tr>
<tr>
<td>Unmount the volume</td>
<td>
<screen><prompt>#</prompt> <userinput>umount /myspace</userinput></screen>
</td>
</tr>
</tbody>
</table>
<table rules="all" width="100%">
<caption>Object Storage (swift)</caption>
<col width="30%"/>
<col width="70%"/>
<thead>
<tr>
<th>Description</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>Display information for the account, container, or object</td>
<td>
<screen><prompt>$</prompt> <userinput>swift stat</userinput>
<prompt>$</prompt> <userinput>swift stat <replaceable>ACCOUNT</replaceable></userinput>
<prompt>$</prompt> <userinput>swift stat <replaceable>CONTAINER</replaceable></userinput>
<prompt>$</prompt> <userinput>swift stat <replaceable>OBJECT</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>List containers</td>
<td>
<screen><prompt>$</prompt> <userinput>swift list</userinput></screen>
</td>
</tr>
<tr>
<td>Create a container</td>
<td>
<screen><prompt>$</prompt> <userinput>swift post <replaceable>CONTAINER_NAME</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Upload file to a container</td>
<td>
<screen><prompt>$</prompt> <userinput>swift upload <replaceable>CONTAINER_NAME</replaceable> <replaceable>FILE_NAME</replaceable></userinput>
<prompt>$</prompt> <userinput>swift upload mycontainer myfile.txt</userinput></screen>
</td>
</tr>
<tr>
<td>List objects in container</td>
<td>
<screen><prompt>$</prompt> <userinput>swift list container</userinput></screen>
</td>
</tr>
<tr>
<td>Download object from container</td>
<td>
<screen><prompt>$</prompt> <userinput>swift download <replaceable>CONTAINER_NAME</replaceable> <replaceable>FILE_NAME</replaceable></userinput></screen>
</td>
</tr>
<tr>
<td>Upload with chunks, for large file</td>
<td>
<screen><prompt>$</prompt> <userinput>swift upload -S <replaceable>SIZE</replaceable> <replaceable>CONTAINER_NAME</replaceable> <replaceable>FILE_NAME</replaceable></userinput>
<prompt>$</prompt> <userinput>swift upload -S 64 container largeFile</userinput></screen>
</td>
</tr>
</tbody>
</table>
</appendix>

151
doc/user-guide/bk-user-guide.xml
View File

@ -1,151 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
]>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="os-user-guide">
<title>OpenStack End User Guide</title>
<titleabbrev>End User Guide</titleabbrev>
<info>
<author>
<personname>
<firstname/>
<surname/>
</personname>
<affiliation>
<orgname>OpenStack Foundation</orgname>
</affiliation>
</author>
<copyright>
<year>2014</year>
<year>2015</year>
<holder>OpenStack Foundation</holder>
</copyright>
<releaseinfo>current</releaseinfo>
<productname>OpenStack</productname>
<pubdate/>
<legalnotice role="cc-by">
<annotation>
<remark>Copyright details are filled in by the
template.</remark>
</annotation>
</legalnotice>
<abstract>
<para>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.</para>
<para>This guide documents OpenStack Juno, OpenStack
Icehouse and OpenStack Havana releases.</para>
</abstract>
<revhistory>
<revision>
<date>2014-10-15</date>
<revdescription>
<itemizedlist>
<listitem>
<para>
For the Juno release, this guide has
been updated with information about
the Database service for OpenStack (trove).
</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2014-05-09</date>
<revdescription>
<itemizedlist>
<listitem>
<para>Add a command line cheat sheet.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2014-04-17</date>
<revdescription>
<itemizedlist>
<listitem>
<para>For the Icehouse release, this guide
has been updated with changes to the
dashboard plus the moving of the
command reference appendix as
indicated below.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2014-01-31</date>
<revdescription>
<itemizedlist>
<listitem>
<para>Removed the command reference appendix. This
information is now in the <link
xlink:href="http://docs.openstack.org/cli-reference/content/"
><citetitle>OpenStack Command-Line
Interface Reference</citetitle></link>.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2013-12-30</date>
<revdescription>
<itemizedlist>
<listitem>
<para>Added the OpenStack Python SDK
chapter.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2013-10-17</date>
<revdescription>
<itemizedlist>
<listitem>
<para>Havana release.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2013-08-19</date>
<revdescription>
<itemizedlist>
<listitem>
<para>Editorial changes.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2013-07-29</date>
<revdescription>
<itemizedlist>
<listitem>
<para>First edition of this
document.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
</info>
<xi:include href="../common/ch_using_openstack_overview.xml"/>
<xi:include href="ch_dashboard.xml"/>
<xi:include href="ch_cli.xml"/>
<xi:include href="ch_sdk.xml"/>
<xi:include href="hot/index.xml"/>
<xi:include href="app_cheat_sheet.xml"/>
<xi:include href="../common/app_support.xml"/>
</book>

45
doc/user-guide/ch_cli.xml
View File

@ -1,45 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="ch_cli">
<info>
<title>OpenStack command-line clients</title>
</info>
<xi:include href="../common/section_cli_overview.xml"/>
<?hard-pagebreak?>
<xi:include href="../common/section_cli_install.xml"/>
<?hard-pagebreak?>
<xi:include href="../common/section_cli_version.xml"/>
<?hard-pagebreak?>
<xi:include href="../common/section_cli_openrc.xml"/>
<?hard-pagebreak?>
<xi:include href="../common/section_cli_glance_manage_images.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_nova_configure_instances.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_nova_boot.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_nova_manage_instances.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_nova_userdata.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_nova_migrate_instances.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_nova_config-drive.xml"/>
<?hard-pagebreak?>
<xi:include href="../common/section_cli_neutron_manage_networks.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_swift_howto.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_heat.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_ceilometer.xml"/>
<?hard-pagebreak?>
<xi:include href="../common/section_cli_cinder_manage_volumes.xml"/>
<?hard-pagebreak?>
<xi:include href="section_cli_trove.xml"/>
</chapter>

37
doc/user-guide/ch_dashboard.xml
View File

@ -1,37 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="ch_dashboard">
<info>
<title>OpenStack dashboard</title>
</info>
<para>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.</para>
<?hard-pagebreak?>
<xi:include href="../common/section_dashboard_access.xml"/>
<?hard-pagebreak?>
<xi:include
href="section_dashboard_manage_images.xml"/>
<?hard-pagebreak?>
<!-- end user guide -->
<xi:include href="section_dashboard_access_and_security.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_launch_instances.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_create_networks.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_manage_containers.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_manage_volumes.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_stacks.xml"/>
<?hard-pagebreak?>
<xi:include href="section_dashboard_databases.xml"/>
</chapter>

37
doc/user-guide/ch_sdk.xml
View File

@ -1,37 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="ch_sdk">
<info>
<title>OpenStack Python SDK</title>
</info>
<para>Use the OpenStack Python Software Development Kit (SDK) 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. All OpenStack command-line tools are implemented
using the Python SDK.</para>
<para>You should also be familiar with:</para>
<itemizedlist spacing="compact">
<listitem>
<para>RESTful web services</para>
</listitem>
<listitem>
<para>HTTP/1.1</para>
</listitem>
<listitem>
<para>JSON and XML data serialization formats</para>
</listitem>
</itemizedlist>
<xi:include href="section_sdk_install.xml"/>
<xi:include href="section_sdk_authenticate.xml"/>
<xi:include href="section_sdk_manage_images.xml"/>
<xi:include href="section_object-api-cors-headers.xml"/>
<xi:include href="section_object-api-expire-objects.xml"/>
<xi:include href="section_sdk_configure_instances.xml"/>
<xi:include href="section_sdk_neutron.xml"/>
<xi:include href="section_sdk_nova.xml"/>
</chapter>

8
doc/user-guide/hot/README.rst
View File

@ -1,8 +0,0 @@
**The contents of this directory are autogenerated - do NOT modify these files,
your changes will be lost on the next update.**
To generate the files::
cd doc/hot-guide
make xml
openstack-dn2osdbk --toplevel chapter build/xml ../user-guide/hot

17
doc/user-guide/hot/index.xml
View File

@ -1,17 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="hot-guide">
<!-- WARNING: This file is automatically generated. Do not edit it. -->
<title>HOT guide</title>
<xi:include href="section_hello_world.xml"/>
<xi:include href="section_hot_spec.xml"/>
<xi:include href="section_basic_resources.xml"/>
<xi:include href="section_software_deployment.xml"/>
<xi:include href="section_environment.xml"/>
<xi:include href="section_composition.xml"/>
</chapter>

33
doc/user-guide/hot/section_advanced_topics.xml
View File

@ -1,33 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="hot-advanced-topics">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Advanced topics</title>
<section xml:id="networking">
<?dbhtml stop-chunking?>
<title>Networking</title>
<section xml:id="load-balancer">
<title>Load balancer</title>
<para>TODO</para>
</section>
<section xml:id="firewall">
<title>Firewall</title>
<para>TODO</para>
</section>
<section xml:id="vpn">
<title>VPN</title>
<para>TODO</para>
</section>
</section>
<section xml:id="auto-scaling">
<?dbhtml stop-chunking?>
<title>Auto scaling</title>
<section xml:id="alarming">
<title>Alarming</title>
<para>TODO</para>
</section>
<section xml:id="up-scaling-and-down-scaling">
<title>Up scaling and down scaling</title>
<para>TODO</para>
</section>
</section>
</section>

429
doc/user-guide/hot/section_basic_resources.xml
View File

@ -1,429 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="hot-basic-resources">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Instances</title>
<!--For consistency let's define a few values to use in the samples:
* image name: ubuntu-trusty-x86_64
* shared/provider network name: "public"
* tenant network and subnet names: "private" and "private-subnet"-->
<section xml:id="manage-instances">
<?dbhtml stop-chunking?>
<title>Manage instances</title>
<section xml:id="create-an-instance">
<title>Create an instance</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> resource to create a Compute instance. The
<literal>flavor</literal> property is the only mandatory one, but you need to define a boot
source using one of the <literal>image</literal> or <literal>block_device_mapping</literal> properties.</para>
<para>You also need to define the <literal>networks</literal> property to indicate to which networks
your instance must connect if multiple networks are available in your tenant.</para>
<para>The following example creates a simple instance, booted from an image, and
connecting to the <literal>private</literal> network:</para>
<programlisting language="yaml">resources:
instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: private</programlisting>
</section>
<section xml:id="connect-an-instance-to-a-network">
<title>Connect an instance to a network</title>
<para>Use the <literal>networks</literal> property of an <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> resource to
define which networks an instance should connect to. Define each network as a
YAML map, containing one of the following keys:</para>
<variablelist role="definition_list">
<varlistentry>
<term>
<literal>port</literal>
</term>
<listitem>
<para>The ID of an existing Networking port. You usually create this port in the
same template using an <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Port.html">OS::Neutron::Port</link></literal> resource. You will be
able to associate a floating IP to this port, and the port to your Compute
instance.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>network</literal>
</term>
<listitem>
<para>The name or ID of an existing network. You don't need to create an
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Port.html">OS::Neutron::Port</link></literal> resource if you use this property, but you will
not be able to associate a floating IP with the instance interface in the
template.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following example demonstrates the use of the <literal>port</literal> and <literal>network</literal>
properties:</para>
<programlisting language="yaml">resources:
instance_port:
type: OS::Neutron::Port
properties:
network: private
fixed_ips:
- subnet_id: "private-subnet"
instance1:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- port: { get_resource: instance_port }
instance2:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: private</programlisting>
</section>
<section xml:id="create-and-associate-security-groups-to-an-instance">
<title>Create and associate security groups to an instance</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__SecurityGroup.html">OS::Neutron::SecurityGroup</link></literal> resource to create security
groups.</para>
<para>Define the <literal>security_groups</literal> property of the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Port.html">OS::Neutron::Port</link></literal>
resource to associate security groups to a port, then associate the port to an
instance.</para>
<para>The following example creates a security group allowing inbound connections on
ports 80 and 443 (web server) and associates this security group to an instance
port:</para>
<programlisting language="yaml">resources:
web_secgroup:
type: OS::Neutron::SecurityGroup
properties:
rules:
- protocol: tcp
remote_ip_prefix: 0.0.0.0/0
port_range_min: 80
port_range_max: 80
- protocol: tcp
remote_ip_prefix: 0.0.0.0/0
port_range_min: 443
port_range_max: 443
instance_port:
type: OS::Neutron::Port
properties:
network: private
security_groups:
- default
- { get_resource: web_secgroup }
fixed_ips:
- subnet_id: private-subnet
instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- port: { get_resource: instance_port }</programlisting>
</section>
<section xml:id="create-and-associate-a-floating-ip-to-an-instance">
<title>Create and associate a floating IP to an instance</title>
<para>You can use two sets of resources to create and associate floating IPs to
instances.</para>
<section xml:id="os-nova-resources">
<title>OS::Nova resources</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__FloatingIP.html">OS::Nova::FloatingIP</link></literal> resource to create a floating IP, and
the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__FloatingIPAssociation.html">OS::Nova::FloatingIPAssociation</link></literal> resource to associate the
floating IP to an instance.</para>
<para>The following example creates an instance and a floating IP, and associate the
floating IP to the instance:</para>
<programlisting language="yaml">resources:
floating_ip:
type: OS::Nova::FloatingIP
properties:
pool: public
inst1:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: private
association:
type: OS::Nova::FloatingIPAssociation
properties:
floating_ip: { get_resource: floating_ip }
server_id: { get_resource: instance }</programlisting>
</section>
<section xml:id="os-neutron-resources">
<title>OS::Neutron resources</title>
<note>
<para>The Networking service (neutron) must be enabled on your OpenStack
deployment to use these resources.</para>
</note>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__FloatingIP.html">OS::Neutron::FloatingIP</link></literal> resource to create a floating IP, and
the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__FloatingIPAssociation.html">OS::Neutron::FloatingIPAssociation</link></literal> resource to associate the
floating IP to a port:</para>
<programlisting language="yaml">parameters:
net:
description: name of network used to launch instance.
type: string
default: private
resources:
inst1:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: {get_param: net}
floating_ip:
type: OS::Neutron::FloatingIP
properties:
floating_network: public
association:
type: OS::Neutron::FloatingIPAssociation
properties:
floatingip_id: { get_resource: floating_ip }
port_id: {get_attr: [inst1, addresses, {get_param: net}, 0, port]}</programlisting>
<para>You can also create an OS::Neutron::Port and associate that with the server and
the floating IP. However the approach mentioned above will work better
with stack updates.</para>
<programlisting language="yaml">resources:
instance_port:
type: OS::Neutron::Port
properties:
network: private
fixed_ips:
- subnet_id: "private-subnet"
floating_ip:
type: OS::Neutron::FloatingIP
properties:
floating_network: public
association:
type: OS::Neutron::FloatingIPAssociation
properties:
floatingip_id: { get_resource: floating_ip }
port_id: { get_resource: instance_port }</programlisting>
</section>
</section>
<section xml:id="enable-remote-access-to-an-instance">
<title>Enable remote access to an instance</title>
<para>The <literal>key_name</literal> attribute of the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> resource defines
the key pair to use to enable SSH remote access:</para>
<programlisting language="yaml">resources:
my_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
key_name: my_key</programlisting>
<note>
<para>For more information about key pairs, see the <link xlink:href="http://docs.openstack.org/user-guide/content/cli_configure_instances.html">Configure access and
security for instances</link> section of the OpenStack user guide.</para>
</note>
</section>
<section xml:id="create-a-key-pair">
<title>Create a key pair</title>
<para>You can create new key pairs with the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__KeyPair.html">OS::Nova::KeyPair</link></literal> resource. Key
pairs can be imported or created during the stack creation.</para>
<para>If the <literal>public_key</literal> property is not specified, the Orchestration module
creates a new key pair. If the <literal>save_private_key</literal> property is set to
<literal>true</literal>, the <literal>private_key</literal> attribute of the resource holds the private key.</para>
<para>The following example creates a new key pair and uses it as authentication key
for an instance:</para>
<programlisting language="yaml">resources:
my_key:
type: OS::Nova::KeyPair
properties:
name: key1
save_private_key: true
my_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
key_name: { get_resource: my_key }
outputs:
private_key:
description: Private key
value: { get_attr: [ my_key, private_key ] }</programlisting>
</section>
</section>
<section xml:id="manage-networks">
<?dbhtml stop-chunking?>
<title>Manage networks</title>
<section xml:id="create-a-network-and-a-subnet">
<title>Create a network and a subnet</title>
<note>
<para>The Networking service (neutron) must be enabled on your OpenStack
deployment to create and manage networks and subnets. Networks and subnets
cannot be created if your deployment uses legacy networking (nova-network).</para>
</note>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Net.html">OS::Neutron::Net</link></literal> resource to create a network, and the
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Subnet.html">OS::Neutron::Subnet</link></literal> resource to provide a subnet for this network:</para>
<programlisting language="yaml">resources:
new_net:
type: OS::Neutron::Net
new_subnet:
type: OS::Neutron::Subnet
properties:
network_id: { get_resource: new_net }
cidr: "10.8.1.0/24"
dns_nameservers: [ "8.8.8.8", "8.8.4.4" ]
ip_version: 4</programlisting>
</section>
<section xml:id="create-and-manage-a-router">
<title>Create and manage a router</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Router.html">OS::Neutron::Router</link></literal> resource to create a router. You can
define its gateway with the <literal>external_gateway_info</literal> property:</para>
<programlisting language="yaml">resources:
router1:
type: OS::Neutron::Router
properties:
external_gateway_info: { network: public }</programlisting>
<para>You can connect subnets to routers with the
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__RouterInterface.html">OS::Neutron::RouterInterface</link></literal> resource:</para>
<programlisting language="yaml">resources:
subnet1_interface:
type: OS::Neutron::RouterInterface
properties:
router_id: { get_resource: router1 }
subnet: private-subnet</programlisting>
</section>
<section xml:id="complete-network-example">
<title>Complete network example</title>
<para>The following example creates a network stack:</para>
<itemizedlist>
<listitem>
<para>A network and an associated subnet.</para>
</listitem>
<listitem>
<para>A router with an external gateway.</para>
</listitem>
<listitem>
<para>An interface to the new subnet for the new router.</para>
</listitem>
</itemizedlist>
<para>In this example, the <literal>public</literal> network is an existing shared network:</para>
<programlisting language="yaml">resources:
internal_net:
type: OS::Neutron::Net
internal_subnet:
type: OS::Neutron::Subnet
properties:
network_id: { get_resource: internal_net }
cidr: "10.8.1.0/24"
dns_nameservers: [ "8.8.8.8", "8.8.4.4" ]
ip_version: 4
internal_router:
type: OS::Neutron::Router
properties:
external_gateway_info: { network: public }
internal_interface:
type: OS::Neutron::RouterInterface
properties:
router_id: { get_resource: internal_router }
subnet: { get_resource: internal_subnet }</programlisting>
</section>
</section>
<section xml:id="manage-volumes">
<?dbhtml stop-chunking?>
<title>Manage volumes</title>
<section xml:id="create-a-volume">
<title>Create a volume</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Cinder__Volume.html">OS::Cinder::Volume</link></literal> resource to create a new Block Storage
volume.</para>
<para>For example:</para>
<programlisting language="yaml">resources:
my_new_volume:
type: OS::Cinder::Volume
properties:
size: 10</programlisting>
<para>The volumes that you create are empty by default. Use the <literal>image</literal> property to
create a bootable volume from an existing image:</para>
<programlisting language="yaml">resources:
my_new_bootable_volume:
type: OS::Cinder::Volume
properties:
size: 10
image: ubuntu-trusty-x86_64</programlisting>
<para>You can also create new volumes from another volume, a volume snapshot, or a
volume backup. Use the <literal>source_volid</literal>, <literal>snapshot_id</literal> or <literal>backup_id</literal>
properties to create a new volume from an existing source.</para>
<para>For example, to create a new volume from a backup:</para>
<programlisting language="yaml">resources:
another_volume:
type: OS::Cinder::Volume
properties:
backup_id: 2fff50ab-1a9c-4d45-ae60-1d054d6bc868</programlisting>
<para>In this example the <literal>size</literal> property is not defined because the Block Storage
service uses the size of the backup to define the size of the new volume.</para>
</section>
<section xml:id="attach-a-volume-to-an-instance">
<title>Attach a volume to an instance</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Cinder__VolumeAttachment.html">OS::Cinder::VolumeAttachment</link></literal> resource to attach a volume to
an instance.</para>
<para>The following example creates a volume and an instance, and attaches the volume
to the instance:</para>
<programlisting language="yaml">resources:
new_volume:
type: OS::Cinder::Volume
properties:
size: 1
new_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
volume_attachment:
type: OS::Cinder::VolumeAttachment
properties:
volume_id: { get_resource: new_volume }
instance_uuid: { get_resource: new_instance }</programlisting>
</section>
<section xml:id="boot-an-instance-from-a-volume">
<title>Boot an instance from a volume</title>
<para>Use the <literal>block_device_mapping</literal> property of the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal>
resource to define a volume used to boot the instance. This property is a list
of volumes to attach to the instance before its boot.</para>
<para>The following example creates a bootable volume from an image, and uses it to
boot an instance:</para>
<programlisting language="yaml">resources:
bootable_volume:
type: OS::Cinder::Volume
properties:
size: 10
image: ubuntu-trusty-x86_64
instance:
type: OS::Nova::Server
properties:
flavor: m1.small
networks:
- network: private
block_device_mapping:
- device_name: vda
volume_id: { get_resource: bootable_volume }
delete_on_termination: false</programlisting>
<!--TODO
A few elements that probably belong here:
- OS::Swift::Container
- OS::Trove::Instance-->
</section>
</section>
</section>

144
doc/user-guide/hot/section_composition.xml
View File

@ -1,144 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="composition">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Template composition</title>
<para>When writing complex templates you are encouraged to break up your
template into separate smaller templates. These can then be brought
together using template resources. This is a mechanism to define a resource
using a template, thus composing one logical stack with multiple templates.</para>
<para>Template resources provide a feature similar to the
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/AWS__CloudFormation__Stack.html">AWS::CloudFormation::Stack</link></literal> resource, but also provide a way to:</para>
<itemizedlist>
<listitem>
<para>Define new resource types and build your own resource library.</para>
</listitem>
<listitem>
<para>Override the default behaviour of existing resource types.</para>
</listitem>
</itemizedlist>
<para>To achieve this:</para>
<itemizedlist>
<listitem>
<para>The Orchestration client gets the associated template files and passes them
along in the <literal>files</literal> section of the <literal>POST stacks/</literal> API request.</para>
</listitem>
<listitem>
<para>The environment in the Orchestration engine manages the mapping of resource
type to template creation.</para>
</listitem>
<listitem>
<para>The Orchestration engine translates template parameters into resource
properties.</para>
</listitem>
</itemizedlist>
<para>The following examples illustrate how you can use a custom template to define
new types of resources. These examples use a custom template stored in a
<literal>my_nova.yml</literal> file:</para>
<programlisting language="yaml">heat_template_version: 2014-10-16
parameters:
key_name:
type: string
description: Name of a KeyPair
resources:
server:
type: OS::Nova::Server
properties:
key_name: {get_param: key_name}
flavor: m1.small
image: ubuntu-trusty-x86_64</programlisting>
<section xml:id="use-the-template-filename-as-type">
<?dbhtml stop-chunking?>
<title>Use the template filename as type</title>
<para>The following template defines the <literal>my_nova.yaml</literal> file as value for the
<literal>type</literal> property of a resource:</para>
<programlisting language="yaml">heat_template_version: 2014-10-16
resources:
my_server:
type: my_nova.yaml
properties:
key_name: my_key</programlisting>
<para>The <literal>key_name</literal> argument of the <literal>my_nova.yaml</literal> template gets its value from
the <literal>key_name</literal> property of the new template.</para>
<note>
<para>The above reference to <literal>my_nova.yaml</literal> assumes it is in the same directory.
You can use any of the following forms:</para>
<itemizedlist>
<listitem>
<para>Relative path (<literal>my_nova.yaml</literal>)</para>
</listitem>
<listitem>
<para>Absolute path (<literal>file:///home/user/templates/my_nova.yaml</literal>)</para>
</listitem>
<listitem>
<para>Http URL (<literal>http://example.com/templates/my_nova.yaml</literal>)</para>
</listitem>
<listitem>
<para>Https URL (<literal>https://example.com/templates/my_nova.yaml</literal>)</para>
</listitem>
</itemizedlist>
</note>
<para>To create the stack run:</para>
<programlisting language="console">$ heat stack-create -f main.yaml stack1</programlisting>
</section>
<section xml:id="define-a-new-resource-type">
<?dbhtml stop-chunking?>
<title>Define a new resource type</title>
<para>You can associate a name to the <literal>my_nova.yaml</literal> template in an environment
file. If the name is already known by the Orchestration module then your new
resource will override the default one.</para>
<para>In the following example a new <literal>OS::Nova::Server</literal> resource overrides the
default resource of the same name.</para>
<para>An <literal>env.yaml</literal> environment file holds the definition of the new resource:</para>
<programlisting language="yaml">resource_registry:
"OS::Nova::Server": my_nova.yaml</programlisting>
<note>
<para>See <xref linkend="environments"/> for more detail about environment files.</para>
</note>
<para>You can now use the new <literal>OS::Nova::Server</literal> in your new template:</para>
<programlisting language="yaml">heat_template_version: 2014-10-16
resources:
my_server:
type: OS::Nova::Server
properties:
key_name: my_key</programlisting>
<para>To create the stack run:</para>
<programlisting language="console">$ heat stack-create -f main.yaml -e env.yaml example-two</programlisting>
</section>
<section xml:id="get-access-to-nested-attributes">
<?dbhtml stop-chunking?>
<title>Get access to nested attributes</title>
<para>There are implicit attributes of a template resource. These are
accessible as follows:</para>
<programlisting language="yaml">heat_template_version: 2014-10-16
resources:
my_server:
type: my_nova.yaml
outputs:
test_out:
value: {get_attr: my_server, resource.server, first_address}</programlisting>
</section>
<section xml:id="making-your-template-resource-more-transparent">
<?dbhtml stop-chunking?>
<title>Making your template resource more "transparent"</title>
<para>If you wish to be able to return the ID of one of the inner resources
instead of the nested stack's identifier, you can add the special reserved
output "OS::stack_id" to your template resource.</para>
<programlisting language="yaml">heat_template_version: 2014-10-16
resources:
server:
type: OS::Nova::Server
outputs:
OS::stack_id:
value: {get_resource: server}</programlisting>
<para>Now when you use "get_resource" from the outer template heat
will use the nova server id and not the template resource identifier.</para>
</section>
</section>

108
doc/user-guide/hot/section_environment.xml
View File

@ -1,108 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="environments">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Environments</title>
<para>The environment affects the runtime behaviour of a template. It provides a way
to override the resource implementations and a mechanism to place parameters
that the service needs.</para>
<para>To fully understand the runtime behavior you have to consider what plug-ins are
installed on the cloud you're using.</para>
<section xml:id="environment-file-format">
<?dbhtml stop-chunking?>
<title>Environment file format</title>
<para>The environment is a yaml text file that contains two main sections:</para>
<variablelist role="definition_list">
<varlistentry>
<term>
<literal>parameters</literal>
</term>
<listitem>
<para>A map of key/pair values.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>resource_registry</literal>
</term>
<listitem>
<para>Definition of custom resources.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Use the -e option of the <command>heat stack-create</command> command to
create a stack using with the environment defined in such a file.</para>
<para>You can also provide environment parameters as a list of key/value pairs using
the -P option of the <command>heat stack-create</command> command.</para>
<para>In the following example the environment is read from the <literal>my_env.yaml</literal>
file and an extra parameter is provided using the -P option:</para>
<programlisting language="console">$ heat stack-create my_stack -e my_env.yaml -P "param1=val1;param2=val2" -f my_tmpl.yaml</programlisting>
</section>
<section xml:id="global-and-effective-environments">
<?dbhtml stop-chunking?>
<title>Global and effective environments</title>
<para>The environment used for a stack is the combination of the environment you
use with the template for the stack, and a global environment that is
determined by your cloud operator. An entry in the user environment takes
precedence over the global environment. OpenStack includes a default global
environment, but you cloud operator can add additional environment entries.</para>
<!--TODO:
move this to a heat section in the admin-guide-cloud
The cloud operator can add to the global environment
by putting environment files in a configurable directory wherever
the Orchestration engine runs. The configuration variable is named
"environment_dir" is found in the "[DEFAULT]" section
of "/etc/heat/heat.conf". The default for that directory is
"/etc/heat/environment.d". Its contents are combined in whatever
order the shell delivers them when the service starts up,
which is the time when these files are read.
If the "my_env.yaml" file from the example above had been put in the
"environment_dir" then the user's command line could be this:
::
heat stack-create my_stack -P "some_parm=bla" -f my_tmpl.yaml-->
</section>
<section xml:id="define-values-for-a-template-arguments">
<?dbhtml stop-chunking?>
<title>Define values for a template arguments</title>
<para>You can define values for the template arguments in the <literal>parameters</literal> section
of an environment file:</para>
<programlisting language="yaml">parameters:
KeyName: my_keypair
InstanceType: m1.tiny
ImageId: F18-x86_64-cfntools</programlisting>
</section>
<section xml:id="create-and-override-resources">
<?dbhtml stop-chunking?>
<title>Create and override resources</title>
<para>You can create or override resources in the <literal>resource_registry</literal> section of an
environment file. The resource you provide in this manner must have an
identifier, and references either other resources IDs or the URL of an existing
template file.</para>
<para>The following example maps the new <literal>OS::Networking::FloatingIP</literal>
resource to the existing <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__FloatingIP.html">OS::Nova::FloatingIP</link></literal> resource:</para>
<programlisting language="yaml">resource_registry:
"OS::Networking::FloatingIP": "OS::Nova::FloatingIP"</programlisting>
<para>You can use wildcards to map multiple resources:</para>
<programlisting language="yaml">resource_registry:
"OS::Network*": "OS::Neutron*"</programlisting>
<para>To create or override a resource with a custom resource, create a template file
to define this resource, and provide the URL to the template file in the
environment file:</para>
<programlisting language="yaml">resource_registry:
"AWS::EC2::Instance": file:///path/to/my_instance.yaml</programlisting>
<para>The supported URL scheme are <literal>file</literal>, <literal>http</literal> and <literal>https</literal>.</para>
<note>
<para>The template file extension must be <literal>.yaml</literal> or <literal>.template</literal>, or it will
not be treated as a custom template resource.</para>
</note>
<para>You can limit the usage of a custom resource to a specific resource of the
template:</para>
<programlisting language="yaml">resource_registry:
resources:
my_db_server:
"OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml</programlisting>
</section>
</section>

77
doc/user-guide/hot/section_functions.xml
View File

@ -1,77 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="hot-functions">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>HOT functions</title>
<section xml:id="link-between-resources">
<?dbhtml stop-chunking?>
<title>Link between resources</title>
<itemizedlist>
<listitem>
<para>get_param</para>
</listitem>
<listitem>
<para>get_resource</para>
</listitem>
<listitem>
<para>Ref</para>
</listitem>
<listitem>
<para>Fn::GetAtt / get_attr</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="string-manipulations">
<?dbhtml stop-chunking?>
<title>String manipulations</title>
<itemizedlist>
<listitem>
<para>get_file</para>
</listitem>
<listitem>
<para>list_join</para>
</listitem>
<listitem>
<para>str_replace</para>
</listitem>
<listitem>
<para>Fn::Base64</para>
</listitem>
<listitem>
<para>Fn::Join</para>
</listitem>
<listitem>
<para>Fn::Split</para>
</listitem>
<listitem>
<para>Fn::Replace</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="lookup-structured-data">
<?dbhtml stop-chunking?>
<title>Lookup structured data</title>
<itemizedlist>
<listitem>
<para>Fn::FindInMap</para>
</listitem>
<listitem>
<para>Fn::MemberListToMap</para>
</listitem>
<listitem>
<para>Fn::Select</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="misc">
<?dbhtml stop-chunking?>
<title>Misc</title>
<itemizedlist>
<listitem>
<para>Fn::ResourceFacade / resource_facade</para>
</listitem>
<listitem>
<para>Fn::GetAZs</para>
</listitem>
</itemizedlist>
</section>
</section>

185
doc/user-guide/hot/section_hello_world.xml
View File

@ -1,185 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<!--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.-->
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="hello-world">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Writing a hello world HOT template</title>
<para>HOT is a new template format meant to replace the CloudFormation-compatible
format (CFN) as the native format supported by the Orchestration module over
time.
This guide is targeted towards template authors and explains how to write
HOT templates based on examples. A detailed specification of HOT can be found
at <xref linkend="hot-spec"/>.</para>
<para>This section gives an introduction on how to write HOT templates, starting from
very basic steps and then going into more and more detail by means of examples.</para>
<section xml:id="a-most-basic-template">
<?dbhtml stop-chunking?>
<title>A most basic template</title>
<para>The most basic template you can think of contains only a single resource
definition using only predefined properties. For example, the template below
could be used to deploy a single compute instance:</para>
<programlisting language="yaml">heat_template_version: 2013-05-23
description: Simple template to deploy a single compute instance
resources:
my_instance:
type: OS::Nova::Server
properties:
key_name: my_key
image: ubuntu-trusty-x86_64
flavor: m1.small</programlisting>
<para>Each HOT template has to include the <literal>heat_template_version</literal> key with value
<literal>2013-05-23</literal>, the current HOT version. While the <literal>description</literal> key is
optional, it is good practice to include some useful text that describes what
users can do with the template. In case you want to provide a longer
description that does not fit on a single line, you can provide multi-line text
in YAML, for example:</para>
<programlisting language="yaml">description: &gt;
This is how you can provide a longer description
of your template that goes over several lines.</programlisting>
<para>The <literal>resources</literal> section is required and must contain at least one resource
definition. In the above example, a compute instance is defined with fixed
values for the <literal>key_name</literal>, <literal>image</literal> and <literal>flavor</literal> properties.</para>
<note>
<para>All the defined elements (key pair, image, flavor) have to exist in the
OpenStack environment where the template is used.</para>
</note>
</section>
<section xml:id="input-parameters">
<?dbhtml stop-chunking?>
<title>Input parameters</title>
<para>Input parameters defined in the <literal>parameters</literal> section of a template
allow users to customize a template during deployment. For example, this allows
for providing custom key pair names or image IDs to be used for a deployment.
From a template author's perspective, this helps to make a template more easily
reusable by avoiding hardcoded assumptions.</para>
<para>The following example extends the previous template to provide parameters for
the key pair, image and flavor properties of the resource:</para>
<programlisting language="yaml">heat_template_version: 2013-05-23
description: Simple template to deploy a single compute instance
parameters:
key_name:
type: string
label: Key Name
description: Name of key-pair to be used for compute instance
image_id:
type: string
label: Image ID
description: Image to be used for compute instance
flavor:
type: string
label: Instance Type
description: Type of instance (flavor) to be used
resources:
my_instance:
type: OS::Nova::Server
properties:
key_name: { get_param: key_name }
image: { get_param: image_id }
flavor: { get_param: flavor }</programlisting>
<para>Values for the three parameters must be defined by the template user during the
deployment of a stack. The <literal>get_param</literal> intrinsic function retrieves a
user-specified value for a given parameter and uses this value for the
associated resource property.</para>
<para>For more information about intrinsic functions, see
<xref linkend="hot-spec-intrinsic-functions"/>.</para>
<section xml:id="providing-default-values">
<title>Providing default values</title>
<para>You can provide default values for parameters. If a user doesn't define a value
for a parameter, the default value is used during the stack deployment. The
following example defines a default value <literal>m1.small</literal> for the
<literal>flavor</literal> property:</para>
<programlisting language="yaml">parameters:
flavor:
type: string
label: Instance Type
description: Flavor to be used
default: m1.small</programlisting>
<note>
<para>If a template doesn't define a default value for a parameter, then the user
must define the value, otherwise the stack creation will fail.</para>
</note>
</section>
<section xml:id="hiding-parameters-values">
<title>Hiding parameters values</title>
<para>The values that a user provides when deploying a stack are available in the
stack details and can be accessed by any user in the same tenant. To hide the
value of a parameter, use the <literal>hidden</literal> boolean attribute of the parameter:</para>
<programlisting language="yaml">parameters:
database_password:
type: string
label: Database Password
description: Password to be used for database
hidden: true</programlisting>
</section>
<section xml:id="restricting-user-input">
<title>Restricting user input</title>
<para>You can restrict the values of an input parameter to make sure that the user
defines valid data for this parameter. The <literal>constraints</literal> property of an input
parameter defines a list of constraints to apply for the parameter.
The following example restricts the <literal>flavor</literal> parameter to a list of three
possible values:</para>
<programlisting language="yaml">parameters:
flavor:
type: string
label: Instance Type
description: Type of instance (flavor) to be used
constraints:
- allowed_values: [ m1.medium, m1.large, m1.xlarge ]
description: Value must be one of m1.medium, m1.large or m1.xlarge.</programlisting>
<para>The following example defines multiple constraints for a password definition:</para>
<programlisting language="yaml">parameters:
database_password:
type: string
label: Database Password
description: Password to be used for database
hidden: true
constraints:
- length: { min: 6, max: 8 }
description: Password length must be between 6 and 8 characters.
- allowed_pattern: "[a-zA-Z0-9]+"
description: Password must consist of characters and numbers only.
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
description: Password must start with an uppercase character.</programlisting>
<para>The list of supported constraints is available in the
<xref linkend="hot-spec-parameters-constraints"/> section.</para>
<note>
<para>You can define multiple constraints of the same type. Especially in the
case of allowed patterns this not only allows for keeping regular
expressions simple and maintainable, but also for keeping error messages to
be presented to users precise.</para>
</note>
</section>
</section>
<section xml:id="template-outputs">
<?dbhtml stop-chunking?>
<title>Template outputs</title>
<para>In addition to template customization through input parameters, you can
provide information about the resources created during the stack deployment to
the users in the <literal>outputs</literal> section of a template. In the following example
the output section provides the IP address of the <literal>my_instance</literal> resource:</para>
<programlisting language="yaml">outputs:
instance_ip:
description: The IP address of the deployed instance
value: { get_attr: [my_instance, first_address] }</programlisting>
<note>
<para>Output values are typically resolved using intrinsic function such as
the <literal>get_attr</literal>. See <xref linkend="hot-spec-intrinsic-functions"/> for more information
about intrinsic functions..</para>
</note>
<para>See <xref linkend="hot-spec-outputs"/> for more information about the <literal>outputs</literal> section.</para>
</section>
</section>

784
doc/user-guide/hot/section_hot_spec.xml
View File

@ -1,784 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<!--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.-->
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="hot-spec">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Heat Orchestration Template (HOT) specification</title>
<section xml:id="template-structure">
<?dbhtml stop-chunking?>
<title>Template structure</title>
<para>HOT templates are defined in YAML and use the following structure:</para>
<programlisting language="yaml">heat_template_version: 2013-05-23
description:
# description of the template
parameter_groups:
# declaration of input parameter groups and order
parameters:
# declaration of input parameters
resources:
# declaration of template resources
outputs:
# declaration of output parameters</programlisting>
<variablelist role="definition_list">
<varlistentry>
<term>heat_template_version</term>
<listitem>
<para>This key with value <literal>2013-05-23</literal> (or a later date) indicates that the
YAML document is a HOT template of the specified version.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>description</term>
<listitem>
<para>This optional key gives a description of the template, or
the workload that can be deployed using the template.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>parameter_groups</term>
<listitem>
<para>This section specifies how the input parameters should be
grouped and the order to provide the parameters in.</para>
<para>This section is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>parameters</term>
<listitem>
<para>This section specifies input parameters that have to
be provided when instantiating the template.</para>
<para>This section is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>resources</term>
<listitem>
<para>This section contains the declaration of the resources of the template.
This section with at least one resource must be defined in any HOT
template, or the template would not really do anything when being
instantiated.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>outputs</term>
<listitem>
<para>This section specifies output parameters available to users once the
template has been instantiated.</para>
<para>This section is optional.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="hot-spec-parameter-groups">
<?dbhtml stop-chunking?>
<title>Parameter groups section</title>
<para>The <literal>parameter_groups</literal> section specifies how the input parameters should be
grouped and the order to provide the parameters in. These groups are typically
used to describe expected behavior for downstream user interfaces.</para>
<para>These groups are specified in a list with each group containing a list of
associated parameters. The lists are used to denote the expected order of the
parameters. A parameter can only be included in one group. Use the name of the
parameter to add it to a group. The parameters details are defined in
the <literal>parameters</literal> section.</para>
<programlisting language="yaml">parameter_groups:
- label: &lt;human-readable label of parameter group&gt;
description: &lt;description of the parameter group&gt;
parameters:
- &lt;param name&gt;
- &lt;param name&gt;</programlisting>
<variablelist role="definition_list">
<varlistentry>
<term>label</term>
<listitem>
<para>A human-readable label that defines the associated group of parameters.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>description</term>
<listitem>
<para>A human-readable description of the parameter group.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>parameters</term>
<listitem>
<para>A list of parameters that belong with this parameter group.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>param name</term>
<listitem>
<para>The name of a parameter defined in the <literal>parameters</literal> section.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="hot-spec-parameters">
<?dbhtml stop-chunking?>
<title>Parameters section</title>
<para>The <literal>parameters</literal> section defines input parameters that have to be
provided when instantiating the template. Such parameters are typically used to
customize each deployment, or for binding to environment specifics like certain
images.</para>
<para>Each parameter is specified in a separated nested block with the name of the
parameter defined in the first line and additional attributes such as a type or
a default value defined as nested elements:</para>
<programlisting language="yaml">parameters:
&lt;param name&gt;:
type: &lt;string | number | json | comma_delimited_list | boolean&gt;
label: &lt;human-readable name of the parameter&gt;
description: &lt;description of the parameter&gt;
default: &lt;default value for parameter&gt;
hidden: &lt;true | false&gt;
constraints:
&lt;parameter constraints&gt;</programlisting>
<variablelist role="definition_list">
<varlistentry>
<term>param name</term>
<listitem>
<para>The name of the parameter.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>type</term>
<listitem>
<para>The type of the parameter. Supported types
are <literal>string</literal>, <literal>number</literal>, <literal>comma_delimited_list</literal>, <literal>json</literal> and
<literal>boolean</literal>.</para>
<para>This attribute is required.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>label</term>
<listitem>
<para>A human readable name for the parameter.</para>
<para>This attribute is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>description</term>
<listitem>
<para>A human readable description for the parameter.</para>
<para>This attribute is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>default</term>
<listitem>
<para>A default value for the parameter. This value is used if the user doesn't
specify his own value during deployment.</para>
<para>This attribute is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>hidden</term>
<listitem>
<para>Defines whether the parameters should be hidden when a user requests
information about a stack created from the template. This attribute can be
used to hide passwords specified as parameters.</para>
<para>This attribute is optional and defaults to <literal>false</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>constraints</term>
<listitem>
<para>A list of constraints to apply. The constraints are validated by the
Orchestration engine when a user deploys a stack. The stack creation fails
if the parameter value doesn't comply to the constraints.</para>
<para>This attribute is optional.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following example shows a minimalistic definition of two parameters:</para>
<programlisting language="yaml">parameters:
user_name:
type: string
label: User Name
description: User name to be configured for the application
port_number:
type: number
label: Port Number
description: Port number to be configured for the web server</programlisting>
<note>
<para>The description and the label are optional, but defining these attributes
is good practice to provide useful information about the role of the
parameter to the user.</para>
</note>
<section xml:id="hot-spec-parameters-constraints">
<title>Parameter constraints</title>
<para>The <literal>constraints</literal> block of a parameter definition defines
additional validation constraints that apply to the value of the
parameter. The parameter values provided by a user are validated against the
constraints at instantiation time. The constraints are defined as a list with
the following syntax:</para>
<programlisting language="yaml">constraints:
- &lt;constraint type&gt;: &lt;constraint definition&gt;
description: &lt;constraint description&gt;</programlisting>
<variablelist role="definition_list">
<varlistentry>
<term>constraint type</term>
<listitem>
<para>Type of constraint to apply. The set of currently supported constraints is
given below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>constraint definition</term>
<listitem>
<para>The actual constraint, depending on the constraint type. The
concrete syntax for each constraint type is given below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>description</term>
<listitem>
<para>A description of the constraint. The text
is presented to the user when the value he defines violates the constraint.
If omitted, a default validation message is presented to the user.</para>
<para>This attribute is optional.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following example shows the definition of a string parameter with two
constraints. Note that while the descriptions for each constraint are optional,
it is good practice to provide concrete descriptions to present useful messages
to the user at deployment time.</para>
<programlisting language="yaml">parameters:
user_name:
type: string
label: User Name
description: User name to be configured for the application
constraints:
- length: { min: 6, max: 8 }
description: User name must be between 6 and 8 characters
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
description: User name must start with an uppercase character</programlisting>
<note>
<para>While the descriptions for each constraint are optional, it is good practice
to provide concrete descriptions so useful messages can be presented to the
user at deployment time.</para>
</note>
<para>The following sections list the supported types of parameter constraints, along
with the syntax for each type.</para>
<section xml:id="length">
<title>length</title>
<para>The <literal>length</literal> constraint applies to parameters of type <literal>string</literal>. It defines
a lower and upper limit for the length of the string value.</para>
<para>The syntax of the <literal>length</literal> constraint is:</para>
<programlisting language="yaml">length: { min: &lt;lower limit&gt;, max: &lt;upper limit&gt; }</programlisting>
<para>It is possible to define a length constraint with only a lower limit or an
upper limit. However, at least one of <literal>min</literal> or <literal>max</literal> must be specified.</para>
</section>
<section xml:id="range">
<title>range</title>
<para>The <literal>range</literal> constraint applies to parameters of type <literal>number</literal>. It defines a
lower and upper limit for the numeric value of the parameter.</para>
<para>The syntax of the <literal>range</literal> constraint is:</para>
<programlisting language="yaml">range: { min: &lt;lower limit&gt;, max: &lt;upper limit&gt; }</programlisting>
<para>It is possible to define a range constraint with only a lower limit or an
upper limit. However, at least one of <literal>min</literal> or <literal>max</literal> must be specified.</para>
<para>The minimum and maximum boundaries are included in the range. For example, the
following range constraint would allow for all numeric values between 0 and 10:</para>
<programlisting language="yaml">range: { min: 0, max: 10 }</programlisting>
</section>
<section xml:id="allowed-values">
<title>allowed_values</title>
<para>The <literal>allowed_values</literal> constraint applies to parameters of type <literal>string</literal> or
<literal>number</literal>. It specifies a set of possible values for a parameter. At
deployment time, the user-provided value for the respective parameter must
match one of the elements of the list.</para>
<para>The syntax of the <literal>allowed_values</literal> constraint is:</para>
<programlisting language="yaml">allowed_values: [ &lt;value&gt;, &lt;value&gt;, ... ]</programlisting>
<para>Alternatively, the following YAML list notation can be used:</para>
<programlisting language="yaml">allowed_values:
- &lt;value&gt;
- &lt;value&gt;
- ...</programlisting>
<para>For example:</para>
<programlisting language="yaml">parameters:
instance_type:
type: string
label: Instance Type
description: Instance type for compute instances
constraints:
- allowed_values:
- m1.small
- m1.medium
- m1.large</programlisting>
</section>
<section xml:id="allowed-pattern">
<title>allowed_pattern</title>
<para>The <literal>allowed_pattern</literal> constraint applies to parameters of type <literal>string</literal>.
It specifies a regular expression against which a user-provided parameter value
must evaluate at deployment.</para>
<para>The syntax of the <literal>allowed_pattern</literal> constraint is:</para>
<programlisting language="yaml">allowed_pattern: &lt;regular expression&gt;</programlisting>
<para>For example:</para>
<programlisting language="yaml">parameters:
user_name:
type: string
label: User Name
description: User name to be configured for the application
constraints:
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
description: User name must start with an uppercase character</programlisting>
</section>
<section xml:id="custom-constraint">
<title>custom_constraint</title>
<para>The <literal>custom_constraint</literal> constraint adds an extra step of validation,
generally to check that the specified resource exists in the backend. Custom
constraints get implemented by plug-ins and can provide any kind of advanced
constraint validation logic.</para>
<para>The syntax of the <literal>custom_constraint</literal> constraint is:</para>
<programlisting language="yaml">custom_constraint: &lt;name&gt;</programlisting>
<para>The <literal>name</literal> attribute specifies the concrete type of custom constraint. It
corresponds to the name under which the respective validation plugin has been
registered in the Orchestration engine.</para>
<para>For example:</para>
<programlisting language="yaml">parameters:
key_name
type: string
description: SSH key pair
constraints:
- custom_constraint: nova.keypair</programlisting>
</section>
</section>
<section xml:id="hot-spec-pseudo-parameters">
<title>Pseudo Parameters</title>
<para>In addition to parameters defined by a template author, the Orchestration
module also creates two parameters for every stack that allow referential
access to the stack's name and identifier. These parameters are named
<literal>OS::stack_name</literal> for the stack name and <literal>OS::stack_id</literal> for the stack
identifier. These values are accessible via the <literal>get_param</literal> intrinsic
function, just like user-defined parameters.</para>
</section>
</section>
<section xml:id="hot-spec-resources">
<?dbhtml stop-chunking?>
<title>Resources section</title>
<para>The <literal>resources</literal> section defines actual resources that make up a stack
deployed from the HOT template (for instance compute instances, networks,
storage volumes).</para>
<para>Each resource is defined as a separate block in the <literal>resources</literal> section with
the following syntax:</para>
<programlisting language="yaml">resources:
&lt;resource ID&gt;:
type: &lt;resource type&gt;
properties:
&lt;property name&gt;: &lt;property value&gt;
metadata:
&lt;resource specific metadata&gt;
depends_on: &lt;resource ID or list of ID&gt;
update_policy: &lt;update policy&gt;
deletion_policy: &lt;deletion policy&gt;</programlisting>
<variablelist role="definition_list">
<varlistentry>
<term>resource ID</term>
<listitem>
<para>A resource ID which must be unique within the <literal>resources</literal> section of the
template.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>type</term>
<listitem>
<para>The resource type, such as <literal>OS::Nova::Server</literal> or <literal>OS::Neutron::Port</literal>.</para>
<para>This attribute is required.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>properties</term>
<listitem>
<para>A list of resource-specific properties. The property value can be provided
in place, or via a function (see <link linkend="hot-spec-intrinsic-functions"><emphasis>Intrinsic functions</emphasis></link>).</para>
<para>This section is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>metadata</term>
<listitem>
<para>Resource-specific metadata.</para>
<para>This section is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>depends_on</term>
<listitem>
<para>Dependencies of the resource on one or more resources of the template.</para>
<para>See <link linkend="hot-spec-resources-dependencies"><emphasis>Resource dependencies</emphasis></link> for details.</para>
<para>This attribute is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>update_policy</term>
<listitem>
<para>Update policy for the resource, in the form of a nested dictionary. Whether
update policies are supported and what the exact semantics are depends on
the type of the current resource.</para>
<para>This attribute is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>deletion_policy</term>
<listitem>
<para>Deletion policy for the resource. Which type of deletion policy is
supported depends on the type of the current resource.</para>
<para>This attribute is optional.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Depending on the type of resource, the resource block might include more
resource specific data.</para>
<para>All resource types that can be used in CFN templates can also be used in HOT
templates, adapted to the YAML structure as outlined above.</para>
<para>The following example demonstrates the definition of a simple compute resource
with some fixed property values:</para>
<programlisting language="yaml">resources:
my_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: F18-x86_64-cfntools</programlisting>
<section xml:id="hot-spec-resources-dependencies">
<title>Resource dependencies</title>
<para>The <literal>depends_on</literal> attribute of a resource defines a dependency between this
resource and one or more other resources.</para>
<para>If a resource depends on just one other resource, the ID of the other resource
is specified as string of the <literal>depends_on</literal> attribute, as shown in the
following example:</para>
<programlisting language="yaml">resources:
server1:
type: OS::Nova::Server
depends_on: server2
server2:
type: OS::Nova::Server</programlisting>
<para>If a resource depends on more than one other resources, the value of the
<literal>depends_on</literal> attribute is specified as a list of resource IDs, as shown in
the following example:</para>
<programlisting language="yaml">resources:
server1:
type: OS::Nova::Server
depends_on: [ server2, server3 ]
server2:
type: OS::Nova::Server
server3:
type: OS::Nova::Server</programlisting>
</section>
</section>
<section xml:id="hot-spec-outputs">
<?dbhtml stop-chunking?>
<title>Outputs section</title>
<para>The <literal>outputs</literal> section defines output parameters that should be available to
the user once a stack has been created. This would be, for example, parameters
such as IP addresses of deployed instances, or URLs of web applications
deployed as part of a stack.</para>
<para>Each output parameter is defined as a separate block within the outputs section
according to the following syntax:</para>
<programlisting language="yaml">outputs:
&lt;parameter name&gt;:
description: &lt;description&gt;
value: &lt;parameter value&gt;</programlisting>
<variablelist role="definition_list">
<varlistentry>
<term>parameter name</term>
<listitem>
<para>The output parameter name, which must be unique within the <literal>outputs</literal>
section of a template.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>description</term>
<listitem>
<para>A short description of the output parameter.</para>
<para>This attribute is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>parameter value</term>
<listitem>
<para>The value of the output parameter. This value is usually resolved by means
of a function. See <link linkend="hot-spec-intrinsic-functions"><emphasis>Intrinsic functions</emphasis></link> for details about
the functions.</para>
<para>This attribute is required.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The example below shows how the IP address of a compute resource can
be defined as an output parameter:</para>
<programlisting language="yaml">outputs:
instance_ip:
description: IP address of the deployed compute instance
value: { get_attr: [my_instance, first_address] }</programlisting>
</section>
<section xml:id="hot-spec-intrinsic-functions">
<?dbhtml stop-chunking?>
<title>Intrinsic functions</title>
<para>HOT provides a set of intrinsic functions that can be used inside templates
to perform specific tasks, such as getting the value of a resource attribute at
runtime. The following section describes the role and syntax of the intrinsic
functions.</para>
<section xml:id="get-attr">
<title>get_attr</title>
<para>The <literal>get_attr</literal> function references an attribute of a
resource. The attribute value is resolved at runtime using the resource
instance created from the respective resource definition.</para>
<para>The syntax of the <literal>get_attr</literal> function is:</para>
<programlisting language="yaml">get_attr:
- &lt;resource ID&gt;
- &lt;attribute name&gt;
- &lt;key/index 1&gt; (optional)
- &lt;key/index 2&gt; (optional)
- ...</programlisting>
<variablelist role="definition_list">
<varlistentry>
<term>resource ID</term>
<listitem>
<para>The resource ID for which the attribute needs to be resolved.</para>
<para>The resource ID must exist in the <literal>resources</literal> section of the template.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>attribute name</term>
<listitem>
<para>The attribute name to be resolved. If the attribute returns a complex data
structure such as a list or a map, then subsequent keys or indexes can be
specified. These additional parameters are used to navigate the data
structure to return the desired value.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following example demonstrates how to use the <literal>get_param</literal> function:</para>
<programlisting language="yaml">resources:
my_instance:
type: OS::Nova::Server
# ...
outputs:
instance_ip:
description: IP address of the deployed compute instance
value: { get_attr: [my_instance, first_address] }
instance_private_ip:
description: Private IP address of the deployed compute instance
value: { get_attr: [my_instance, networks, private, 0] }</programlisting>
<para>In this example, if the networks attribute contained the following data:</para>
<programlisting language="yaml">{"public": ["2001:0db8:0000:0000:0000:ff00:0042:8329", "1.2.3.4"],
"private": ["10.0.0.1"]}</programlisting>
<para>then the value of <literal>the get_attr</literal> function would resolve to <literal>10.0.0.1</literal>
(first item of the <literal>private</literal> entry in the <literal>networks</literal> map).</para>
</section>
<section xml:id="get-file">
<title>get_file</title>
<para>The <literal>get_file</literal> function returns the content of a file into the template.
It is generally used as a file inclusion mechanism for files
containing scripts or configuration files.</para>
<para>The syntax of <literal>the get_file</literal> function is:</para>
<programlisting language="yaml">get_file: &lt;content key&gt;</programlisting>
<para>The <literal>content key</literal> is used to look up the <literal>files</literal> dictionary that is
provided in the REST API call. The Orchestration client command
(<command>heat</command>) is <literal>get_file</literal> aware and will populate the <literal>files</literal>
dictionary with the actual content of fetched paths and URLs. The
Orchestration client command supports relative paths and will transform these
to the absolute URLs required by the Orchestration API.</para>
<note>
<para>The <literal>get_file</literal> argument must be a static path or URL and not rely on
intrinsic functions like <literal>get_param</literal>. the Orchestration client does not
process intrinsic functions (they are only processed by the Orchestration
engine).</para>
</note>
<para>The example below demonstrates the <literal>get_file</literal> function usage with both
relative and absolute URLs:</para>
<programlisting language="yaml">resources:
my_instance:
type: OS::Nova::Server
properties:
# general properties ...
user_data:
get_file: my_instance_user_data.sh
my_other_instance:
type: OS::Nova::Server
properties:
# general properties ...
user_data:
get_file: http://example.com/my_other_instance_user_data.sh</programlisting>
<para>The <literal>files</literal> dictionary generated by the Orchestration client during
instantiation of the stack would contain the following keys:
* <literal>file:///path/to/my_instance_user_data.sh</literal>
* <literal>http://example.com/my_other_instance_user_data.sh*</literal></para>
</section>
<section xml:id="get-param">
<title>get_param</title>
<para>The <literal>get_param</literal> function references an input parameter of a template. It
resolves to the value provided for this input parameter at runtime.</para>
<para>The syntax of the <literal>get_param</literal> function is:</para>
<programlisting language="yaml">get_param:
- &lt;parameter name&gt;
- &lt;key/index 1&gt; (optional)
- &lt;key/index 2&gt; (optional)
- ...</programlisting>
<variablelist role="definition_list">
<varlistentry>
<term>parameter name</term>
<listitem>
<para>The parameter name to be resolved. If the parameters returns a complex data
structure such as a list or a map, then subsequent keys or indexes can be
specified. These additional parameters are used to navigate the data
structure to return the desired value.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following example demonstrates the use of the <literal>get_param</literal> function:</para>
<programlisting language="yaml">parameters:
instance_type:
type: string
label: Instance Type
description: Instance type to be used.
server_data:
type: json
resources:
my_instance:
type: OS::Nova::Server
properties:
flavor: { get_param: instance_type}
metadata: { get_param: [ server_data, metadata ] }
key_name: { get_param: [ server_data, keys, 0 ] }</programlisting>
<para>In this example, if the <literal>instance_type</literal> and <literal>server_data</literal> parameters
contained the following data:</para>
<programlisting language="yaml">{"instance_type": "m1.tiny",
{"server_data": {"metadata": {"foo": "bar"},
"keys": ["a_key","other_key"]}}}</programlisting>
<para>then the value of the property <literal>flavor</literal> would resolve to <literal>m1.tiny</literal>,
<literal>metadata</literal> would resolve to <literal>{"foo": "bar"}</literal> and <literal>key_name</literal> would resolve
to <literal>a_key</literal>.</para>
</section>
<section xml:id="get-resource">
<title>get_resource</title>
<para>The <literal>get_resource</literal> function references another resource within the
same template. At runtime, it is resolved to reference the ID of the referenced
resource, which is resource type specific. For example, a reference to a
floating IP resource returns the respective IP address at runtime. The syntax
of the <literal>get_resource</literal> function is:</para>
<programlisting language="yaml">get_resource: &lt;resource ID&gt;</programlisting>
<para>The resource ID of the referenced resource is given as single parameter to the
get_resource function.</para>
<para>For example:</para>
<programlisting language="yaml">resources:
instance_port:
type: OS::Neutron::Port
properties: ...
instance:
type: OS::Nova::Server
properties:
...
networks:
port: { get_resource: instance_port }</programlisting>
</section>
<section xml:id="list-join">
<title>list_join</title>
<para>The <literal>list_join</literal> function joins a list of strings with the given delimiter.</para>
<para>The syntax of the <literal>list_join</literal> function is:</para>
<programlisting language="yaml">list_join:
- &lt;delimiter&gt;
- &lt;list to join&gt;</programlisting>
<para>For example:</para>
<programlisting language="yaml">list_join: [', ', ['one', 'two', 'and three']]</programlisting>
<para>This resolve to the string <literal>one, two, and three</literal>.</para>
</section>
<section xml:id="resource-facade">
<title>resource_facade</title>
<para>The <literal>resource_facade</literal> function retrieves data in a parent provider template.</para>
<para>A provider template provides a custom definition of a resource, called its
facade. For more information about custom templates, see <xref linkend="composition"/>.
The syntax of the <literal>resource_facade</literal> function is:</para>
<programlisting language="yaml">resource_facade: &lt;data type&gt;</programlisting>
<para><literal>data type</literal> can be one of <literal>metadata</literal>, <literal>deletion_policy</literal> or
<literal>update_policy</literal>.</para>
</section>
<section xml:id="str-replace">
<title>str_replace</title>
<para>The <literal>str_replace</literal> function dynamically constructs strings by
providing a template string with placeholders and a list of mappings to assign
values to those placeholders at runtime. The placeholders are replaced with
mapping values wherever a mapping key exactly matches a placeholder.</para>
<para>The syntax of the <literal>str_replace</literal> function is:</para>
<programlisting language="yaml">str_replace:
template: &lt;template string&gt;
params: &lt;parameter mappings&gt;</programlisting>
<variablelist role="definition_list">
<varlistentry>
<term>template</term>
<listitem>
<para>Defines the template string that contains placeholders which will be
substituted at runtime.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>params</term>
<listitem>
<para>Provides parameter mappings in the form of dictionary. Each key refers to a
placeholder used in the <literal>template</literal> attribute.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following example shows a simple use of the <literal>str_replace</literal> function in the
outputs section of a template to build a URL for logging into a deployed
application:</para>
<programlisting language="yaml">resources:
my_instance:
type: OS::Nova::Server
# general metadata and properties ...
outputs:
Login_URL:
description: The URL to log into the deployed application
value:
str_replace:
template: http://host/MyApplication
params:
host: { get_attr: [ my_instance, first_address ] }</programlisting>
<para>The following examples show the use of the <literal>str_replace</literal> function to build an
instance initialization script:</para>
<programlisting language="yaml">parameters:
DBRootPassword:
type: string
label: Database Password
description: Root password for MySQL
hidden: true
resources:
my_instance:
type: OS::Nova::Server
properties:
# general properties ...
user_data:
str_replace:
template: |
#!/bin/bash
echo "Hello world"
echo "Setting MySQL root password"
mysqladmin -u root password $db_rootpassword
# do more things ...
params:
$db_rootpassword: { get_param: DBRootPassword }</programlisting>
</section>
</section>
</section>

719
doc/user-guide/hot/section_software_deployment.xml
View File

@ -1,719 +0,0 @@
<?xml version='1.0' encoding='UTF-8'?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="hot-software-deployment">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Software configuration</title>
<para>There are a variety of options to configure the software which runs on the
servers in your stack. These can be broadly divided into the following:</para>
<itemizedlist>
<listitem>
<para>Custom image building</para>
</listitem>
<listitem>
<para>User-data boot scripts and cloud-init</para>
</listitem>
<listitem>
<para>Software deployment resources</para>
</listitem>
</itemizedlist>
<para>This section will describe each of these options and provide examples for
using them together in your stacks.</para>
<section xml:id="image-building">
<?dbhtml stop-chunking?>
<title>Image building</title>
<para>The first opportunity to influence what software is configured on your servers
is by booting them with a custom-built image. There are a number of reasons
you might want to do this, including:</para>
<itemizedlist>
<listitem>
<para><emphasis role="Boot speed"/> - since the required software is already on the image there
is no need to download and install anything at boot time.</para>
</listitem>
<listitem>
<para><emphasis role="Boot reliability"/> - software downloads can fail for a number of reasons
including transient network failures and inconsistent software repositories.</para>
</listitem>
<listitem>
<para><emphasis role="Test verification"/> - custom built images can be verified in test
environments before being promoted to production.</para>
</listitem>
<listitem>
<para><emphasis role="Configuration dependencies"/> - post-boot configuration may depend on
agents already being installed and enabled</para>
</listitem>
</itemizedlist>
<para>A number of tools are available for building custom images, including:</para>
<itemizedlist>
<listitem>
<para><link xlink:href="http://git.openstack.org/cgit/openstack/diskimage-builder">diskimage-builder</link> image building tools for OpenStack</para>
</listitem>
<listitem>
<para><link xlink:href="http://imgfac.org/">imagefactory</link> builds images for a variety of operating system/cloud
combinations</para>
</listitem>
</itemizedlist>
<para>Examples in this guide which require custom images will use <link xlink:href="http://git.openstack.org/cgit/openstack/diskimage-builder">diskimage-builder</link>.</para>
</section>
<section xml:id="user-data-boot-scripts-and-cloud-init">
<?dbhtml stop-chunking?>
<title>User-data boot scripts and cloud-init</title>
<para>When booting a server it is possible to specify the contents of the user-data
to be passed to that server. This user-data is made available either from
configured config-drive or from the <link xlink:href="http://docs.openstack.org/admin-guide-cloud/content/section_metadata-service.html">Metadata service</link>.</para>
<para>How this user-data is consumed depends on the image being booted, but the most
commonly used tool for default cloud images is <link xlink:href="http://cloudinit.readthedocs.org/en/latest/">Cloud-init</link>.</para>
<para>Whether the image is using <link xlink:href="http://cloudinit.readthedocs.org/en/latest/">Cloud-init</link> or not, it should be possible to
specify a shell script in the user_data property and have it be executed by
the server during boot:</para>
<programlisting language="yaml">resources:
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data: |
#!/bin/bash
echo "Running boot script"
# ...</programlisting>
<!---->
<blockquote>
<para><emphasis role="Tip"/>: debugging these scripts it is often useful to view the boot
log using <literal>nova console-log &lt;server-id&gt;</literal> to view the progress of boot
script execution.</para>
</blockquote>
<para>Often there is a need to set variable values based on parameters or resources
in the stack. This can be done with the <literal>str_replace</literal> intrinsic function:</para>
<programlisting language="yaml">parameters:
foo:
default: bar
resources:
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data:
str_replace:
template: |
#!/bin/bash
echo "Running boot script with $FOO"
# ...
params:
$FOO: {get_param: foo}</programlisting>
<!---->
<blockquote>
<para><emphasis role="Warning"/>: If a stack-update is performed and there are any changes
at all to the content of user_data then the server will be replaced
(deleted and recreated) so that the modified boot configuration can be
run on a new server.</para>
</blockquote>
<para>When these scripts grow it can become difficult to maintain them inside the
template, so the <literal>get_file</literal> intrinsic function can be used to maintain the
script in a separate file:</para>
<programlisting language="yaml">parameters:
foo:
default: bar
resources:
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data:
str_replace:
template: {get_file: the_server_boot.sh}
params:
$FOO: {get_param: foo}</programlisting>
<!---->
<blockquote>
<para><emphasis role="Tip"/>: <literal>str_replace</literal> can replace any strings, not just strings
starting with <literal>$</literal>. However doing this for the above example is useful
because the script file can be executed for testing by passing in
environment variables.</para>
</blockquote>
<section xml:id="choosing-the-user-data-format">
<title>Choosing the user_data_format</title>
<para>The <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> user_data_format property determines how the
user_data should be formatted for the server. For the default value
<literal>HEAT_CFNTOOLS</literal>, the user_data is bundled as part of the heat-cfntools
cloud-init boot configuration data. While <literal>HEAT_CFNTOOLS</literal> is the default
for <literal>user_data_format</literal>, it is considered legacy and <literal>RAW</literal> or
<literal>SOFTWARE_CONFIG</literal> will generally be more appropriate.</para>
<para>For <literal>RAW</literal> the user_data is passed to Nova unmodified. For a <link xlink:href="http://cloudinit.readthedocs.org/en/latest/">Cloud-init</link>
enabled image, the following are both valid <literal>RAW</literal> user-data:</para>
<programlisting language="yaml">resources:
server_with_boot_script:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: |
#!/bin/bash
echo "Running boot script"
# ...
server_with_cloud_config:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: |
#cloud-config
final_message: "The system is finally up, after $UPTIME seconds"</programlisting>
<para>For <literal>SOFTWARE_CONFIG</literal> user_data is bundled as part of the software config
data, and metadata is derived from any associated
<link linkend="software-deployment-resources">Software deployment resources</link>.</para>
</section>
<section xml:id="signals-and-wait-conditions">
<title>Signals and wait conditions</title>
<para>Often it is necessary to pause further creation of stack resources until the
boot configuration script has notified that it has reached a certain state.
This is usually either to notify that a service is now active, or to pass out
some generated data which is needed by another resource. The resources
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__WaitCondition.html">OS::Heat::WaitCondition</link></literal> and <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SwiftSignal.html">OS::Heat::SwiftSignal</link></literal> both perform
this function using different techniques and tradeoffs.</para>
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__WaitCondition.html">OS::Heat::WaitCondition</link></literal> is implemented as a call to the
<link xlink:href="http://developer.openstack.org/api-ref-orchestration-v1.html">Orchestration API</link> resource signal. The token is created using credentials
for a user account which is scoped only to the wait condition handle
resource. This user is created when the handle is created, and is associated
to a project which belongs to the stack, in an identity domain which is
dedicated to the orchestration service.</para>
<para>Sending the signal is a simple HTTP request, as with this example using <link xlink:href="http://curl.haxx.se/">curl</link>:</para>
<programlisting language="sh">curl -i -X POST -H 'X-Auth-Token: &lt;token&gt;' \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
'&lt;wait condition URL&gt;' --data-binary '&lt;json containing signal data&gt;'</programlisting>
<para>The JSON containing the signal data is expected to be of the following format:</para>
<programlisting language="json">{
"status": "SUCCESS",
"reason": "The reason which will appear in the 'heat event-list' output",
"data": "Data to be used elsewhere in the template via get_attr",
"id": "Optional unique ID of signal"
}</programlisting>
<para>All of these values are optional, and if not specified will be set to the
following defaults:</para>
<programlisting language="json">{
"status": "SUCCESS",
"reason": "Signal &lt;id&gt; received",
"data": null,
"id": "&lt;sequential number starting from 1 for each signal received&gt;"
}</programlisting>
<para>If <literal>status</literal> is set to <literal>FAILURE</literal> then the resource (and the stack) will go
into a <literal>FAILED</literal> state using the <literal>reason</literal> as failure reason.</para>
<para>The following template example uses the convenience attribute <literal>curl_cli</literal>
which builds a curl command with a valid token:</para>
<programlisting language="yaml">resources:
wait_condition:
type: OS::Heat::WaitCondition
properties:
handle: {get_resource: wait_handle}
# Note, count of 5 vs 6 is due to duplicate signal ID 5 sent below
count: 5
timeout: 300
wait_handle:
type: OS::Heat::WaitConditionHandle
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data:
str_replace:
template: |
#!/bin/sh
# Below are some examples of the various ways signals
# can be sent to the Handle resource
# Simple success signal
wc_notify --data-binary '{"status": "SUCCESS"}'
# Or you optionally can specify any of the additional fields
wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal2"}'
wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal3", "data": "data3"}'
wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal4", "data": "data4"}'
# If you require control of the ID, you can pass it.
# The ID should be unique, unless you intend for duplicate
# signals to overwrite each other. The following two calls
# do the exact same thing, and will be treated as one signal
# (You can prove this by changing count above to 7)
wc_notify --data-binary '{"status": "SUCCESS", "id": "5"}'
wc_notify --data-binary '{"status": "SUCCESS", "id": "5"}'
# Example of sending a failure signal, optionally
# reason, id, and data can be specified as above
# wc_notify --data-binary '{"status": "FAILURE"}'
params:
wc_notify: { get_attr: [wait_handle, curl_cli] }
outputs:
wc_data:
value: { get_attr: [wait_condition, data] }
# this would return the following json
# {"1": null, "2": null, "3": "data3", "4": "data4", "5": null}
wc_data_4:
value: { get_attr: [wait_condition, data, '4'] }
# this would return "data4"</programlisting>
<!---->
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SwiftSignal.html">OS::Heat::SwiftSignal</link></literal> is implemented by creating an Object Storage
API temporary URL which is populated with signal data with an HTTP PUT. The
orchestration service will poll this object until the signal data is available.
Object versioning is used to store multiple signals.</para>
<para>Sending the signal is a simple HTTP request, as with this example using <link xlink:href="http://curl.haxx.se/">curl</link>:</para>
<programlisting language="sh">curl -i -X PUT '&lt;object URL&gt;' --data-binary '&lt;json containing signal data&gt;'</programlisting>
<para>The above template example only needs to have the <literal>type</literal> changed to the
swift signal resources:</para>
<programlisting language="yaml">resources:
signal:
type: OS::Heat::SwiftSignal
properties:
handle: {get_resource: wait_handle}
timeout: 300
signal_handle:
type: OS::Heat::SwiftSignalHandle
# ...</programlisting>
<para>The decision to use <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__WaitCondition.html">OS::Heat::WaitCondition</link></literal> or
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SwiftSignal.html">OS::Heat::SwiftSignal</link></literal> will depend on a few factors:</para>
<itemizedlist>
<listitem>
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SwiftSignal.html">OS::Heat::SwiftSignal</link></literal> depends on the availability of an Object
Storage API</para>
</listitem>
<listitem>
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__WaitCondition.html">OS::Heat::WaitCondition</link></literal> depends on whether the orchestration
service has been configured with a dedicated stack domain (which may depend
on the availability of an Identity V3 API).</para>
</listitem>
<listitem>
<para>The preference to protect signal URLs with token authentication or a
secret webhook URL.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="software-config-resources">
<title>Software config resources</title>
<para>Boot configuration scripts can also be managed as their own resources. This
allows configuration to be defined once and run on multiple server resources.
These software-config resources are stored and retrieved via dedicated calls
to the <link xlink:href="http://developer.openstack.org/api-ref-orchestration-v1.html">Orchestration API</link>. It is not possible to modify the contents of an
existing software-config resource, so a stack-update which changes any
existing software-config resource will result in API calls to create a new
config and delete the old one.</para>
<para>The resource <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareConfig.html">OS::Heat::SoftwareConfig</link></literal> is used for storing configs
represented by text scripts, for example:</para>
<programlisting language="yaml">resources:
boot_script:
type: OS::Heat::SoftwareConfig
properties:
group: ungrouped
config: |
#!/bin/bash
echo "Running boot script"
# ...
server_with_boot_script:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: {get_resource: boot_script}</programlisting>
<para>The resource <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__CloudConfig.html">OS::Heat::CloudConfig</link></literal> allows <link xlink:href="http://cloudinit.readthedocs.org/en/latest/">Cloud-init</link> cloud-config to
be represented as template YAML rather than a block string. This allows
intrinsic functions to be included when building the cloud-config. This also
ensures that the cloud-config is valid YAML, although no further checks for
valid cloud-config are done.</para>
<programlisting language="yaml">parameters:
file_content:
type: string
description: The contents of the file /tmp/file
resources:
boot_config:
type: OS::Heat::CloudConfig
properties:
cloud_config:
write_files:
- path: /tmp/file
content: {get_param: file_content}
server_with_cloud_config:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: {get_resource: boot_config}</programlisting>
<!---->
<para>The resource <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__MultipartMime.html">OS::Heat::MultipartMime</link></literal> allows multiple
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareConfig.html">OS::Heat::SoftwareConfig</link></literal> and <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__CloudConfig.html">OS::Heat::CloudConfig</link></literal>
resources to be combined into a single <link xlink:href="http://cloudinit.readthedocs.org/en/latest/">Cloud-init</link> multi-part message:</para>
<programlisting language="yaml">parameters:
file_content:
type: string
description: The contents of the file /tmp/file
other_config:
type: string
description: The ID of a software-config resource created elsewhere
resources:
boot_config:
type: OS::Heat::CloudConfig
properties:
cloud_config:
write_files:
- path: /tmp/file
content: {get_param: file_content}
boot_script:
type: OS::Heat::SoftwareConfig
properties:
group: ungrouped
config: |
#!/bin/bash
echo "Running boot script"
# ...
server_init:
type: OS::Heat::MultipartMime
properties:
parts:
- config: {get_resource: boot_config}
- config: {get_resource: boot_script}
- config: {get_resource: other_config}
server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: {get_resource: server_init}</programlisting>
<!---->
</section>
</section>
<section xml:id="software-deployment-resources">
<?dbhtml stop-chunking?>
<title>Software deployment resources</title>
<para>There are many situations where it is not desirable to replace the server
whenever there is a configuration change. The
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareDeployment.html">OS::Heat::SoftwareDeployment</link></literal> resource allows any number of software
configurations to be added or removed from a server throughout its life-cycle.</para>
<section xml:id="building-custom-image-for-software-deployments">
<title>Building custom image for software deployments</title>
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareConfig.html">OS::Heat::SoftwareConfig</link></literal> resources are used to store software
configuration, and a <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareDeployment.html">OS::Heat::SoftwareDeployment</link></literal> resource is used
to associate a config resource with one server. The <literal>group</literal> attribute on
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareConfig.html">OS::Heat::SoftwareConfig</link></literal> specifies what tool will consume the
config content.</para>
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareConfig.html">OS::Heat::SoftwareConfig</link></literal> has the ability to define a schema of
<literal>inputs</literal> and which the configuration script supports. Inputs are mapped to
whatever concept the configuration tool has for assigning
variables/parameters.</para>
<para>Likewise, <literal>outputs</literal> are mapped to the tool's capability to export structured
data after configuration execution. For tools which do not support this,
outputs can always be written to a known file path for the hook to read.</para>
<para>The <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareDeployment.html">OS::Heat::SoftwareDeployment</link></literal> resource allows values to be
assigned to the config inputs, and the resource remains in an <literal>IN_PROGRESS</literal>
state until the server signals to heat what (if any) output values were
generated by the config script.</para>
</section>
<section xml:id="custom-image-script">
<title>Custom image script</title>
<para>Each of the following examples requires that the servers be booted with a
custom image. The following script uses diskimage-builder to create an image
required in later examples:</para>
<programlisting language="sh"># Clone the required repositories. Some of these are also available
# via pypi or as distro packages.
git clone https://git.openstack.org/openstack/diskimage-builder.git
git clone https://git.openstack.org/openstack/tripleo-image-elements.git
git clone https://git.openstack.org/openstack/heat-templates.git
# Required by diskimage-builder to discover element collections
export ELEMENTS_PATH=tripleo-image-elements/elements:heat-templates/hot/software-config/elements
# The base operating system element(s) provided by the diskimage-builder
# elements collection. Other values which may work include:
# centos7, debian, opensuse, rhel, rhel7, or ubuntu
export BASE_ELEMENTS="fedora selinux-permissive"
# Install and configure the os-collect-config agent to poll the heat service
# for configuration changes to execute
export AGENT_ELEMENTS="os-collect-config os-refresh-config os-apply-config"
# heat-config installs an os-refresh-config script which will invoke the
# appropriate hook to perform configuration. The element heat-config-script
# installs a hook to perform configuration with shell scripts
export DEPLOYMENT_BASE_ELEMENTS="heat-config heat-config-script"
# Install a hook for any other chosen configuration tool(s).
# Elements which install hooks include:
# heat-config-cfn-init, heat-config-puppet, or heat-config-salt
export DEPLOYMENT_TOOL=""
# The name of the qcow2 image to create, and the name of the image
# uploaded to the OpenStack image registry.
export IMAGE_NAME=fedora-software-config
# Create the image
diskimage-builder/bin/disk-image-create vm $BASE_ELEMENTS $AGENT_ELEMENTS \
$DEPLOYMENT_BASE_ELEMENTS $DEPLOYMENT_TOOL -o $IMAGE_NAME.qcow2
# Upload the image, assuming valid credentials are already sourced
glance image-create --disk-format qcow2 --container-format bare \
--name $IMAGE_NAME &lt; $IMAGE_NAME.qcow2</programlisting>
<!---->
</section>
<section xml:id="configuring-with-scripts">
<title>Configuring with scripts</title>
<para>The <link linkend="custom-image-script">Custom image script</link> already includes the <literal>heat-config-script</literal> element
so the built image will already have the ability to configure using shell
scripts.</para>
<para>Config inputs are mapped to shell environment variables. The script can
communicate outputs to heat by writing to the file
<literal>$heat_outputs_path.&lt;output name&gt;</literal>. See the following example for a script
which expects inputs <literal>foo</literal>, <literal>bar</literal> and generates an output <literal>result</literal>.</para>
<programlisting language="yaml">resources:
config:
type: OS::Heat::SoftwareConfig
properties:
group: script
inputs:
- name: foo
- name: bar
outputs:
- name: result
config: |
#!/bin/sh -x
echo "Writing to /tmp/$bar"
echo $foo &gt; /tmp/$bar
echo -n "The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action" &gt; $heat_outputs_path.result
echo "Written to /tmp/$bar"
echo "Output to stderr" 1&gt;&amp;2
deployment:
type: OS::Heat::SoftwareDeployment
properties:
config:
get_resource: config
server:
get_resource: server
input_values:
foo: fooooo
bar: baaaaa
server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: SOFTWARE_CONFIG
outputs:
result:
value:
get_attr: [deployment, result]
stdout:
value:
get_attr: [deployment, deploy_stdout]
stderr:
value:
get_attr: [deployment, deploy_stderr]
status_code:
value:
get_attr: [deployment, deploy_status_code]</programlisting>
<!---->
<blockquote>
<para><emphasis role="Tip"/>: A config resource can be associated with multiple deployment
resources, and each deployment can specify the same or different values
for the <literal>server</literal> and <literal>input_values</literal> properties.</para>
</blockquote>
<para>As can be seen in the <literal>outputs</literal> section of the above template, the
<literal>result</literal> config output value is available as an attribute on the
<literal>deployment</literal> resource. Likewise the captured stdout, stderr and status_code
are also available as attributes.</para>
</section>
<section xml:id="configuring-with-os-apply-config">
<title>Configuring with os-apply-config</title>
<para>The agent toolchain of <literal>os-collect-config</literal>, <literal>os-refresh-config</literal> and
<literal>os-apply-config</literal> can actually be used on their own to inject heat stack
configuration data into a server running a custom image.</para>
<para>The custom image needs to have the following to use this approach:</para>
<itemizedlist>
<listitem>
<para>All software dependencies installed</para>
</listitem>
<listitem>
<para><link xlink:href="http://git.openstack.org/cgit/openstack/os-refresh-config">os-refresh-config</link> scripts to be executed on configuration changes</para>
</listitem>
<listitem>
<para><link xlink:href="http://git.openstack.org/cgit/openstack/os-apply-config">os-apply-config</link> templates to transform the heat-provided config data into
service configuration files</para>
</listitem>
</itemizedlist>
<para>The projects <link xlink:href="http://git.openstack.org/cgit/openstack/tripleo-image-elements">tripleo-image-elements</link> and <link xlink:href="http://git.openstack.org/cgit/openstack/tripleo-heat-templates">tripleo-heat-templates</link> demonstrate
this approach.</para>
</section>
<section xml:id="configuring-with-cfn-init">
<title>Configuring with cfn-init</title>
<para>Likely the only reason to use the <literal>cfn-init</literal> hook is to migrate templates
which contain <link xlink:href="http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html">AWS::CloudFormation::Init</link> metadata without needing a
complete rewrite of the config metadata. It is included here as it introduces
a number of new concepts.</para>
<para>To use the <literal>cfn-init</literal> tool the <literal>heat-config-cfn-init</literal> element is required
to be on the built image, so <link linkend="custom-image-script">Custom image script</link> needs to be modified with
the following:</para>
<programlisting language="sh">export DEPLOYMENT_TOOL="heat-config-cfn-init"</programlisting>
<!---->
<para>Configuration data which used to be included in the
<literal>AWS::CloudFormation::Init</literal> section of resource metadata is instead moved
to the <literal>config</literal> property of the config resource, as in the following
example:</para>
<programlisting language="yaml">resources:
config:
type: OS::Heat::StructuredConfig
properties:
group: cfn-init
inputs:
- name: bar
config:
config:
files:
/tmp/foo:
content:
get_input: bar
mode: '000644'
deployment:
type: OS::Heat::StructuredDeployment
properties:
name: 10_deployment
signal_transport: NO_SIGNAL
config:
get_resource: config
server:
get_resource: server
input_values:
bar: baaaaa
other_deployment:
type: OS::Heat::StructuredDeployment
properties:
name: 20_other_deployment
signal_transport: NO_SIGNAL
config:
get_resource: config
server:
get_resource: server
input_values:
bar: barmy
server:
type: OS::Nova::Server
properties:
image: {get_param: image}
flavor: {get_param: flavor}
key_name: {get_param: key_name}
user_data_format: SOFTWARE_CONFIG</programlisting>
<!---->
<para>There are a number of things to note about this template example:</para>
<itemizedlist>
<listitem>
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__StructuredConfig.html">OS::Heat::StructuredConfig</link></literal> is like
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareConfig.html">OS::Heat::SoftwareConfig</link></literal> except that the <literal>config</literal> property
contains structured YAML instead of text script. This is useful for a
number of other configuration tools including ansible, salt and
os-apply-config.</para>
</listitem>
<listitem>
<para><literal>cfn-init</literal> has no concept of inputs, so <literal>{get_input: bar}</literal> acts as a
placeholder which gets replaced with the
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__StructuredDeployment.html">OS::Heat::StructuredDeployment</link></literal><literal>input_values</literal> value when the
deployment resource is created.</para>
</listitem>
<listitem>
<para><literal>cfn-init</literal> has no concept of outputs, so specifying
<literal>signal_transport: NO_SIGNAL</literal> will mean that the deployment resource will
immediately go into the <literal>CREATED</literal> state instead of waiting for a
completed signal from the server.</para>
</listitem>
<listitem>
<para>The template has 2 deployment resources deploying the same config with
different <literal>input_values</literal>. The order these are deployed in on the server
is determined by sorting the values of the <literal>name</literal> property for each
resource (10_deployment, 20_other_deployment)</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="configuring-with-puppet">
<title>Configuring with puppet</title>
<para>The <link xlink:href="http://puppetlabs.com/">puppet</link> hook makes it possible to write configuration as puppet manifests
which are deployed and run in a masterless environment.</para>
<para>To specify configuration as puppet manifests the <literal>heat-config-puppet</literal>
element is required to be on the built image, so <link linkend="custom-image-script">Custom image script</link> needs
to be modified with the following:</para>
<programlisting language="sh">export DEPLOYMENT_TOOL="heat-config-puppet"</programlisting>
<!---->
<programlisting language="yaml">resources:
config:
type: OS::Heat::SoftwareConfig
properties:
group: puppet
inputs:
- name: foo
- name: bar
outputs:
- name: result
config:
get_file: example-puppet-manifest.pp
deployment:
type: OS::Heat::SoftwareDeployment
properties:
config:
get_resource: config
server:
get_resource: server
input_values:
foo: fooooo
bar: baaaaa
server:
type: OS::Nova::Server
properties:
image: {get_param: image}
flavor: {get_param: flavor}
key_name: {get_param: key_name}
user_data_format: SOFTWARE_CONFIG
outputs:
result:
value:
get_attr: [deployment, result]
stdout:
value:
get_attr: [deployment, deploy_stdout]</programlisting>
<!---->
<para>This demonstrates the use of the <literal>get_file</literal> function, which will attach the
contents of the file <literal>example-puppet-manifest.pp</literal>, containing:</para>
<programlisting language="puppet">file { 'barfile':
ensure =&gt; file,
mode =&gt; '0644',
path =&gt; '/tmp/$::bar',
content =&gt; '$::foo',
}
file { 'output_result':
ensure =&gt; file,
path =&gt; '$::heat_outputs_path.result',
mode =&gt; '0644',
content =&gt; 'The file /tmp/$::bar contains $::foo',
}</programlisting>
<!---->
</section>
</section>
</section>

11178
doc/user-guide/locale/fr.po
View File

File diff suppressed because it is too large Load Diff

11174
doc/user-guide/locale/ja.po
View File

File diff suppressed because it is too large Load Diff

8041
doc/user-guide/locale/user-guide.pot
View File

File diff suppressed because it is too large Load Diff

81
doc/user-guide/pom.xml
View File

@ -1,81 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>
<groupId>org.openstack.docs</groupId>
<artifactId>parent-pom</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>openstack-user-guide</artifactId>
<packaging>jar</packaging>
<name>OpenStack User Guide</name>
<properties>
<!-- This is set by Jenkins according to the branch. -->
<release.path.name>local</release.path.name>
<comments.enabled>1</comments.enabled>
</properties>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
<build>
<plugins>
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<!-- version is set in ../pom.xml file -->
<executions>
<!-- Configuration for OpenStack End User Guide -->
<execution>
<id>generate-webhelp</id>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<profileAudience>enduser</profileAudience>
<includes> bk-user-guide.xml</includes>
<generateToc>
appendix toc,title
article/appendix nop
article toc,title
book toc,title,figure,table,example,equation
chapter toc,title
section toc
part toc,title
qandadiv toc
qandaset toc
reference toc,title
set toc,title
</generateToc>
<webhelpDirname>user-guide</webhelpDirname>
<pdfFilenameBase>user-guide</pdfFilenameBase>
</configuration>
</execution>
</executions>
<configuration>
<profileAudience>enduser</profileAudience>
<chapterAutolabel>1</chapterAutolabel>
<sectionAutolabel>0</sectionAutolabel>
<tocSectionDepth>1</tocSectionDepth>
<formalProcedures>0</formalProcedures>
<highlightSource>false</highlightSource>
<xincludeSupported>true</xincludeSupported>
<showXslMessages>true</showXslMessages>
<sourceDirectory>.</sourceDirectory>
<feedbackEmail>diane.fleming@rackspace.com</feedbackEmail>
<branding>openstack</branding>
<enableDisqus>${comments.enabled}</enableDisqus>
<disqusShortname>os-user-guide</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
<suppressFooterNavigation>0</suppressFooterNavigation>
<canonicalUrlBase>http://docs.openstack.org/user-guide/content</canonicalUrlBase>
<glossaryCollection>${basedir}/../glossary/glossary-terms.xml</glossaryCollection>
</configuration>
</plugin>
</plugins>
</build>
</project>

29
doc/user-guide/roadmap.rst
View File

@ -1,29 +0,0 @@
Roadmap for End User Guide
--------------------------
This file is stored with the source to offer ideas for what to work on.
Put your name next to a task if you want to work on it and put a WIP
review up on review.openstack.org.
May 20, 2014
To do tasks:
- Add a chapter describing the HOT templates for Orchestration, how to use them
- Add reference information about HOT templates for Orchestration;
attempt to automate
Ongoing tasks:
- Ensure it meets conventions and standards
- Continually update with latest OpenStack dashboard (horizon)
information including great descriptions of fields and why you set a
setting
- Continually add Python examples to SDK chapter
Wishlist tasks:
- Investigate moving to simpler markup and still enabling translation
- Replace all individual client commands (like keystone, nova) with
openstack client commands
- Create a new security group, boot a VM, and then add the newly
created security group to the running VM

6
doc/user-guide/samples/large-object-upload-next-segment-req.txt
View File

@ -1,6 +0,0 @@
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

6
doc/user-guide/samples/large-object-upload-segment-req.txt
View File

@ -1,6 +0,0 @@
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

24
doc/user-guide/samples/meta_data.json
View File

@ -1,24 +0,0 @@
{
"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"
}

33
doc/user-guide/samples/meta_data_ec2.json
View File

@ -1,33 +0,0 @@
{
"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"
]
}

17
doc/user-guide/samples/slo-manifest-example.txt
View File

@ -1,17 +0,0 @@
[
{
"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
}
]

6
doc/user-guide/samples/upload-manifest-req.txt
View File

@ -1,6 +0,0 @@
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}

1
doc/user-guide/samples/upload-manifest-resp.txt
View File

@ -1 +0,0 @@
[...]

7
doc/user-guide/samples/xml_curl.txt
View File

@ -1,7 +0,0 @@
curl -i https://dfw.servers.api.rackspacecloud.com/v2/$account/servers.xml \
-X POST \
-H "X-Auth-Project-Id: $account" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
-H "X-Auth-Token: $token" \
-T server_post_req.xml | ppxml

164
doc/user-guide/section_cli_ceilometer.xml
View File

@ -1,164 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="ceilometer_cli_commands">
<title>Measure cloud resources</title>
<para>Telemetry measures cloud resources in OpenStack. It collects data related to billing. Currently, this metering service is available through
only the <command>ceilometer</command> command-line client.</para>
<para>To model data, Telemetry uses the following abstractions:</para>
<variablelist wordsize="10">
<varlistentry>
<term><emphasis role="bold">Meter</emphasis></term>
<listitem>
<para>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
<literal>cpu_util</literal> meter exists for
each instance. The life cycle of a meter is
decoupled from the existence of its related
resource. The meter persists after the resource
goes away.</para>
<para>A meter has the following attributes:</para>
<itemizedlist>
<listitem>
<para>String name</para>
</listitem>
<listitem>
<para>A unit of measurement</para>
</listitem>
<listitem>
<para>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)</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Sample</emphasis></term>
<listitem>
<para>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 <emphasis role="italic">volume</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Statistic</emphasis></term>
<listitem>
<para>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:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">count</emphasis>.
The number of samples in each
period.</para>
</listitem>
<listitem>
<para><emphasis role="bold">max</emphasis>.
The maximum number of sample volumes in
each period.</para>
</listitem>
<listitem>
<para><emphasis role="bold">min</emphasis>.
The minimum number of sample volumes in
each period.</para>
</listitem>
<listitem>
<para><emphasis role="bold">avg</emphasis>.
The average of sample volumes over each
period.</para>
</listitem>
<listitem>
<para><emphasis role="bold">sum</emphasis>.
The sum of sample volumes over each
period.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">Alarm</emphasis></term>
<listitem>
<para>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 <literal>ok</literal>, <literal>alarm</literal>, and <literal>insufficient data</literal>.
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.</para>
</listitem>
</varlistentry>
</variablelist>
<para>This example uses the <command>heat</command> client to
create an auto-scaling stack and the
<command>ceilometer</command> client to measure
resources.</para>
<procedure>
<step>
<para>Create an auto-scaling stack by running the following command. The <literal>-f</literal> option
specifies the name of the stack template file, and the <literal>-P</literal> option specifies the
<literal>KeyName</literal> parameter as <literal>heat_key</literal>.</para>
<screen><prompt>$</prompt> <userinput>heat stack-create -f cfn/F17/AutoScalingCeilometer.yaml -P "KeyName=heat_key"</userinput></screen>
</step>
<step>
<para>List the heat resources that were created:</para>
<screen><prompt>$</prompt> <userinput>heat resource-list</userinput>
<computeroutput>+--------------------------+-----------------------------------------+-----------------+----------------------+
| resource_name | resource_type |resource_status | updated_time |
+--------------------------+-----------------------------------------+-----------------+----------------------+
| CfnUser | AWS::IAM::User |CREATE_COMPLETE | 2013-10-02T05:53:41Z |
| WebServerKeys | AWS::IAM::AccessKey |CREATE_COMPLETE | 2013-10-02T05:53:42Z |
| LaunchConfig | AWS::AutoScaling::LaunchConfiguration |CREATE_COMPLETE | 2013-10-02T05:53:43Z |
| ElasticLoadBalancer | AWS::ElasticLoadBalancing::LoadBalancer |UPDATE_COMPLETE | 2013-10-02T05:55:58Z |
| WebServerGroup | AWS::AutoScaling::AutoScalingGroup |CREATE_COMPLETE | 2013-10-02T05:55:58Z |
| WebServerScaleDownPolicy | AWS::AutoScaling::ScalingPolicy |CREATE_COMPLETE | 2013-10-02T05:56:00Z |
| WebServerScaleUpPolicy | AWS::AutoScaling::ScalingPolicy |CREATE_COMPLETE | 2013-10-02T05:56:00Z |
| CPUAlarmHigh | OS::Ceilometer::Alarm |CREATE_COMPLETE | 2013-10-02T05:56:02Z |
| CPUAlarmLow | OS::Ceilometer::Alarm |CREATE_COMPLETE | 2013-10-02T05:56:02Z |
+--------------------------+-----------------------------------------+-----------------+----------------------+</computeroutput></screen>
</step>
<step>
<para>List the alarms that are set:</para>
<screen><prompt>$</prompt> <userinput>ceilometer alarm-list</userinput>
<computeroutput>+--------------------------------------+------------------------------+-------------------+---------+------------+-------------------------------+
| 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 |
+--------------------------------------+------------------------------+-------------------+---------+------------+-----------------------------+</computeroutput></screen>
</step>
<step>
<para>List the meters that are set:</para>
<screen><prompt>$</prompt> <userinput>ceilometer meter-list</userinput>
<computeroutput>+--------------------------+------------+----------+-----------------------------------------------------------------------+------------------------------------+
| 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 |
+--------------------------+------------+----------+-----------------------------------------------------------------------+------------------------------------+</computeroutput></screen>
</step>
<step>
<para>List samples:</para>
<screen><prompt>$</prompt> <userinput>ceilometer sample-list -m cpu_util</userinput>
<computeroutput>+--------------------------------------+----------+-------+---------------+------+---------------------+
| Resource ID | Name | Type | Volume | Unit | Timestamp |
+--------------------------------------+----------+-------+---------------+------+---------------------+
| 3965b41b-81b0-4386-bea5-6ec37c8841c1 | cpu_util | gauge | 3.98333333333 | % | 2013-10-02T10:50:12 |
+--------------------------------------+----------+-------+---------------+------+---------------------+</computeroutput></screen>
</step>
<step>
<para>View statistics:</para>
<screen><prompt>$</prompt> <userinput>ceilometer statistics -m cpu_util</userinput>
<computeroutput>+--------+---------------------+---------------------+-------+---------------+---------------+---------------+---------------+----------+---------------------+---------------------+
| 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 |
+--------+---------------------+---------------------+-------+---------------+---------------+---------------+---------------+----------+---------------------+---------------------+</computeroutput></screen>
</step>
</procedure>
</section>

138
doc/user-guide/section_cli_heat.xml
View File

@ -1,138 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="heat-stack-create">
<?dbhtml stop-chunking?>
<title>Create and manage stacks</title>
<para>The Orchestration module enables you to orchestrate multiple composite cloud applications.
This module 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 <glossterm>Heat Orchestration Template (HOT)</glossterm> format through a REST
API.</para>
<para>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.</para>
<para>The template languages are described
in <link xlink:href="http://docs.openstack.org/developer/heat/template_guide/index.html">the
Template Guide</link> in the <link
xlink:href="http://docs.openstack.org/developer/heat/">Heat developer
documentation</link>.</para>
<section xml:id="create_stack">
<title>Create a stack from an example template file</title>
<itemizedlist>
<listitem>
<para>To create a stack, or template, from an <link
xlink:href="http://git.openstack.org/cgit/openstack/heat-templates"
>example template file</link>, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>heat stack-create mystack --template-file /<replaceable>PATH_TO_HEAT_TEMPLATES</replaceable>/WordPress_Single_Instance.template</userinput>
<userinput>--parameters "InstanceType=m1.large;DBUsername=<replaceable>USERNAME</replaceable>;DBPassword=<replaceable>PASSWORD</replaceable>;KeyName=<replaceable>HEAT_KEY</replaceable>;LinuxDistribution=F17"</userinput></screen>
<para>The <literal>--parameters</literal> values that
you specify depend on the parameters that are defined
in the template. If a website hosts the template file, you can specify the URL with the
<literal>--template-url</literal> parameter
instead of the <literal>--template-file</literal>
parameter.</para>
<para>The command returns the following output:</para>
<screen><computeroutput>+--------------------------------------+---------------+--------------------+----------------------+
| id | stack_name | stack_status | creation_time |
+--------------------------------------+---------------+--------------------+----------------------+
| 4c712026-dcd5-4664-90b8-0915494c1332 | mystack | CREATE_IN_PROGRESS | 2013-04-03T23:22:08Z |
+--------------------------------------+---------------+--------------------+----------------------+</computeroutput></screen>
</listitem>
<listitem>
<para>You can also use the
<command>template-validate</command> command
to validate a template file without creating a
stack from it.</para>
<note><para>Previous versions of the heat client
used <command>validate</command> instead of
<command>template-validate</command>, but
it has been deprecated in favor of
<command>template-validate</command>.
</para></note>
<para>To do so, run the following command:</para>
<screen><prompt>$</prompt> <userinput>heat template-validate --template-file /<replaceable>PATH_TO_HEAT_TEMPLATES</replaceable>/WordPress_Single_Instance.template</userinput></screen>
<para>If validation fails, the response returns an
error message.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="stack_info">
<title>Get information about stacks</title>
<para>To explore the state and history of a particular stack,
you can run a number of commands.</para>
<itemizedlist>
<listitem>
<para>To see which stacks are visible to the current
user, run the following command:</para>
<screen><prompt>$</prompt> <userinput>heat stack-list</userinput>
<computeroutput>+--------------------------------------+---------------+-----------------+----------------------+
| id | stack_name | stack_status | creation_time |
+--------------------------------------+---------------+-----------------+----------------------+
| 4c712026-dcd5-4664-90b8-0915494c1332 | mystack | CREATE_COMPLETE | 2013-04-03T23:22:08Z |
| 7edc7480-bda5-4e1c-9d5d-f567d3b6a050 | my-otherstack | CREATE_FAILED | 2013-04-03T23:28:20Z |
+--------------------------------------+---------------+-----------------+----------------------+</computeroutput></screen>
</listitem>
<listitem>
<para>To show the details of a stack, run the
following command:</para>
<screen><prompt>$</prompt> <userinput>heat stack-show mystack</userinput></screen>
</listitem>
<listitem>
<para>A stack consists of a collection of resources. To list the resources and their
status, run the following command:</para>
<screen><prompt>$</prompt> <userinput>heat resource-list mystack</userinput>
<computeroutput>+---------------------+--------------------+-----------------+----------------------+
| logical_resource_id | resource_type | resource_status | updated_time |
+---------------------+--------------------+-----------------+----------------------+
| WikiDatabase | AWS::EC2::Instance | CREATE_COMPLETE | 2013-04-03T23:25:56Z |
+---------------------+--------------------+-----------------+----------------------+</computeroutput></screen>
</listitem>
<listitem>
<para>To show the details for a specific resource in a stack, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>heat resource-show mystack WikiDatabase</userinput></screen></listitem>
<listitem><para>Some resources have associated metadata which can change throughout the life cycle of a
resource. Show the metadata by running the following command:</para>
<screen><prompt>$</prompt> <userinput>heat resource-metadata mystack WikiDatabase</userinput></screen>
</listitem>
<listitem>
<para>A series of events is generated during the life cycle of a stack. To display
life cycle events, run the following command::</para>
<screen><prompt>$</prompt> <userinput>heat event-list mystack</userinput>
<computeroutput>+---------------------+----+------------------------+-----------------+----------------------+
| logical_resource_id | id | resource_status_reason | resource_status | event_time |
+---------------------+----+------------------------+-----------------+----------------------+
| WikiDatabase | 1 | state changed | IN_PROGRESS | 2013-04-03T23:22:09Z |
| WikiDatabase | 2 | state changed | CREATE_COMPLETE | 2013-04-03T23:25:56Z |
+---------------------+----+------------------------+-----------------+----------------------+</computeroutput></screen>
</listitem>
<listitem>
<para>To show the details for a particular event, run
the following command:</para>
<screen><prompt>$</prompt> <userinput>heat event-show WikiDatabase 1</userinput></screen>
</listitem>
</itemizedlist>
</section>
<section xml:id="update_stack">
<title>Update a stack</title>
<para>To update an existing stack from a modified
template file, run a command like the following
command:</para>
<screen><prompt>$</prompt> <userinput>heat stack-update mystack --template-file /path/to/heat/templates/WordPress_Single_Instance_v2.template</userinput>
<userinput>--parameters "InstanceType=m1.large;DBUsername=wp;DBPassword=verybadpassword;KeyName=heat_key;LinuxDistribution=F17"</userinput>
<computeroutput>+--------------------------------------+---------------+-----------------+----------------------+
| id | stack_name | stack_status | creation_time |
+--------------------------------------+---------------+-----------------+----------------------+
| 4c712026-dcd5-4664-90b8-0915494c1332 | mystack | UPDATE_COMPLETE | 2013-04-03T23:22:08Z |
| 7edc7480-bda5-4e1c-9d5d-f567d3b6a050 | my-otherstack | CREATE_FAILED | 2013-04-03T23:28:20Z |
+--------------------------------------+---------------+-----------------+----------------------+</computeroutput></screen>
<para>Some resources are updated in-place, while
others are replaced with new resources.</para>
</section>
</section>

153
doc/user-guide/section_cli_nova_baremetal.xml
View File

@ -1,153 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="baremetal">
<title>Manage bare-metal nodes</title>
<para>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 tenant clouds such as a
high-performance computing cluster or for deploying OpenStack itself.</para>
<para>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.</para>
<note><para>Development efforts are focused on moving the driver out of the Compute
code base in the Icehouse release.</para></note>
<para>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.</para>
<itemizedlist>
<title>Commands</title>
<para>The following commands can be used to manage bare-metal nodes.</para>
<listitem>
<para><command>baremetal-interface-add</command>. Adds a network interface
to a bare-metal node.</para>
</listitem>
<listitem>
<para><command>baremetal-interface-list</command>. Lists network
interfaces associated with a bare-metal node.</para>
</listitem>
<listitem>
<para><command>baremetal-interface-remove</command>. Removes a network
interface from a bare-metal node.</para>
</listitem>
<listitem>
<para><command>baremetal-node-create</command>. Creates a bare-metal
node.</para>
</listitem>
<listitem>
<para><command>baremetal-node-delete</command>. Removes a bare-metal node
and any associated interfaces.</para>
</listitem>
<listitem>
<para><command>baremetal-node-list</command>. Lists available bare-metal
nodes.</para>
</listitem>
<listitem>
<para><command>baremetal-node-show</command>. Shows information about a
bare-metal node.</para>
</listitem>
</itemizedlist>
<section xml:id="cli_nova_baremetal-create">
<title>Create a bare-metal node</title>
<para>When you create a bare-metal node, your PM address, user name, and
password should match those that are configured in your hardware's
BIOS/IPMI configuration.</para>
<screen><prompt>$</prompt> <userinput>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</userinput></screen>
<para>The following example shows the command and results from creating
a node with the PM address <filename>1.2.3.4</filename>, the PM user name
<systemitem class="username">ipmi</systemitem>, and password <literal>ipmi</literal>.</para>
<screen><prompt>$</prompt> <userinput>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</userinput>
<computeroutput>+------------------+-------------------+
| 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 |
+------------------+-------------------+</computeroutput></screen></section>
<section xml:id="cli_nova_baremetal-interface">
<title>Add a network interface to the node:</title>
<para>For each NIC on the node, you must create an interface, specifying the
interface's MAC address.</para>
<screen><prompt>$</prompt> <userinput>nova baremetal-interface-add 1 aa:bb:cc:dd:ee:ff</userinput>
<computeroutput>+-------------+-------------------+
| Property | Value |
+-------------+-------------------+
| datapath_id | 0 |
| id | 1 |
| port_no | 0 |
| address | aa:bb:cc:dd:ee:ff |
+-------------+-------------------+</computeroutput></screen></section>
<section xml:id="cli_nova_baremetal-instancelaunch">
<title>Launch an instance
from a bare-metal image:</title>
<para>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.</para>
<screen><prompt>$</prompt> <userinput>nova boot --image my-baremetal-image --flavor my-baremetal-flavor test</userinput>
<computeroutput>+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | BUILD |
| id | cc302a8f-cd81-484b-89a8-b75eb3911b1b |
... wait for instance to become active ...</computeroutput></screen>
<note>
<para>Set the <parameter>--availability_zone</parameter> 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:</para>
<screen><prompt>$</prompt> <userinput>nova boot --availability_zone zone:<replaceable>HOST</replaceable>,<replaceable>NODE</replaceable></userinput></screen>
<para><literal>host</literal> is optional for the
<literal>--availability_zone</literal> parameter. You can specify
simply <literal>zone:,node</literal>. You must still use the
comma.</para>
</note>
</section>
<section xml:id="cli_nova_baremetal-list">
<title>List bare-metal nodes and
interfaces:</title>
<para>Use the <command>nova baremetal-node-list</command> 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:</para>
<screen><prompt>$</prompt> <userinput>nova baremetal-node-list</userinput>
<computeroutput>+----+--------+------+-----------+---------+-------------------+------+------------+-------------+-------------+---------------+
| 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 |
+----+--------+------+-----------+---------+-------------------+------+------------+-------------+-------------+---------------+</computeroutput></screen></section>
<section xml:id="cli_nova_baremetal-details">
<title>Show details for a bare-metal node:</title>
<para>Use the <command>nova baremetal-node-list</command> command to view
the details for a bare-metal node.</para>
<screen><prompt>$</prompt> <userinput>nova baremetal-node-show 1</userinput>
<computeroutput>+------------------+--------------------------------------+
| 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 |
+------------------+--------------------------------------+</computeroutput></screen></section>
</section>

305
doc/user-guide/section_cli_nova_boot.xml
View File

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

247
doc/user-guide/section_cli_nova_config-drive.xml
View File

@ -1,247 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="config-drive">
<title>Store metadata on a configuration drive</title>
<para>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 <link
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/section_metadata-service.html"
>metadata service</link>. This metadata is different from the user
data.</para>
<para>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.</para>
<para>Any modern guest operating system that is capable of mounting an ISO
9660 or VFAT file system can use the configuration drive.</para>
<section xml:id="requirements">
<title>Requirements and guidelines</title>
<para>To use the configuration drive, you must follow the following
requirements for the compute host and image.</para>
<itemizedlist>
<title>Compute host requirements</title>
<listitem>
<para>The following hypervisors support the configuration drive:
libvirt, XenServer, Hyper-V, and VMware.</para>
</listitem>
<listitem>
<para>To use configuration drive with libvirt, XenServer, or
VMware, you must first install the
<package>genisoimage</package> package on each compute
host. Otherwise, instances do not boot properly.</para>
<para>Use the <literal>mkisofs_cmd</literal> flag to
set the path where you install the
<package>genisoimage</package> program. If
<package>genisoimage</package> is in same path
as the <systemitem class="service"
>nova-compute</systemitem> service, you do not
need to set this flag.</para>
</listitem>
<listitem>
<para>To use configuration drive with Hyper-V, you must set the
<literal>mkisofs_cmd</literal> value to the full path to
an <literal>mkisofs.exe</literal> installation.
Additionally, you must set the
<literal>qemu_img_cmd</literal> value in the
<literal>hyperv</literal> configuration section to the
full path to an <literal>qemu-img</literal> command
installation.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Image requirements</title>
<listitem>
<para>An image built with a recent version of the
<package>cloud-init</package> package can
automatically access metadata passed through the
configuration drive. The <package>cloud-init</package>
package version 0.7.1 works with Ubuntu and Fedora based
images, such as Red Hat Enterprise Linux.</para>
</listitem>
<listitem>
<para>If an image does not have the
<package>cloud-init</package> 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. See <xref linkend="config_drive_contents"/>
for details about how data is organized on the configuration
drive.</para>
</listitem>
<listitem>
<para>If you use Xen with a configuration drive, use
the <literal>xenapi_disable_agent</literal>
configuration parameter to disable the
agent.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Guidelines</title>
<listitem>
<para>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 <filename>ec2</filename> directory.</para>
</listitem>
<listitem>
<para>When you create images that access configuration drive
data and multiple directories are under the
<filename>openstack</filename> 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.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="enable_config_drive">
<title>Enable and access the configuration drive</title>
<procedure>
<step>
<para>To enable the configuration drive, pass the
<literal>--config-drive true</literal>
parameter to the <command>nova boot</command>
command.</para>
<para>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:</para>
<screen><prompt>$</prompt> <userinput>nova boot --config-drive true --image my-image-name --key-name mykey --flavor 1 --user-data ./my-user-data.txt myinstance --file /etc/network/interfaces=/home/myuser/instance-interfaces --file known_hosts=/home/myuser/.ssh/known_hosts --meta role=webservers --meta essential=false</userinput></screen>
<para>You can also configure the Compute service to always
create a configuration drive by setting the following option
in the <filename>/etc/nova/nova.conf</filename> file:</para>
<programlisting language="ini">force_config_drive=true</programlisting>
<note>
<para>If a user passes the
<literal>--config-drive true</literal> flag to the
<command>nova boot</command> command, an
administrator cannot disable the configuration
drive.</para>
</note>
</step>
<step>
<para>If your guest operating system supports accessing disk by
label, you can mount the configuration drive as the
<filename>/dev/disk/by-label/<replaceable>configurationDriveVolumeLabel</replaceable></filename>
device. In the following example, the configuration drive
has the <filename>config-2</filename> volume label.</para>
<screen><prompt>#</prompt> <userinput>mkdir -p /mnt/config</userinput>
<prompt>#</prompt> <userinput>mount /dev/disk/by-label/config-2 /mnt/config</userinput></screen>
<note>
<para>Ensure that you use at least version 0.3.1 of CirrOS
for configuration drive support.</para>
</note>
<para>If your guest operating system does not use
<literal>udev</literal>, the
<filename>/dev/disk/by-label</filename>
directory is not present.</para>
<para>You can use the <command>blkid</command> command
to identify the block device that corresponds to
the configuration drive. For example, when you
boot the CirrOS image with the
<literal>m1.tiny</literal> flavor, the device
is <filename>/dev/vdb</filename>:</para>
<screen><prompt>#</prompt> <userinput>blkid -t LABEL="config-2" -odevice</userinput></screen>
<screen><computeroutput>/dev/vdb</computeroutput></screen>
<para>Once identified, you can mount the
device:</para>
<screen><prompt>#</prompt> <userinput>mkdir -p /mnt/config</userinput>
<prompt>#</prompt> <userinput>mount /dev/vdb /mnt/config</userinput></screen>
</step>
</procedure>
<simplesect xml:id="config_drive_contents">
<title>Configuration drive contents</title>
<para>In this example, the contents of the configuration drive are
as follows:</para>
<screen><computeroutput>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</computeroutput></screen>
<para>The files that appear on the configuration drive
depend on the arguments that you pass to the
<command>nova boot</command> command.</para>
</simplesect>
<simplesect xml:id="os_metadata_format">
<title>OpenStack metadata format</title>
<para>The following example shows the contents of the
<filename>openstack/2012-08-10/meta_data.json</filename> and
<filename>openstack/latest/meta_data.json</filename> files.
These files are identical. The file contents are formatted for
readability.</para>
<programlisting language="json"><xi:include parse="text" href="samples/meta_data.json"/></programlisting>
<para>Note the effect of the <literal>--file
/etc/network/interfaces=/home/myuser/instance-interfaces</literal>
argument that was passed to the <command>nova
boot</command> command. The contents of this file
are contained in the
<filename>openstack/content/0000</filename> file
on the configuration drive, and the path is specified
as <filename>/etc/network/interfaces</filename> in the
<filename>meta_data.json</filename> file.</para>
</simplesect>
<simplesect xml:id="ec2_metadata_format">
<title>EC2 metadata format</title>
<para>The following example shows the contents of the
<filename>ec2/2009-04-04/meta-data.json</filename> and the
<filename>ec2/latest/meta-data.json</filename> files. These
files are identical. The file contents are formatted to improve
readability.</para>
<programlisting language="json"><xi:include href="samples/meta_data_ec2.json" parse="text"/></programlisting>
</simplesect>
<simplesect xml:id="user_data">
<title>User data</title>
<para>The
<filename>openstack/2012-08-10/user_data</filename>,
<filename>openstack/latest/user_data</filename>,
<filename>ec2/2009-04-04/user-data</filename>, and
<filename>ec2/latest/user-data</filename> file are
present only if the <literal>--user-data</literal>
flag and the contents of the user data file are passed
to the <command>nova boot</command> command.</para>
</simplesect>
<simplesect xml:id="config_drive_format">
<title>Configuration drive format</title>
<para>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
<filename>/etc/nova/nova.conf</filename>
file:</para>
<programlisting language="ini">config_drive_format=iso9660</programlisting>
<para>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
<filename>/etc/nova/nova.conf</filename> file:</para>
<programlisting language="ini">config_drive_cdrom=true</programlisting>
<para>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
<filename>/etc/nova/nova.conf</filename>
file:</para>
<programlisting language="ini">config_drive_format=vfat</programlisting>
<para>If you choose VFAT, the configuration drive is
64&nbsp;MB.</para>
</simplesect>
</section>
</section>

217
doc/user-guide/section_cli_nova_configure_instances.xml
View File

@ -1,217 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="cli_configure_instances">
<title>Configure access and security for instances</title>
<?dbhtml stop-chunking?>
<para>When you launch a virtual machine, you can inject a <emphasis
role="italic">key pair</emphasis>, which provides SSH access to your
instance. For this to work, the image must contain the
<literal>cloud-init</literal> package.</para>
<para>You 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.</para>
<para>If an image uses a static root password or a static key set&mdash;neither is recommended&mdash;you must not provide a key pair when you launch the instance.</para>
<para>A <emphasis role="italic">security group</emphasis> is a named
collection of network access rules that you 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.</para>
<para>The associated <emphasis role="italic">rules</emphasis> 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.</para>
<para>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:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Source of traffic</emphasis>.
Enable traffic to instances from either IP addresses
inside the cloud from other group members or from all
IP addresses.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Protocol</emphasis>. Choose
TCP for SSH, ICMP for pings, or UDP.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Destination port on virtual
machine</emphasis>. 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.</para>
</listitem>
</itemizedlist>
<para>Rules are automatically enforced as soon as you create or
modify them.</para>
<note>
<para>Instances that use the default security group cannot, by default, be
accessed from any IP address outside of the cloud. If you want those IP
addresses to access the instances, you must modify the rules for the
default security group.</para>
<para>You can also assign a floating IP address to a running instance to
make it accessible from outside the cloud. See <xref
linkend="manage_ip_addresses"/>.</para></note>
<?hard-pagebreak?>
<section xml:id="create_import_keys">
<title>Add a key pair</title>
<procedure>
<para>You can generate a key pair or upload an existing public
key.</para>
<step>
<para>To generate a key pair, run the following command:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-add <replaceable>KEY_NAME</replaceable> > <replaceable>MY_KEY</replaceable>.pem</userinput></screen>
<para>The command generates a key pair with the name that you
specify for <replaceable>KEY_NAME</replaceable>, writes the
private key to the <filename>.pem</filename> file that you
specify, and registers the public key at the Nova
database.</para>
</step>
<step>
<para>To set the permissions of the <filename>.pem</filename>
file so that only you can read and write to it, run the
following command:</para>
<screen><prompt>$</prompt> <userinput>chmod 600 <replaceable>MY_KEY</replaceable>.pem</userinput></screen>
</step>
</procedure>
</section>
<section xml:id="import_keypair_cli">
<title>Import a key pair</title>
<procedure>
<step>
<para>If you have already generated a key pair and the public
key is located at <filename>~/.ssh/id_rsa.pub</filename>,
run the following command to upload the public key:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-add --pub_key ~/.ssh/id_rsa.pub <replaceable>KEY_NAME</replaceable></userinput></screen>
<para>The command registers the public key at the Nova database
and names the key pair the name that you specify for
<literal><replaceable>KEY_NAME</replaceable></literal>.</para>
</step>
<step>
<para>To ensure that the key pair has been successfully
imported, list key pairs as follows:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-list</userinput></screen>
</step>
</procedure>
</section>
<section xml:id="configure_security_groups_rules">
<title>Create and manage security groups</title>
<procedure>
<step>
<para>To list the security groups for the current project,
including descriptions, enter the following command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list</userinput></screen>
</step>
<step>
<para>To create a security group with a specified name
and description, enter the following
command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-create <replaceable>SECURITY_GROUP_NAME</replaceable> <replaceable>GROUP_DESCRIPTION</replaceable></userinput></screen>
</step>
<step>
<para>To delete a specified group, enter the following
command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-delete <replaceable>SECURITY_GROUP_NAME</replaceable> </userinput></screen>
<note>
<para>You cannot delete the default security group
for a project. Also, you cannot delete a
security group that is assigned to a running
instance.</para>
</note>
</step>
</procedure>
</section>
<section xml:id="security_grp_rules_cli">
<title>Create and manage security group rules</title>
<procedure>
<para>Modify security group rules with the <command>nova
secgroup-*-rule</command> commands. Before you begin, source
the OpenStack RC file. For details, see <xref
linkend="cli_openrc"/>.</para>
<step>
<para>To list the rules for a security group, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules <replaceable>SECURITY_GROUP_NAME</replaceable></userinput></screen>
</step>
<step>
<para>To allow SSH access to the instances, choose one of the
following options:</para>
<itemizedlist>
<listitem>
<para>Allow access from all IP addresses, specified as
IP subnet <filename>0.0.0.0/0</filename> in CIDR
notation:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule <replaceable>SECURITY_GROUP_NAME</replaceable> tcp 22 22 0.0.0.0/0</userinput></screen>
</listitem>
<listitem>
<para>Allow access only from IP addresses from other
security groups (source groups) to access the
specified port:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto tcp --from_port 22 \
--to_port 22 <replaceable>SECURITY_GROUP_NAME</replaceable> <replaceable>SOURCE_GROUP_NAME</replaceable></userinput></screen>
</listitem>
</itemizedlist>
</step>
<step>
<para>To allow pinging of the instances, choose one of the
following options:</para>
<itemizedlist>
<listitem>
<para>Allow pinging from all IP addresses, specified as
IP subnet <filename>0.0.0.0/0</filename> in CIDR
notation:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule <replaceable>SECURITY_GROUP_NAME</replaceable> icmp -1 -1 0.0.0.0/0</userinput></screen>
<para>This allows access to all codes and all types of ICMP traffic.</para>
</listitem>
<listitem>
<para>Allow only members of other security groups
(source groups) to ping instances:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto icmp --from_port -1 \
--to_port -1 <replaceable>SECURITY_GROUP_NAME</replaceable> <replaceable>SOURCE_GROUP_NAME</replaceable></userinput></screen>
</listitem>
</itemizedlist>
</step>
<step>
<para>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:</para>
<itemizedlist>
<listitem>
<para>Allow UDP access from IP addresses, specified as
IP subnet <filename>0.0.0.0/0</filename> in CIDR
notation:<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule SECURITY_GROUP_NAME udp 53 53 0.0.0.0/0</userinput></screen></para>
</listitem>
<listitem>
<para>Allow only IP addresses from other security groups
(source groups) to access the specified port:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-group-rule --ip_proto udp --from_port 53 \
--to_port 53 <replaceable>SECURITY_GROUP_NAME</replaceable> <replaceable>SOURCE_GROUP_NAME</replaceable></userinput></screen>
</listitem>
</itemizedlist>
</step>
</procedure>
<section xml:id="security_grp_rules_cli_delete">
<title>Delete a security group rule</title>
<para>To delete a security group rule, specify the
same arguments that you used to create the
rule.</para>
<para>For example, to delete the security group rule that permits SSH
access from all IP addresses, run the following command.</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-delete-rule <replaceable>SECURITY_GROUP_NAME</replaceable> tcp 22 22 0.0.0.0/0</userinput></screen>
</section>
</section>
</section>

140
doc/user-guide/section_cli_nova_floating_ips.xml
View File

@ -1,140 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="manage_ip_addresses">
<title>Manage IP addresses</title>
<para>Each instance has a private, fixed IP address and can also have a public, or floating,
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.</para>
<para>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.</para>
<para>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:</para>
<para>
<itemizedlist>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>Disassociate a floating IP address from an instance in the project.</para>
</listitem>
<listitem>
<para>Delete a floating IP from the project; deleting a floating IP automatically
deletes that IP's associations.</para>
</listitem>
</itemizedlist>
</para>
<para>Use the <command>nova floating-ip-*</command> commands to manage floating IP
addresses.</para>
<section xml:id="floating_ips_proc">
<title>List floating IP address information</title>
<itemizedlist>
<listitem>
<para>To list all pools that provide floating IP addresses, run:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-pool-list</userinput>
<computeroutput>+--------+
| name |
+--------+
| public |
| test |
+--------+</computeroutput></screen>
<note><para>If this list is empty, the cloud administrator must configure a pool of floating IP
addresses.</para></note>
</listitem>
<listitem><para>To list all floating IP addresses that are allocated to the current project, run:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-list</userinput>
<computeroutput>+--------------+--------------------------------------+----------+--------+
| Ip | Instance Id | Fixed Ip | Pool |
+--------------+--------------------------------------+----------+--------+
| 172.24.4.225 | 4a60ff6a-7a3c-49d7-9515-86ae501044c6 | 10.0.0.2 | public |
| 172.24.4.226 | None | None | public |
+--------------+--------------------------------------+----------+--------+</computeroutput></screen>
<para>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.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="floating_ip_allocate">
<title>Associate floating IP addresses</title>
<para>You can assign a floating IP address to a project and to an instance.</para>
<procedure>
<step>
<para>Run the following command to allocate a floating IP address to the current
project. By default, the floating IP address is allocated from the
<systemitem>public</systemitem> pool. The command outputs the allocated IP
address.</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-create</userinput>
<computeroutput>+--------------+-------------+----------+--------+
| Ip | Instance Id | Fixed Ip | Pool |
+--------------+-------------+----------+--------+
| 172.24.4.225 | None | None | public |
+--------------+-------------+----------+--------+</computeroutput></screen>
<note><para>If more than one IP address pool is available, you can specify the pool from which to allocate
the IP address, using the pool's name. For example, to allocate a floating
IP address from the <literal>test</literal> pool, run:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-create test</userinput></screen>
</note>
</step>
<step>
<para>List all project instances with which a floating IP address could be
associated:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput>
<computeroutput>+--------------------------------------+------+---------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+------+---------+------------+-------------+------------------+
| d5c854f9-d3e5-4fce-94d9-3d9f9f8f2987 | VM1 | ACTIVE | - | Running | private=10.0.0.3 |
| 42290b01-0968-4313-831f-3b489a63433f | VM2 | SHUTOFF | - | Shutdown | private=10.0.0.4 |
+--------------------------------------+------+---------+------------+-------------+------------------+</computeroutput></screen>
</step>
<step>
<para>Associate an IP address with an instance in the project, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-associate <replaceable>INSTANCE_NAME_OR_ID</replaceable> <replaceable>FLOATING_IP_ADDRESS</replaceable></userinput></screen>
<para>For example:</para>
<para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-associate VM1 172.24.4.225</userinput></screen>
</para>
<para>Notice that the instance is now associated with two IP addresses:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput>
<computeroutput>+--------------------------------------+------+---------+------------+-------------+--------------------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+------+---------+------------+-------------+--------------------------------+
| d5c854f9-d3e5-4fce-94d9-3d9f9f8f2987 | VM1 | ACTIVE | - | Running | private=10.0.0.3, 172.24.4.225 |
| 42290b01-0968-4313-831f-3b489a63433f | VM2 | SHUTOFF | - | Shutdown | private=10.0.0.4 |
+--------------------------------------+------+---------+------------+-------------+--------------------------------+</computeroutput></screen>
<para>After you associate the IP address and configure security group rules for the instance, the instance is
publicly available at the floating IP address.</para>
<note><para>If an instance is connected to multiple networks, you can associate a floating IP
address with a specific fixed IP address using the optional
<parameter>--fixed-address</parameter> parameter:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-associate --fixed-address <replaceable>FIXED_IP_ADDRESS</replaceable> <replaceable>INSTANCE_NAME_OR_ID</replaceable> <replaceable>FLOATING_IP_ADDRESS</replaceable></userinput></screen>
</note>
</step>
</procedure>
</section>
<section xml:id="floating_ip_disassociate">
<title>Disassociate floating IP addresses</title>
<procedure>
<step>
<para>Release a floating IP address from an instance, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-disassociate <replaceable>INSTANCE_NAME_OR_ID</replaceable> <replaceable>FLOATING_IP_ADDRESS</replaceable></userinput></screen>
</step>
<step>
<para>Release the floating IP address from the current project, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova floating-ip-delete <replaceable>FLOATING_IP_ADDRESS</replaceable></userinput></screen>
<para>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.</para>
</step>
</procedure>
</section>
</section>

47
doc/user-guide/section_cli_nova_get_console.xml
View File

@ -1,47 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="instance_console">
<title>Access an instance through a console</title>
<para>In order to see the console output of an instance, regardless
of whether or not the console log has output, either VNC or SPICE
is used. This allows for relaying keyboard and mouse activity to
and from the instance in question.</para>
<para>There are three common remote console access methods in use
with OpenStack:</para>
<variablelist>
<varlistentry><term>novnc</term>
<listitem><para>An in-browser VNC client implemented
using HTML5 Canvas and WebSockets</para></listitem>
</varlistentry>
<varlistentry><term>spice</term>
<listitem><para>A complete in-browser client solution for
interaction with virtualized instances</para></listitem>
</varlistentry>
<varlistentry><term>xvpvnc</term>
<listitem><para>A Java client offering console access to
an instance</para></listitem>
</varlistentry>
</variablelist>
<para>Example:</para>
<para>To access an instance through a remote console, run the
following command:</para> <screen><prompt>$</prompt> <userinput>nova <command>get-vnc-console</command> <replaceable>INSTANCE_NAME</replaceable> <replaceable>VNC_TYPE</replaceable></userinput></screen>
<para>The command returns a URL from which you can access your instance:</para>
<screen><computeroutput>+--------+------------------------------------------------------------------------------+
| Type | Url |
+--------+------------------------------------------------------------------------------+
| xvpvnc | http://192.168.5.96:6081/console?token=c83ae3a3-15c4-4890-8d45-aefb494a8d6c |
+--------+------------------------------------------------------------------------------+</computeroutput></screen>
<para><replaceable>VNC_TYPE</replaceable> can be replaced by any of
the above values as connection types.</para>
<para>When using SPICE to view the console of an instance,
a browser plugin can be used directly on the instance page,
or the <command>get-vnc-console</command> command can be
used with it, as well, by returning a token-authenticated
address such as the one above.</para>
<para>For further information and comparisons (including security
considerations, please see the
<link xlink:href="http://docs.openstack.org/security-guide/content/ch026_compute.html">security guide</link>.</para>
</section>

26
doc/user-guide/section_cli_nova_manage_instances.xml
View File

@ -1,26 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="cli_manage_instances">
<title>Manage instances and hosts</title>
<para>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.</para>
<para>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.</para>
<xi:include href="section_cli_nova_floating_ips.xml"/>
<xi:include href="section_cli_nova_resizerebuild.xml"/>
<xi:include href="section_cli_nova_search_ip.xml"/>
<xi:include href="section_cli_nova_startstop.xml"/>
<xi:include href="section_cli_nova_reboot.xml"/>
<xi:include href="section_cli_nova_terminate.xml"/>
<xi:include href="section_cli_nova_get_console.xml"/>
<xi:include href="section_cli_nova_baremetal.xml"/>
<xi:include href="../common/section_cli_nova_usage_statistics.xml"/>
</section>

121
doc/user-guide/section_cli_nova_migrate_instances.xml
View File

@ -1,121 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="cli_migrate_instances">
<?dbhtml stop-chunking?>
<title>Use snapshots to migrate instances</title>
<para>To use snapshots to migrate instances from OpenStack projects to clouds, complete these steps.</para>
<procedure>
<step>
<para>In the source project, perform the following steps:</para>
<orderedlist>
<listitem>
<para><link linkend="create_snapshot">Create a snapshot of the instance.</link></para>
</listitem>
<listitem>
<para><link linkend="download_snapshot">Download the snapshot as an image.</link></para>
</listitem>
</orderedlist></step>
<step>
<para>In the destination project, perform the following steps:</para>
<orderedlist>
<listitem>
<para><link linkend="import_snapshot">Import the snapshot to the new environment.</link></para>
</listitem>
<listitem>
<para><link linkend="boot_from_snapshot">Boot a new instance from the snapshot.</link></para>
</listitem>
</orderedlist></step>
</procedure>
<note>
<para>Some cloud providers allow only administrators to perform this task.</para>
</note>
<section xml:id="create_snapshot">
<title>Create a snapshot of the instance</title>
<procedure>
<step>
<para>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 get the instance name.</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput>
<computeroutput>+--------------------------------------+------------+--------+------------------------------+
| ID | Name | Status | Networks |
+--------------------------------------+------------+--------+------------------------------+
| c41f3074-c82a-4837-8673-fa7e9fea7e11 | myInstance | ACTIVE | private=10.0.0.3 |
+--------------------------------------+------------+--------+------------------------------+</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>nova stop example</userinput></screen>
</step>
<step>
<para>Use the <command>nova list</command> command to confirm that the instance shows a
<literal>SHUTOFF</literal> status.</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput>
<computeroutput>+--------------------------------------+------------+---------+------------------------------+
| ID | Name | Status | Networks |
+--------------------------------------+------------+---------+------------------------------+
| c41f3074-c82a-4837-8673-fa7e9fea7e11 | myInstance | SHUTOFF | private=10.0.0.3 |
+--------------------------------------+------------+---------+------------------------------+</computeroutput></screen>
</step>
<step>
<para>Use the <command>nova
image-create</command> command to take a snapshot. Use the <command>nova
image-list</command> command to check the status until the status
is <literal>ACTIVE</literal>:</para>
<screen><prompt>$</prompt> <userinput>nova image-create --poll myInstance myInstanceSnapshot</userinput>
<computeroutput>Instance snapshotting... 50% complete</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>nova image-list</userinput>
<computeroutput>+--------------------------------------+---------------------------------+--------+--------+
| ID | Name | Status | Server |
+--------------------------------------+---------------------------------+--------+--------+
| 657ebb01-6fae-47dc-986a-e49c4dd8c433 | cirros-0.3.2-x86_64-uec | ACTIVE | |
| 72074c6d-bf52-4a56-a61c-02a17bf3819b | cirros-0.3.2-x86_64-uec-kernel | ACTIVE | |
| 3c5e5f06-637b-413e-90f6-ca7ed015ec9e | cirros-0.3.2-x86_64-uec-ramdisk | ACTIVE | |
| f30b204e-1ce6-40e7-b8d9-b353d4d84e7d | myInstanceSnapshot | ACTIVE | |
+--------------------------------------+---------------------------------+--------+--------+</computeroutput></screen>
</step>
</procedure>
</section>
<section xml:id="download_snapshot">
<title>Download the snapshot as an image</title>
<procedure>
<step>
<para>Get the image ID:</para>
<screen><prompt>$</prompt> <userinput>nova image-list</userinput>
<computeroutput>+--------------------------------------+-------------------+--------+--------------------------------------+
| ID | Name | Status | Server |
+--------------------------------------+-------------------+--------+--------------------------------------+
| f30b204e-1ce6-40e7-b8d9-b353d4d84e7d | myInstanceSnapshot| ACTIVE | c41f3074-c82a-4837-8673-fa7e9fea7e11 |
+--------------------------------------+-------------------+--------+--------------------------------------+</computeroutput></screen>
</step>
<step>
<para>Download the snapshot by using the image ID that
was returned in the previous step:</para>
<screen><prompt>$</prompt> <userinput>glance image-download --file snapshot.raw f30b204e-1ce6-40e7-b8d9-b353d4d84e7d</userinput></screen>
<note>
<para>The <command>glance image-download</command>
command requires the image ID and cannot use
the image name.</para>
<para>Ensure there is sufficient space on the
destination file system for the image
file.</para>
</note>
</step>
<step>
<para>Make the image available to the new environment, either through HTTP or with direct upload to a
machine (<command>scp</command>).</para>
</step>
</procedure>
</section>
<section xml:id="import_snapshot">
<title>Import the snapshot to new environment</title>
<para>In the new project or cloud environment, import
the snapshot:</para>
<screen><prompt>$</prompt> <userinput>glance image-create --copy-from <replaceable>IMAGE_URL</replaceable></userinput></screen>
</section>
<section xml:id="boot_from_snapshot">
<title>Boot a new instance from the snapshot</title>
<para>In the new project or cloud environment, use the
snapshot to create the new instance:</para>
<screen><prompt>$</prompt> <userinput>nova boot --flavor m1.tiny --image myInstanceSnapshot myNewInstance</userinput></screen>
</section>
</section>

50
doc/user-guide/section_cli_nova_reboot.xml
View File

@ -1,50 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="reboot">
<title>Reboot an instance</title>
<para>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.</para>
<procedure> <step><para>By default, when you reboot an instance, it is a soft reboot.</para>
<screen><prompt>$</prompt> <userinput>nova reboot <replaceable>SERVER</replaceable></userinput></screen></step></procedure>
<procedure> <step><para>To perform a hard reboot, pass the <parameter>--hard</parameter> parameter, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova reboot --hard <replaceable>SERVER</replaceable></userinput></screen></step></procedure>
<para>It is also possible to reboot a running instance into
rescue mode. This operation may be required, if a filesystem
of an instance becomes corrupted with a prolonged usage,
for example.</para>
<note>
<para>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.</para>
</note>
<para>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.</para>
<procedure> <step><para>To perform an instance reboot into rescue
mode, run the following command:</para>
<screen><prompt>$</prompt> <userinput>nova rescue <replaceable>SERVER</replaceable></userinput></screen></step></procedure>
<procedure> <step><para>To restart the instance from the normal
boot disk, run the following command:</para>
<screen><prompt>$</prompt> <userinput>nova unrescue <replaceable>SERVER</replaceable></userinput></screen></step></procedure>
<procedure> <step><para>If you want to rescue an instance with a specific
image, rather than the default one, use the
<parameter>--rescue_image_ref</parameter> parameter, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova rescue --rescue_image_ref <replaceable>IMAGE_ID</replaceable><replaceable> SERVER</replaceable></userinput></screen></step></procedure>
</section>

89
doc/user-guide/section_cli_nova_resizerebuild.xml
View File

@ -1,89 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nova_cli_resize">
<title>Change the size of your server</title>
<para>You change the size of a server by changing its flavor.</para>
<procedure>
<step>
<para>Show information about your server, including its size, which is shown as the value of the flavor
property.</para>
<screen><prompt>$</prompt> <userinput>nova show myCirrosServer</userinput>
<computeroutput>+-------------------------------------+----------------------------------------------------------------+
| Property | Value |
+-------------------------------------+----------------------------------------------------------------+
| status | ACTIVE |
| updated | 2013-07-18T15:08:20Z |
| OS-EXT-STS:task_state | None |
| OS-EXT-SRV-ATTR:host | devstack |
| key_name | None |
| image | cirros-0.3.2-x86_64-uec (397e713c-b95b-4186-ad46-6126863ea0a9) |
| private network | 10.0.0.3 |
| hostId | 6e1e69b71ac9b1e6871f91e2dfc9a9b9ceca0f05db68172a81d45385 |
| OS-EXT-STS:vm_state | active |
| OS-EXT-SRV-ATTR:instance_name | instance-00000005 |
| OS-EXT-SRV-ATTR:hypervisor_hostname | devstack |
| flavor | m1.small (2) |
| id | 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 |
| security_groups | [{u'name': u'default'}] |
| user_id | 376744b5910b4b4da7d8e6cb483b06a8 |
| name | myCirrosServer |
| created | 2013-07-18T15:07:59Z |
| tenant_id | 66265572db174a7aa66eba661f58eb9e |
| OS-DCF:diskConfig | MANUAL |
| metadata | {u'description': u'Small test image', u'creator': u'joecool'} |
| accessIPv4 | |
| accessIPv6 | |
| progress | 0 |
| OS-EXT-STS:power_state | 1 |
| OS-EXT-AZ:availability_zone | nova |
| config_drive | |
+-------------------------------------+----------------------------------------------------------------+</computeroutput></screen>
<para>The size (flavor) of the server is <literal>m1.small (2)</literal>.</para>
</step>
<step>
<para>List the available flavors with the following command:</para>
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput>
<computeroutput>+-----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+-----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 1 | m1.tiny | 512 | 1 | 0 | | 1 | 1.0 | True |
| 2 | m1.small | 2048 | 20 | 0 | | 1 | 1.0 | True |
| 3 | m1.medium | 4096 | 40 | 0 | | 2 | 1.0 | True |
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
+-----+-----------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen>
</step>
<step>
<para>To resize the server, pass the server ID or name and the new flavor to the <command>nova
resize</command> command. Include the <literal>--poll</literal> parameter to report the resize
progress.</para>
<screen><prompt>$</prompt> <userinput>nova resize myCirrosServer 4 --poll</userinput></screen>
<screen><computeroutput>Instance resizing... 100% complete
Finished</computeroutput> </screen>
</step>
<step>
<para>Show the status for your server:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput>
<computeroutput>+--------------------------------------+----------------+--------+-----------------------------------------+
| ID | Name | Status | Networks |
+--------------------------------------+----------------+--------+-----------------------------------------+
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | RESIZE | private=172.16.101.6, public=10.4.113.6 |
+--------------------------------------+----------------+--------+-----------------------------------------+</computeroutput></screen>
<para>When the resize completes, the status becomes VERIFY_RESIZE.</para>
</step>
<step>
<para>Confirm the resize:</para>
<screen><prompt>$</prompt> <userinput>nova resize-confirm 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5</userinput></screen>
<para>The server status becomes ACTIVE.</para>
</step>
<step>
<para>If the resize fails or does not work as expected, you can
revert the resize:</para>
<screen><prompt>$</prompt> <userinput>nova resize-revert 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5</userinput></screen>
<para>The server status becomes ACTIVE.</para>
</step>
</procedure>
</section>

20
doc/user-guide/section_cli_nova_search_ip.xml
View File

@ -1,20 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="search_ip">
<title>Search for an instance using IP address</title>
<para>You can search for an instance using the IP address parameter,
<literal>--ip</literal>, with the <command>nova list</command>
command.</para>
<screen><prompt>$</prompt> <userinput>nova list --<parameter>ip</parameter> <replaceable>IP_ADDRESS</replaceable> </userinput></screen>
<para>The following example shows the results of a search on
<filename>10.0.0.4</filename>.</para>
<screen><prompt>$</prompt> <userinput>nova list --<parameter>ip</parameter> <replaceable>10.0.0.4</replaceable></userinput>
<computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
</section>

78
doc/user-guide/section_cli_nova_startstop.xml
View File

@ -1,78 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nova_cli_stop_start">
<title>Stop and start an instance</title>
<para>Use one of the following methods to stop and start an
instance.</para>
<section xml:id="pause_server">
<title>Pause and unpause an instance</title>
<itemizedlist>
<listitem>
<para>To pause an instance, run the following command:</para>
<screen><prompt>$</prompt> <userinput>nova pause <replaceable>INSTANCE_NAME</replaceable></userinput> </screen>
<para>This command stores the state of the VM in RAM. A paused
instance continues to run in a frozen state.</para></listitem>
<listitem><para>To unpause the instance, run the following command:</para>
<screen><prompt>$</prompt> <userinput>nova unpause <replaceable>INSTANCE_NAME</replaceable></userinput> </screen>
</listitem>
</itemizedlist>
</section>
<section xml:id="suspend_resume">
<title>Suspend and resume an instance</title>
<itemizedlist>
<para>Administrative users might want to suspend an instance if
it is infrequently used or to perform system maintenance. When
you suspend an instance, its VM state is stored on disk, all
memory is written to disk, and the virtual machine is stopped.
Suspending an instance is similar to placing a device in
hibernation.</para>
<note>
<para>Suspending an instance will not free allocated memory or
virtual CPU resources. To release them, delete the instance.</para>
</note>
<listitem>
<para>To initiate a hypervisor-level suspend operation, run
the following command:</para>
<screen><prompt>$</prompt> <userinput>nova suspend <replaceable>INSTANCE_NAME</replaceable></userinput></screen>
</listitem>
<listitem>
<para>To resume a suspended instance, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>nova resume <replaceable>INSTANCE_NAME</replaceable></userinput></screen>
</listitem>
</itemizedlist>
</section>
<section xml:id="shelve_server">
<title>Shelve and unshelve an instance</title>
<para>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.</para>
<para>You can complete the following shelving tasks:</para>
<variablelist>
<varlistentry><term>Shelve an instance</term>
<listitem><para>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. Use the following
command:</para>
<screen><prompt>$</prompt> <userinput>nova shelve <replaceable>SERVERNAME</replaceable></userinput></screen>
</listitem>
</varlistentry>
<varlistentry><term>Unshelve an instance</term>
<listitem><para>Restores the instance:</para>
<screen><prompt>$</prompt> <userinput>nova unshelve <replaceable>SERVERNAME</replaceable></userinput></screen>
</listitem>
</varlistentry>
<varlistentry><term>Remove a shelved instance</term>
<listitem><para>Removes the instance from the server; data and resource associations are deleted. If an
instance is no longer needed, you can move that instance off the hypervisor in order to
minimize resource usage:</para>
<screen><prompt>$</prompt> <userinput>nova shelve-offload <replaceable>SERVERNAME</replaceable></userinput></screen>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>

35
doc/user-guide/section_cli_nova_terminate.xml
View File

@ -1,35 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="terminating">
<title>Delete an instance</title>
<para>When you no longer need an instance, you can delete it.</para>
<procedure><step>
<para>List all instances:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput>
<computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
| 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 |
| d7efd3e4-d375-46d1-9d57-372b6e4bdb7f | newServer | ERROR | None | NOSTATE | |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
</step><step>
<para>Run the <command>nova delete</command> command to delete the instance. The following example shows deletion
of the <filename>newServer</filename> instance, which is in <literal>ERROR</literal> state:</para>
<screen><prompt>$</prompt> <userinput>nova delete newServer</userinput></screen>
<para>The command does not notify that your server was deleted.</para></step><step>
<para>To verify that the server was deleted, run the <command>nova list</command> command:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput>
<computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| ID | Name | Status | Task State | Power State | Networks |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+
| 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 | myCirrosServer | ACTIVE | None | Running | private=10.0.0.3 |
| 8a99547e-7385-4ad1-ae50-4ecfaaad5f42 | myInstanceFromVolume | ACTIVE | None | Running | private=10.0.0.4 |
+--------------------------------------+----------------------+--------+------------+-------------+------------------+</computeroutput></screen>
<para>The deleted instance does not appear in the list.</para>
</step>
</procedure>
</section>

19
doc/user-guide/section_cli_nova_userdata.xml
View File

@ -1,19 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="inserting_userdata">
<title>Provide user data to instances</title>
<para>A <glossterm baseform="user data">user data</glossterm> file is a special key in the metadata service that
holds a file that cloud-aware applications in the guest instance
can access. For example, one application that uses user data is
the <link xlink:href="https://help.ubuntu.com/community/CloudInit"
>cloud-init</link> system, which is an open-source package from
Ubuntu that is available on various Linux distributions and which
handles early initialization of a cloud instance.</para>
<para>You can place user data in a local file and pass it through
the <parameter>--user-data &lt;user-data-file&gt;</parameter>
parameter at instance creation:</para>
<screen><prompt>$</prompt> <userinput>nova boot --image ubuntu-cloudimage --flavor 1 --user-data mydata.file</userinput></screen>
</section>

141
doc/user-guide/section_cli_swift_howto.xml
View File

@ -1,141 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="managing-openstack-object-storage-with-swift-cli">
<title>Manage objects and containers</title>
<?dbhtml stop-chunking?>
<para>The OpenStack Object Storage service provides the
<command>swift</command> 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.</para>
<para>This client is based on the native swift client library,
<literal>client.py</literal>, which seamlessly re-authenticates
if the current token expires during processing, retries operations
multiple times, and provides a processing concurrency of
10.</para>
<section xml:id="cli_create_containers">
<title>Create and manage containers</title>
<itemizedlist>
<listitem>
<para>To create a container, run the following command and replace
<replaceable>CONTAINER</replaceable> with the name of your
container.</para>
<screen><prompt>$</prompt> <userinput>swift post <replaceable>CONTAINER</replaceable></userinput></screen></listitem>
<listitem>
<para>To list all containers, run the following command:</para>
<screen><prompt>$</prompt> <userinput>swift list</userinput></screen>
</listitem>
<listitem>
<para>To check the status of containers, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>swift stat</userinput></screen>
<screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
Containers: 2
Objects: 3
Bytes: 268826
Accept-Ranges: bytes
X-Timestamp: 1392683866.17952
Content-Type: text/plain; charset=utf-8</computeroutput></screen>
<para>You can also use the <command>swift stat</command>
command with the <replaceable>ACCOUNT</replaceable> or
<replaceable>CONTAINER</replaceable> names as
parameters.</para>
<screen><prompt>$</prompt> <userinput>swift stat <replaceable>CONTAINER</replaceable></userinput></screen>
<screen><computeroutput>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</computeroutput></screen>
</listitem>
</itemizedlist>
</section>
<section xml:id="cli_manage_access_swift">
<title>Manage access</title>
<itemizedlist>
<listitem>
<para>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
<literal>X-Container-Read</literal> and
<literal>X-Container-Write</literal> headers.</para>
<para>To give a user read access, use the <command>swift
post</command> command with the <parameter>-r</parameter>
parameter. To give a user write access, use the
<parameter>-w</parameter> parameter.</para>
<para>The following example enables the
<literal>testuser</literal> user to read objects in the
container:</para>
<screen><prompt>$</prompt> <userinput>swift post -r 'testuser'</userinput></screen>
<para>You can also use this command with a list of
users.</para>
</listitem>
<listitem>
<para>If you use StaticWeb middleware to enable Object Storage
to serve public web content, use <literal>.r:</literal>,
followed by a list of allowed referrers.</para>
<para>The following command gives object access to all
referring domains:</para>
<screen><prompt>$</prompt> <userinput>swift post -r '.r:*'</userinput></screen>
</listitem>
</itemizedlist>
</section>
<section xml:id="cli_manage_objects">
<title>Manage objects</title>
<itemizedlist>
<listitem>
<para>To upload an object to a container, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>swift upload <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
<para>To upload in chunks, for large files, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>swift upload -S <replaceable>CHUNK_SIZE</replaceable> <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
</listitem>
<listitem>
<para>To check the status of the object, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>swift stat <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
<screen><computeroutput>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</computeroutput></screen>
</listitem>
<listitem>
<para>To list the objects in a container, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>swift list <replaceable>CONTAINER</replaceable></userinput></screen>
</listitem>
<listitem>
<para>To download an object from a container, run the
following command:</para>
<screen><prompt>$</prompt> <userinput>swift download <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
</listitem>
</itemizedlist>
</section>
<xi:include href="section_object-api-env-vars.xml"/>
<xi:include href="section_object-api-versioning.xml"/>
<xi:include href="section_object-api-response-formats.xml"/>
<xi:include href="section_object-api-large-lists.xml"/>
<xi:include href="section_object-api-pseudo-hier-folders.xml"/>
<xi:include href="section_object-api-discoverability.xml"/>
<xi:include href="section_object-api-create-large-objects.xml"/>
<xi:include href="section_object-api-archive-auto-extract.xml"/>
<xi:include href="section_object-api-bulk-delete.xml"/>
<xi:include href="section_object-api-create-website.xml"/>
</section>

973
doc/user-guide/section_cli_trove.xml
View File

@ -1,973 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="trove-manage-db">
<title>Create and manage databases</title>
<para>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.</para>
<section xml:id="create_db">
<title>Create and access a database</title>
<para>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.</para>
<para>This example shows you how to create and access a MySQL 5.5 database.</para>
<procedure>
<title>To create and access a database</title>
<step>
<title>Determine which flavor to use for your database</title>
<para>When you create a database instance, you must specify a nova flavor. The flavor
indicates various characteristics of the instance, such as RAM, root volume size, and so
on. The default nova flavors are not sufficient to create database instances. You might
need to create or obtain some new nova flavors that work for databases.</para>
<para>The first step is to list flavors by using the nova <command>flavor-list</command>
command.</para>
<para>Here are the default flavors, although you may have additional custom flavors in your
environment:</para>
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput>
<computeroutput>+-----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+-----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 1 | m1.tiny | 512 | 1 | 0 | | 1 | 1.0 | True |
| 2 | m1.small | 2048 | 20 | 0 | | 1 | 1.0 | True |
| 3 | m1.medium | 4096 | 40 | 0 | | 2 | 1.0 | True |
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True |
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True |
+-----+-----------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen>
<para>Now take a look at the minimum requirements for various database instances:</para>
<informaltable rules="all" width="60%">
<col width="25%"/>
<col width="25%"/>
<col width="25%"/>
<col width="25%"/>
<thead>
<tr>
<th>Database</th>
<th>RAM (MB)</th>
<th>Disk (GB)</th>
<th>VCPUs</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>MySQL</para>
</td>
<td>
<para>512</para>
</td>
<td>
<para>5</para>
</td>
<td>
<para>1</para>
</td>
</tr>
<tr>
<td>
<para>Cassandra</para>
</td>
<td>
<para>2048</para>
</td>
<td>
<para>5</para>
</td>
<td>
<para>1</para>
</td>
</tr>
<tr>
<td>
<para>MongoDB</para>
</td>
<td>
<para>1024</para>
</td>
<td>
<para>5</para>
</td>
<td>
<para>1</para>
</td>
</tr>
<tr>
<td>
<para>Redis</para>
</td>
<td>
<para>512</para>
</td>
<td>
<para>5</para>
</td>
<td>
<para>1</para>
</td>
</tr>
</tbody>
</informaltable>
<itemizedlist>
<listitem>
<para>If you have a custom flavor that meets the needs of the database that you want to
create, proceed to <xref linkend="create-database-instance"/> and use that
flavor.</para>
</listitem>
<listitem>
<para>If your environment does not have a suitable flavor, an administrative user must
create a custom flavor by using the nova <command>flavor-create</command>
command.</para>
</listitem>
</itemizedlist>
<formalpara>
<title>MySQL example</title>
<para>This example creates a flavor that you can use with a MySQL database. This example
has the following attributes:</para>
</formalpara>
<itemizedlist>
<listitem>
<para>Flavor name: <literal>mysql_minimum</literal></para>
</listitem>
<listitem>
<para>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 <literal>6</literal>.</para>
</listitem>
<listitem>
<para>RAM: <literal>512</literal></para>
</listitem>
<listitem>
<para>Root volume size in GB: <literal>5</literal></para>
</listitem>
<listitem>
<para>Virtual CPUs: <literal>1</literal></para>
</listitem>
</itemizedlist>
<screen><prompt>$</prompt> <userinput>nova flavor-create mysql-minimum 6 512 5 1</userinput>
<computeroutput>+----+---------------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+----+---------------+-----------+------+-----------+------+-------+-------------+-----------+
| 6 | mysql-minimum | 512 | 5 | 0 | | 1 | 1.0 | True |
+----+---------------+-----------+------+-----------+------+-------+-------------+-----------+</computeroutput></screen>
</step>
<step xml:id="create-database-instance">
<title>Create a database instance</title>
<para>This example creates a database instance with the following characteristics:</para>
<itemizedlist>
<listitem>
<para>Name of the instance: <literal>mysql_instance_1</literal></para>
</listitem>
<listitem>
<para>Database flavor: <literal>6</literal></para>
</listitem>
</itemizedlist>
<para>In addition, this command specifies these options for the instance:</para>
<itemizedlist>
<listitem>
<para>A volume size of <literal>5</literal> (5 GB).</para>
</listitem>
<listitem>
<para>The <literal>myDB</literal> database.</para>
</listitem>
<listitem>
<para>The database is based on the <literal>mysql</literal> data store and the
<literal>mysql-5.5</literal> datastore_version.</para>
</listitem>
<listitem>
<para>The <literal>userA</literal> user with the <literal>password</literal>
password.</para>
</listitem>
</itemizedlist>
<screen><prompt>$</prompt> <userinput>trove create mysql_instance_1 6 --size 5 --databases myDB \
--users userA:password --datastore_version mysql-5.5 \
--datastore mysql</userinput>
<computeroutput>+-------------------+---------------------------------------------------------------------------------------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} |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+</computeroutput></screen>
</step>
<step>
<title>Get the IP address of the database instance</title>
<para>First, use the trove <command>list</command> command to list all instances and their
IDs:</para>
<screen><prompt>$</prompt> <userinput>trove list</userinput>
<computeroutput>+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+
| 5599dad6-731e-44df-bb60-488da3da9cfe | mysql_instance_1 | mysql | mysql-5.5 | BUILD | 6 | 5 |
+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+</computeroutput></screen>
<para>This command returns the instance ID of your new instance.</para>
<para>You can now pass in the instance ID with the trove <command>show</command> command to
get the IP address of the instance. In this example, replace
<replaceable>INSTANCE_ID</replaceable> with
<literal>5599dad6-731e-44df-bb60-488da3da9cfe</literal>.</para>
<screen><prompt>$</prompt> <userinput>trove show <replaceable>INSTANCE_ID</replaceable></userinput>
<computeroutput>+-------------------+--------------------------------------+
| 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 |
+-------------------+--------------------------------------+</computeroutput></screen>
<para>This command returns the IP address of the database instance.</para>
</step>
<step>
<title>Access the new database</title>
<para>You can now access the new database you just created (myDB) by using typical database
access commands. In this MySQL example, replace <replaceable>IP_ADDRESS</replaceable> with
<literal>172.16.200.2</literal>.</para>
<screen><prompt>$</prompt> <userinput>mysql -u userA -ppassword -h <replaceable>IP_ADDRESS</replaceable> myDB</userinput></screen>
</step>
</procedure>
</section>
<section xml:id="backup_db">
<title>Backup and restore a database</title>
<para>You can use Database services to backup a database and store the backup artifact in the
Object Storage module. 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.</para>
<para>This example shows you how to back up and restore a MySQL database.</para>
<procedure>
<title>To backup and restore a database</title>
<step>
<title>Backup the database instance</title>
<para>As background, assume that you have <link linkend="create_db">created a database
instance</link> with the following characteristics:</para>
<itemizedlist>
<listitem>
<para>Name of the database instance: <literal>guest1</literal></para>
</listitem>
<listitem>
<para>Flavor ID: <literal>10</literal></para>
</listitem>
<listitem>
<para>Root volume size: <literal>2</literal></para>
</listitem>
<listitem>
<para>Databases: <literal>db1</literal> and <literal>db2</literal></para>
</listitem>
<listitem>
<para>Users: The <literal>user1</literal> user with the <literal>password</literal>
password</para>
</listitem>
</itemizedlist>
<para>First, get the ID of the <literal>guest1</literal> database instance by using the
trove <command>list</command> command:</para>
<screen><prompt>$</prompt> <userinput>trove list</userinput>
<computeroutput>+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+
| 97b4b853-80f6-414f-ba6f-c6f455a79ae6 | guest1 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+</computeroutput></screen>
<para>Back up the database instance by using the trove <command>backup-create</command>
command. In this example, the backup is called <literal>backup1</literal>. In this
example, replace <replaceable>INSTANCE_ID</replaceable> with
<literal>97b4b853-80f6-414f-ba6f-c6f455a79ae6</literal>:</para>
<note>
<para>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.</para>
</note>
<screen><prompt>$</prompt> <userinput>trove backup-create <replaceable>INSTANCE_ID</replaceable> backup1</userinput>
<computeroutput>+-------------+--------------------------------------+
| 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 |
+-------------+--------------------------------------+</computeroutput></screen>
<para>Note that the command returns both the ID of the original instance
(<literal>instance_id</literal>) and the ID of the backup artifact
(<literal>id</literal>).</para>
<para>Later on, use the trove <command>backup-list</command> command to get this
information:</para>
<screen><prompt>$</prompt> <userinput>trove backup-list</userinput>
<computeroutput>+--------------------------------------+--------------------------------------+---------+-----------+-----------+---------------------+
| 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 |
+--------------------------------------+--------------------------------------+---------+-----------+-----------+---------------------+</computeroutput></screen>
<para>You can get additional information about the backup by using the trove
<command>backup-show</command> command and passing in the
<replaceable>BACKUP_ID</replaceable>, which is
<literal>8af30763-61fd-4aab-8fe8-57d528911138</literal>.</para>
<screen><prompt>$</prompt> <userinput>trove backup-show <replaceable>BACKUP_ID</replaceable></userinput>
<computeroutput>+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
| Property | Value |
+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
| created | 2014-03-18T17:09:07 |
| description | None |
| id | 8af30763-61fd-4aab-8fe8-57d528911138 |
| instance_id | 97b4b853-80f6-414f-ba6f-c6f455a79ae6 |
| locationRef | http://10.0.0.1:8080/v1/AUTH_626734041baa4254ae316de52a20b390/database_backups/8af30763-61fd-4aab-8fe8-57d528911138.xbstream.gz.enc |
| name | backup1 |
| parent_id | None |
| size | 0.17 |
| status | COMPLETED |
| updated | 2014-03-18T17:09:11 |
+-------------+-------------------------------------------------------------------------------------------------------------------------------------+</computeroutput></screen>
</step>
<step>
<title>Restore a database instance</title>
<para>Now assume that your <literal>guest1</literal> database instance is damaged and you
need to restore it. In this example, you use the trove <command>create</command> command
to create a new database instance called <literal>guest2</literal>.</para>
<itemizedlist>
<listitem>
<para>You specify that the new <literal>guest2</literal> instance has the same flavor
(<literal>10</literal>) and the same root volume size (<literal>2</literal>) as the
original <literal>guest1</literal> instance.</para>
</listitem>
<listitem>
<para>You use the <code>--backup</code> argument to indicate that this new instance is
based on the backup artifact identified by <replaceable>BACKUP_ID</replaceable>. In
this example, replace <replaceable>BACKUP_ID</replaceable> with
<literal>8af30763-61fd-4aab-8fe8-57d528911138</literal>.</para>
</listitem>
</itemizedlist>
<screen><prompt>$</prompt> <userinput>trove create guest2 10 --size 2 --backup <replaceable>BACKUP_ID</replaceable></userinput>
<computeroutput>+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 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': 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 | ac7a2b35-a9b4-4ff6-beac-a1bcee86d04b |
| name | guest2 |
| status | BUILD |
| updated | 2014-03-18T17:12:03 |
| volume | {u'size': 2} |
+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+</computeroutput></screen>
</step>
<step>
<title>Verify backup</title>
<para>Now check that the new <literal>guest2</literal> instance has the same characteristics
as the original <literal>guest1</literal> instance.</para>
<para>Start by getting the ID of the new <literal>guest2</literal> instance.</para>
<screen><prompt>$</prompt> <userinput>trove list</userinput>
<computeroutput>+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+
| 97b4b853-80f6-414f-ba6f-c6f455a79ae6 | guest1 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
| ac7a2b35-a9b4-4ff6-beac-a1bcee86d04b | guest2 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+</computeroutput></screen>
<para>Use the trove <command>show</command> command to display information about the new
guest2 instance. Pass in guest2's <replaceable>INSTANCE_ID</replaceable>, which is
<literal>ac7a2b35-a9b4-4ff6-beac-a1bcee86d04b</literal>.</para>
<screen><prompt>$</prompt> <userinput>trove show <replaceable>INSTANCE_ID</replaceable></userinput>
<computeroutput>+-------------------+--------------------------------------+
| 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 |
+-------------------+--------------------------------------+</computeroutput></screen>
<para>Note that the data store, flavor ID, and volume size have the same values as in the
original <literal>guest1</literal> instance.</para>
<para>Use the trove <command>database-list</command> command to check that the original
databases (<literal>db1</literal> and <literal>db2</literal>) are present on the restored
instance.</para>
<screen><prompt>$</prompt> <userinput>trove database-list <replaceable>INSTANCE_ID</replaceable></userinput>
<computeroutput>+--------------------+
| name |
+--------------------+
| db1 |
| db2 |
| performance_schema |
| test |
+--------------------+</computeroutput></screen>
<para>Use the trove <command>user-list</command> command to check that the original user
(<literal>user1</literal>) is present on the restored instance.</para>
<screen><prompt>$</prompt> <userinput>trove user-list <replaceable>INSTANCE_ID</replaceable></userinput>
<computeroutput>+--------+------+-----------+
| name | host | databases |
+--------+------+-----------+
| user1 | % | db1, db2 |
+--------+------+-----------+</computeroutput></screen>
</step>
<step>
<title>Notify users</title>
<para>Tell the users who were accessing the now-disabled <literal>guest1</literal> database
instance that they can now access <literal>guest2</literal>. Provide them with
<literal>guest2</literal>'s name, IP address, and any other information they might need.
(You can get this information by using the trove <command>show</command> command.)</para>
</step>
<step>
<title>Clean up</title>
<para>At this point, you might want to delete the disabled <literal>guest1</literal>
instance, by using the trove <command>delete</command> command.</para>
<screen><prompt>$</prompt> <userinput>trove delete <replaceable>INSTANCE_ID</replaceable></userinput></screen>
</step>
</procedure>
</section>
<section xml:id="backup_db_incremental">
<title>Use incremental backups</title>
<para>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.</para>
<para>Restoring a database instance from an incremental backup is the same as creating a
database instance from a regular backup&mdash;the Database service handles the complexities of
applying the chain of incremental backups.</para>
<para>This example shows you how to use incremental backups with a MySQL database.</para>
<formalpara>
<title>Assumptions</title>
<para>Assume that you have <link linkend="backup_db">created a regular backup</link> for
the following database instance:</para>
</formalpara>
<itemizedlist>
<listitem>
<para>Instance name: <literal>guest1</literal></para>
</listitem>
<listitem>
<para>ID of the instance (<replaceable>INSTANCE_ID</replaceable>):
<literal>792a6a56-278f-4a01-9997-d997fa126370</literal></para>
</listitem>
<listitem>
<para>ID of the regular backup artifact (<replaceable>BACKUP_ID</replaceable>):
<literal>6dc3a9b7-1f3e-4954-8582-3f2e4942cddd</literal></para>
</listitem>
</itemizedlist>
<procedure>
<title>To create and use incremental backups</title>
<step>
<title>Create your first incremental backup</title>
<para>Use the trove <command>backup-create</command> command and specify:</para>
<itemizedlist>
<listitem>
<para>The <replaceable>INSTANCE_ID</replaceable> of the database instance you are doing
the incremental backup for (in this example,
<literal>792a6a56-278f-4a01-9997-d997fa126370</literal>)</para>
</listitem>
<listitem>
<para>The name of the incremental backup you are creating:
<literal>backup1.1</literal></para>
</listitem>
<listitem>
<para>The <replaceable>BACKUP_ID</replaceable> of the parent backup. In this case, the
parent is the regular backup, with an ID of
<literal>6dc3a9b7-1f3e-4954-8582-3f2e4942cddd</literal></para>
</listitem>
</itemizedlist>
<screen><prompt>$</prompt> <userinput>trove backup-create <replaceable>INSTANCE_ID</replaceable> backup1.1 --parent <replaceable>BACKUP_ID</replaceable></userinput>
<computeroutput>+-------------+--------------------------------------+
| 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 |
+-------------+--------------------------------------+</computeroutput></screen>
<para>Note that this command returns both the ID of the database instance you are
incrementally backing up (<literal>instance_id</literal>) and a new ID for the new
incremental backup artifact you just created (<literal>id</literal>).</para>
</step>
<step>
<title>Create your second incremental backup</title>
<para>The name of your second incremental backup is <literal>backup1.2</literal>. This time,
when you specify the parent, pass in the ID of the incremental backup you just created in
the previous step (<literal>backup1.1</literal>). In this example, it is
<literal>1d474981-a006-4f62-b25f-43d7b8a7097e</literal>.</para>
<screen><prompt>$</prompt> <userinput>trove backup-create <replaceable>INSTANCE_ID</replaceable> backup1.2 --parent <replaceable>BACKUP_ID</replaceable></userinput>
<computeroutput>+-------------+--------------------------------------+
| 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 |
+-------------+--------------------------------------+</computeroutput></screen>
</step>
<step>
<title>Restore using incremental backups</title>
<para>Now assume that your <literal>guest1</literal> database instance is damaged and you
need to restore it from your incremental backups. In this example, you use the trove
<command>create</command> command to create a new database instance called
<literal>guest2</literal>.</para>
<para>To incorporate your incremental backups, you simply use the <code>--backup</code>
parameter to pass in the <replaceable>BACKUP_ID</replaceable> of your most recent
incremental backup. The Database service handles the complexities of applying the chain of
all previous incremental backups.</para>
<screen><prompt>$</prompt> <userinput>trove create guest2 10 --size 1 --backup <replaceable>BACKUP_ID</replaceable></userinput>
<computeroutput>+-------------------+-----------------------------------------------------------+
| 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} |
+-------------------+-----------------------------------------------------------+</computeroutput></screen>
</step>
</procedure>
</section>
<section xml:id="manage_db_config">
<title>Manage database configuration</title>
<para>You can manage database configuration tasks by using configuration groups. Configuration
groups let you set configuration options, in bulk, on one or more databases.</para>
<para>This example assumes you have <link linkend="create_db">created a MySQL database</link>
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.</para>
<procedure>
<title>To bulk-configure a database or databases</title>
<step>
<title>List available options</title>
<para>First, determine which configuration options you can set. Different data store
versions have different configuration options.</para>
<para>List the names and IDs of all available versions of the <literal>mysql</literal> data
store:</para>
<screen><prompt>$</prompt> <userinput>trove datastore-version-list mysql</userinput>
<computeroutput>+--------------------------------------+-----------+
| id | name |
+--------------------------------------+-----------+
| eeb574ce-f49a-48b6-820d-b2959fcd38bb | mysql-5.5 |
+--------------------------------------+-----------+</computeroutput></screen>
<para>Pass in the data store version ID with the trove
<command>configuration-parameter-list</command> command to get the available
options:</para>
<screen><prompt>$</prompt> <userinput>trove configuration-parameter-list <replaceable>DATASTORE_VERSION_ID</replaceable></userinput>
<computeroutput>+--------------------------------+---------+---------+----------------------+------------------+
| 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 |
+--------------------------------+---------+---------+----------------------+------------------+</computeroutput></screen>
<para>In this example, the <command>configuration-parameter-list</command> command returns a
list of options that work with MySQL 5.5.</para>
</step>
<step>
<title>Create a configuration group</title>
<para>A configuration group contains a comma-separated list of key-value pairs. Each pair
consists of a configuration option and its value.</para>
<para>You can create a configuration group by using the trove
<command>configuration-create</command> command. The general syntax for this command
is:</para>
<screen><prompt>$</prompt> <userinput>trove configuration-create <replaceable>NAME</replaceable> <replaceable>VALUES</replaceable> --datastore <replaceable>DATASTORE_NAME</replaceable></userinput></screen>
<itemizedlist>
<listitem>
<para><replaceable>NAME</replaceable>. The name you want to use for this group.</para>
</listitem>
<listitem>
<para><replaceable>VALUES</replaceable>. The list of key-value pairs.</para>
</listitem>
<listitem>
<para><replaceable>DATASTORE_NAME</replaceable>. The name of the associated data
store.</para>
</listitem>
</itemizedlist>
<para>Set <replaceable>VALUES</replaceable> as a JSON dictionary, for example:</para>
<programlisting language="json">{"myFirstKey" : "someString", "mySecondKey" : someInt}</programlisting>
<para>This example creates a configuration group called <literal>group1</literal>.
<literal>group1</literal> contains just one key and value pair, and this pair sets the
<option>sync_binlog</option> option to <literal>1</literal>.</para>
<screen><prompt>$</prompt> <userinput>trove configuration-create group1 '{"sync_binlog" : 1}' --datastore mysql</userinput>
<computeroutput>+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| datastore_version_id | eeb574ce-f49a-48b6-820d-b2959fcd38bb |
| description | None |
| id | 9a9ef3bc-079b-476a-9cbf-85aa64f898a5 |
| name | group1 |
| values | {"sync_binlog": 1} |
+----------------------+--------------------------------------+</computeroutput></screen>
</step>
<step>
<title>Examine your existing configuration</title>
<para>Before you use the newly-created configuration group, look at how the
<option>sync_binlog</option> option is configured on your database. Replace the
following sample connection values with values that connect to your database:</para>
<screen><prompt>$</prompt> <userinput>mysql -u user7 -ppassword -h 172.16.200.2 myDB7</userinput>
<computeroutput>Welcome to the MySQL monitor. Commands end with ; or \g.
...</computeroutput>
<prompt>mysql&gt;</prompt> <userinput>show variables like 'sync_binlog';</userinput>
<computeroutput>+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| sync_binlog | 0 |
+---------------+-------+</computeroutput></screen>
<para>As you can see, the <option>sync_binlog</option> option is currently set to
<literal>0</literal> for the <literal>myDB7</literal> database.</para>
</step>
<step>
<title>Change the database configuration using a configuration group</title>
<para>You can change a database's configuration by attaching a configuration group to a
database instance. You do this by using the trove <command>configuration-attach</command>
command and passing in the ID of the database instance and the ID of the configuration group.</para>
<para>Get the ID of the database instance:</para>
<screen><prompt>$</prompt> <userinput>trove list</userinput>
<computeroutput>+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+
| 26a265dd-1c88-4333-b3ed-6b4e9e87ffbb | mysql_instance_7 | mysql | mysql-5.5 | ACTIVE | 6 | 5 |
+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+</computeroutput></screen>
<para>Get the ID of the configuration group:</para>
<screen><prompt>$</prompt> <userinput>trove configuration-list</userinput>
<computeroutput>+--------------------------------------+--------+-------------+--------------------------------------+
| id | name | description | datastore_version_id |
+--------------------------------------+--------+-------------+--------------------------------------+
| 9a9ef3bc-079b-476a-9cbf-85aa64f898a5 | group1 | None | eeb574ce-f49a-48b6-820d-b2959fcd38bb |
+--------------------------------------+--------+-------------+--------------------------------------+</computeroutput></screen>
<para>Attach the configuration group to the database instance:</para>
<note>
<para>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.</para>
</note>
<screen><prompt>$</prompt> <userinput>trove configuration-attach <replaceable>DB_INSTANCE_ID</replaceable> <replaceable>CONFIG_GROUP_ID</replaceable></userinput></screen>
</step>
<step>
<title>Re-examine the database configuration</title>
<para>Display the <option>sync_binlog</option> setting again:</para>
<screen><prompt>mysql&gt;</prompt> <userinput>show variables like 'sync_binlog';</userinput>
<computeroutput>+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| sync_binlog | 1 |
+---------------+-------+</computeroutput></screen>
<para>As you can see, the <option>sync_binlog</option> option is now set to
<literal>1</literal>, as specified in the <literal>group1</literal> configuration
group.</para>
</step>
</procedure>
<formalpara>
<title>Conclusion</title>
<para>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:</para>
</formalpara>
<itemizedlist>
<listitem>
<para>A configuration group can specify a large number of option values.</para>
</listitem>
<listitem>
<para>You can apply a configuration group to hundreds or thousands of database instances in
your environment.</para>
</listitem>
</itemizedlist>
<para>Used in this way, configuration groups let you modify your database cloud configuration,
on the fly, on a massive scale.</para>
<formalpara>
<title>Maintenance</title>
<para>There are also a number of useful maintenance features for working with configuration
groups. You can:</para>
</formalpara>
<itemizedlist>
<listitem>
<para>Disassociate a configuration group from a database instance, using the trove
<command>configuration-detach</command> command.</para>
</listitem>
<listitem>
<para>Modify a configuration group on the fly, using the trove
<command>configuration-patch</command> command.</para>
</listitem>
<listitem>
<para>Find out what instances are using a configuration group, using the trove
<command>configuration-instances</command> command.</para>
</listitem>
<listitem>
<para>Delete a configuration group, using the trove <command>configuration-delete</command>
command. You might want to do this if no instances use a group.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="set_up_replication">
<title>Set up database replication</title>
<para>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.</para>
<itemizedlist>
<listitem>
<para>Replicas are read-only.</para>
</listitem>
<listitem>
<para>When you create a replica, do not specify the <option>--users</option> or <option>--databases</option> options.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
</itemizedlist>
<para>This example shows you how to replicate a MySQL database instance.</para>
<procedure>
<title>To set up replication</title>
<step>
<title>Get the instance ID</title>
<para>Get the ID of the original instance you want to replicate:</para>
<screen><prompt>$</prompt> <userinput>trove list</userinput>
<computeroutput>+--------------------------------------+----------+-------------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+--------------------------------------+------------+-----------+-------------------+--------+-----------+------+
| 97b4b853-80f6-414f-ba6f-c6f455a79ae6 | base_1 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
+--------------------------------------+----------+-------------+-------------------+--------+-----------+------+</computeroutput></screen>
</step>
<step>
<title>Create the replica</title>
<para>Create a new instance that will be a replica of the original instance. You do this by passing in the <option>--replica_of</option> option with the trove <command>create</command> command. This example creates a replica called <literal>replica_1</literal>. <literal>replica_1</literal> is a replica of the original instance, <literal>base_1</literal>:</para>
<screen><prompt>$</prompt> <userinput>trove create replica_1 6 --size=5 --datastore_version mysql-5.5 --datastore mysql --replica_of <replaceable>ID_OF_ORIGINAL_INSTANCE</replaceable></userinput></screen>
</step>
<step>
<title>Verify replication status</title>
<para>Pass in <literal>replica_1</literal>'s instance ID with the trove <command>show</command> command to verify that the newly created <literal>replica_1</literal> instance is a replica of the original <literal>base_1</literal>. Note that the <literal>replica_of</literal> property is set to the ID of <literal>base_1</literal>.</para>
<screen><prompt>$</prompt> <userinput>trove show <replaceable>INSTANCE_ID_OF_REPLICA_1</replaceable></userinput>
<computeroutput>+-------------------+--------------------------------------+
| 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 |
+-------------------+--------------------------------------+</computeroutput></screen>
<para>Now pass in <literal>base_1</literal>'s instance ID with the trove <command>show</command> command to list the replica(s) associated with the original instance. Note that the <literal>replicas</literal> property is set to the ID of <literal>replica_1</literal>. If there are multiple replicas, they appear as a comma-separated list.</para>
<screen><prompt>$</prompt> <userinput>trove show <replaceable>INSTANCE_ID_OF_BASE_1</replaceable></userinput>
<computeroutput>+-------------------+--------------------------------------+
| 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 |
+-------------------+--------------------------------------+</computeroutput></screen>
</step>
<step>
<title>Detach the replica</title>
<para>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.</para>
<para>You detach a replica using the trove <command>detach-replica</command> command:</para>
<screen><prompt>$</prompt> <userinput>trove detach-replica <replaceable>INSTANCE_ID_OF_REPLICA</replaceable></userinput></screen>
</step>
</procedure>
</section>
<section xml:id="set_up_clustering">
<title>Set up database clustering</title>
<para>You can store data across multiple machines by setting up MongoDB sharded clusters.</para>
<para>Each cluster includes:</para>
<itemizedlist>
<listitem>
<para>One or more <emphasis>shards</emphasis>. Each shard consists of a three member replica set (three instances organized as a replica set).</para>
</listitem>
<listitem>
<para>One or more <emphasis>query routers</emphasis>. 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).</para>
</listitem>
<listitem>
<para>One or more <emphasis>config servers</emphasis>. Config servers store the metadata that links requested data with the shard that contains it.</para>
</listitem>
</itemizedlist>
<para>This example shows you how to set up a MongoDB sharded cluster.</para>
<note>
<formalpara>
<title>Before you begin</title>
<para>Make sure that:</para>
</formalpara>
<itemizedlist>
<listitem>
<para>The administrative user has registered a MongoDB datastore type and version.</para>
</listitem>
<listitem>
<para>The administrative user has created an appropriate <link linkend="create_db">flavor that meets the MongoDB minimum requirements</link>.</para>
</listitem>
</itemizedlist>
</note>
<procedure>
<title>To set up clustering</title>
<step>
<title>Create a cluster</title>
<para>Create a cluster by using the trove <command>cluster-create</command> command. This command creates a one-shard cluster. Pass in:</para>
<itemizedlist>
<listitem>
<para>The name of the cluster.</para>
</listitem>
<listitem>
<para>The name and version of the datastore you want to use.</para>
</listitem>
<listitem>
<para>The three instances you want to include in the replication set for the first shard. Specify each instance by using the <option>--instance</option> argument and the associated flavor ID and volume size. Use the same flavor ID and volume size for each instance. In this example, flavor <literal>7</literal> is a custom flavor that meets the MongoDB minimum requirements.</para>
</listitem>
</itemizedlist>
<screen><prompt>$</prompt> <userinput>trove cluster-create cluster1 mongodb "2.4" \
--instance flavor_id=7,volume=2 --instance flavor_id=7,volume=2 \
--instance flavor_id=7,volume=2</userinput>
<computeroutput>+-------------------+--------------------------------------+
| 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 |
+-------------------+--------------------------------------+</computeroutput></screen>
</step>
<step>
<title>Display cluster information</title>
<para>Display information about a cluster by using the trove <command>cluster-show</command> command. Pass in the ID of the cluster.</para>
<para>The cluster ID display when you first create a cluster. (If you need to find it later on, use the trove <command>cluster-list</command> command to list the names and IDs of all the clusters in your system.)</para>
<screen><prompt>$</prompt> <userinput>trove cluster-show <replaceable>CLUSTER_ID</replaceable></userinput>
<computeroutput>+-------------------+--------------------------------------+
| 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 |
+-------------------+--------------------------------------+</computeroutput>
</screen>
<note>
<formalpara>
<title>Your application connects to this IP address</title>
<para>The trove <command>cluster-show</command> command displays the IP address of the query router. This is the IP address your application uses to retrieve data from the database.</para>
</formalpara>
</note>
</step>
<step>
<title>List cluster instances</title>
<para>List the instances in a cluster by using the trove <command>cluster-instances</command> command.</para>
<screen><prompt>$</prompt> <userinput>trove cluster-instances <replaceable>CLUSTER_ID</replaceable></userinput>
<computeroutput>+--------------------------------------+----------------+-----------+------+
| 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 |
+--------------------------------------+----------------+-----------+------+</computeroutput></screen>
<formalpara>
<title>Naming conventions for replication sets and instances</title>
<para>Note that the <literal>Name</literal> column displays an instance name that includes the replication set name. The replication set names and instance names are automatically generated, following these rules:</para>
</formalpara>
<itemizedlist>
<listitem>
<formalpara>
<title>Replication set name</title>
<para>This name consists of the cluster name, followed by the string -rs<replaceable>n</replaceable>, where <replaceable>n</replaceable> 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 <literal>cluster1</literal>, and there is only one replication set, so the replication set name is <literal>cluster1-rs1</literal>.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Instance name</title>
<para>This name consists of the replication set name followed by the string -<replaceable>n</replaceable>, where <replaceable>n</replaceable> is 1 for the first instance in a replication set, 2 for the the second instance, and so on. In this example, the instance names are <literal>cluster1-rs1-1</literal>, <literal>cluster1-rs1-2</literal>, and <literal>cluster1-rs1-3</literal>.</para>
</formalpara>
</listitem>
</itemizedlist>
</step>
<step>
<title>List clusters</title>
<para>List all the clusters in your system, using the trove <command>cluster-list</command> command.</para>
<screen><prompt>$</prompt> <userinput>trove cluster-list</userinput>
<computeroutput>+--------------------------------------+----------+-----------+-------------------+-----------+
| 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 |
+--------------------------------------+----------+-----------+-------------------+-----------+</computeroutput></screen>
</step>
<step>
<title>Delete a cluster</title>
<para>Delete a cluster, using the trove <command>cluster-delete</command> command.</para>
<screen><prompt>$</prompt> <userinput>trove cluster-delete <replaceable>CLUSTER_ID</replaceable></userinput></screen>
</step>
</procedure>
<simplesect>
<title>Query routers and config servers</title>
<para>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).</para>
</simplesect>
</section>
</section>

299
doc/user-guide/section_dashboard_access_and_security.xml
View File

@ -1,299 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="Launching_Instances_using_Dashboard">
<title>Configure access and security for instances</title>
<?dbhtml stop-chunking?>
<para>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 <link
linkend="security_groups_add_rule">add rules to the default
security group</link> or add a new security group with rules.</para>
<para>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
<literal>cloud-init</literal> package. Each project should
have at least one key pair. For more information, see <xref
linkend="keypair_add"/>.</para>
<para>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 <xref linkend="dashboard_import_keypair"
/>.</para>
<para>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.</para>
<section xml:id="security_groups_add_rule">
<title>Add a rule to the default security group</title>
<para>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.</para>
<para>This procedure can be adjusted as necessary to add
additional security group rules to a project, if your
cloud requires them.</para>
<procedure>
<note>
<para>When adding a rule, you must specify the protocol used
with the destination port or source port.</para>
</note>
<step>
<para>Log in to the dashboard, choose a project, and
click <guilabel>Access &amp; Security</guilabel>.
The <guilabel>Security Groups</guilabel> tab shows
the security groups that are available for this
project.</para>
</step>
<step>
<para>Select the <guilabel>default</guilabel> security
group and click <guibutton>Edit
Rules</guibutton>.</para>
</step>
<step>
<para>To allow SSH access, click <guibutton>Add
Rule</guibutton>.</para>
</step>
<step>
<para>In the Add Rule dialog box, enter the following
values:</para>
<informaltable rules="all" width="75%">
<col width="50%"/>
<col width="50%"/>
<tbody>
<tr>
<td><para><guilabel>Rule</guilabel></para></td>
<td>
<para><literal>SSH</literal></para></td>
</tr>
<tr>
<td>
<para><guilabel>Remote</guilabel>
</para></td>
<td>
<para><literal>CIDR</literal></para></td>
</tr>
<tr>
<td>
<para><guilabel>CIDR</guilabel></para></td>
<td>
<para><literal>0.0.0.0/0</literal></para>
</td>
</tr>
</tbody>
</informaltable>
<note>
<para>To accept requests from a particular range
of IP addresses, specify the IP address block
in the <guilabel>CIDR</guilabel> box.</para>
</note>
</step>
<step>
<para>Click <guibutton>Add</guibutton>.</para>
<para>Instances will now have SSH port 22 open for
requests from any IP address.</para>
</step>
<step>
<para>To add an ICMP rule, click <guibutton>Add
Rule</guibutton>.</para>
</step>
<step>
<para>In the Add Rule dialog box, enter the following
values:</para>
<informaltable rules="all" width="75%">
<col width="50%"/>
<col width="50%"/>
<tr>
<td><para><guilabel>Rule</guilabel></para></td>
<td><para><literal>All ICMP</literal></para></td>
</tr>
<tr>
<td><para><guilabel>Direction</guilabel></para></td>
<td><para><literal>Ingress</literal></para></td>
</tr>
<tr>
<td><para><guilabel>Remote</guilabel></para></td>
<td><para><literal>CIDR</literal></para></td>
</tr>
<tr>
<td><para><guilabel>CIDR</guilabel></para></td>
<td><para><literal>0.0.0.0/0</literal></para></td>
</tr>
</informaltable>
</step>
<step>
<para>Click <guibutton>Add</guibutton>.</para>
<para>Instances will now accept all incoming ICMP
packets.</para>
</step>
</procedure>
</section>
<section xml:id="keypair_add">
<title>Add a key pair</title>
<para>Create at least one key pair for each project.</para>
<procedure>
<step>
<para>Log in to the dashboard, choose a project, and
click <guilabel>Access &amp;
Security</guilabel>.</para>
</step>
<step>
<para>Click the <guilabel>Keypairs</guilabel> tab,
which shows the key pairs that are available for
this project.</para>
</step>
<step>
<para>Click <guibutton>Create
Keypair</guibutton>.</para>
</step>
<step>
<para>In the Create Keypair
dialog box, enter a name for your key pair, and
click <guibutton>Create
Keypair</guibutton>.</para>
</step>
<step>
<para>Respond to the prompt to download the key
pair.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_import_keypair">
<title>Import a key pair</title>
<procedure>
<step>
<para>Log in to the dashboard, choose a project, and
click <guilabel>Access &amp;
Security</guilabel>.</para>
</step>
<step>
<para>Click the <guilabel>Keypairs</guilabel> tab,
which shows the key pairs that are available for
this project.</para>
</step>
<step>
<para>Click <guibutton>Import
Keypair</guibutton>.</para>
</step>
<step>
<para>In the Import Keypair
dialog box, enter the name of your key pair, copy
the public key into the <guilabel>Public
Key</guilabel> box, and then click
<guibutton>Import Keypair</guibutton>.</para>
</step>
<step>
<para>Save the <filename>*.pem</filename> file
locally.</para></step>
<step><para>To change its permissions so that only
you can read and write to the file, run the
following command:</para>
<screen><prompt>$</prompt> <userinput>chmod 0600 <replaceable>yourPrivateKey</replaceable>.pem</userinput></screen>
<note>
<para>If you are using the dashboard from a
Windows computer, use PuTTYgen to load the
<filename>*.pem</filename> file and
convert and save it as
<filename>*.ppk</filename>. For more
information see the <link
xlink:href="http://winscp.net/eng/docs/ui_puttygen"
>WinSCP web page for
PuTTYgen</link>.</para>
</note>
</step>
<step>
<para>To make the key pair known to SSH, run the
<command>ssh-add</command> command.</para>
<screen><prompt>$</prompt> <userinput>ssh-add <replaceable>yourPrivateKey</replaceable>.pem</userinput></screen>
</step>
</procedure>
<para>The Compute database registers the public key of the key
pair.</para>
<para>The dashboard lists the key pair on the <guilabel>Access
&amp; Security</guilabel> tab.</para>
</section>
<section xml:id="add_floating_ip">
<title>Allocate a floating IP address to an instance</title>
<para>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.
</para>
<para>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.</para>
<procedure>
<step>
<para>Log in to the dashboard, choose a project, and click
<guilabel>Access &amp; Security</guilabel>.</para>
</step>
<step>
<para>Click the <guilabel>Floating IPs</guilabel> tab,
which shows the floating IP addresses allocated to
instances.</para>
</step>
<step>
<para>Click <guibutton>Allocate IP to Project</guibutton>.</para>
</step>
<step>
<para>Choose the pool from which to pick the IP
address.</para>
</step>
<step>
<para>Click <guibutton>Allocate IP</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Floating IPs</guilabel> list, click
<guibutton> Associate</guibutton>.</para>
</step>
<step>
<para>In the Manage Floating IP
Associations dialog box, choose the
following options: <itemizedlist>
<listitem>
<para>The <guilabel>IP Address</guilabel>
field is filled automatically, but you
can add a new IP address by clicking
the <guibutton>+</guibutton>
button.</para>
</listitem>
<listitem>
<para>In the <guilabel>Ports to be
associated</guilabel> field, select
a port from the list.</para>
<para>The list shows all the instances
with their fixed IP addresses.</para>
</listitem>
</itemizedlist>
</para>
</step>
<step>
<para>Click <guibutton>Associate</guibutton>.</para>
</step>
</procedure>
<note>
<para>To disassociate an IP address from an instance, click
the <guibutton>Disassociate</guibutton> button.</para>
<para>To release the floating IP address back into the pool of
addresses, click the <guibutton>More</guibutton>
button and select the <guilabel>Release Floating
IP</guilabel> option.</para>
</note>
</section>
</section>

188
doc/user-guide/section_dashboard_create_networks.xml
View File

@ -1,188 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_create_networks">
<title>Create and manage networks</title>
<?dbhtml stop-chunking?>
<para>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).</para>
<para>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 <link
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/ch_networking.html"
><emphasis role="italic">OpenStack Cloud Administrator
Guide</emphasis></link>.</para>
<section xml:id="dashboard_create_network">
<title>Create a network</title>
<procedure>
<step>
<para>Log in to the dashboard, choose a project, and click
<guibutton>Networks</guibutton>.</para>
</step>
<step>
<para>Click <guibutton>Create Network</guibutton>.</para>
</step>
<step>
<para>In the Create Network dialog box, specify the
following values.</para>
<informaltable rules="all" width="75%">
<col width="30%"/>
<col width="70%"/>
<thead>
<tr>
<th colspan="2" align="center"
><guilabel>Network</guilabel> tab</th>
</tr>
</thead>
<tbody>
<tr>
<td><para><guilabel>Network Name</guilabel></para></td>
<td><para>Specify a name to identify the network.</para></td>
</tr>
<tr>
<th colspan="2" align="center">
<guilabel>Subnet</guilabel> tab</th>
</tr>
<tr>
<td><para><guilabel>Create Subnet</guilabel></para></td>
<td><para>Select this check box to create a
subnet</para><para>You do not have to specify a subnet
when you create a network, but if you do not, any
attached instance receives an Error status.</para></td>
</tr>
<tr>
<td><para><guilabel>Subnet Name</guilabel></para></td>
<td><para>Specify a name for the subnet.</para></td>
</tr>
<tr>
<td><para><guilabel>Network Address</guilabel></para></td>
<td><para>Specify the IP address for the subnet.</para></td>
</tr>
<tr>
<td><para><guilabel>IP Version</guilabel></para></td>
<td><para>Select IPv4 or IPv6.</para></td>
</tr>
<tr>
<td><para><guilabel>Gateway IP</guilabel></para></td>
<td><para>Specify an IP address for a specific gateway. This parameter is
optional.</para></td>
</tr>
<tr>
<td><para><guilabel>Disable Gateway</guilabel></para></td>
<td><para>Select this check box to disable a gateway IP address.</para></td>
</tr>
<tr>
<th colspan="2" align="center"
><guilabel>Subnet Detail</guilabel> tab</th>
</tr>
<tr>
<td><para><guilabel>Enable DHCP</guilabel></para></td>
<td><para>Select this check box to enable DHCP.</para></td>
</tr>
<tr>
<td><para><guilabel>Allocation Pools</guilabel></para></td>
<td><para>Specify IP address pools.</para></td>
</tr>
<tr>
<td><para><guilabel>DNS Name Servers</guilabel></para></td>
<td><para>Specify a name for the DNS server.</para></td>
</tr>
<tr>
<td><para><guilabel>Host Routes</guilabel></para></td>
<td><para>Specify the IP address of host routes.</para></td>
</tr>
</tbody>
</informaltable>
</step>
<step>
<para>Click <guilabel>Create</guilabel>.</para>
<para>The dashboard shows the network on the
<guilabel>Networks</guilabel> tab.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_create_router">
<title>Create a router</title>
<procedure>
<step>
<para>Log in to the dashboard, choose a project, and click
<guibutton>Routers</guibutton>.</para>
</step>
<step>
<para>Click <guibutton>Create Router</guibutton>.</para>
</step>
<step><para>In the Create Router dialog box, specify a name for the router
and click <guibutton>Create Router</guibutton>.</para>
<para>The new router is now displayed in the
<guilabel>Routers</guilabel> tab.</para>
</step>
<step>
<para>Click the new router's <guibutton>Set Gateway</guibutton> button.
</para>
</step>
<step>
<para>In the <guilabel>External Network</guilabel> field,
specify the network to which the router will connect, and
then click <guibutton>Set Gateway</guibutton>.</para>
</step>
<step>
<para>To connect a private network to the newly created
router, perform the following steps:</para>
<substeps>
<step>
<para>On the <guilabel>Routers</guilabel> tab, click the
name of the router.</para>
</step>
<step>
<para>On the Router Details page, click <guilabel>Add
Interface</guilabel>.</para>
</step>
<step>
<para>In the Add Interface dialog box, specify the
following information:</para>
<informaltable rules="all" width="75%">
<col width="30%"/>
<col width="70%"/>
<tbody>
<tr>
<td>
<para><guilabel>Subnet</guilabel>
</para>
</td>
<td>
<para>Select a subnet.</para>
</td>
</tr>
<tr>
<td>
<para><guilabel>IP Address (optional)</guilabel></para>
</td>
<td>
<para>Enter the router interface IP address for the
selected subnet.</para>
<para>Note: If this value is not set, then by
default, the first host IP address in the subnet
is used by OpenStack Networking.</para>
</td>
</tr>
</tbody>
</informaltable>
<para>The <guilabel>Router Name</guilabel> and <guilabel>Router ID</guilabel>
fields are automatically updated.</para>
</step>
</substeps>
</step>
<step>
<para>Click <guilabel>Add Interface</guilabel>.</para>
</step>
</procedure>
<para>You have successfully created the router. You can view
the new topology from the <guilabel>Network Topology</guilabel>
tab.</para>
</section>
</section>

219
doc/user-guide/section_dashboard_databases.xml
View File

@ -1,219 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="dashboard_databases">
<title>Create and manage databases</title>
<?dbhtml stop-chunking?>
<para>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.</para>
<section xml:id="dashboard_create_db_instance">
<title>Create a database instance</title>
<formalpara>
<title>Prerequisites</title>
<para>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.</para>
</formalpara>
<procedure>
<step>
<title>Configure a default datastore.</title>
<para>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.</para>
<substeps>
<step>
<para>Add the following line to <filename>/etc/trove/trove.conf</filename>:</para>
<programlisting language="ini">default_datastore = <replaceable>DATASTORE_NAME</replaceable></programlisting>
<para>Replace <replaceable>DATASTORE_NAME</replaceable> with the name that the administrative user set when issuing the <command>trove-manage</command> command to create the datastore. You can use the trove <command>datastore-list</command> command to display the datastores that are available in your environment.</para>
<para>For example, if your MySQL datastore name is set to <literal>mysql</literal>, your entry would look like this:</para>
<programlisting language="ini">default_datastore = mysql</programlisting>
</step>
<step>
<para>Restart Database services on the controller node:</para>
<screen><prompt>#</prompt> <userinput>service trove-api restart</userinput>
<prompt>#</prompt> <userinput>service trove-taskmanager restart</userinput>
<prompt>#</prompt> <userinput>service trove-conductor restart</userinput></screen>
</step>
</substeps>
</step>
<step>
<title>Verify flavor.</title>
<para>Make sure an <link linkend="create_db">appropriate flavor exists</link> for the type of database instance you want.</para>
</step>
</procedure>
<formalpara>
<title>Create database instance</title>
<para>Once you have configured a default datastore and verified that you have an appropriate flavor, you can create a database instance.</para>
</formalpara>
<procedure>
<step>
<para>Log in to the dashboard, choose a project, and click <guilabel>Databases</guilabel>.</para>
</step>
<step>
<para>Click <guilabel>Database Instances</guilabel>. This lists the instances that already exist in your environment.</para>
</step>
<step>
<para>Click <guibutton>Launch Instance</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Launch Database</guilabel> dialog box, specify the following values.</para>
<informaltable rules="all" width="75%">
<col width="30%"/>
<col width="70%"/>
<thead>
<tr>
<th colspan="2" align="center"><guilabel>Details</guilabel></th>
</tr>
</thead>
<tbody>
<tr>
<td><para><guilabel>Database Name</guilabel></para></td>
<td><para>Specify a name for the database instance.</para></td>
</tr>
<tr>
<td><para><guilabel>Flavor</guilabel></para></td>
<td><para>Select an appropriate flavor for the instance.</para></td>
</tr>
<tr>
<td><para><guilabel>Volume Size</guilabel></para></td>
<td><para>Select a volume size. Volume size is expressed in GB.</para></td>
</tr>
<tr>
<th colspan="2" align="center">
<guilabel>Initialize Databases</guilabel></th>
</tr>
<tr>
<td><para><guilabel>Initial Database</guilabel></para></td>
<td>
<para>Optionally provide a comma separated list of databases to create, for example:</para>
<para><literal>database1</literal>, <literal>database2</literal>, <literal>database3</literal></para>
</td>
</tr>
<tr>
<td><para><guilabel>Initial Admin User</guilabel></para></td>
<td><para>Create an initial admin user. This user will have access to all the databases you create.</para></td>
</tr>
<tr>
<td><para><guilabel>Password</guilabel></para></td>
<td><para>Specify a password associated with the initial admin user you just named.</para></td>
</tr>
<tr>
<td><para><guilabel>Host</guilabel></para></td>
<td><para>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.</para></td>
</tr>
</tbody>
</informaltable>
</step>
<step>
<para>Click the <guibutton>Launch</guibutton> button. The new database instance appears in the databases list.</para>
</step>
</procedure>
</section>
<section xml:id="dashboard_backup_db">
<title>Backup and restore a database</title>
<para>You can use Database services to backup a database and store the backup artifact in the
Object Storage module. 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.</para>
<para>This example shows you how to back up and restore a MySQL database.</para>
<procedure>
<title>To backup and restore a database</title>
<step>
<title>Backup the database instance.</title>
<substeps>
<step>
<para>Log in to the dashboard, choose a project, and click <guilabel>Databases</guilabel>.</para>
</step>
<step>
<para>Click <guilabel>Database Instances</guilabel>. This displays the existing instances in your system.</para>
</step>
<step>
<para>Click <guibutton>Create Backup</guibutton>.</para>
</step>
<step>
<para>In the Backup Database dialog box, specify the following values:</para>
<informaltable rules="all" width="75%">
<col width="30%"/>
<col width="70%"/>
<tbody>
<tr>
<td><para><guilabel>Name</guilabel></para></td>
<td><para>Specify a name for the backup.</para></td>
</tr>
<tr>
<td><para><guilabel>Database Instance</guilabel></para></td>
<td><para>Select the instance you want to back up.</para></td>
</tr>
<tr>
<td><para><guilabel>Description</guilabel></para></td>
<td><para>Specify an optional description.</para></td>
</tr>
</tbody>
</informaltable>
</step>
<step>
<para>Click <guibutton>Backup</guibutton>. The new backup appears in the backup list.</para>
</step>
</substeps>
</step>
<step>
<title>Restore a database instance.</title>
<para>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.</para>
<substeps>
<step>
<para>Log in to the dashboard, choose a project, and click <guilabel>Databases</guilabel>.</para>
</step>
<step>
<para>Click <guilabel>Database Backups</guilabel>. This lists the available backups.</para>
</step>
<step>
<para>Check the backup you want to use and click <guibutton>Restore Backup</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Launch Database</guilabel> dialog box, specify the <link linkend="dashboard_create_db_instance">values you want to use for the new database instance</link>. Click the <guilabel>Restore From Database</guilabel> tab and make sure that this new instance is based on the correct backup.</para>
</step>
<step>
<para>Click <guibutton>Launch</guibutton>. The new instance appears in the database instances list.</para>
</step>
</substeps>
</step>
</procedure>
</section>
<section xml:id="dashboard_update_db">
<title>Update a database instance</title>
<para>You can change various characteristics of a database instance, such as its volume size and flavor.</para>
<procedure>
<title>To change the volume size of an instance</title>
<step>
<para>Log in to the dashboard, choose a project, and click <guilabel>Databases</guilabel>.</para>
</step>
<step>
<para>Click <guilabel>Database Instances</guilabel>. This displays the existing instances in your system.</para>
</step>
<step>
<para>Check the instance you want to work with. In the <guilabel>Actions</guilabel> column, expand the drop down menu and select <guilabel>Resize Volume</guilabel>.</para>
</step>
<step>
<para>In the Resize Database Volume dialog box, fill in the <guilabel>New Size</guilabel> 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.</para>
</step>
<step>
<para>Click <guilabel>Resize Database Volume</guilabel>.</para>
</step>
</procedure>
<procedure>
<title>To change the flavor of an instance</title>
<step>
<para>Log in to the dashboard, choose a project, and click <guilabel>Databases</guilabel>.</para>
</step>
<step>
<para>Click <guilabel>Database Instances</guilabel>. This displays the existing instances in your system.</para>
</step>
<step>
<para>Check the instance you want to work with. In the <guilabel>Actions</guilabel> column, expand the drop down menu and select <guilabel>Resize Instance</guilabel>.</para>
</step>
<step>
<para>In the Resize Database Instance dialog box, expand the drop down menu in the <guilabel>New Flavor</guilabel> field. Select the new flavor you want for the instance.</para>
</step>
<step>
<para>Click <guilabel>Resize Database Instance</guilabel>.</para>
</step>
</procedure>
</section>
</section>

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