From 64b52b03d3b591938dab171714d14c7812f9dcb0 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Wed, 22 Apr 2015 20:28:21 +0200 Subject: [PATCH] FirstApp: Edits section5 Wrap overlong lines, follow markup conventions. Change-Id: I406a32e9fe13aefe37374e7ddc387099ed90003d --- openstack-firstapp/doc/source/section5.rst | 158 +++++++++++++-------- 1 file changed, 95 insertions(+), 63 deletions(-) diff --git a/openstack-firstapp/doc/source/section5.rst b/openstack-firstapp/doc/source/section5.rst index e3350961b..d6b49e230 100644 --- a/openstack-firstapp/doc/source/section5.rst +++ b/openstack-firstapp/doc/source/section5.rst @@ -1,58 +1,71 @@ -=========================== -Section Five: Block Storage -=========================== +============= +Block Storage +============= -.. todo:: (For nick: Restructure the introduction to this chapter to provide context of what we're actually - going to do.) +.. 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 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. -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. +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. -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. +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. -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:`section9`). Others should read -on to learn about how to work with block storage and move the Fractal app database server to use it. +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:`section9`). Others +should read on to learn about how to work with block storage and move +the Fractal app 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 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. .. only:: dotnet - .. warning:: This section has not yet been completed for the .NET SDK + .. warning:: This section has not yet been completed for the .NET SDK. .. only:: fog - .. warning:: This section has not yet been completed for the fog SDK + .. warning:: This section has not yet been completed for the fog SDK. .. only:: jclouds - .. warning:: This section has not yet been completed for the jclouds SDK + .. warning:: This section has not yet been completed for the jclouds SDK. .. only:: node - .. warning:: This section has not yet been completed for the pkgcloud SDK + .. warning:: This section has not yet been completed for the pkgcloud SDK. .. only:: openstacksdk - .. warning:: This section has not yet been completed for the OpenStack SDK + .. warning:: This section has not yet been completed for the OpenStack SDK. .. only:: phpopencloud - .. warning:: This section has not yet been completed for the PHP-OpenCloud SDK + .. warning:: This section has not yet been completed for the + PHP-OpenCloud SDK. As always, connect to the API endpoint: @@ -107,11 +120,12 @@ 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. +Now that you have created a storage volume, let's attach it to an +already running instance. -Using Block Storage for the Fractal Database Server ---------------------------------------------------- +Using Block Storage for the Fractal database server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 @@ -131,8 +145,9 @@ 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`: +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:: libcloud @@ -143,7 +158,8 @@ use the server object from the previous snippet and attach the volume to it at : Log in to the server to be able to run the following steps. -.. note:: Replace :code:`IP_SERVICES` with the IP address of the services instance and USERNAME to the appropriate username. +.. note:: Replace :code:`IP_SERVICES` with the IP address of the + services instance and USERNAME to the appropriate username. Now prepare the empty block device. @@ -157,14 +173,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 :code:`/var/lib/mysql` onto the new volume (temporary mounted at :code:`/mnt/database`). +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`). :: # systemctl stop mariadb # mv /var/lib/mysql/* /mnt/database -Sync the filesystems and mount the new blockdevice now containing the database files to :code:`/var/lib/mysql`. +Sync the filesystems and mount the new blockdevice now containing the +database files to :file:`/var/lib/mysql`. :: @@ -174,7 +193,8 @@ Sync the filesystems and mount the new blockdevice now containing the database f # 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 previously stopped MySQL database service and check +if everything is working like expected. :: @@ -182,9 +202,10 @@ Finally start the previously stopped MySQL database service and check if everyth # mysql -ufaafo -ppassword -h localhost faafo -e 'show tables;' 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 re-attach it elsewhere, or destroy the +volume with the below steps. .. warning:: The following operations are destructive and will result in data loss. @@ -205,9 +226,11 @@ 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): +There are also many other useful features, such as the ability to +create snapshots of volumes (handy for backups): .. only:: libcloud @@ -216,32 +239,38 @@ There are also many other useful features, such as the ability to create snapsho * snapshot_name = 'test_backup_1' connnection.create_volume_snapshot('test', name='test backup 1') - .. todo:: Do we need a note here to mention that 'test' is the volume name and not the volume object? + .. 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 `libcloud documentation `_. + You can find information about these calls and more in the + `libcloud documentation + `_. 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). +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). -.. note:: This OpenStack Database service is not installed in many clouds right now, but if your cloud does - support it, it can make your life a lot easier when working with databases. +.. note:: This OpenStack Database service is not installed in many + clouds right now, but if your cloud does support 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 don't generally support the service yet, but you can use the +'trove' commandline client to work with it instead. Install the trove commandline 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 'openrc' file using this guide: +Then set up the necessary variables for your cloud in an :file:`openrc.sh` file +using this guide: http://docs.openstack.org/cli-reference/content/cli_openrc.html -Ensure you have an openrc.sh file, source it and then check your trove client works: -:: +Ensure you have an :file:`openrc.sh` file, source it and then check +your trove client works: :: $ cat openrc.sh export OS_USERNAME=your_auth_username @@ -256,18 +285,21 @@ Ensure you have an openrc.sh file, source it and then check your trove client wo 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. +to use in `these slides +`_. Steps +to work with an existing database service installation start on +slide 28. 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: +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: -* :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:`/section6`: to automatically orchestrate the application +* :doc:`/section7`: to learn about more complex networking +* :doc:`/section8`: for advice for developers new to operations