diff --git a/doc/source/getting_started/create_a_stack.rst b/doc/source/getting_started/create_a_stack.rst new file mode 100644 index 0000000000..08e0f49daa --- /dev/null +++ b/doc/source/getting_started/create_a_stack.rst @@ -0,0 +1,107 @@ +.. + 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. + +.. _create-a-stack: + +Creating your first stack +========================= + +Confirming you can access a Heat endpoint +----------------------------------------- + +Before any Heat commands can be run, your cloud credentials need to be +sourced:: + + $ source openrc + +You can confirm that Heat is available with this command:: + + $ heat stack-list + +This should return an empty line + +Preparing to create a stack +--------------------------- + +Your cloud will have different flavors and images available for +launching instances, you can discover what is available by running:: + + $ openstack flavor list + $ openstack image list + + +To allow you to SSH into instances launched by Heat, a keypair will be +generated:: + + $ openstack keypair create heat_key > heat_key.priv + $ chmod 600 heat_key.priv + +Launching a stack +----------------- +Now lets launch a stack, using an example template from the heat-templates repository:: + + $ heat stack-create -u http://git.openstack.org/cgit/openstack/heat-templates/plain/hot/F20/WordPress_Native.yaml -P key_name=heat_key -P image_id=my-fedora-image -P instance_type=m1.small teststack + +Which will respond:: + + +--------------------------------------+-----------+--------------------+----------------------+ + | ID | Name | Status | Created | + +--------------------------------------+-----------+--------------------+----------------------+ + | (uuid) | teststack | CREATE_IN_PROGRESS | (timestamp) | + +--------------------------------------+-----------+--------------------+----------------------+ + +List stacks +~~~~~~~~~~~ +List the stacks in your tenant:: + + $ heat stack-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 stack-show 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 output-show``:: + + $ WebsiteURL=$(heat output-show --format raw teststack WebsiteURL) + $ curl $WebsiteURL + +Delete the instance when done +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Note: The list operation will show no running stack.:: + + $ heat stack-delete teststack + $ heat stack-list + +You can explore other heat commands by refering to the +`Heat chapter +`_ +of the `OpenStack Command-Line Interface Reference +`_ then read +the :ref:`template-guide` and start authoring your own templates. diff --git a/doc/source/getting_started/on_devstack.rst b/doc/source/getting_started/on_devstack.rst index 1e37cf3945..b6d36b88be 100644 --- a/doc/source/getting_started/on_devstack.rst +++ b/doc/source/getting_started/on_devstack.rst @@ -74,87 +74,8 @@ Get pretty HTML with traces:: Note that osprofiler should be run with the admin user name & tenant. +Create a stack +-------------- -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 stack-list - -This should return an empty line - -Preparing Nova for running stacks ---------------------------------- - -Enabling Heat in devstack will replace the default Nova flavors with -flavors 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, using an example template from the heat-templates repository:: - - heat stack-create teststack -u - http://git.openstack.org/cgit/openstack/heat-templates/plain/hot/F20/WordPress_Native.yaml -P key_name=heat_key -P image_id=Fedora-x86_64-20-20131211.1-sda - -Which will respond:: - - +--------------------------------------+-----------+--------------------+----------------------+ - | ID | Name | Status | Created | - +--------------------------------------+-----------+--------------------+----------------------+ - | (uuid) | teststack | CREATE_IN_PROGRESS | (timestamp) | - +--------------------------------------+-----------+--------------------+----------------------+ - - -List stacks -~~~~~~~~~~~ -List the stacks in your tenant:: - - heat stack-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 stack-show 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 stack-delete teststack - heat stack-list +Now that you have a working Heat environment you can go to +:ref:`create-a-stack`. diff --git a/doc/source/index.rst b/doc/source/index.rst index 9e0f70b185..569e5a48e3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -43,15 +43,15 @@ Heat's purpose and vision This documentation offers information aimed at end-users, operators and developers of Heat. -Getting Started -=============== +Using Heat +========== .. toctree:: :maxdepth: 1 - getting_started/index - templates/index + getting_started/create_a_stack template_guide/index + templates/index glossary Man Pages @@ -65,13 +65,14 @@ Man Pages Developers Documentation ======================== .. toctree:: - :maxdepth: 1 + :maxdepth: 1 - architecture - pluginguide - schedulerhints - gmr - supportstatus + getting_started/index + architecture + pluginguide + schedulerhints + gmr + supportstatus API Documentation ======================== diff --git a/doc/source/template_guide/index.rst b/doc/source/template_guide/index.rst index 6001ca2c4f..76996f03a7 100644 --- a/doc/source/template_guide/index.rst +++ b/doc/source/template_guide/index.rst @@ -11,6 +11,8 @@ License for the specific language governing permissions and limitations under the License. +.. _template-guide: + Template Guide ============== @@ -31,4 +33,4 @@ Template Guide functions .. existing_templates -.. advanced_topics \ No newline at end of file +.. advanced_topics diff --git a/doc/source/templates/index.rst b/doc/source/templates/index.rst index 9915b33496..b482fd4de4 100644 --- a/doc/source/templates/index.rst +++ b/doc/source/templates/index.rst @@ -13,16 +13,16 @@ This page documents the templates at https://github.com/openstack/heat-templates/ -HOT Templates -============= +Example HOT Templates +===================== .. toctree:: :maxdepth: 1 hot/hello_world -CFN Templates -============= +Example CFN Templates +===================== .. toctree:: :maxdepth: 1