diff --git a/openstack-firstapp/doc/source/section1.rst b/openstack-firstapp/doc/source/section1.rst index 6ad1a7640..ff7c24db7 100644 --- a/openstack-firstapp/doc/source/section1.rst +++ b/openstack-firstapp/doc/source/section1.rst @@ -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 `_. - .. warning:: This document has not yet been completed for the .NET SDK + `OpenStack SDK for Microsoft .NET 0.9.1 or better installed + `_. + .. warning:: This document has not yet been completed for the .NET SDK. .. only:: fog - `fog 1.19 or better installed `_ 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 + `_ + 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 `_. - .. warning:: This document has not yet been completed for the jclouds SDK + `jClouds 1.8 or better 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 better installed + `_. .. only:: node - `a recent version of pkgcloud installed `_. - .. warning:: This document has not yet been completed for the pkgcloud SDK + `a recent version of pkgcloud installed + `_. + + .. 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 `_. - .. warning:: This document has not yet been completed for the php-opencloud SDK + `a recent version of php-opencloud installed + `_. + .. 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: -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 `_. +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 `_. -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 `_ 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: -* 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 -