openstack/api-site
Code Issues Proposed changes

Merge "FirstApp: Edits section1"

Browse Source
This commit is contained in:
Jenkins 2015-04-24 04:01:10 +00:00 committed by Gerrit Code Review
commit 2e13e11d6f
1 changed files with 214 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,66 +1,74 @@
============================
Section One: Getting Started
============================
===============
Getting started
===============
Who should read this book
-------------------------
Who should read this book?
~~~~~~~~~~~~~~~~~~~~~~~~~~
This book has been written for software developers who wish to deploy
applications to OpenStack clouds.
This book is for software developers who want to deploy applications to
OpenStack clouds.
We've assumed that you're an experienced programmer, but that you haven't
necessarily created an application for cloud in general, or for OpenStack in
particular.
We assume that you're an experienced programmer who has not created a cloud
application in general or an OpenStack application in particular.
If you're already familiar with OpenStack, you'll save time learning about the
general concepts, and you'll still find value in learning how to work
programmatically with it's components.
If you're familiar with OpenStack, this section teaches you how to program
with its components.
What you will learn
-------------------
What you will learn?
~~~~~~~~~~~~~~~~~~~~
Deploying applications in a cloud environment can be very different from the
traditional siloed approachyou see in traditional IT, so in addition to learning
to deploy applications on OpenStack, you will also learn some best practices for
cloud application development. Overall, this guide covers the following:
traditional IT approach. You will learn how to deploy applications on
OpenStack and some best practices for cloud application development. Overall,
this guide covers:
* :doc:`/section1` - The most basic cloud application -- creating and destroying virtual resources
* :doc:`/section2` - The architecture of a sample cloud-based application
* :doc:`/section3` - The importance of message queues
* :doc:`/section4` - Scaling up and down in response to changes in application load
* :doc:`/section5` - Using object or block storage to create persistance
* :doc:`/section6` - Orchestrating 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 may not have been exposed to operations tasks before
* :doc:`/section9` - Taking your application to the next level by spreading it across multiple regions or clouds
* :doc:`/section1`: The most basic cloud application -- creating and
destroying virtual resources
* :doc:`/section2`: The architecture of a sample cloud-based application
* :doc:`/section3`: The importance of message queues
* :doc:`/section4`: Scaling up and down in response to changes in
application load
* :doc:`/section5`: Using object or block storage to create persistence
* :doc:`/section6`: Orchestrating 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 may not have been
exposed to operations tasks before
* :doc:`/section9`: Taking your application to the next level by
spreading it across multiple regions or clouds
A general overview
------------------
~~~~~~~~~~~~~~~~~~
This tutorial actually involves two applications; the first, a fractal
generator, simply uses mathematical equations to generate images. We'll provide
that application to you in its entirety, because really, it's just an excuse;
the real application we will be showing you is the code that enables you to make
use of OpenStack to run it. That application includes:
generator, simply uses mathematical equations to generate
images. We'll provide that application to you in its entirety, because
really, it's just an excuse; the real application we will be showing
you is the code that enables you to make use of OpenStack to run
it. That application includes:
* Creating and destroying compute resources. (Those are the virtual machine instances on which the Fractals app runs.)
* Cloud-related architecture decisions, such as breaking individual functions out into microservices and modularizing them.
* Creating and destroying compute resources. (Those are the virtual
machine instances on which the Fractals application runs.)
* Cloud-related architecture decisions, such as breaking individual
functions out into micro-services and modularizing them.
* Scaling up and down to customize the amount of available resources.
* Object and block storage for persistance of files and databases.
* Object and block storage for file and database persistence.
* Orchestration services to automatically adjust to the environment.
* Networking customization for better performance and segregation.
* A few other crazy things we think ordinary folks won't want to do ;).
Choosing your OpenStack SDK
---------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Future versions of this book will cover completing these tasks with various
toolkits, such as the OpenStack SDK, and using various languages, such as Java
or Ruby. For now, however, this initial incarnation focuses on using Python with
Apache Libcloud. That said, if you're not a master Python programmer,
don't despair; the code is fairly straightforward, and should be readable to
anyone with a programming background.
Future versions of this book will cover completing these tasks with
various toolkits, such as the OpenStack SDK, and using various
languages, such as Java or Ruby. For now, however, this initial
incarnation focuses on using Python with Apache Libcloud. That said,
if you're not a master Python programmer, don't despair; the code is
fairly straightforward, and should be readable to anyone with a
programming background.
If you're a developer for an alternate toolkit and would like to see this book
support it, great! Please feel free to submit alternate code snippets, or to
@ -75,7 +83,7 @@ Language Name Description
============= ============= ================================================================= ====================================================
Python Libcloud A Python-based library managed by the Apache Foundation.
This library enables you to work with multiple types of clouds. https://libcloud.apache.org
Python OpenStack SDK A python-based libary specifically developed for OpenStack. https://github.com/stackforge/python-openstacksdk
Python OpenStack SDK A python-based library specifically developed for OpenStack. https://github.com/stackforge/python-openstacksdk
Java jClouds A Java-based library. Like libcloud, it's also managed by the https://jclouds.apache.org
Apache Foundation and works with multiple types of clouds.
Ruby fog A Ruby-based SDK for multiple clouds. http://www.fogproject.org
@ -93,64 +101,80 @@ A list of all available SDKs is available on the
What you need
-------------
We assume you already have access to an OpenStack cloud.
You should have a project (tenant) with a quota of at least
6 instances. The Fractals application itself runs in Ubuntu, Debian, and Fedora-based and
openSUSE-based distributions, so you'll need to be creating instances using one
of these operating systems.
We assume you already have access to an OpenStack cloud. You should
have a project (tenant) with a quota of at least six instances. The
Fractals application itself runs in Ubuntu, Debian, and Fedora-based
and openSUSE-based distributions, so you'll need to be creating
instances using one of these operating systems.
Interact with the cloud itself, you will also need to have
.. only:: dotnet
`OpenStack SDK for Microsoft .NET 0.9.1 or better installed <https://www.nuget.org/packages/OpenStack-SDK-DotNet>`_.
.. warning:: This document has not yet been completed for the .NET SDK
`OpenStack SDK for Microsoft .NET 0.9.1 or better installed
<https://www.nuget.org/packages/OpenStack-SDK-DotNet>`_.
.. warning:: This document has not yet been completed for the .NET SDK.
.. only:: fog
`fog 1.19 or better installed <http://www.fogproject.org/wiki/index.php?title=FOGUserGuide#Installing_FOG>`_ and working
with ruby gems 1.9
.. warning:: This document has not yet been completed for the fog SDK
`fog 1.19 or better installed
<http://www.fogproject.org/wiki/index.php?title=FOGUserGuide#Installing_FOG>`_
and working with ruby gems 1.9.
.. warning:: This document has not yet been completed for the fog SDK.
.. only:: jclouds
`jClouds 1.8 or better installed <https://jclouds.apache.org/start/install>`_.
.. warning:: This document has not yet been completed for the jclouds SDK
`jClouds 1.8 or better installed
<https://jclouds.apache.org/start/install>`_.
.. warning:: This document has not yet been completed for the jclouds SDK.
.. only:: libcloud
`libcloud 0.15.1 or better installed <https://libcloud.apache.org/getting-started.html>`_.
`libcloud 0.15.1 or better installed
<https://libcloud.apache.org/getting-started.html>`_.
.. only:: node
`a recent version of pkgcloud installed <https://github.com/pkgcloud/pkgcloud#getting-started>`_.
.. warning:: This document has not yet been completed for the pkgcloud SDK
`a recent version of pkgcloud installed
<https://github.com/pkgcloud/pkgcloud#getting-started>`_.
.. warning::
This document has not yet been completed for the pkgcloud
SDK.
.. only:: openstacksdk
the OpenStack SDK installed.
.. warning:: This document has not yet been completed for the OpenStack SDK
.. warning::
This document has not yet been completed for the OpenStack SDK.
.. only:: phpopencloud
`a recent version of php-opencloud installed <http://docs.php-opencloud.com/en/latest/>`_.
.. warning:: This document has not yet been completed for the php-opencloud SDK
`a recent version of php-opencloud installed
<http://docs.php-opencloud.com/en/latest/>`_.
.. warning::
This document has not yet been completed for the php-opencloud
SDK.
You will need the following 5 pieces of information, which you can obtain from
your cloud provider:
You need the following information, which you can
obtain from your cloud provider:
* auth URL
* username
* user name
* password
* project id or name (Projects are also known as tenants.)
* project ID or name (projects are also known as tenants.)
* cloud region
You can also get this information by downloading the OpenStack RC file from the
OpenStack Dashboard. To download this file, log into the Horizon dashboard and
click Project->Access & Security->API Access->Download OpenStack RC file.
If you choose this route, be aware that the "auth URL" doesn't include the path.
In other words, if your openrc.sh file shows:
You can also get this information by downloading the OpenStack RC file
from the OpenStack dashboard. To download this file, log in to the
Horizon dashboard and click :guilabel:`Project->Access & Security->API
Access->Download OpenStack RC file`. If you choose this route, be
aware that the "auth URL" doesn't include the path. For example,
if your :file:`openrc.sh` file shows:
.. code-block:: bash
@ -163,9 +187,8 @@ the actual auth URL will be
http://controller:5000
How you'll interact with OpenStack
----------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Throughout this tutorial, you'll be interacting with your OpenStack cloud
through code, using one of the SDKs listed in section "Choosing your OpenStack
@ -193,33 +216,38 @@ libcloud.
from openstack import connection
conn = connection.Connection(auth_url="http://controller:5000/v3",
user_name="your_auth_username", password="your_auth_password", ...)
user_name="your_auth_username",
password="your_auth_password", ...)
.. Note:: We'll use the :code:`conn` object throughout the tutorial, so ensure you always have one handy.
.. note:: We'll use the :code:`conn` object throughout the tutorial,
so ensure you always have one handy.
.. only:: libcloud
.. Note:: If you receive the exception :code:`libcloud.common.types.InvalidCredsError: 'Invalid credentials with the provider'` while
trying to run one of the following API calls please double-check your credentials.
.. note:: If you receive the exception
:code:`libcloud.common.types.InvalidCredsError: 'Invalid
credentials with the provider'` while trying to run one
of the following API calls please double-check your
credentials.
.. Note:: If your provider says they do not use regions, try a blank string ('') for the region_name.
.. note:: If your provider says they do not use regions, try a
blank string ('') for the `region_name`.
Flavors and Images
------------------
Flavors and images
~~~~~~~~~~~~~~~~~~
In order to run your application, the first thing you'll need to do is create a
virtual machine, or launch an instance. This instance behaves (for all intents
and purposes) as a normal server.
To run your application, you must create a virtual machine, or launch an
instance. This instance behaves like a normal server.
In order to launch an instance, you will need to choose a flavor and an image.
The flavor is essentially the size of the instance, such as its number of CPUs,
amount of RAM and disk. An image is a prepared OS instalation from which your
instance is cloned. Keep in mind when booting instances that larger flavors can
be more expensive (in terms of resources, and therefore monetary cost, if you're
working in a public cloud) than smaller ones.
To launch an instance, you must choose a flavor and an image. The flavor is
essentially the size of the instance, such as its number of CPUs, and the
amount of RAM and disk. An image is a prepared OS installation from which your
instance is cloned. When you boot instances, larger flavors can be more
expensive than smaller ones (in terms of resources and therefore monetary
cost if you're working in a public cloud).
You can easily find out the images available in your cloud by
You can easily list the images that are available in your cloud by
running some API calls:
.. only:: fog
@ -241,7 +269,7 @@ running some API calls:
<NodeImage: id=2cccbea0-cea9-4f86-a3ed-065c652adda5, name=ubuntu-14.04, driver=OpenStack ...>
<NodeImage: id=f2a8dadc-7c7b-498f-996a-b5272c715e55, name=cirros-0.3.3-x86_64, driver=OpenStack ...>
You can also get information on the various flavors:
You can also get information about available flavors:
.. only:: fog
@ -255,7 +283,7 @@ You can also get information on the various flavors:
:start-after: step-3
:end-before: step-4
This code should produce output something like:
This code produces output like:
.. code-block:: python
@ -268,26 +296,23 @@ You can also get information on the various flavors:
Your images and flavors will be different, of course.
Choose an image and flavor to use for your first instance. To start with, we
only need about 1GB of RAM, 1 CPU and a GB of disk, so in this example, the
:code:`m1.small` flavor, which exceeds these requirements, in conjuction with
the Ubuntu image, is a safe choice.
The flavor and image you choose here will be used throughout this guide, so you
will need to change the IDs in the following tutorial sections to correspond to
Choose an image and flavor for your first instance. You need about 1GB of RAM,
1 CPU, and 1 GB of disk. In this example, the :code:`m1.small` flavor, which
exceeds these requirements, in conjunction with the Ubuntu image, is a safe
choice. The flavor and image you choose here is used throughout this guide, so
you must change the IDs in the following tutorial sections to correspond to
your desired flavor and image.
If you don't see the image you want available in your cloud, you can usually
upload a new one - depending on your cloud's policy settings. There is a guide
on how to aquire images
`available here <http://docs.openstack.org/image-guide/content/ch_obtaining_images.html>`_.
If the image you want is not available in your cloud, you can usually upload a
new one, depending on your cloud's policy settings. For information about how
to upload images, see `obtaining images <http://docs.openstack.org/image-guide/content/ch_obtaining_images.html>`_.
Set the image and size variables to appropriate values for your cloud. We'll use
these in later sections.
Set the image and size variables to appropriate values for your cloud. We'll
use these in later sections.
First tell the connection to retrieve a specific image, using the ID of the
image you have chosen to work with in the previous section:
.. only:: fog
.. literalinclude:: ../../samples/fog/section1.rb
@ -330,18 +355,18 @@ Next tell the script what flavor you want to use:
Now you're ready to actually launch the instance.
Booting an instance
-------------------
~~~~~~~~~~~~~~~~~~~
Now that you have selected an image and flavor, use it to create an instance.
.. only:: libcloud
.. note:: The following instance creation assumes that you only have one
tenant network. If you have multiple tenant networks defined, you will
need to add a networks parameter to the create_node call. You'll know
this is the case if you see an error stating 'Exception: 400 Bad Request
Multiple possible networks found, use a Network ID to be more specific.'
See :doc:`/appendix` for details.
.. note:: The following instance creation assumes that you have only one
tenant network. If you have multiple tenant networks, you must add a
networks parameter to the create_node call. You'll know this is the
case if you see an error stating 'Exception: 400 Bad Request Multiple
possible networks found, use a Network ID to be more specific.' See
:doc:`/appendix` for details.
Start by creating the instance.
@ -406,15 +431,13 @@ If you then output a list of existing instances...
for instance in instances:
print(instance)
Before we move on, there's one more thing you need to do.
Before we move on, there's one more thing you must do.
Destroying an instance
----------------------
~~~~~~~~~~~~~~~~~~~~~~
It is important to keep in mind that cloud resources (including running
instances you are no longer using) can cost money. Learning to remove cloud
resources will help you avoid any unexpected costs incurred by unnecessary
cloud resources.
Cloud resources, including running instances that you no longer use, can cost
money. Removing cloud resources can help you avoid any unexpected costs.
.. only:: fog
@ -429,40 +452,44 @@ cloud resources.
:end-before: step-9
If you then list the instances again, you'll see that the instance no longer appears.
If you list the instances again, you'll see that the instance no longer
appears.
Leave your shell open, as you will use it for another instance deployment in this section.
Leave your shell open, as you will use it for another instance
deployment in this section.
Deploy the application to a new instance
----------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now that you are familiar with how to create and destroy instances, it is time
to deploy the sample application. The instance you create for the app will be
similar to the first instance you created, but this time, we'll briefly
introduce a few extra concepts.
Now that you are familiar with how to create and destroy instances, you can
deploy the sample application. The instance that you create for the
application is similar to the first instance that you created, but this time,
we'll briefly introduce a few extra concepts.
.. note:: Internet connectivity from your cloud instance is required to download the application.
.. note:: Internet connectivity from your cloud instance is required
to download the application.
When you create an instance for the application, you're going to want to give it
a bit more information than the bare instance we created and destroyed a little
while ago. We'll go into more detail in later sections, but for now, simply create
these resources so you can feed them to the instance:
When you create an instance for the application, you're going to want
to give it a bit more information than the bare instance we created
and destroyed a little while ago. We'll go into more detail in later
sections, but for now, simply create these resources so you can feed
them to the instance:
* A key pair. In order to access your instance, you will need to import an SSH
public key into OpenStack to create a key pair. This key pair will be installed
on the new instance by OpenStack. Typically, your public key is written to
* A key pair. To access your instance, you must import an SSH public key
into OpenStack to create a key pair. OpenStack installs this key pair on the
new instance. Typically, your public key is written to
:code:`.ssh/id_rsa.pub`. If you do not have an SSH public key file, follow
the instructions `here <https://help.github.com/articles/generating-ssh-keys/>`_
first. We'll cover this in depth in section 2.
.. only:: fog
.. warning:: This section has not been completed
.. warning:: This section has not been completed.
.. only:: libcloud
In the following example, :code:`pub_key_file` should be set to the location
of your public SSH key file.
In the following example, :code:`pub_key_file` should be set to
the location of your public SSH key file.
.. literalinclude:: ../../samples/libcloud/section1.py
:start-after: step-9
@ -472,8 +499,8 @@ these resources so you can feed them to the instance:
<KeyPair name=demokey fingerprint=aa:bb:cc... driver=OpenStack>
* Network access. By default, OpenStack will filter all traffic. You'll need to
create a security group that will allow HTTP and SSH access and apply it to
* Network access. By default, OpenStack filters all traffic. You must
create a security group that allows HTTP and SSH access and apply it to
your instance. We'll go into more detail in section 2.
.. only:: fog
@ -488,14 +515,14 @@ these resources so you can feed them to the instance:
:start-after: step-10
:end-before: step-11
* Userdata. During instance creation, userdata may be provided to OpenStack in
order to configure instances after they boot. The userdata is applied to an
instance by the cloud-init service. This service should be pre-installed on
the image you have chosen. We'll go into more detail in section 2.
* Userdata. During instance creation, userdata may be provided to OpenStack to
configure instances after they boot. The userdata is applied to an instance
by the cloud-init service. This service should be pre-installed on the image
you have chosen. We'll go into more detail in section 2.
.. only:: fog
.. warning:: This section has not been completed
.. warning:: This section has not been completed.
.. only:: libcloud
@ -506,14 +533,14 @@ these resources so you can feed them to the instance:
Now you're ready to boot and configure the new instance.
Booting and configuring an instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------
Use the image, flavor, key pair, and userdata to create a new instance. After
Use the image, flavor, key pair, and userdata to create a new instance. After
requesting the new instance, wait for it to finish.
.. only:: fog
.. warning:: This section has not been completed
.. warning:: This section has not been completed.
.. only:: libcloud
@ -521,31 +548,33 @@ requesting the new instance, wait for it to finish.
:start-after: step-12
:end-before: step-13
When the instance boots up, the information in the ex_userdata variable tells it
to go ahead and deploy the Fractals app.
When the instance boots up, the information in the ex_userdata
variable tells it to go ahead and deploy the Fractals application.
Associating a Floating IP for external connectivity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------------------------
We'll cover networking in greater detail in section 7, but in order to actually
see the application running, you'll need to know where to look for it. Your
instance will have outbound network access by default, but in order to provision
inbound network access (in other words, to make it reachable from the Internet)
you will need an IP address. In some cases, your instance may be provisioned
with a publicly routable IP by default. You'll be able to tell in this case
because when you list the instances you'll see an IP address listed under
public_ips or private_ips.
We'll cover networking in greater detail in section 7, but in order to
actually see the application running, you'll need to know where to
look for it. Your instance will have outbound network access by
default, but in order to provision inbound network access (in other
words, to make it reachable from the Internet) you will need an IP
address. In some cases, your instance may be provisioned with a
publicly rout-able IP by default. You'll be able to tell in this case
because when you list the instances you'll see an IP address listed
under `public_ips` or `private_ips`.
If not, then you'll need to create a floating IP and attach it to your instance.
If not, then you'll need to create a floating IP and attach it to your
instance.
.. only:: fog
.. warning:: This section has not been completed
.. warning:: This section has not been completed.
.. only:: libcloud
Use :code:`ex_list_floating_ip_pools()` and select the first pool of
Floating IP addresses. Allocate this to your project and attach it
Floating IP addresses. Allocate this to your project and attach it
to your instance.
.. literalinclude:: ../../samples/libcloud/section1.py
@ -569,12 +598,13 @@ If not, then you'll need to create a floating IP and attach it to your instance.
Now go ahead and run the script to start the deployment.
Accessing the application
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
Deploying application data and configuration to the instance can take some time. Consider
enjoying a cup of coffee while you wait. After the application has been deployed, you will be able to
visit the awesome graphic interface at the link provided below using your
preferred browser.
Deploying application data and configuration to the instance can take
some time. Consider enjoying a cup of coffee while you wait. After the
application has been deployed, you will be able to visit the awesome
graphic interface at the following link using your preferred
browser.
.. only:: libcloud
@ -590,29 +620,33 @@ preferred browser.
:alt: screenshot of the webinterface
:figclass: align-center
Next Steps
----------
Next steps
~~~~~~~~~~
Don't worry if you don't understand every part of what just happened. As we move
on to :doc:`/section2`, we'll go into these concepts in more detail.
Don't worry if you don't understand every part of what just
happened. As we move on to :doc:`/section2`, we'll go into these
concepts in more detail.
* :doc:`/section3` - to learn how to scale the application further
* :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:`/section9` - to see all the crazy things we think ordinary folks won't want to do ;)
* :doc:`/section3`: to learn how to scale the application further
* :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:`/section9`: to see all the crazy things we think ordinary
folks won't want to do ;)
Full example code
-----------------
~~~~~~~~~~~~~~~~~
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.
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.
.. only:: libcloud
.. literalinclude:: ../../samples/libcloud/section1.py
:language: python