Adding tutorial for OpenStack Shade library

Fixed also a bunch of English-language to the getting started text

co-authored-by: Diane Fleming

Change-Id: I9318cdefb628a7441a984f7c8f200202b41430dd

firstapp/README.rst

@@ -1,52 +1,46 @@
 ========================================
-Writing your first OpenStack application
+Writing Your First OpenStack Application
 ========================================
 
-This tutorial works with the `First App Application for OpenStack <https://github.com/stackforge/faafo/>`_.
+This directory contains the "Writing Your First OpenStack Application"
+tutorial.
+
+The tutorials work with an application that can be found at
+`https://github.com/stackforge/faafo <https://github.com/stackforge/faafo/>`_.
 
 Prerequisites
-=============
+-------------
 
-To build the documentation, install `Python Tox <https://tox.readthedocs.org/>`_.
+To build the documentation, you must install the Graphviz package.
-
-To install Tox for Ubuntu 14.04 and later::
-
-    apt-get install python-tox python-dev libxml2-dev libxslt1-dev
-
-Structure
-=========
 
 /source
 ~~~~~~~
 
 The :code:`/source` directory contains the tutorial documentation as
-`reStructuredText <http://docutils.sourceforge.net/rst.html>`_ (RST). The
+`reStructuredText <http://docutils.sourceforge.net/rst.html>`_ (RST).
-documentation is built with `Sphinx <http://sphinx-doc.org/>`_.
 
-The RST source includes conditional output logic. To invoke
+To build the documentation, you must install `Sphinx <http://sphinx-doc.org/>`_ and the
-:code:`sphinx-build` with :code:`-t libcloud`::
+`OpenStack docs.openstack.org Sphinx theme (openstackdocstheme) <https://pypi.python.org/pypi/openstackdocstheme/>`_. When
+you invoke tox, these dependencies are automatically pulled in from the
+top-level :code:`test-requirements.txt`.
+
+You must also install `Graphviz <http://www.graphviz.org/>`_ on your build system.
+
+The RST source includes conditional output logic. The following command
+invokes :code:`sphinx-build` with :code:`-t libcloud`::
 
   tox -e firstapp-libcloud
 
 Only the sections marked :code:`.. only:: libcloud` in the RST are built.
 
-To build the documentation, you must install `Sphinx <http://sphinx-doc.org/>`_
-and the
-`OpenStack docs.openstack.org Sphinx theme (openstackdocstheme) <https://pypi.python.org/pypi/openstackdocstheme>`_.
-
-When you invoke tox, these dependencies are automatically pulled in from the
-top-level :code:`test-requirements.txt`.
-
-You must also install `Graphviz <http://www.graphviz.org/>`_ on your build system.
-
 /samples
 ~~~~~~~~
 
-The code samples in the guide are located in this directory. The code samples
+The code samples in this guide are located in this directory. The code samples
 for each SDK are located in separate subdirectories.
 
 /build-libcloud
 ~~~~~~~~~~~~~~~
 
-The HTML documentation is built in this directory. This directory is included
+The HTML documentation is built in this directory. The :code:`.gitignore` file
-in the project :code:`.gitignore`.
+for the project specifies this directory.

firstapp/samples/shade/clouds.yml

@@ -0,0 +1,8 @@
+clouds:
+    myfavoriteopenstack:
+        auth:
+            auth_url: https://controller:5000/
+            username: $YOUR_USERNAME
+            password: $YOUR_PASSWORD
+            project_name: $YOUR_PROJECT
+        region_name: $REGION

firstapp/samples/shade/getting_started.py

