From a2d1b7ee3836798beec8d1368cfd4fdd39b2a590 Mon Sep 17 00:00:00 2001 From: Steve Baker Date: Mon, 5 Oct 2015 12:35:59 +1300 Subject: [PATCH] Aim first doc link list at end users This change renames the first doc link section Getting Started to Using Heat and makes the content relevant to end users of Heat. End users author templates, create stacks, and use the heat CLI. They are not necessarily interested in installing heat from packages or devstack. This change breaks out the basic create-stack content into its own page and links to that from the first Using Heat contents list. The rest of the getting started content is moved to the Developers section for now, pending later changes aimed at developers and operators. Change-Id: I79988e08864c5a87ebc4f8f5a39102d50b26f748 --- doc/source/getting_started/create_a_stack.rst | 107 ++++++++++++++++++ doc/source/getting_started/on_devstack.rst | 87 +------------- doc/source/index.rst | 21 ++-- doc/source/template_guide/index.rst | 4 +- doc/source/templates/index.rst | 8 +- 5 files changed, 129 insertions(+), 98 deletions(-) create mode 100644 doc/source/getting_started/create_a_stack.rst 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