From dabd8f84b945c135c55f1bbd1791cf8f3dc86b3d Mon Sep 17 00:00:00 2001 From: Caleb Boylan Date: Thu, 8 Oct 2015 16:07:20 -0700 Subject: [PATCH] Add block storage to shade's firstapp tutorial (df) Edits for clarity. Change-Id: Ic31aea856ee2e9ff06ca07438d6a01c9bf8955f6 --- firstapp/samples/shade/block_storage.py | 32 ++++ firstapp/source/block_storage.rst | 195 +++++++++++++----------- 2 files changed, 142 insertions(+), 85 deletions(-) create mode 100644 firstapp/samples/shade/block_storage.py diff --git a/firstapp/samples/shade/block_storage.py b/firstapp/samples/shade/block_storage.py new file mode 100644 index 000000000..af60dfa0f --- /dev/null +++ b/firstapp/samples/shade/block_storage.py @@ -0,0 +1,32 @@ +# step-1 +import shade + +conn = shade.openstack_cloud(cloud='myfavoriteopenstack') + +# step-2 +volume = conn.create_volume(size=1, display_name='test') + +# step-3 +volumes = conn.list_volumes() +for vol in volumes: + print(vol) + +# step-4 +db_group = conn.create_security_group('database', 'for database service') +conn.create_security_group_rule(db_group['name'], 3306, 3306, 'TCP') + +instance = conn.create_server(wait=True, auto_ip=False, + name=name, + image=image['id'], + flavor=flavor['id'], + security_groups=[db_group['name']]) + +# step-5 +conn.attach_volume(instance, volume, '/dev/vdb') + +# step-6 +conn.detach_volume(instance, volume) +conn.delete_volume(volume['id']) + +# step-7 +# step-8 diff --git a/firstapp/source/block_storage.rst b/firstapp/source/block_storage.rst index 6db7b6000..db5e408e7 100644 --- a/firstapp/source/block_storage.rst +++ b/firstapp/source/block_storage.rst @@ -5,42 +5,35 @@ Block Storage .. todo:: (For nick: Restructure the introduction to this chapter to provide context of what we're actually going to do.) -By default, data in OpenStack instances is stored on 'ephemeral' -disks. These stay with the instance throughout its lifetime, but when -the instance is terminated, that storage disappears -- along with all -the data stored on it. Ephemeral storage is allocated to a single -instance and cannot be moved to another instance. +By default, data in OpenStack instances is stored on 'ephemeral' disks. These +disks stay with the instance throughout its lifetime, but when the instance is +terminated, that storage and all the data stored on it disappears. Ephemeral +storage is allocated to a single instance and cannot be moved to another +instance. -In this section, we will introduce block storage. Block storage -(sometimes referred to as volume storage) provides you with access to -persistent storage devices. You interact with block storage by -attaching volumes to running instances, just as you might attach a USB -drive to a physical server. Volumes can be detached from one instance -and re-attached to another, and the data remains intact. Block -storage is implemented in OpenStack by the OpenStack Block Storage -(cinder) project. +This section introduces block storage, also known as volume storage, which +provides access to persistent storage devices. You interact with block storage +by attaching volumes to running instances just as you might attach a USB drive +to a physical server. You can detach volumes from one instance and reattach +them to another instance and the data remains intact. The OpenStack Block +Storage (cinder) project implements block storage. -One component of the Fractal app that cannot be allowed to fail is the -database server, which is used to keep track of all of the data about -fractals that have been created, including their storage location. So -while you may have configured the images to be stored in Object -Storage in the previous section, without the database we lose track of -where in Object Storage they are, and the parameters that were used to -create them. +Though you might have configured Object Storage to store images, the Fractal +application needs a database to track the location of and parameters that were +used to create images in Object Storage. This database server cannot fail. -Advanced users should consider how to remove the database from the -architecture altogether and replace it with metadata in the Object -Storage (then contribute these steps to :doc:`craziness`). Others -should read on to learn about how to work with block storage and move -the Fractal app database server to use it. +If you are an advanced user, consider how you might remove the database from +the architecture and replace it with Object Storage metadata (then contribute +these steps to :doc:`craziness`). Other users can continue reading to learn +how to work with block storage and move the Fractal application database +server to use it. Basics ~~~~~~ -Later on, we'll use a volume from the block storage service to provide -persistent storage for the Fractal app's database server, but first - -let's cover the basics, such as creating and attaching a block storage -device. +Later on, we'll use a Block Storage volume to provide persistent storage for +the database server for the Fractal application. But first, learn how to +create and attach a Block Storage device. .. only:: dotnet @@ -91,6 +84,12 @@ As always, connect to the API endpoint: ex_tenant_name=project_name, ex_force_service_region=region_name) +.. only:: shade + + .. literalinclude:: ../samples/shade/block_storage.py + :language: python + :start-after: step-1 + :end-before: step-2 To try it out, make a 1GB volume called :test'. @@ -105,7 +104,14 @@ To try it out, make a 1GB volume called :test'. -.. note:: The parameter :code:`size` is in GigaBytes. +.. only:: shade + + .. literalinclude:: ../samples/shade/block_storage.py + :language: python + :start-after: step-2 + :end-before: step-3 + +.. note:: The parameter :code:`size` is in gigabytes. List all volumes to see if it was successful: @@ -120,18 +126,24 @@ List all volumes to see if it was successful: [] -Now that you have created a storage volume, let's attach it to an -already running instance. +.. only:: shade + .. literalinclude:: ../samples/shade/block_storage.py + :language: python + :start-after: step-3 + :end-before: step-4 -Using Block Storage for the Fractal database server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Attach the storage volume to a running instance. -Firstly, we're going to need a new server for our dedicated database. -Start a new instance called :code:`app-database` using the image, flavor -and keypair you have been using since :doc:`/getting_started`. -We will also need a new security group to allow access to the database server -(for mysql, port 3306) from the network: +Use Block Storage for the Fractal database server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You need a server for the dedicated database. Use the image, flavor, and +keypair that you used in :doc:`/getting_started` to launch an +:code:`app-database` instance. + +You also need a security group to permit access to the database server (for +MySQL, port 3306) from the network: .. only:: libcloud @@ -145,9 +157,16 @@ We will also need a new security group to allow access to the database server ex_keyname=keypair_name, ex_security_groups=[db_group]) -Using the unique identifier (UUID) for the volume, make a new volume -object, then use the server object from the previous snippet and -attach the volume to it at :code:`/dev/vdb`: +.. only:: shade + + .. literalinclude:: ../samples/shade/block_storage.py + :language: python + :start-after: step-4 + :end-before: step-5 + +Create a volume object by using the unique identifier (UUID) for the volume. +Then, use the server object from the previous code snippet to attach the +volume to it at :code:`/dev/vdb`: .. only:: libcloud @@ -156,10 +175,17 @@ attach the volume to it at :code:`/dev/vdb`: volume = connection.ex_get_volume('755ab026-b5f2-4f53-b34a-6d082fb36689') connection.attach_volume(instance, volume, '/dev/vdb') -Log in to the server to be able to run the following steps. +.. only:: shade + + .. literalinclude:: ../samples/shade/block_storage.py + :language: python + :start-after: step-5 + :end-before: step-6 + +Log in to the server to run the following steps. .. note:: Replace :code:`IP_SERVICES` with the IP address of the - services instance and USERNAME to the appropriate username. + services instance and USERNAME to the appropriate user name. Now prepare the empty block device. @@ -173,17 +199,17 @@ Now prepare the empty block device. .. todo:: Outputs missing, add attaching log from dmesg. -Stop the running MySQL database service and move the database files -from :file:`/var/lib/mysql` onto the new volume (temporary mounted at -:file:`/mnt/database`). +Stop the running MySQL database service and move the database files from +:file:`/var/lib/mysql` to the new volume, which is temporarily mounted at +:file:`/mnt/database`. :: # systemctl stop mariadb # mv /var/lib/mysql/* /mnt/database -Sync the filesystems and mount the new blockdevice now containing the -database files to :file:`/var/lib/mysql`. +Sync the file systems and mount the block device that contains the database +files to :file:`/var/lib/mysql`. :: @@ -193,8 +219,8 @@ database files to :file:`/var/lib/mysql`. # echo "/dev/vdb /var/lib/mysql ext4 defaults 1 2" >> /etc/fstab # mount /var/lib/mysql -Finally start the previously stopped MySQL database service and check -if everything is working like expected. +Finally, start the stopped MySQL database service and validate that everything +works as expected. :: @@ -204,11 +230,11 @@ if everything is working like expected. Extras ~~~~~~ -You can detach the volume and re-attach it elsewhere, or destroy the -volume with the below steps. +You can detach the volume and reattach it elsewhere, or use the following +steps to destroy the volume. .. warning:: - The following operations are destructive and will result in data loss. + The following operations are destructive and result in data loss. To detach and destroy a volume: @@ -226,14 +252,20 @@ To detach and destroy a volume: connection.destroy_volume(volume) -.. note:: :code:`detach_volume` and :code:`destroy_volume` take a - volume object, not a name. + .. note:: :code:`detach_volume` and :code:`destroy_volume` take a + volume object, not a name. -There are also many other useful features, such as the ability to -create snapshots of volumes (handy for backups): +.. only:: shade + + .. literalinclude:: ../samples/shade/block_storage.py + :language: python + :start-after: step-6 + :end-before: step-7 .. only:: libcloud + Other features, such as creating volume snapshots, are useful for backups: + .. code-block:: python * snapshot_name = 'test_backup_1' @@ -242,34 +274,32 @@ create snapshots of volumes (handy for backups): .. todo:: Do we need a note here to mention that 'test' is the volume name and not the volume object? - You can find information about these calls and more in the + For information about these and other calls, see `libcloud documentation `_. +Work with the OpenStack Database service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Working with the OpenStack Database service -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You created the database manually above, which is fine for a case with -a single database you won't touch often like this. However, OpenStack -also has a component code-named :code:`trove` that provides Database -as a Service (DBaaS). +Previously, you manually created the database, which is useful for a a single +database that you rarely update. However, the OpenStack :code:`trove` +component provides Database as a Service (DBaaS). .. note:: This OpenStack Database service is not installed in many - clouds right now, but if your cloud does support it, it can + clouds right now, but if your cloud supports it, it can make your life a lot easier when working with databases. -SDKs don't generally support the service yet, but you can use the -'trove' commandline client to work with it instead. +SDKs do not generally support the service yet, but you can use the +'trove' command-line client to work with it instead. -Install the trove commandline client by following this guide: +Install the trove command-line client by following this guide: http://docs.openstack.org/cli-reference/content/install_clients.html -Then set up the necessary variables for your cloud in an :file:`openrc.sh` file -using this guide: +Then, set up necessary variables for your cloud in an :file:`openrc.sh` file +by using this guide: http://docs.openstack.org/cli-reference/content/cli_openrc.html -Ensure you have an :file:`openrc.sh` file, source it and then check +Ensure you have an :file:`openrc.sh` file, source it, and validate that your trove client works: :: $ cat openrc.sh @@ -284,21 +314,16 @@ your trove client works: :: $ trove --version 1.0.9 -From there, you can find a good resource on what is supported and how -to use in `these slides -`_. Steps -to work with an existing database service installation start on -slide 28. +For information about supported features and how to work with an existing +database service installation, see these +`slides `_. - - -Next Steps +Next steps ~~~~~~~~~~ -You should now be fairly confident working with Block Storage volumes. -There are several calls we did not cover. To see these and more, refer -to the volume documentation of your SDK, or try a different step in -the tutorial, including: +You should now be fairly confident working with Block Storage volumes. For +information about other calls, see the volume documentation for your SDK or +try one of these tutorial steps: * :doc:`/orchestration`: to automatically orchestrate the application * :doc:`/networking`: to learn about more complex networking