@@ -0,0 +1,94 @@
+#step-1
+from shade import *
+
+simple_logging(debug=True)
+conn = openstack_cloud(cloud='myfavoriteopenstack')
+
+#step-2
+images = conn.list_images()
+for image in images:
+    print(image)
+
+#step-3
+flavors =  conn.list_flavors()
+for flavor in flavors:
+    print(flavor)
+
+#step-4
+image_id = 'c55094e9-699c-4da9-95b4-2e2e75f4c66e'
+image = conn.get_image(image_id)
+print(image)
+
+#step-5
+flavor_id = 'subsonic'
+flavor = conn.get_flavor(flavor_id)
+print(flavor)
+
+#step-6
+instance_name = 'testing'
+testing_instance = conn.create_server(wait=True, auto_ip=True,
+    name=instance_name,
+    image=image_id,
+    flavor=flavor_id)
+print(testing_instance)
+
+#step-7
+instances = conn.list_servers()
+for instance in instances:
+    print(instance)
+
+#step-8
+conn.delete_server(name=instance_name)
+
+#step-9
+print('Checking for existing SSH keypair...')
+keypair_name = 'demokey'
+pub_key_file = '~/.ssh/demo_key.pub'
+
+if conn.search_keypairs(keypair_name):
+    print('Keypair already exists. Skipping import.')
+else:
+    print('Adding keypair...')
+    conn.create_keypair(keypair_name, open(pub_key_file, 'r').read().strip())
+
+for keypair in conn.list_keypairs():
+    print(keypair)
+
+#step-10
+print('Checking for existing security groups...')
+sec_group_name = 'all-in-one'
+if conn.search_security_groups(sec_group_name):
+    print('Security group already exists. Skipping creation.')
+else:
+    print('Creating security group.')
+    conn.create_security_group(sec_group_name, 'network access for all-in-one application.')
+    conn.create_security_group_rule(sec_group_name, 80, 80, 'TCP')
+    conn.create_security_group_rule(sec_group_name, 22, 22, 'TCP')
+
+conn.search_security_groups(sec_group_name)
+
+#step-11
+ex_userdata = '''#!/usr/bin/env bash
+
+curl -L -s https://git.openstack.org/cgit/stackforge/faafo/plain/contrib/install.sh | bash -s -- \
+-i faafo -i messaging -r api -r worker -r demo
+'''
+
+#step-12
+instance_name = 'all-in-one'
+testing_instance = conn.create_server(wait=True, auto_ip=False,
+    name=instance_name,
+    image=image_id,
+    flavor=flavor_id,
+    key_name=keypair_name,
+    security_groups=[sec_group_name],
+    userdata=ex_userdata)
+
+#step-13
+f_ip = conn.available_floating_ip()
+
+#step-14
+conn.attach_ip_to_server(testing_instance['id'], f_ip['id'])
+
+#step-15
+print('The Fractals app will be deployed to http://%s' % f_ip['floating_ip_address'] )

firstapp/source/getting_started.rst

@@ -27,9 +27,9 @@ A general overview
 
 This tutorial shows two applications. The first application is a simple
 fractal generator that uses mathematical equations to generate beautiful
-`fractal images <http://en.wikipedia.org/wiki/Fractal>`_ . We show
+`fractal images <http://en.wikipedia.org/wiki/Fractal>`_ . We show you this
-you this application in its entirety so that you can compare it to the second,
+application in its entirety so that you can compare it to a second, more
-more robust, application.
+robust, application.
 
 The second application is an OpenStack application that enables you to:
 
@@ -56,6 +56,8 @@ 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
+Python         Shade         A Python-based library developed by OpenStack Infra team to       https://github.com/openstack-infra/shade
+                             operate multiple OpenStack clouds.
 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.                             https://github.com/fog/fog/blob/master/lib/fog/openstack/docs/getting_started.md
@@ -147,8 +149,13 @@ To interact with the cloud, you must also have
 
        This document has not yet been completed for the php-opencloud SDK.
 
-You need the following information that you can obtain from your cloud
+.. only:: shade
-provider:
+
+     `a recent version of shade library installed <https://pypi.python.org/pypi/shade/0.11.0>`_.
+
+     .. note:: Before proceeding, install the latest version of shade.
+
+Obtain the following information from your cloud provider:
 
 * auth URL
 * user name
