diff --git a/docs/GettingStarted.rst b/docs/GettingStarted.rst index e0472e25f..aa2cf0240 100644 --- a/docs/GettingStarted.rst +++ b/docs/GettingStarted.rst @@ -1,417 +1,8 @@ Getting Started With Heat ========================= -.. - 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. +There are `getting started guides`_ for several distributions in the Heat documentation -.. - #!/bin/bash - - # Exit on error - set -e +This is the old guide location, so please update any links to this page. -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 17/18 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Note: - - On Fedora 17 using the `Preview Repository`_ to install the OpenStack Folsom release is recommended - - On Fedora 18 you can use the included OpenStack Folsom release or the Grizzly `Preview Repository`_ - -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 - -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 - - -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 - -If running OpenStack grizzly installed via tools/openstack, it is necessary to modify the default service user password:: - - sudo sed -i "s/verybadpass/secrete/" /etc/heat/heat-api-cfn.conf - sudo sed -i "s/verybadpass/secrete/" /etc/heat/heat-api-cloudwatch.conf - sudo sed -i "s/verybadpass/secrete/" /etc/heat/heat-api.conf - -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 < 0)) - do - echo "Waiting for Stack creation to complete..." >&2 - sleep 5 - done - - $HEAT_DESCRIBE | grep -q "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. 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 '/WebsiteURL<\/OutputKey>/,/<\/member>/ {' \ - -e '// {' \ - -e 's/\([^<]*\)<\/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 - -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 - -.. - echo; echo 'Success!' +.. _getting started guides: http://docs.openstack.org/developer/heat/getting_started/index.html