openstack/api-site
Code Issues Proposed changes

Text updates to firstapp tutorial

Browse Source 
-Updated wording for clarity.
-Updated section description links to be consistent
in each section of the tutorial.

Change-Id: I59a0d4cabc653f8c52e15d504059ba7905f7857f
This commit is contained in:
Karen Bradshaw 2015-04-28 12:49:07 -04:00
parent ab21f23fab
commit 86cfe26fcf
4 changed files with 88 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
openstack-firstapp/doc/source/section1.rst
View File

@ -20,26 +20,14 @@ What you will learn
Deploying applications in a cloud environment can be very different from
deploying them in a traditional IT environment. This guide teaches you how to
deploy applications on OpenStack and some best practices for cloud application
development. Overall, this guide describes:
* :doc:`/section1`: How to manage resources to develop a basic cloud application
* :doc:`/section2`: The architecture of a sample cloud-based application
* :doc:`/section3`: The importance of message queues
* :doc:`/section4`: How to scale up and down in response to changes in
application load
* :doc:`/section5`: How to use object or block storage to create persistence
* :doc:`/section6`: How to orchestrate your cloud for better control of the
environment
* :doc:`/section7`: Networking choices and actions to help relieve
potential congestion
* :doc:`/section8`: Advice for developers who are new to operations
* :doc:`/section9`: How to distribute your application across multiple regions or clouds
development.
A general overview
~~~~~~~~~~~~~~~~~~
This tutorial shows two applications. The first application is a simple
fractal generator that uses mathematical equations to generate images. We show
fractal generator that uses mathematical equations to generate beautiful
`fractal images <http://en.wikipedia.org/wiki/Fractal>`_ . We show
you this application in its entirety so that you can compare it to the second,
more robust, application.
@ -50,10 +38,10 @@ The second application is an OpenStack application that enables you to:
* Make cloud-related architecture decisions such as turning
functions into micro-services and modularizing them.
* Scale available resources up and down.
* Use object and block storage for file and database persistence.
* Use Object and Block storage for file and database persistence.
* Use Orchestration services to automatically adjust to the environment.
* Customize networking for better performance and segregation.
* Learn some crazy things that you might not think to do ;)
* Explore and apply advanced OpenStack cloud features.
Choose your OpenStack SDK
~~~~~~~~~~~~~~~~~~~~~~~~~
@ -185,7 +173,7 @@ How you'll interact with OpenStack
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In this tutorial, you interact with your OpenStack cloud through one of the
SDKs listed in "Choosing your OpenStack SDK." The code snippets in this
SDKs listed in "Choose your OpenStack SDK." The code snippets in this
initial version of the guide assume that you're using Libcloud.
.. only:: fog
@ -619,14 +607,16 @@ Don't worry if these concepts are not yet completely clear. In
* :doc:`/section8`: Get advice about operations
* :doc:`/section9`: Learn some crazy things that you might not think to do ;)
Full example code
~~~~~~~~~~~~~~~~~
.. todo:: List the next sections here or simply reference section2.
The following file contains all the code snippets that this tutorial
describes. This comprehensive code sample lets you see and run the code
snippets in context.
Complete code sample
~~~~~~~~~~~~~~~~~~~~
Before you run this program, confirm that you have set your authentication
The following file contains all of the code from this section of the
tutorial. This comprehensive code sample lets you view and run the code
as a single script.
Before you run this script, confirm that you have set your authentication
information, the flavor ID, and image ID.
.. only:: libcloud

59
openstack-firstapp/doc/source/section2.rst
View File