@@ -156,29 +163,28 @@ provider:
 * project ID or name (projects are also known as tenants)
 * cloud region
 
-You can also download the OpenStack RC file from the OpenStack dashboard. Log
+You can also download the OpenStack RC file from the OpenStack Horizon
-in to the Horizon dashboard and click :guilabel:`Project->Access &
+dashboard. Log in to the dashboard and click :guilabel:`Project->Access &
-Security->API Access->Download OpenStack RC file`. If you choose this route,
+Security->API Access->Download OpenStack RC file`. If you use this method, be
-be aware that the "auth URL" doesn't include the path. For example, if your
+aware that the "auth URL" does not include the path. For example, if your
 :file:`openrc.sh` file shows:
 
 .. code-block:: bash
 
         export OS_AUTH_URL=http://controller:5000/v2.0
 
-the actual auth URL will be
+The actual auth URL is:
 
 .. code-block:: python
 
         http://controller:5000
 
-
 How you'll interact with OpenStack
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In this tutorial, you interact with your OpenStack cloud through one of the
+In this tutorial, you interact with your OpenStack cloud through the SDK that
-SDKs you have chosen in "Choose your OpenStack SDK." This guide assumes you
+you chose in "Choose your OpenStack SDK." This guide assumes that you know how
-are familiar with running code snippets in your language of choice.
+to run code snippets in your language of choice.
 
 .. only:: fog
 
@@ -242,12 +248,30 @@ are familiar with running code snippets in your language of choice.
 
     .. note:: If you receive the
               :code:`libcloud.common.types.InvalidCredsError: 'Invalid
-              credentials with the provider'` exception while trying to run
+              credentials with the provider'` exception when you run
-              one of the following API calls, double-check your credentials.
+              one of these API calls, double-check your credentials.
 
     .. note:: If your provider does not support regions, try a
               blank string ('') for the `region_name`.
 
+.. only:: shade
+
+    Use your credentials above to specify the cloud provider name,
+    user name, password, project_name and region_name in the file
+    :file:`~/.config/openstack/clouds.yml`.
+
+    .. literalinclude:: ../samples/shade/clouds.yml
+        :language: yaml
+
+    .. note:: If you do use a public cloud `known by shade
+              <http://git.openstack.org/cgit/openstack/os-client-config/tree/os_client_config/vendors>`_,
+              you can avoid specifying :code:`auth_url:` and instead specify
+              :code:`profile: $PROVIDER_NAME` in the clouds.yml file.
+
+    .. literalinclude::  ../samples/shade/getting_started.py
+        :start-after: step-1
+        :end-before: step-2
+
 Flavors and images
 ~~~~~~~~~~~~~~~~~~
 
@@ -321,6 +345,38 @@ To list the images that are available in your cloud, run some API calls:
         Image Id: 3e0e8270-0da4-4fec-bfc7-eeb763604cad - Image Name: cirros-0.3.4-x86_64-uec-ramdisk
         Image Id: 0b151382-d2f1-44d7-835b-6408bd523917 - Image Name: cirros-0.3.4-x86_64-uec-kernel
 
+.. only:: shade
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :language: python
+        :start-after: step-2
+        :end-before: step-3
+
+    This code returns output like this:
+
+    .. code-block:: none
+
+        checksum: 750a56555d4ec7303f5dc33b007ff632
+        container_format: bare
+        created_at: '2014-07-14T19:02:15Z'
+        direct_url:
+        rbd://7e14670e-a6f8-445b-b632-4b79bafc4781/masseffect-images/b4efbc2a-6130-4f2e-b436-55a618c4de20/snap
+        disk_format: raw
+        file: /v2/images/b4efbc2a-6130-4f2e-b436-55a618c4de20/file
+        id: b4efbc2a-6130-4f2e-b436-55a618c4de20
+        min_disk: 10
+        min_ram: 1024
+        name: Debian-7.0-Wheezy
+        owner: 0bacd8121bb548698f340455b38bf561
+        protected: false
+        schema: /v2/schemas/image
+        size: 5242880000
+        status: active
+        tags: []
+        updated_at: '2014-10-15T22:42:52Z'
+        visibility: public
+
+
 You can also get information about available flavors:
 
 .. only:: fog
