Add Getting Started Guides the developer doc's
These have been copied from the wiki. DocImpact Signed-off-by: Angus Salkeld <asalkeld@redhat.com> Change-Id: I4c93bc5a1811e674cef3c7868e7cf9a457c12dea
This commit is contained in:
Angus Salkeld
parent
3fb34493bf
commit
2b420437fd
25
doc/source/getting_started/index.rst
Normal file
25
doc/source/getting_started/index.rst
Normal file
@ -0,0 +1,25 @@
|
||||
..
|
||||
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.
|
||||
|
||||
Getting Started Guides
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
on_devstack
|
||||
on_fedora
|
||||
on_ubuntu
|
||||
on_other
|
||||
|
||||
.. update index
|
||||
111
doc/source/getting_started/on_devstack.rst
Normal file
111
doc/source/getting_started/on_devstack.rst
Normal file
@ -0,0 +1,111 @@
|
||||
..
|
||||
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.
|
||||
|
||||
Heat and Devstack
|
||||
=================
|
||||
Heat is fully integrated into DevStack. This is a convenient way to try out or develop heat alongside the current development state of all the other OpenStack projects. Heat on DevStack works on both Ubuntu and Fedora.
|
||||
|
||||
These instructions assume you already have a working DevStack installation which can launch basic instances.
|
||||
|
||||
Configure DevStack to enable Heat
|
||||
---------------------------------
|
||||
Adding the following line to your `localrc` file will enable the heat services
|
||||
::
|
||||
ENABLED_SERVICES+=,heat,h-api,h-api-cfn,h-api-cw,h-eng
|
||||
|
||||
It would also be useful to automatically download and register a VM image that Heat can launch.
|
||||
::
|
||||
IMAGE_URLS+=",http://fedorapeople.org/groups/heat/prebuilt-jeos-images/F16-x86_64-cfntools.qcow2,http://fedorapeople.org/groups/heat/prebuilt-jeos-images/F16-i386-cfntools.qcow2"
|
||||
|
||||
URLs for any of [http://fedorapeople.org/groups/heat/prebuilt-jeos-images/ these prebuilt JEOS images] can be specified.
|
||||
|
||||
That is all the configuration that is required. When you run `./stack.sh` the Heat processes will be launched in `screen` with the labels prefixed with `h-`.
|
||||
|
||||
Confirming heat is responding
|
||||
-----------------------------
|
||||
Before any heat commands can be run, the authentication environment needs to be loaded
|
||||
::
|
||||
source openrc
|
||||
|
||||
You can confirm that Heat is running and responding with this command
|
||||
::
|
||||
heat list
|
||||
|
||||
This should return an empty line
|
||||
|
||||
Preparing Nova for running stacks
|
||||
---------------------------------
|
||||
Enabling Heat in devstack will replace the default Nova flavors with flavours that the Heat example templates expect. You can see what those flavors are by running
|
||||
::
|
||||
|
||||
nova flavor-list
|
||||
|
||||
Heat needs to launch instances with a keypair, so we need to generate one
|
||||
::
|
||||
|
||||
nova keypair-add heat_key > heat_key.priv
|
||||
chmod 600 heat_key.priv
|
||||
|
||||
Launching a stack
|
||||
-----------------
|
||||
Now lets launch a stack, assuming that DEST is left as the default /opt/stack::
|
||||
|
||||
heat create teststack -f
|
||||
/opt/stack/heat/templates/WordPress_Single_Instance.template -P "InstanceType=m1.large;DBUsername=wp;DBPassword=verybadpassword;KeyName=heat_key;LinuxDistribution=F16"
|
||||
|
||||
Which will respond::
|
||||
|
||||
+--------------------------------------+-----------+--------------------+----------------------+
|
||||
| ID | Name | Status | Created |
|
||||
+--------------------------------------+-----------+--------------------+----------------------+
|
||||
| (uuid) | teststack | CREATE_IN_PROGRESS | (timestamp) |
|
||||
+--------------------------------------+-----------+--------------------+----------------------+
|
||||
|
||||
|
||||
List stacks
|
||||
~~~~~~~~~~~
|
||||
List the stacks in your tenant::
|
||||
|
||||
heat list
|
||||
|
||||
List stack events
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
List the events related to a particular stack::
|
||||
|
||||
heat event-list teststack
|
||||
|
||||
Describe the wordpress stack
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Show detailed state of a stack::
|
||||
|
||||
heat describe teststack
|
||||
|
||||
Note: After a few seconds, the stack_status should change from IN_PROGRESS to CREATE_COMPLETE.
|
||||
|
||||
Verify instance creation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Because the software takes some time to install from the repository, it may be a few minutes before the Wordpress instance is in a running state.
|
||||
|
||||
Point a web browser at the location given by the WebsiteURL Output as shown by heat stack-show teststack::
|
||||
|
||||
wget ${WebsiteURL}
|
||||
|
||||
Delete the instance when done
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Note: The list operation will show no running stack.::
|
||||
|
||||
heat delete teststack
|
||||
heat list
|
||||
407
doc/source/getting_started/on_fedora.rst
Normal file
407
doc/source/getting_started/on_fedora.rst
Normal file
@ -0,0 +1,407 @@
|
||||
..
|
||||
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.
|
||||
|
||||
Getting Started With Heat on Fedora
|
||||
===================================
|
||||
|
||||
..
|
||||
This file is a ReStructuredText document, but can be converted to a script
|
||||
using the accompanying rst2script.sed script. Any blocks that are indented by
|
||||
4 spaces (including comment blocks) will appear in the script. To document
|
||||
code that should not appear in the script, use an indent of less than 4
|
||||
spaces. (Using a Quoted instead of Indented Literal block also works.)
|
||||
To include code in the script that should not appear in the output, make it
|
||||
a comment block.
|
||||
|
||||
..
|
||||
#!/bin/bash
|
||||
|
||||
# Exit on error
|
||||
set -e
|
||||
|
||||
Get Heat
|
||||
--------
|
||||
|
||||
Clone the heat repository_ from GitHub at ``git://github.com/openstack/heat.git``. Note that OpenStack must be installed before heat.
|
||||
Optionally, one may wish to install Heat via RPM. Creation instructions are in the readme in the heat-rpms_ repository at ``git://github.com/heat-api/heat-rpms.git``.
|
||||
|
||||
.. _repository: https://github.com/openstack/heat
|
||||
.. _heat-rpms: https://github.com/heat-api/heat-rpms
|
||||
|
||||
Install OpenStack
|
||||
-----------------
|
||||
|
||||
Installing OpenStack on Fedora 16/17/18
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Note:
|
||||
- On Fedora 16 you have to enable the `Preview Repository`_ to install the required OpenStack Essex release.
|
||||
- On Fedora 17 you can use the included OpenStack Essex release, or optionally enable the `Preview Repository`_ to install the newer OpenStack Folsom release.
|
||||
- On Fedora 18 you can use the included OpenStack Folsom release
|
||||
|
||||
A script called "``openstack``" in the tools directory of the repository will install and start OpenStack for you on Fedora::
|
||||
|
||||
./tools/openstack install -y -r ${MYSQL_ROOT_PASSWORD}
|
||||
|
||||
If you use this method, you will need to manually create a guest network. How this is done depends on your environment. An example network create operation:
|
||||
|
||||
..
|
||||
SUBNET=10.0.0.0/24
|
||||
|
||||
::
|
||||
|
||||
sudo nova-manage network create demonet ${SUBNET} 1 256 --bridge=demonetbr0
|
||||
|
||||
Where ``${SUBNET}`` is of the form ``10.0.0.0/24``. The network range here, must *not* be one used on your existing physical network. It should be a range dedicated for the network that OpenStack will configure. So if ``10.0.0.0/24`` clashes with your local network, pick another subnet.
|
||||
|
||||
Currently, the bridge is not created immediately upon running this command, but is actually added when Nova first requires it.
|
||||
|
||||
If you wish to set up OpenStack manually on Fedora, read `Getting Started With OpenStack On Fedora`_.
|
||||
|
||||
.. _Getting Started With OpenStack on Fedora: http://fedoraproject.org/wiki/Getting_started_with_OpenStack_on_Fedora_17
|
||||
.. _Preview Repository: http://fedoraproject.org/wiki/OpenStack#Preview_repository
|
||||
|
||||
Download or alternatvely generate a JEOS image
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
It is possible to use either heat-jeos to create an image or download a
|
||||
prebuilt image of a desired distribution.
|
||||
|
||||
Note heat-jeos does not work in virt on virt situations. In this case, it
|
||||
is recommended that the prebuilt images are used.
|
||||
|
||||
Download a prebuilt image and copy to libvirt images location
|
||||
-------------------------------------------------------------
|
||||
Download a prebuilt image from ``http://fedorapeople.org/groups/heat/prebuilt-jeos-images/``.
|
||||
|
||||
Note: This example assumes F17-x86_64-cfntools qcow2 was downloaded.
|
||||
|
||||
::
|
||||
|
||||
sudo cp Downloads/F17-x86_64-cfntools.qcow2 /var/lib/libvirt/images
|
||||
|
||||
Register with glance:
|
||||
|
||||
::
|
||||
|
||||
glance image-create --name=F17-x86_64-cfntools --disk-format=qcow2 --container-format=bare < /var/lib/libvirt/images/F17-x86_64-cfntools.qcow2
|
||||
|
||||
Alternatively Download Fedora 17 DVD and copy it to libvirt images location
|
||||
---------------------------------------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
sudo cp Downloads/Fedora-17-x86_64-DVD.iso /var/lib/libvirt/images
|
||||
|
||||
Alternatively Install OZ
|
||||
------------------------
|
||||
|
||||
It is recommended to install the latest upstream oz, as this supports Fedora 17 (and Ubuntu U10/U12) guests::
|
||||
|
||||
git clone -q https://github.com/clalancette/oz.git
|
||||
pushd oz
|
||||
rm -f ~/rpmbuild/RPMS/noarch/oz-*
|
||||
make rpm
|
||||
sudo yum -q -y localinstall ~/rpmbuild/RPMS/noarch/oz-*
|
||||
popd
|
||||
|
||||
Note: In the steps above, it's only necessary to be root for the yum localinstall, it's recommended not to be root while building the rpm.
|
||||
|
||||
If you do not require F17/U10/U12 support, oz can be installed directly via yum::
|
||||
|
||||
yum install oz
|
||||
|
||||
Alternatively Download and install heat-jeos via git
|
||||
----------------------------------------------------
|
||||
Download heat-jeos via git
|
||||
|
||||
::
|
||||
|
||||
git clone -q git://github.com/sdake/heat-jeos.git
|
||||
pushd heat-jeos
|
||||
sudo python setup.py install
|
||||
popd
|
||||
|
||||
Alternatively Create a JEOS with heat_jeos tools
|
||||
------------------------------------------------
|
||||
::
|
||||
|
||||
sudo -E heat-jeos -y create F17-x86_64-cfntools --register-with-glance
|
||||
|
||||
Note: The ``-E`` option to ``sudo`` preserves the environment, specifically the keystone credentials, when ``heat-jeos`` is run as root.
|
||||
|
||||
Note: ``heat-jeos`` must be run as root in order to create the cfntools disk image.
|
||||
|
||||
Note: If you want to enable debugging output from Oz, add '``-d``' (debugging) to the ``heat-jeos`` command.
|
||||
|
||||
You can run ``heat-jeos list`` to pick a different JEOS image.
|
||||
|
||||
|
||||
Install and Configure Heat
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Install heat from source
|
||||
------------------------
|
||||
|
||||
In the heat directory, run the install script::
|
||||
|
||||
sudo ./install.sh
|
||||
|
||||
Source the keystone credentials created with tools/openstack
|
||||
------------------------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
source ~/.openstack/keystonerc
|
||||
|
||||
Note: these credentials will be required for all future steps.
|
||||
|
||||
Allocate Floating IP Addresses to OpenStack
|
||||
-------------------------------------------
|
||||
|
||||
If you want to use templates that depend on ``AWS::EC2::EIP`` or ``AWS::EC2::EIPAssociation`` (multi-instance stacks often do, single-instance less often but it's still possible), see the wiki page on `Configuring Floating IPs`_.
|
||||
|
||||
.. _Configuring Floating IPs: http://wiki.openstack.org/Heat/Configuring-Floating-IPs
|
||||
|
||||
Setup the MySQL database for Heat
|
||||
---------------------------------
|
||||
|
||||
::
|
||||
|
||||
heat-db-setup rpm -y -r ${MYSQL_ROOT_PASSWORD}
|
||||
|
||||
Note: the first argument is either ``rpm`` for RPM-based distros (such as Fedora) or ``deb`` for Debian-based distros (such as Ubuntu). To prompt for confirmation when e.g. installing MySQL Server, omit the ``-y`` option. Run ``heat-db-setup --help`` for detailed documentation.
|
||||
|
||||
Register heat with keystone
|
||||
---------------------------
|
||||
|
||||
::
|
||||
|
||||
sudo -E ./bin/heat-keystone-setup
|
||||
|
||||
Note: The ``-E`` option to ``sudo`` preserves the environment, specifically the keystone credentials, when ``heat-keystone-setup`` is run as root. This script needs to run as root in order to read the admin password.
|
||||
|
||||
Register a SSH key-pair with OpenStack Nova
|
||||
-------------------------------------------
|
||||
|
||||
This is for Heat to associate with the virtual machines.
|
||||
|
||||
::
|
||||
|
||||
nova keypair-add --pub_key ~/.ssh/id_rsa.pub ${USER}_key
|
||||
|
||||
|
||||
Verify JEOS registration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Check that there is a ``F17-x86_64-cfntools`` JEOS in glance:
|
||||
|
||||
..
|
||||
GLANCE_INDEX=$(cat <<EOF
|
||||
|
||||
::
|
||||
|
||||
glance index
|
||||
|
||||
..
|
||||
EOF
|
||||
)
|
||||
$GLANCE_INDEX | grep -q "F17-x86_64-cfntools"
|
||||
|
||||
Update heat engine configuration file
|
||||
-------------------------------------
|
||||
|
||||
The heat engine configuration file should be updated with the address of the bridge device (demonetbr0), however this device is not created by nova-network until the first instance is launched, so we assume that $BRIDGE_IP is 10.0.0.1 if $SUBNET is 10.0.0.0/24 as in the instructions above:
|
||||
|
||||
..
|
||||
BRIDGE_IP=`echo $SUBNET | awk -F'[./]' '{printf "%d.%d.%d.%d", $1, $2, $3, or($4, 1)}'`
|
||||
|
||||
::
|
||||
|
||||
sudo sed -i -e "/heat_metadata_server_url/ s/127\.0\.0\.1/${BRIDGE_IP}/" /etc/heat/heat-engine.conf
|
||||
sudo sed -i -e "/heat_waitcondition_server_url/ s/127\.0\.0\.1/${BRIDGE_IP}/" /etc/heat/heat-engine.conf
|
||||
sudo sed -i -e "/heat_watch_server_url/ s/127\.0\.0\.1/${BRIDGE_IP}/" /etc/heat/heat-engine.conf
|
||||
|
||||
Launch the Heat services
|
||||
------------------------
|
||||
|
||||
::
|
||||
|
||||
sudo -E bash -c 'heat-api-cfn & heat-engine &'
|
||||
|
||||
..
|
||||
sleep 5
|
||||
|
||||
Launch a Wordpress instance
|
||||
---------------------------
|
||||
|
||||
::
|
||||
|
||||
heat-cfn create wordpress --template-file=templates/WordPress_Single_Instance.template --parameters="InstanceType=m1.xlarge;DBUsername=${USER};DBPassword=verybadpass;KeyName=${USER}_key"
|
||||
|
||||
List stacks
|
||||
-----------
|
||||
|
||||
::
|
||||
|
||||
heat-cfn list
|
||||
|
||||
List stack events
|
||||
-----------------
|
||||
|
||||
::
|
||||
|
||||
heat-cfn event-list wordpress
|
||||
|
||||
Describe the ``wordpress`` stack
|
||||
--------------------------------
|
||||
|
||||
..
|
||||
HEAT_DESCRIBE=$(cat <<EOF
|
||||
|
||||
::
|
||||
|
||||
heat-cfn describe wordpress
|
||||
|
||||
..
|
||||
EOF
|
||||
)
|
||||
|
||||
After a few seconds, the ``StackStatus`` should change from ``CREATE_IN_PROGRESS`` to ``CREATE_COMPLETE``.
|
||||
|
||||
..
|
||||
# Wait for Stack creation
|
||||
CREATING="<StackStatus>CREATE_IN_PROGRESS</StackStatus>"
|
||||
retries=24
|
||||
while $HEAT_DESCRIBE | grep -q $CREATING && ((retries-- > 0))
|
||||
do
|
||||
echo "Waiting for Stack creation to complete..." >&2
|
||||
sleep 5
|
||||
done
|
||||
|
||||
$HEAT_DESCRIBE | grep -q "<StackStatus>CREATE_COMPLETE</StackStatus>"
|
||||
|
||||
|
||||
Verify instance creation
|
||||
------------------------
|
||||
|
||||
Because the software takes some time to install from the repository, it may be a few minutes before the Wordpress intance is in a running state. One way to check is to login via ssh and ``tail -f /var/log/yum.log``. Once ``mysql-server`` installs, the instance should be ready to go.
|
||||
|
||||
..
|
||||
WebsiteURL=$($HEAT_DESCRIBE | sed \
|
||||
-e '/<OutputKey>WebsiteURL<\/OutputKey>/,/<\/member>/ {' \
|
||||
-e '/<OutputValue>/ {' \
|
||||
-e 's/<OutputValue>\([^<]*\)<\/OutputValue>/\1/' \
|
||||
-e p \
|
||||
-e '}' -e '}' \
|
||||
-e d \
|
||||
)
|
||||
HOST=`echo $WebsiteURL | sed -r -e 's#http://([^/]+)/.*#\1#'`
|
||||
|
||||
retries=9
|
||||
while ! ping -q -c 1 $HOST >/dev/null && ((retries-- > 0)); do
|
||||
echo "Waiting for host networking..." >&2
|
||||
sleep 2
|
||||
done
|
||||
test $retries -ge 0
|
||||
|
||||
sleep 10
|
||||
|
||||
retries=49
|
||||
while ! ssh -o PasswordAuthentication=no -o StrictHostKeyChecking=no \
|
||||
-q -t -l ec2-user $HOST \
|
||||
sudo grep -q mysql-server /var/log/yum.log && \
|
||||
((retries-- > 0))
|
||||
do
|
||||
echo "Waiting for package installation..." >&2
|
||||
sleep 5
|
||||
done
|
||||
test $retries -ge 0
|
||||
|
||||
echo "Pausing to wait for application startup..." >&2
|
||||
sleep 60
|
||||
|
||||
Point a web browser at the location given by the ``WebsiteURL`` Output as shown by ``heat-cfn describe``::
|
||||
|
||||
wget ${WebsiteURL}
|
||||
|
||||
Delete the instance when done
|
||||
-----------------------------
|
||||
|
||||
::
|
||||
|
||||
heat-cfn delete wordpress
|
||||
heat-cfn list
|
||||
|
||||
Note: This operation will show no running stack.
|
||||
|
||||
Other Templates
|
||||
---------------
|
||||
Check out the ``Wordpress_2_Instances_with_EBS_EIP.template``. This uses a few different APIs in OpenStack nova, such as the Volume API, the Floating IP API and the Security Groups API, as well as the general nova launching and monitoring APIs.
|
||||
|
||||
IPtables rules
|
||||
--------------
|
||||
|
||||
Some templates require the instances to be able to connect to the heat CFN API (for metadata update via cfn-hup and waitcondition notification via cfn-signal):
|
||||
|
||||
Open up port 8000 so that the guests can communicate with the heat-api-cfn server::
|
||||
|
||||
sudo iptables -I INPUT -p tcp --dport 8000 -j ACCEPT -i demonetbr0
|
||||
|
||||
Open up port 8003 so that the guests can communicate with the heat-api-cloudwatch server::
|
||||
|
||||
sudo iptables -I INPUT -p tcp --dport 8003 -j ACCEPT -i demonetbr0
|
||||
|
||||
Note the above rules will not persist across reboot, so you may wish to add them to /etc/sysconfig/iptables
|
||||
|
||||
Start the Heat Cloudwatch server
|
||||
--------------------------------
|
||||
|
||||
If you wish to try any of the HA or autoscaling templates (which collect stats from instances via the CloudWatch API), it is neccessary to start the heat-api-cloudwatch server::
|
||||
|
||||
sudo -E bash -c 'heat-api-cloudwatch &'
|
||||
|
||||
Further information on using the heat cloudwatch features is available in the Using-Cloudwatch_ wiki page
|
||||
|
||||
.. _Using-Cloudwatch: http://wiki.openstack.org/Heat/Using-CloudWatch
|
||||
|
||||
Using the OpenStack Heat API
|
||||
----------------------------
|
||||
|
||||
CloudFormation (heat-api-cfn) and a native OpenStack Heat API (heat-api) are provided. To use the recommended Heat API, a python client library is necessary. To use this library, clone the python-heatclient repository_ from GitHub at ``git://github.com/openstack/python-heatclient.git``.
|
||||
|
||||
Install python-heatclient from source
|
||||
-------------------------------------
|
||||
|
||||
In the python-heatclient directory, run the install script::
|
||||
|
||||
sudo ./setup.py install
|
||||
|
||||
Note that python-heatclient may be installed on a different server than heat itself.
|
||||
Note that pip can be used to install python-heatclient, but the instructions vary for each distribution. Read your distribution documentation if you wish to install with pip.
|
||||
|
||||
Start the OpenStack specific Heat API
|
||||
-------------------------------------
|
||||
|
||||
When using heat-pythonclient, the OpenStack API service provided by heat must be started::
|
||||
|
||||
sudo bash -c 'heat-api &'
|
||||
|
||||
List stacks
|
||||
-----------
|
||||
|
||||
::
|
||||
|
||||
heat stack-list
|
||||
|
||||
..
|
||||
echo; echo 'Success!'
|
||||
22
doc/source/getting_started/on_other.rst
Normal file
22
doc/source/getting_started/on_other.rst
Normal file
@ -0,0 +1,22 @@
|
||||
..
|
||||
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.
|
||||
|
||||
Installing OpenStack on other Distributions
|
||||
===========================================
|
||||
|
||||
- There is a `Debian packaging team for OpenStack`_.
|
||||
- There are instructions for `installing OpenStack on Ubuntu`_.
|
||||
- Various other distributions may have packaging teams or Getting Started guides available.
|
||||
|
||||
.. _Debian packaging team for OpenStack: http://wiki.openstack.org/Packaging/Debian
|
||||
.. _installing OpenStack on Ubuntu: http://docs.openstack.org/bexar/openstack-compute/admin/content/ch03s02.html
|
||||
273
doc/source/getting_started/on_ubuntu.rst
Normal file
273
doc/source/getting_started/on_ubuntu.rst
Normal file
@ -0,0 +1,273 @@
|
||||
..
|
||||
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.
|
||||
|
||||
Getting Started With Heat on Ubuntu
|
||||
===================================
|
||||
|
||||
This guide will help to get the current git master of Heat to run on Ubuntu. It makes the following assumptions:
|
||||
|
||||
- The host is running Ubuntu 12.04 or 12.10
|
||||
- There is a working OpenStack installation based on Folsom, Grizzly or Havana, or that one will be installed via the tools/openstack_ubuntu script described below
|
||||
- Heat will be installed on the controller host of the existing OpenStack installation (or if doing a single-host evaluation, on the same host as all other OpenStack services)
|
||||
|
||||
Get Heat
|
||||
--------
|
||||
|
||||
Clone the heat repository_ from GitHub at ``git://github.com/openstack/heat.git``. Note that OpenStack must be installed before heat.
|
||||
|
||||
.. _repository: https://github.com/openstack/heat
|
||||
|
||||
Install OpenStack
|
||||
-----------------
|
||||
|
||||
Note, this section may be skipped if you already have a working OpenStack installation
|
||||
|
||||
Installing OpenStack on Ubuntu 12.04/12.10
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A script called openstack_ubuntu in the tools directory of the Heat repository will install and start OpenStack for you on Ubuntu:
|
||||
''Note currently only tested on 12.04, if it works for you on 12.10, please let us know''
|
||||
::
|
||||
|
||||
./tools/openstack_ubuntu install -r ${MYSQL_ROOT_PASSWORD}
|
||||
|
||||
If you use this method, you will need to manually create a guest network. How this is done depends on your environment. An example network create operation:
|
||||
|
||||
..
|
||||
SUBNET=10.0.0.0/24
|
||||
|
||||
::
|
||||
|
||||
sudo nova-manage network create --label=demonet --fixed_range_v4=${SUBNET} --bridge=demonetbr0 --bridge_interface=eth0
|
||||
|
||||
Where ''${SUBNET}'' is of the form ''10.0.0.0/24''. The network range here, must *not* be one used on your existing physical network. It should be a range dedicated for the network that OpenStack will configure. So if ''10.0.0.0/24'' clashes with your local network, pick another subnet.
|
||||
|
||||
The example above assumes you want to bridge with physical device ''eth0''
|
||||
|
||||
Currently, the bridge is not created immediately upon running this command, but is actually added when Nova first requires it.
|
||||
|
||||
Load keystone authentication into your environment and verify everything is ok.
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
. ~/.openstack/keystonerc
|
||||
keystone user-list
|
||||
glance index
|
||||
nova list
|
||||
|
||||
Note ''~/.openstack/keystonerc'' is created by tools/openstack_ubuntu, replace this step with your own credentials file for an admin user if OpenStack was installed by some other method
|
||||
|
||||
Install prerequisites
|
||||
---------------------
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install python-pip gcc python2.7-dev
|
||||
sudo apt-get install git
|
||||
sudo apt-get install build-essential devscripts debhelper python-all gdebi-core
|
||||
sudo apt-get install python-setuptools python-prettytable python-lxml
|
||||
sudo apt-get install libguestfs*
|
||||
|
||||
Install python-heatclient (optional)
|
||||
------------------------------------
|
||||
*NOTE* If running 12.04 LTS with the packaged Openstack Essex release, do not install python-heatclient, as it will break your OpenStack installation, because it explicitly requires a version of the prettytable library (>0.6) which causes problems with the Essex cli tools (keystone/nova/glance) in 12.04 : https://bugs.launchpad.net/keystone/+bug/995976 The packaged python-prettytable (0.5 version) works OK
|
||||
|
||||
::
|
||||
|
||||
sudo pip install python-heatclient
|
||||
|
||||
Install Heat from master
|
||||
------------------------
|
||||
|
||||
::
|
||||
|
||||
git clone git://github.com/openstack/heat.git
|
||||
cd heat
|
||||
sudo ./install.sh
|
||||
|
||||
Modify configuration for admin password
|
||||
---------------------------------------
|
||||
Later a keystone user called '''heat''' will be created. At this point a password for that user needs to be chosen.
|
||||
The following files will need editing:
|
||||
|
||||
- /etc/heat/heat-api-cfn-paste.ini
|
||||
- /etc/heat/heat-api-cloudwatch-paste.ini
|
||||
- /etc/heat/heat-api-paste.ini
|
||||
|
||||
::
|
||||
|
||||
[filter:authtoken]
|
||||
admin_password=<heat admin password>
|
||||
|
||||
|
||||
Create the MySQL Heat database:
|
||||
-------------------------------
|
||||
::
|
||||
|
||||
sudo heat-db-setup deb -r <mysql password>
|
||||
|
||||
Create the keystone authentication parameters
|
||||
---------------------------------------------
|
||||
::
|
||||
|
||||
sudo -E ./bin/heat-keystone-setup
|
||||
|
||||
Install Oz from the upstream master location
|
||||
--------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
git clone https://github.com/clalancette/oz.git
|
||||
cd oz
|
||||
make deb
|
||||
cd ..
|
||||
sudo dpkg -i oz_*_all.deb
|
||||
sudo apt-get -f install
|
||||
|
||||
Note: Select yes to "Create or update supermin appliance.". This will rebuild the guestfs appliance to work with latest updates of Ubuntu. Oz will not work properly without updating the guestfs appliance.
|
||||
|
||||
Note: We recommend cloning oz from the latest master. The debian packaging is broken in older versions and U10/U12 support is not available in Oz shipped with distros.
|
||||
|
||||
Install heat-jeos from master
|
||||
-----------------------------
|
||||
|
||||
The heat-jeos tool builds virtual machine images for use with Heat.
|
||||
::
|
||||
|
||||
git clone git://github.com/sdake/heat-jeos.git
|
||||
cd heat-jeos
|
||||
sudo python setup.py install
|
||||
|
||||
Download ISO images for various distributions
|
||||
---------------------------------------------
|
||||
If you just want to try a basic wordpress template, download http://releases.ubuntu.com/10.04.4/ubuntu-10.04.4-server-amd64.iso
|
||||
|
||||
If you want to try more templates, also download http://download.fedoraproject.org/pub/fedora/linux/releases/17/Fedora/x86_64/iso/Fedora-17-x86_64-DVD.iso
|
||||
|
||||
After download completes, copy the iso image to the location heat-jeos expects:::
|
||||
|
||||
sudo cp Downloads/ubuntu-10.04.4-server-amd64.iso /var/lib/libvirt/images
|
||||
|
||||
Configure your host to work with Heat
|
||||
-------------------------------------
|
||||
|
||||
Create SSH key and add it to the Nova sshkey list
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
::
|
||||
|
||||
ssh-keygen -t rsa
|
||||
nova keypair-add --pub_key ~/.ssh/id_rsa.pub ${USER}_key
|
||||
|
||||
Note: If running in a VM, modify /etc/libvirt/qemu/networks/default.xml:
|
||||
change network to not conflict with host (default 192.168.122.x)
|
||||
::
|
||||
|
||||
sudo service libvirt-bin restart
|
||||
|
||||
If dnsmasq is not running on the default network
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
sudo virsh net-destroy default
|
||||
sudo virsh net-start default
|
||||
|
||||
Configure libguestfs (required by Oz) to work in latest Ubuntu 12
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Some files shipped with Ubuntu 12 are incompatible with libguestfs
|
||||
used by the image creation software Oz. To allow heat-jeos to work
|
||||
properly, run the following commands:
|
||||
|
||||
::
|
||||
|
||||
sudo chmod 644 /boot/vmlinuz*
|
||||
sudo update-guestfs-appliance
|
||||
|
||||
Note: For more details see: http://permalink.gmane.org/gmane.comp.emulators.guestfs/1382
|
||||
and http://libguestfs.org/guestfs-faq.1.html
|
||||
|
||||
Note: If you want to create F17 images, you may need a new libguestfs binary of version 1.18.0 or later. Ubuntu Precise may not have this version yet.
|
||||
|
||||
You can use the Debian Wheezy version including the `guestfs shared library`_, the tools_ and the `python libraries`_.
|
||||
|
||||
.. _guestfs shared library: http://packages.debian.org/wheezy/amd64/libguestfs0/download
|
||||
.. _tools: http://packages.debian.org/wheezy/amd64/libguestfs-tools/download
|
||||
.. _python libraries: http://packages.debian.org/wheezy/amd64/python-guestfs/download
|
||||
|
||||
Create the Heat JEOS image
|
||||
--------------------------
|
||||
::
|
||||
|
||||
sudo -E heat-jeos -y create U10-x86_64-cfntools --register-with-glance
|
||||
|
||||
Note: The -E option to sudo preserves the environment, specifically the keystone credentials, when heat-jeos is run as root.
|
||||
|
||||
Note: heat-jeos must be run as root in order to create the cfntools disk image.
|
||||
|
||||
Experiment with Heat
|
||||
--------------------
|
||||
|
||||
Execute the heat api services
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
::
|
||||
|
||||
sudo heat-engine &
|
||||
sudo heat-api &
|
||||
sudo heat-api-cfn &
|
||||
sudo heat-api-cloudwatch &
|
||||
|
||||
Run the debian wordpress example
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
::
|
||||
|
||||
heat stack-create wordpress --template-file=templates/WordPress_Single_Instance_deb.template --parameters="InstanceType=m1.xlarge;DBUsername=${USER};DBPassword=verybadpassword;KeyName=${USER}_key;LinuxDistribution=U10"
|
||||
|
||||
List stacks
|
||||
~~~~~~~~~~~
|
||||
::
|
||||
|
||||
heat stack-list
|
||||
|
||||
List stack events
|
||||
~~~~~~~~~~~~~~~~~
|
||||
::
|
||||
|
||||
heat event-list wordpress
|
||||
|
||||
Describe the wordpress stack
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
::
|
||||
|
||||
heat stack-show wordpress
|
||||
|
||||
Note: After a few seconds, the Status should change from IN_PROGRESS to CREATE_COMPLETE.
|
||||
|
||||
Verify instance creation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Because the software takes some time to install from the repository, it may be a few minutes before the Wordpress intance is in a running state.
|
||||
|
||||
Point a web browser at the location given by the WebsiteURL Output as shown by heat show-stack wordpress::
|
||||
::
|
||||
|
||||
wget ${WebsiteURL}
|
||||
|
||||
Delete the instance when done
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
heat stack-delete wordpress
|
||||
heat stack-list
|
||||
|
||||
Note: This operation will show no running stack.
|
||||
@ -17,6 +17,9 @@
|
||||
|
||||
.. glossary::
|
||||
|
||||
OpenStack
|
||||
Open source software for building private and public clouds.
|
||||
|
||||
API server
|
||||
HTTP REST API service for heat.
|
||||
|
||||
|
||||
@ -22,7 +22,7 @@ What is the purpose of the project and vision for it?
|
||||
=====================================================
|
||||
|
||||
* Heat provides a template based orchestration for describing a cloud application
|
||||
by executing appropriate OpenStack API calls to generate running cloud applications.
|
||||
by executing appropriate :term:`OpenStack` API calls to generate running cloud applications.
|
||||
* The software integrates other core components of OpenStack into a one-file
|
||||
template system. The templates allow creation of most OpenStack resource types
|
||||
(such as instances, floating ips, volumes, security groups, users, etc), as well
|
||||
@ -41,6 +41,8 @@ Table of contents
|
||||
:maxdepth: 2
|
||||
|
||||
man/index
|
||||
getting_started/index
|
||||
troubleshooting/index
|
||||
glossary
|
||||
|
||||
.. update index
|
||||
|
||||
19
doc/source/troubleshooting/index.rst
Normal file
19
doc/source/troubleshooting/index.rst
Normal file
@ -0,0 +1,19 @@
|
||||
..
|
||||
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.
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
If you encounter issues running heat, see if the solution to the issue is documented on the Troubleshooting_ wiki page. If not, let us know about the problem in the #heat IRC channel on freenode.
|
||||
|
||||
.. _Troubleshooting: http://wiki.openstack.org/Heat/TroubleShooting
|
||||
Loading…
Reference in New Issue
Block a user