diff --git a/openstack-firstapp/doc/source/section1.rst b/openstack-firstapp/doc/source/section1.rst index 8fc0f6d82..57159531b 100644 --- a/openstack-firstapp/doc/source/section1.rst +++ b/openstack-firstapp/doc/source/section1.rst @@ -2,10 +2,10 @@ Getting started =============== -Who should read this book? +Who should read this guide ~~~~~~~~~~~~~~~~~~~~~~~~~~ -This book is for software developers who want to deploy applications to +This guide is for software developers who want to deploy applications to OpenStack clouds. We assume that you're an experienced programmer who has not created a cloud @@ -14,69 +14,54 @@ application in general or an OpenStack application in particular. 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 IT approach. You will learn how to deploy applications on -OpenStack and some best practices for cloud application development. Overall, -this guide covers: +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`: The most basic cloud application -- creating and - destroying virtual resources +* :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`: Scaling up and down in response to changes in +* :doc:`/section4`: How to scale 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 +* :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 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:`/section8`: Advice for developers who are new to operations +* :doc:`/section9`: How to distribute your application 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: +This tutorial shows two applications. The first application is a simple +fractal generator that uses mathematical equations to generate images. We show +you this application in its entirety so that you can compare it to the second, +more robust, application. -* 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 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 ;). +The second application is an OpenStack application that enables you to: +* Create and destroy compute resources. These resources are virtual + machine instances where the Fractals application runs. +* 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 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 ;) -Choosing your OpenStack SDK -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Choose your OpenStack SDK +~~~~~~~~~~~~~~~~~~~~~~~~~ -Future versions of this guide will cover completing these tasks with -various toolkits, such as the OpenStack SDK, and using various -programming languages, such as Java or Ruby. For now, however, this -initial incarnation of the guide 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 -contact any of the authors or members of the Documentation team to coordinate. - -Although this guide (initially) covers only Libcloud, you actually have several -choices when it comes to building an application for an OpenStack cloud. -These choices include: +This guide focuses on how to use Python with Apache Libcloud. Anyone with a +programming background can easily read the code in this guide. Although this +guide focuses on Libcloud, you can use other languages and toolkits with the +OpenStack cloud: ============= ============= ================================================================= ==================================================== Language Name Description URL @@ -84,7 +69,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 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 +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 node.js pkgcloud A Node.js-based SDK for multiple clouds. https://github.com/pkgcloud/pkgcloud @@ -94,43 +79,55 @@ NET Framework OpenStack SDK A .NET based library that can be used to write C++ a .NET ============= ============= ================================================================= ==================================================== -A list of all available SDKs is available on the -`OpenStack wiki `_. +For a list of available SDKs, see `Software Development Kits `_. +Future versions of this guide will show you how to use the OpenStack SDK and +languages such as Java and Ruby to complete these tasks. If you're a developer +for another toolkit that you would like this guide to include, feel free to +submit code snippets. You can also contact OpenStack Documentation team +members. 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 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. +We assume that you can already access an OpenStack cloud. You must have a +project (also known as a tenant) with a minimum quota of six instances. +Because the Fractals application runs in Ubuntu, Debian, Fedora-based, and +openSUSE-based distributions, you must create instances that use one of these +operating systems. -To interact with the cloud itself, you will also need to have +To interact with the cloud, you must also have .. only:: dotnet `OpenStack SDK for Microsoft .NET 0.9.1 or higher installed `_. - .. warning:: This document has not yet been completed for the .NET SDK. + + .. warning:: + + This document has not yet been completed for the .NET SDK. .. only:: fog - `fog 1.19 or better installed + `fog 1.19 or higher installed `_ and working with ruby gems 1.9. - .. warning:: This document has not yet been completed for the fog SDK. + + .. warning:: + + This document has not yet been completed for the fog SDK. .. only:: jclouds - `jClouds 1.8 or better installed - `_. - .. warning:: This document has not yet been completed for the jclouds SDK. + `jClouds 1.8 or higher installed `_. + + .. warning:: + + This document has not yet been completed for the jclouds SDK. .. only:: libcloud - `libcloud 0.15.1 or better installed + `libcloud 0.15.1 or higher installed `_. .. only:: node @@ -140,41 +137,38 @@ To interact with the cloud itself, you will also need to have .. warning:: - This document has not yet been completed for the pkgcloud - SDK. + 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. .. only:: phpopencloud - `a recent version of php-opencloud installed - `_. + `a recent version of php-opencloud installed `_. + .. warning:: - This document has not yet been completed for the php-opencloud - SDK. + This document has not yet been completed for the php-opencloud SDK. - -You need the following information, which you can -obtain from your cloud provider: +You need the following information that you can obtain from your cloud +provider: * auth URL * 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 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: +You can also download the OpenStack RC file from the OpenStack dashboard. 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 @@ -190,10 +184,9 @@ the actual auth URL will be 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 -SDK". In this initial version, the code snippets assume that you're using -libcloud. +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 +initial version of the guide assume that you're using Libcloud. .. only:: fog @@ -203,7 +196,7 @@ libcloud. .. only:: libcloud - To try it out, add the following code to a Python script (or use an + To try it, add the following code to a Python script (or use an interactive Python shell) by calling :code:`python -i`. .. literalinclude:: ../../samples/libcloud/section1.py @@ -220,35 +213,32 @@ libcloud. password="your_auth_password", ...) -.. note:: We'll use the :code:`conn` object throughout the tutorial, - so ensure you always have one handy. +.. note:: Because the tutorial uses the :code:`conn` object, + make sure that you always have one handy. .. only:: libcloud - .. note:: If you receive the exception + .. note:: If you receive the :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. + credentials with the provider'` exception while trying to run + one of the following API calls, double-check your credentials. - .. note:: If your provider says they do not use regions, try a + .. note:: If your provider does not support regions, try a blank string ('') for the `region_name`. Flavors and images ~~~~~~~~~~~~~~~~~~ -To run your application, you must create a virtual machine, or launch an -instance. This instance behaves like a normal server. +To run your application, you must launch an instance. This instance serves as +a virtual machine. -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). +To launch an instance, you choose a flavor and an image. The flavor represents +the size of the instance, including the number of CPUs and amount of RAM and +disk space. An image is a prepared OS installation from which you clone your +instance. When you boot instances in a public cloud, larger flavors can be +more expensive than smaller ones in terms of resources and monetary cost. -You can easily list the images that are available in your cloud by -running some API calls: +To list the images that are available in your cloud, run some API calls: .. only:: fog @@ -296,22 +286,22 @@ You can also get information about available flavors: Your images and flavors will be different, of course. -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. +Choose an image and flavor for your instance. You need about 1GB RAM, 1 CPU, +and a 1GB disk. This example uses the Ubuntu image with the :code:`m1.small` +flavor, which are safe choices. In subsequent tutorial sections in this guide, +you must change the image and flavor IDs to correspond to the image and flavor +that you choose. -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 `_. +If the image that you want is not available in your cloud, you can usually +upload one depending on your cloud's policy settings. For information about +how to upload images, see +`obtaining images `_. Set the image and size variables to appropriate values for your cloud. We'll -use these in later sections. +use these variables 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: +First, tell the connection to get a specifed image by using the ID of the +image that you picked in the previous section: .. only:: fog @@ -331,7 +321,7 @@ image you have chosen to work with in the previous section: -Next tell the script what flavor you want to use: +Next, tell the script which flavor you want to use: .. only:: fog @@ -339,7 +329,6 @@ Next tell the script what flavor you want to use: :start-after: step-5 :end-before: step-6 - .. only:: libcloud .. literalinclude:: ../../samples/libcloud/section1.py @@ -352,25 +341,25 @@ Next tell the script what flavor you want to use: -Now you're ready to actually launch the instance. +Now, you're ready to launch the instance. -Booting an instance -~~~~~~~~~~~~~~~~~~~ +Launch an instance +~~~~~~~~~~~~~~~~~~ -Now that you have selected an image and flavor, use it to create an instance. +Use your selected image and flavor to create an instance. .. only:: libcloud - .. 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 + .. note:: The following instance creation example assumes that you have a + single-tenant network. If you receive the 'Exception: 400 Bad + Request Multiple possible networks found, use a Network ID to be + more specific' error, you have multiple-tenant networks. You + must add a `networks` parameter to the `create_node` call. See :doc:`/appendix` for details. -Start by creating the instance. +Create the instance. -.. note:: An instance may be called a 'node' or 'server' by your SDK. +.. note:: Your SDK might call an instance a 'node' or 'server'. .. only:: fog @@ -401,7 +390,7 @@ Start by creating the instance. } instance = conn.compute.create_server(**args) -If you then output a list of existing instances... +If you list existing instances: .. only:: fog @@ -415,7 +404,7 @@ If you then output a list of existing instances... :start-after: step-7 :end-before: step-8 -... you should see the new instance appear. +The new instance appears. .. only:: libcloud @@ -431,13 +420,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 must do. +Before you move on, you must do one more thing. -Destroying an instance -~~~~~~~~~~~~~~~~~~~~~~ +Destroy an instance +~~~~~~~~~~~~~~~~~~~ -Cloud resources, including running instances that you no longer use, can cost -money. Removing cloud resources can help you avoid any unexpected costs. +Cloud resources such as running instances that you no longer use can cost +money. Destroy cloud resources to avoid unexpected expenses. .. only:: fog @@ -452,36 +441,34 @@ money. Removing cloud resources can help you avoid any unexpected costs. :end-before: step-9 -If you list the instances again, you'll see that the instance no longer -appears. +If you list the instances again, the instance disappears. -Leave your shell open, as you will use it for another instance -deployment in this section. +Leave your shell open to 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, 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. +Now that you know 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. -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'll want to give it a bit +more information than you supplied to the bare instance that you just created +and destroyed. We'll go into more detail in later sections, but for now, +simply create the following resources so that you can feed them to the +instance: -* 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 - `_ - first. We'll cover this in depth in :doc:`/section2`. +* 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 + `these instructions `_ first. + We'll cover these instructions in depth in :doc:`/section2`. .. only:: fog @@ -500,9 +487,9 @@ them to the instance: -* 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 :doc:`/section2`. +* Network access. By default, OpenStack filters all traffic. You must create + a security group and apply it to your instance. The security group allows HTTP + and SSH access. We'll go into more detail in :doc:`/section2`. .. only:: fog @@ -516,10 +503,10 @@ them to the instance: :start-after: step-10 :end-before: step-11 -* 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 :doc:`/section2`. +* Userdata. During instance creation, you can provide userdata to OpenStack to + configure instances after they boot. The cloud-init service applies the + userdata to an instance. You must pre-install the cloud-init service on your + chosen image. We'll go into more detail in :doc:`/section2`. .. only:: fog @@ -531,13 +518,13 @@ them to the instance: :start-after: step-11 :end-before: step-12 -Now you're ready to boot and configure the new instance. +Now, you can boot and configure the instance. -Booting and configuring an instance ------------------------------------ +Boot and configure an instance +------------------------------ -Use the image, flavor, key pair, and userdata to create a new instance. After -requesting the new instance, wait for it to finish. +Use the image, flavor, key pair, and userdata to create a instance. After you +request the instance, wait for it to build. .. only:: fog @@ -549,24 +536,21 @@ 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 application. +When the instance boots, the `ex_userdata` variable value instructs the +instance to deploy the Fractals application. -Associating a Floating IP for external connectivity ---------------------------------------------------- +Associate a floating IP for external connectivity +------------------------------------------------- -We'll cover networking in greater detail in :doc:`/section7`, 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`. +We'll cover networking in detail in :doc:`/section7`. -If not, then you'll need to create a floating IP and attach it to your -instance. +To see the application running, you must know where to look for it. By +default, your instance has outbound network access. To make your instance +reachable from the Internet, you need an IP address. By default in some cases, +your instance is provisioned with a publicly rout-able IP address. In this +case, you'll see an IP address listed under `public_ips` or `private_ips` when +you list the instances. If not, you must create and attach a floating IP +address to your instance. .. only:: fog @@ -574,9 +558,9 @@ instance. .. 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 - to your instance. + Use :code:`ex_list_floating_ip_pools()` and select the first floating IP + address pool. Allocate this pool to your project and attach it to your + instance. .. literalinclude:: ../../samples/libcloud/section1.py :start-after: step-13 @@ -584,35 +568,34 @@ instance. .. todo:: remove extra blank line after break - You should see the Floating IP output to the command line: + You should see the floating IP output to the command line: :: , driver=> - You can then go ahead and attach it to the instance: + You can then attach it to the instance: .. literalinclude:: ../../samples/libcloud/section1.py :start-after: step-14 :end-before: step-15 -Now go ahead and run the script to start the deployment. +Run the script to start the deployment. -Accessing the application -------------------------- +Access 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 following link 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 +deploys, you can visit the awesome graphic interface at the following link +using your preferred browser. .. only:: libcloud .. literalinclude:: ../../samples/libcloud/section1.py :start-after: step-15 -.. note:: If you are not using floating IPs, substitute another IP address as appropriate +.. note:: If you do not use floating IPs, substitute another IP address as appropriate .. figure:: images/screenshot_webinterface.png :width: 800px @@ -624,29 +607,27 @@ browser. 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 these concepts are not yet completely clear. In +:doc:`/section2`, we explore 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`: Learn how to scale your application +* :doc:`/section4`: Learn how to use Object Storage to make your application durable +* :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 ~~~~~~~~~~~~~~~~~ -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 ;) -Before running this program, confirm that you have set your -authentication information and the flavor and image ID. +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. +Before you run this program, confirm that you have set your authentication +information, the flavor ID, and image ID. .. only:: libcloud