@@ -388,13 +444,46 @@ You can also get information about available flavors:
         Flavor Id: 5 - Flavor Name: m1.xlarge
         Flavor Id: 84 - Flavor Name: m1.micro
 
+.. only:: shade
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :language: python
+        :start-after: step-3
+        :end-before: step-4
+
+    This code returns output like this:
+
+    .. code-block:: none
+
+        HUMAN_ID: true
+        NAME_ATTR: name
+        OS-FLV-DISABLED:disabled: false
+        OS-FLV-EXT-DATA:ephemeral: 0
+        disk: 80
+        ephemeral: 0
+        human_id: supersonic
+        id: '200'
+        is_public: true
+        links:
+        -   href:
+            https://compute.dream.io:8774/v2/5d013ac5962749a49af7ff18c2fb228c/flavors/200
+            rel: self
+        -   href:
+            https://compute.dream.io:8774/5d013ac5962749a49af7ff18c2fb228c/flavors/200
+            rel: bookmark
+        name: supersonic
+        os-flavor-access:is_public: true
+        ram: 2048
+        swap: ''
+        vcpus: 1
+
 Your images and flavors will be different, of course.
 
 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`
+and a 1GB disk. This example uses the Ubuntu image with a small
-flavor, which are safe choices. In subsequent tutorial sections in this guide,
+flavor, which is a safe choice. In subsequent tutorial sections in
-you must change the image and flavor IDs to correspond to the image and flavor
+this guide, you must change the image and flavor IDs to correspond to
-that you choose.
+the image and flavor that you choose.
 
 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
@@ -455,6 +544,37 @@ image that you picked in the previous section:
 
         Image Id: 97f55846-6ea5-4e9d-b437-bda97586bd0c - Image Name: cirros-0.3.4-x86_64-uec
 
+.. only:: shade
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-4
+        :end-before: step-5
+
+    This code returns output like this:
+
+    .. code-block:: none
+
+        checksum: da578dd59289a35a0ac7744a0bd85cf5
+        container_format: bare
+        created_at: '2014-10-27T22:05:37Z'
+        direct_url:
+        rbd://7e14670e-a6f8-445b-b632-4b79bafc4781/masseffect-images/c55094e9-699c-4da9-95b4-2e2e75f4c66e/snap
+        disk_format: raw
+        file: /v2/images/c55094e9-699c-4da9-95b4-2e2e75f4c66e/file
+        id: c55094e9-699c-4da9-95b4-2e2e75f4c66e
+        min_disk: 0
+        min_ram: 0
+        name: Ubuntu-14.04-Trusty
+        owner: 0bacd8121bb548698f340455b38bf561
+        protected: false
+        schema: /v2/schemas/image
+        size: 10737418240
+        status: active
+        tags: []
+        updated_at: '2014-10-27T22:08:55Z'
+        visibility: public
+
+
 Next, choose which flavor you want to use:
 
 .. only:: fog
@@ -506,6 +626,40 @@ Next, choose which flavor you want to use:
 
         Flavor Id: 42 - Flavor Name: m1.nano
 
+.. only:: shade
+
+    Since shade can either use the ID or the name in most API calls,
+    let's specify the name for the flavor.
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-5
+        :end-before: step-6
+
+    This code returns output like this:
+
+    .. code-block:: none
+
+        HUMAN_ID: true
+        NAME_ATTR: name
+        OS-FLV-DISABLED:disabled: false
+        OS-FLV-EXT-DATA:ephemeral: 0
+        disk: 80
+        ephemeral: 0
+        human_id: subsonic
+        id: '100'
+        is_public: true
+        links:
+        -   href:
+            https://compute.dream.io:8774/v2/5d013ac5962749a49af7ff18c2fb228c/flavors/100
+            rel: self
+        -   href:
+            https://compute.dream.io:8774/5d013ac5962749a49af7ff18c2fb228c/flavors/100
+            rel: bookmark
+        name: subsonic
+        os-flavor-access:is_public: true
+        ram: 1024
+        swap: ''
+        vcpus: 1
 
 Now, you're ready to launch the instance.
 
@@ -580,6 +734,12 @@ Create the instance.
 
         Instance Id: 4e480ef1-68f0-491f-b237-d9b7f500ef24 at net.openstack.Core.Domain.Link[]
 
+.. only:: shade
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-6
+        :end-before: step-7
+
 If you list existing instances:
 
 .. only:: fog
@@ -608,6 +768,13 @@ If you list existing instances:
         :start-after: step-7
         :end-before: step-8
 
+.. only:: shade
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-7
+        :end-before: step-8
+
+
 The new instance appears.
 
 .. only:: libcloud
@@ -649,7 +816,72 @@ The new instance appears.
 
         Instance Id: 4e480ef1-68f0-491f-b237-d9b7f500ef24 at net.openstack.Core.Domain.Link[]
 
-Before you move on, you must do one more thing.
+.. only:: shade
+
+   .. code-block:: none
+
+       HUMAN_ID: true
+        NAME_ATTR: name
+        OS-DCF:diskConfig: MANUAL
+        OS-EXT-AZ:availability_zone: iad-1
+        OS-EXT-STS:power_state: 1
+        OS-EXT-STS:task_state: null
+        OS-EXT-STS:vm_state: active
+        OS-SRV-USG:launched_at: '2015-07-20T20:31:10.000000'
+        OS-SRV-USG:terminated_at: null
+        accessIPv4: ''
+        accessIPv6: ''
+        addresses:
+            private-network:
+            -   OS-EXT-IPS-MAC:mac_addr: fa:16:3e:60:f5:cd
+                OS-EXT-IPS:type: fixed
+                addr: 2607:f298:6050:4e14:f816:3eff:fe60:f5cd
+                version: 6
+            -   OS-EXT-IPS-MAC:mac_addr: fa:16:3e:60:f5:cd
+                OS-EXT-IPS:type: fixed
+                addr: 10.10.10.14
+                version: 4
+        config_drive: ''
+        created: '2015-07-20T20:30:23Z'
+        flavor:
+            id: '100'
+            links:
+            -   href:
+                https://compute.dream.io:8774/5d013ac5962749a49af7ff18c2fb228c/flavors/100
+                rel: bookmark
+        hostId: f71865b497e6fa71063e292b11846eb64b5a41cd5c00fbb7465b6a48
+        human_id: testing
+        id: 67ecebdc-daff-4d84-bd04-bc76c67b48ec
+        image:
+            id: c55094e9-699c-4da9-95b4-2e2e75f4c66e
+            links:
+            -   href:
+                https://compute.dream.io:8774/5d013ac5962749a49af7ff18c2fb228c/images/c55094e9-699c-4da9-95b4-2e2e75f4c66e
+                rel: bookmark
+        key_name: null
+        links:
+        -   href:
+            https://compute.dream.io:8774/v2/5d013ac5962749a49af7ff18c2fb228c/servers/67ecebdc-daff-4d84-bd04-bc76c67b48ec
+            rel: self
+        -   href:
+            https://compute.dream.io:8774/5d013ac5962749a49af7ff18c2fb228c/servers/67ecebdc-daff-4d84-bd04-bc76c67b48ec
+            rel: bookmark
+        metadata: {}
+        name: testing
+        networks:
+            private-network:
+            - 2607:f298:6050:4e14:f816:3eff:fe60:f5cd
+            - 10.10.10.14
+        os-extended-volumes:volumes_attached: []
+        progress: 0
+        security_groups:
+        -   name: default
+        status: ACTIVE
+        tenant_id: 5d013ac5962749a49af7ff18c2fb228c
+        updated: '2015-07-20T20:31:10Z'
+        user_id: bfd3dbf1c8a242cd90884408de547bb9
+
+Before you continue, you must do one more thing.
 
 Destroy an instance
 ~~~~~~~~~~~~~~~~~~~
@@ -683,6 +915,12 @@ money. Destroy cloud resources to avoid unexpected expenses.
         :start-after: step-8
         :end-before: step-9
 
+.. only:: shade
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-8
+        :end-before: step-9
+
 If you list the instances again, the instance disappears.
 
 Leave your shell open to use it for another instance deployment in this
@@ -738,6 +976,16 @@ instance:
         :start-after: step-9
         :end-before: step-10
 
+.. only:: shade
+
+    In the following example, :code:`pub_key_file` should be set to
+    the location of your public SSH key file.
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-9
+        :end-before: step-10
+
+
 * 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:`/introduction`.
@@ -760,6 +1008,12 @@ instance:
         :start-after: step-10
         :end-before: step-11
 
+.. only:: shade
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-10
+        :end-before: step-11
+
 * User data. During instance creation, you can provide user data to OpenStack to
   configure instances after they boot. The cloud-init service applies the
   user data to an instance. You must pre-install the cloud-init service on your
@@ -781,6 +1035,12 @@ instance:
         :start-after: step-11
         :end-before: step-12
 
+.. only:: shade
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-11
+        :end-before: step-12
+
 Now, you can boot and configure the instance.
 
 Boot and configure an instance
@@ -805,6 +1065,13 @@ request the instance, wait for it to build.
         :start-after: step-12
         :end-before: step-13
 
+.. only:: shade
+
+    The shade framework can select and assign a free floating IP quickly
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-12
+        :end-before: step-13
 
 When the instance boots, the `ex_userdata` variable value instructs the
 instance to deploy the Fractals application.
@@ -871,6 +1138,12 @@ address to your instance.
         :start-after: step-14
         :end-before: step-15
 
+.. only:: shade
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-13
+        :end-before: step-14
+
 
 Run the script to start the deployment.
 
@@ -880,7 +1153,7 @@ 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
 deploys, you can visit the awesome graphic interface at the following link
-using your preferred browser.
+by using your preferred browser.
 
 .. only:: libcloud
 
@@ -892,6 +1165,11 @@ using your preferred browser.
     .. literalinclude:: ../samples/pkgcloud/getting_started.js
         :start-after: step-15
 
+.. only:: shade
+
+    .. literalinclude:: ../samples/shade/getting_started.py
+        :start-after: step-15
+
 .. note:: If you do not use floating IPs, substitute another IP address as appropriate
 
 .. figure:: images/screenshot_webinterface.png
@@ -942,3 +1220,8 @@ information, the flavor ID, and image ID.
 
     .. literalinclude:: ../samples/dotnet/getting_started.cs
        :language: c#
+
+.. only:: shade
+
+    .. literalinclude:: ../samples/libcloud/getting_started.py
+       :language: python

tools/build-firstapp-rst.sh

@@ -9,7 +9,7 @@ for tag in libcloud; do
 done
 
 # Draft documents
-for tag in dotnet fog pkgcloud; do
+for tag in dotnet fog pkgcloud shade; do
     tools/build-rst.sh firstapp  \
         --tag ${tag} --target "draft/firstapp-${tag}"
 done

tox.ini

@@ -109,6 +109,9 @@ commands = sphinx-build -E -W -t openstacksdk firstapp/source firstapp/build-ope
 [testenv:firstapp-todos]
 commands = sphinx-build -E -W -t libcloud firstapp/source firstapp/build/html
 
+[testenv:firstapp-shade]
+commands = sphinx-build -E -W -t shade firstapp/source firstapp/build-shade/html
+
 [doc8]
 # Settings for doc8:
 # Ignore target directories