@ -2,14 +2,6 @@
Introduction to the fractals application architecture
=====================================================
This tutorial works with a scalable cloud application that generates
`fractals <http://en.wikipedia.org/wiki/Fractal>`_ - beautiful images made
using only mathematics, like the following image.
.. figure:: images/fractal-example.png
:scale: 50%
:align: left
This section introduces the application architecture and explains how it was
designed to take advantage of cloud features in general and OpenStack in
particular. It also describes some commands in the previous section.
@ -45,8 +37,12 @@ particular. It also describes some commands in the previous section.
Cloud application architecture principles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Cloud applications typically share several design principles. These principles
influenced many Fractals application design decisions.
Cloud applications typically share several design principles.
These principles influenced the design of the Fractals application.
.. todo:: Do you want to state the core design priniciples or assume
the reader can follow below.
Modularity and micro-services
-----------------------------
@ -142,7 +138,7 @@ logical application functions, we can change this easily.
.. graphviz:: images/architecture.dot
Message queues are used to facilitate communication between the
Fractal application services. The Fractal application uses a so-called `work queue
Fractal application services. The Fractal application uses a `work queue
<https://www.rabbitmq.com/tutorials/tutorial-two-python.html>`_ (or
task queue) to distribute tasks to the worker services.
@ -152,8 +148,8 @@ multiple clerks. The message queue in our application provides a feed
of work requests that can be taken one-at-a-time by worker services,
whether there is a single worker service or hundreds of them.
This is a `useful pattern <https://msdn.microsoft.com/en-us/library/dn568101.aspx>`_ for many
cloud applications that have long lists of requests coming in and a
This is a `useful pattern <https://msdn.microsoft.com/en-us/library/dn568101.aspx>`_
for many cloud applications that have long lists of requests coming in and a
pool of resources from which to service them. This also means that a
worker may crash and the tasks will be processed by other workers.
@ -554,7 +550,7 @@ with :code:`faafo get --help`, :code:`faafo list --help`, and
.. note:: The application stores the generated fractal images directly
in the database used by the API service instance. Storing
image files in database is not good practice. We're doing it
image files in a database is not good practice. We're doing it
here as an example only as an easy way to allow multiple
instances to have access to the data. For best practice, we
recommend storing objects in Object Storage, which is
@ -564,37 +560,36 @@ Next steps
~~~~~~~~~~
You should now have a basic understanding of the architecture of
cloud-based applications. In addition, you now have had practice
cloud-based applications. In addition, you have had practice
starting new instances, automatically configuring them at boot, and
even modularizing an application so that you may use multiple
instances to run it. These are the basic steps for requesting and
using compute resources in order to run your application on an
OpenStack cloud.
From here, you should go to :doc:`/section3` to learn how to scale the
application further. Alternately, you may jump to any of these
From here, you should go to :doc:`/section3` to learn how to scale your
application further. Alternatively, you may jump to any of these
sections:
* :doc:`/section4`: to learn how to make your application more durable
using Object Storage
* :doc:`/section5`: to migrate the database to block storage, or use
the database-as-as-service component
* :doc:`/section6`: to automatically orchestrate the application
* :doc:`/section7`: to learn about more complex networking
* :doc:`/section8`: for advice for developers new to operations
* :doc:`/section4`: Learn how to use Object Storage to make your application more durable
* :doc:`/section5`: Migrate the database to block storage, or use
the database-as-a-service component
* :doc:`/section6`: Automatically orchestrate the application
* :doc:`/section7`: Learn about more complex networking
* :doc:`/section8`: Get advice about operations
* :doc:`/section9`: Learn some crazy things that you might not think to do ;)
Full example code
~~~~~~~~~~~~~~~~~
Complete code sample
~~~~~~~~~~~~~~~~~~~~
Here's every code snippet into a single file, in case you want to run
it all in one, or you are so experienced you don't need instruction ;)
If you are going to use this, don't forget to set your authentication
information and the flavor and image ID.
The following file contains all of the code from this section of the tutorial.
This comprehensive code sample lets you view and run the code as a single script.
Before you run this script, confirm that you have set your authentication
information, the flavor ID, and image ID.
.. only:: libcloud
.. literalinclude:: ../../samples/libcloud/section2.py
:language: python

85
openstack-firstapp/doc/source/section3.rst
View File

@ -11,8 +11,8 @@ Scaling out
One of the most-often cited reasons for designing applications using
cloud patterns is the ability to **scale out**. That is: to add
additional resources as required. This is in contrast to the previous
mentality of increasing capacity by scaling the size of existing
resources up. In order for scale out to be feasible, you'll need to
strategy of increasing capacity by scaling up the size of existing
resources. In order for scale out to be feasible, you'll need to
do two things:
* Architect your application to make use of additional resources.
@ -60,14 +60,15 @@ will be clear that we need more resources.
Generate load
~~~~~~~~~~~~~
You can test for yourself what happens when the Fractals app is under
loaded by:
You can test for yourself what happens when the Fractals application is under
load by:
* maxing out the CPU of the existing worker instances (loading the worker)
* generating a lot of API requests (load up the API)
Generate a lot of worker load
-----------------------------
Create a greater number of tasks
--------------------------------
Use SSH to login to the controller instance, :code:`app-controller`,
using the previous added SSH keypair.
@ -80,7 +81,7 @@ using the previous added SSH keypair.
controller instance and USERNAME to the appropriate
username.
Call the Fractal app's command line interface (:code:`faafo`) to
Call the Fractal application's command line interface (:code:`faafo`) to
request the generation of 5 large fractals.
::
@ -99,8 +100,9 @@ of more than 1 means we are at capacity.
.. note:: Replace :code:`IP_WORKER` with the IP address of the worker
instance and USERNAME to the appropriate username.
Generate a lot of API load
--------------------------
Create a greater number of API service requests
-----------------------------------------------
API load is a slightly different problem to the previous one regarding
capacity to work. We can simulate many requests to the API as follows:
@ -116,7 +118,7 @@ using the previous added SSH keypair.
controller instance and USERNAME to the appropriate
username.
Call the Fractal app's command line interface (:code:`faafo`) in a for
Call the Fractal application's command line interface (:code:`faafo`) in a for
loop to send many requests to the API. The following command will
request a random set of fractals, 500 times:
@ -150,9 +152,8 @@ Remove the old app
------------------
Go ahead and delete the existing instances and security groups you
created in previous sections. Remember; when components in the cloud
aren't doing what you want them to do, just remove them and re-create
something new.
created in previous sections. Remember, when instances in the cloud
are no longer working, remove them and re-create something new.
.. only:: libcloud
@ -177,8 +178,8 @@ required security groups.
A Floating IP helper function
-----------------------------
Define a short function to locate unused or allocate a new floating
IP. This saves a few lines of boring code and prevents you from
Define a short function to locate unused IPs or allocate a new floating
IP. This saves a few lines of code and prevents you from
reaching your Floating IP quota too quickly.
.. only:: libcloud
@ -190,10 +191,11 @@ reaching your Floating IP quota too quickly.
Splitting off the database and message queue
--------------------------------------------
Prior to scaling out our application services like the API service or
the workers we have to add a central database and messaging instance,
called :code:`app-services`, that will be used to track the state of
the fractals and to coordinate the communication between the services.
Prior to scaling out our application services, like the API service or
the workers, we have to add a central database and messaging instance,
called :code:`app-services`. The database and messaging queue will be used
to track the state of the fractals and to coordinate the communication
between the services.
.. only:: libcloud
@ -235,7 +237,6 @@ explain in :doc:`/section7`.
load simulation.
Scaling the workers
-------------------
@ -277,7 +278,7 @@ You will see that the Fractals app has a few new features.
.. note:: Replace :code:`IP_API_1` with the IP address of the first
API instance and USERNAME to the appropriate username.
Use the Fractal app's command line interface to generate fractals
Use the Fractal application's command line interface to generate fractals
:code:`faafo create`. Watch the progress of fractal generation with
the :code:`faafo list`. Use :code:`faafo UUID` to examine some of the
fractals. The generated_by field will show which worker created the
@ -339,7 +340,7 @@ redundant web services. If one dies, the others can be used.
corresponding Floating IPs. Replace FRACTAL_UUID the UUID
of an existing fractal.
Go ahead and test the fault tolerance. Start killing workers and API
Go ahead and test the fault tolerance. Start destroying workers and API
instances. As long as you have one of each, your application should
be fine. There is one weak point though. The database contains the
fractals and fractal metadata. If you lose that instance, the
@ -364,36 +365,38 @@ and autoscaling capabilities to do steps like this automatically.
Next steps
~~~~~~~~~~
You should now be fairly confident about starting new instance, and
about segregating services of an application between them.
You should be fairly confident now about starting new instances, and
distributing services from an application amongst the instances.
As mentioned in :doc:`/section2` the generated fractals images will be
As mentioned in :doc:`/section2` the generated fractal images will be
saved on the local filesystem of the API service instances. Because we
now have multiple API instances up and running the generated fractal
images will be spreaded accross multiple API services, stored on local
instance filesystems. This ends in a lot of :code:`IOError: [Errno 2]
No such file or directory` exceptions when trying to download a
now have multiple API instances up and running, the fractal
images will be spread across multiple API services. This results in a number of
:code:`IOError: [Errno 2] No such file or directory` exceptions when trying to download a
fractal image from an API service instance not holding the fractal
image on its local filesystem.
From here, you should go to :doc:`/section4` to learn how to use
Object Storage to solve this problem in a elegant way. Alternately,
Object Storage to solve this problem in a elegant way. Alternatively,
you may jump to any of these sections:
* :doc:`/section5`: to migrate the database to block storage, or use
the database-as-as-service component
* :doc:`/section6`: to automatically orchestrate the application
* :doc:`/section7`: to learn about more complex networking
* :doc:`/section8`: for advice for developers new to operations
* :doc:`/section5`: Migrate the database to block storage, or use
the database-as-a-service component
* :doc:`/section6`: Automatically orchestrate your application
* :doc:`/section7`: Learn about complex networking
* :doc:`/section8`: Get advice about operations
* :doc:`/section9`: Learn some crazy things that you might not think to do ;)
Full example code
~~~~~~~~~~~~~~~~~
Complete code sample
~~~~~~~~~~~~~~~~~~~~
Here's every code snippet into a single file, in case you want to run
it all in one, or you are so experienced you don't need instruction ;)
If you are going to use this, don't forget to set your authentication
information and the flavor and image ID.
The following file contains all of the code from this
section of the tutorial. This comprehensive code sample lets you view
and run the code as a single script.
Before you run this script, confirm that you have set your authentication
information, the flavor ID, and image ID.
.. only:: libcloud

6
openstack-firstapp/doc/source/section6.rst
View File

@ -1,6 +1,6 @@
==========================
Section Six: Orchestration
==========================
=============
Orchestration
=============
.. todo:: Needs to be restructured so that the fractals app is used as the example for the explanatory material.