From 0e4e71f4190799eaf591db9ead43b06259de11ed Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Thu, 29 Jun 2017 16:25:34 -0400 Subject: [PATCH] import admin-guide content from openstack-manuals Change-Id: I8d3bd82b959ce1e44c212b692e2ce7343373b2c5 Signed-off-by: Doug Hellmann --- doc/source/admin/basics.rst | 495 +++++++++++++++++++++ doc/source/admin/database_module_usage.rst | 410 +++++++++++++++++ doc/source/admin/index.rst | 8 +- 3 files changed, 910 insertions(+), 3 deletions(-) create mode 100644 doc/source/admin/basics.rst create mode 100644 doc/source/admin/database_module_usage.rst diff --git a/doc/source/admin/basics.rst b/doc/source/admin/basics.rst new file mode 100644 index 0000000000..90a71108fe --- /dev/null +++ b/doc/source/admin/basics.rst @@ -0,0 +1,495 @@ +.. _database: + +======== +Database +======== + +The Database service provides database management features. + +Introduction +~~~~~~~~~~~~ + +The Database service provides scalable and reliable cloud +provisioning functionality for both relational and non-relational +database engines. Users can quickly and easily use database features +without the burden of handling complex administrative tasks. Cloud +users and database administrators can provision and manage multiple +database instances as needed. + +The Database service provides resource isolation at high performance +levels, and automates complex administrative tasks such as deployment, +configuration, patching, backups, restores, and monitoring. + +You can modify various cluster characteristics by editing the +``/etc/trove/trove.conf`` file. A comprehensive list of the Database +service configuration options is described in the `Database service +`_ +chapter in the *Configuration Reference*. + +Create a data store +~~~~~~~~~~~~~~~~~~~ + +An administrative user can create data stores for a variety of +databases. + +This section assumes you do not yet have a MySQL data store, and shows +you how to create a MySQL data store and populate it with a MySQL 5.5 +data store version. + + +**To create a data store** + +#. **Create a trove image** + + Create an image for the type of database you want to use, for + example, MySQL, MongoDB, Cassandra. + + This image must have the trove guest agent installed, and it must + have the ``trove-guestagent.conf`` file configured to connect to + your OpenStack environment. To configure ``trove-guestagent.conf``, + add the following lines to ``trove-guestagent.conf`` on the guest + instance you are using to build your image: + + .. code-block:: ini + + rabbit_host = controller + rabbit_password = RABBIT_PASS + nova_proxy_admin_user = admin + nova_proxy_admin_pass = ADMIN_PASS + nova_proxy_admin_tenant_name = service + trove_auth_url = http://controller:35357/v2.0 + + This example assumes you have created a MySQL 5.5 image called + ``mysql-5.5.qcow2``. + + .. important:: + + If you have a guest image that was created with an OpenStack version + before Kilo, modify the guest agent init script for the guest image to + read the configuration files from the directory ``/etc/trove/conf.d``. + + For a backwards compatibility with pre-Kilo guest instances, set the + database service configuration options ``injected_config_location`` to + ``/etc/trove`` and ``guest_info`` to ``/etc/guest_info``. + +#. **Register image with Image service** + + You need to register your guest image with the Image service. + + In this example, you use the :command:`openstack image create` + command to register a ``mysql-5.5.qcow2`` image. + + .. code-block:: console + + $ openstack image create mysql-5.5 --disk-format qcow2 --container-format bare --public < mysql-5.5.qcow2 + +------------------+------------------------------------------------------+ + | Field | Value | + +------------------+------------------------------------------------------+ + | checksum | 133eae9fb1c98f45894a4e60d8736619 | + | container_format | bare | + | created_at | 2016-12-21T12:10:02Z | + | disk_format | qcow2 | + | file | /v2/images/d1afb4f0-2360-4400-8d97-846b1ab6af52/file | + | id | d1afb4f0-2360-4400-8d97-846b1ab6af52 | + | min_disk | 0 | + | min_ram | 0 | + | name | mysql-5.5 | + | owner | 5669caad86a04256994cdf755df4d3c1 | + | protected | False | + | schema | /v2/schemas/image | + | size | 13200896 | + | status | active | + | tags | | + | updated_at | 2016-12-21T12:10:03Z | + | virtual_size | None | + | visibility | public | + +------------------+------------------------------------------------------+ + +#. **Create the data store** + + Create the data store that will house the new image. To do this, use + the :command:`trove-manage` :command:`datastore_update` command. + + This example uses the following arguments: + + .. list-table:: + :header-rows: 1 + :widths: 20 20 20 + + * - Argument + - Description + - In this example: + * - config file + - The configuration file to use. + - ``--config-file=/etc/trove/trove.conf`` + * - name + - Name you want to use for this data store. + - ``mysql`` + * - default version + - You can attach multiple versions/images to a data store. For + example, you might have a MySQL 5.5 version and a MySQL 5.6 + version. You can designate one version as the default, which + the system uses if a user does not explicitly request a + specific version. + - ``""`` + + At this point, you do not yet have a default version, so pass + in an empty string. + + | + + Example: + + .. code-block:: console + + $ trove-manage --config-file=/etc/trove/trove.conf datastore_update mysql "" + +#. **Add a version to the new data store** + + Now that you have a MySQL data store, you can add a version to it, + using the :command:`trove-manage` :command:`datastore_version_update` + command. The version indicates which guest image to use. + + This example uses the following arguments: + + .. list-table:: + :header-rows: 1 + :widths: 20 20 20 + + * - Argument + - Description + - In this example: + + * - config file + - The configuration file to use. + - ``--config-file=/etc/trove/trove.conf`` + + * - data store + - The name of the data store you just created via + ``trove-manage`` :command:`datastore_update`. + - ``mysql`` + + * - version name + - The name of the version you are adding to the data store. + - ``mysql-5.5`` + + * - data store manager + - Which data store manager to use for this version. Typically, + the data store manager is identified by one of the following + strings, depending on the database: + + * cassandra + * couchbase + * couchdb + * db2 + * mariadb + * mongodb + * mysql + * percona + * postgresql + * pxc + * redis + * vertica + - ``mysql`` + + * - glance ID + - The ID of the guest image you just added to the Image + service. You can get this ID by using the glance + :command:`image-show` IMAGE_NAME command. + - bb75f870-0c33-4907-8467-1367f8cb15b6 + + * - packages + - If you want to put additional packages on each guest that + you create with this data store version, you can list the + package names here. + - ``""`` + + In this example, the guest image already contains all the + required packages, so leave this argument empty. + + * - active + - Set this to either 1 or 0: + * ``1`` = active + * ``0`` = disabled + - 1 + + | + + Example: + + .. code-block:: console + + $ trove-manage --config-file=/etc/trove/trove.conf datastore_version_update mysql mysql-5.5 mysql GLANCE_ID "" 1 + + **Optional.** Set your new version as the default version. To do + this, use the :command:`trove-manage` :command:`datastore_update` + command again, this time specifying the version you just created. + + .. code-block:: console + + $ trove-manage --config-file=/etc/trove/trove.conf datastore_update mysql mysql-5.5 + +#. **Load validation rules for configuration groups** + + .. note:: + + **Applies only to MySQL and Percona data stores** + + * If you just created a MySQL or Percona data store, then you need + to load the appropriate validation rules, as described in this + step. + * If you just created a different data store, skip this step. + + **Background.** You can manage database configuration tasks by using + configuration groups. Configuration groups let you set configuration + parameters, in bulk, on one or more databases. + + When you set up a configuration group using the trove + :command:`configuration-create` command, this command compares the configuration + values you are setting against a list of valid configuration values + that are stored in the ``validation-rules.json`` file. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 20 + + * - Operating System + - Location of :file:`validation-rules.json` + - Notes + + * - Ubuntu 14.04 + - :file:`/usr/lib/python2.7/dist-packages/trove/templates/DATASTORE_NAME` + - DATASTORE_NAME is the name of either the MySQL data store or + the Percona data store. This is typically either ``mysql`` + or ``percona``. + + * - RHEL 7, CentOS 7, Fedora 20, and Fedora 21 + - :file:`/usr/lib/python2.7/site-packages/trove/templates/DATASTORE_NAME` + - DATASTORE_NAME is the name of either the MySQL data store or + the Percona data store. This is typically either ``mysql`` or ``percona``. + + | + + Therefore, as part of creating a data store, you need to load the + ``validation-rules.json`` file, using the :command:`trove-manage` + :command:`db_load_datastore_config_parameters` command. This command + takes the following arguments: + + * Data store name + * Data store version + * Full path to the ``validation-rules.json`` file + + | + + This example loads the ``validation-rules.json`` file for a MySQL + database on Ubuntu 14.04: + + .. code-block:: console + + $ trove-manage db_load_datastore_config_parameters mysql mysql-5.5 /usr/lib/python2.7/dist-packages/trove/templates/mysql/validation-rules.json + +#. **Validate data store** + + To validate your new data store and version, start by listing the + data stores on your system: + + .. code-block:: console + + $ trove datastore-list + +--------------------------------------+--------------+ + | id | name | + +--------------------------------------+--------------+ + | 10000000-0000-0000-0000-000000000001 | Legacy MySQL | + | e5dc1da3-f080-4589-a4c2-eff7928f969a | mysql | + +--------------------------------------+--------------+ + + Take the ID of the MySQL data store and pass it in with the + :command:`datastore-version-list` command: + + .. code-block:: console + + $ trove datastore-version-list DATASTORE_ID + +--------------------------------------+-----------+ + | id | name | + +--------------------------------------+-----------+ + | 36a6306b-efd8-4d83-9b75-8b30dd756381 | mysql-5.5 | + +--------------------------------------+-----------+ + +Data store classifications +-------------------------- + +The Database service supports a variety of both relational and +non-relational database engines, but to a varying degree of support for +each *data store*. The Database service project has defined +several classifications that indicate the quality of support for each +data store. Data stores also implement different extensions. +An extension is called a *strategy* and is classified similar to +data stores. + +Valid classifications for a data store and a strategy are: + +* Experimental + +* Technical preview + +* Stable + +Each classification builds on the previous one. This means that a data store +that meets the ``technical preview`` requirements must also meet all the +requirements for ``experimental``, and a data store that meets the ``stable`` +requirements must also meet all the requirements for ``technical preview``. + +**Requirements** + +* Experimental + + A data store is considered to be ``experimental`` if it meets these criteria: + + * It implements a basic subset of the Database service API including + ``create`` and ``delete``. + + * It has guest agent elements that allow guest agent creation. + + * It has a definition of supported operating systems. + + * It meets the other + `Documented Technical Requirements `_. + + A strategy is considered ``experimental`` if: + + * It meets the + `Documented Technical Requirements `_. + +* Technical preview + + A data store is considered to be a ``technical preview`` if it meets the + requirements of ``experimental`` and further: + + * It implements APIs required to plant and start the capabilities of the + data store as defined in the + `Datastore Compatibility Matrix `_. + + .. note:: + + It is not required that the data store implements all features like + resize, backup, replication, or clustering to meet this classification. + + * It provides a mechanism for building a guest image that allows you to + exercise its capabilities. + + * It meets the other + `Documented Technical Requirements `_. + + .. important:: + + A strategy is not normally considered to be ``technical + preview``. + +* Stable + + A data store or a strategy is considered ``stable`` if: + + * It meets the requirements of ``technical preview``. + + * It meets the other + `Documented Technical Requirements `_. + +**Initial Classifications** + +The following table shows the current classification assignments for the +different data stores. + +.. list-table:: + :header-rows: 1 + :widths: 30 30 + + * - Classification + - Data store + * - Stable + - MySQL + * - Technical Preview + - Cassandra, MongoDB + * - Experimental + - All others + +Redis data store replication +---------------------------- + +Replication strategies are available for Redis with +several commands located in the Redis data store +manager: + +- :command:`create` +- :command:`detach-replica` +- :command:`eject-replica-source` +- :command:`promote-to-replica-source` + +Additional arguments for the :command:`create` command +include :command:`--replica_of` and +:command:`--replica_count`. + +Redis integration and unit tests +-------------------------------- + +Unit tests and integration tests are also available for +Redis. + +#. Install trovestack: + + .. code-block:: console + + $ ./trovestack install + + .. note:: + + Trovestack is a development script used for integration + testing and Database service development installations. + Do not use Trovestack in a production environment. For + more information, see `the Database service + developer docs `_ + +#. Start Redis: + + .. code-block:: console + + $ ./trovestack kick-start redis + +#. Run integration tests: + + .. code-block:: console + + $ ./trovestack int-tests --group=replication + + You can run :command:`--group=redis_supported` + instead of :command:`--group=replication` if needed. + +Configure a cluster +~~~~~~~~~~~~~~~~~~~ + +An administrative user can configure various characteristics of a +MongoDB cluster. + +**Query routers and config servers** + +**Background.** Each cluster includes at least one query router and +one config server. Query routers and config servers count against your +quota. When you delete a cluster, the system deletes the associated +query router(s) and config server(s). + +**Configuration.** By default, the system creates one query router and +one config server per cluster. You can change this by editing +the ``/etc/trove/trove.conf`` file. These settings are in the +``mongodb`` section of the file: + +.. list-table:: + :header-rows: 1 + :widths: 30 30 + + * - Setting + - Valid values are: + + * - num_config_servers_per_cluster + - 1 or 3 + + * - num_query_routers_per_cluster + - 1 or 3 diff --git a/doc/source/admin/database_module_usage.rst b/doc/source/admin/database_module_usage.rst new file mode 100644 index 0000000000..9b0ca21af6 --- /dev/null +++ b/doc/source/admin/database_module_usage.rst @@ -0,0 +1,410 @@ +.. _database_module_usage: + +===================================== +Create and use modules for a database +===================================== + +To continue with this document, we recommend that you have installed +the Database service and populated your data store with images for the +type and versions of databases that you want, and that you can create +and access a database. + +This example shows you how to create and apply modules to a MySQL 5.6 +database and redis 3.2.6 database cluster. + +Create and apply a module to a mysql database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. **Create the module file and trove module** + + If you wish to apply a module, you must create the module first + and register it with the trove service. A user can not directly + apply a module to a trove instance. + + The module created here is a demo module called ping. It is the + basic type made for testing purposes. To create it, it is as + simple as the following :command: ``echo`` command: + + .. code-block:: console + + $ echo "message=Module.V1" > ping1.dat + + You can create a test module and mysql database with the module + applied by doing the following: + + .. code-block:: console + + $ trove module-create mymod ping ping1.dat --live_update \ + --datastore mysql + + +----------------------+--------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------+ + | apply_order | 5 | + | auto_apply | False | + | created | 2017-06-02T17:06:21 | + | datastore | all | + | datastore_id | None | + | datastore_version | all | + | datastore_version_id | None | + | description | None | + | id | 0065a8ed-0668-4db5-a4ad-d88d0a166388 | + | instance_count | 2 | + | is_admin | True | + | live_update | True | + | md5 | 7f700cc7b99606615f8b51946f6d3228 | + | name | mymod | + | priority_apply | False | + | tenant | eac1e46e5f7840e39012aff46a92073a | + | tenant_id | eac1e46e5f7840e39012aff46a92073a | + | type | ping | + | updated | 2017-06-02T17:06:21 | + | visible | True | + +----------------------+--------------------------------------+ + + $ trove create myinst 15 --size 1 --module mymod --datastore mysql + + +-------------------------+--------------------------------------+ + | Property | Value | + +-------------------------+--------------------------------------+ + | created | 2017-06-02T17:22:24 | + | datastore | mysql | + | datastore_version | 5.6 | + | encrypted_rpc_messaging | True | + | flavor | 15 | + | id | 6221b30c-8292-4378-b624-c7e9b0f8ba9e | + | name | myinst | + | region | RegionOne | + | server_id | None | + | status | BUILD | + | tenant_id | eac1e46e5f7840e39012aff46a92073a | + | updated | 2017-06-02T17:22:24 | + | volume | 1 | + | volume_id | None | + +-------------------------+--------------------------------------+ + +.. _show_and_list_modules: + +#. **Show and list modules** + + You can view the modules on your instance by doing the following: + + .. code-block:: console + + $ trove module-query myinst + + +-------+------+-----------+---------+--------+-----------+------------------------+------------------------+ + | Name | Type | Datastore | Version | Status | Message | Created | Updated | + +-------+------+-----------+---------+--------+-----------+------------------------+------------------------+ + | mymod | ping | all | all | OK | Module.V1 | 2017-06-02 17:23:40.50 | 2017-06-02 17:23:40.50 | + +-------+------+-----------+---------+--------+-----------+------------------------+------------------------+ + + You can count the instances each module is applied to by doing the + following: + + .. code-block:: console + + $ trove module-instance-count mymod + + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | True | 1 | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + + You can list the instances that have a particular module applied + by doing the following: + + .. code-block:: console + + $ trove module-instances mymod + + +--------------------------------------+--------+-----------+-------------------+--------+-----------+------+-----------+----------------------------------+ + | ID | Name | Datastore | Datastore Version | Status | Flavor ID | Size | Region | Tenant ID | + +--------------------------------------+--------+-----------+-------------------+--------+-----------+------+-----------+----------------------------------+ + | 6221b30c-8292-4378-b624-c7e9b0f8ba9e | myinst | mysql | 5.6 | ACTIVE | 15 | 1 | RegionOne | eac1e46e5f7840e39012aff46a92073a | + +--------------------------------------+--------+-----------+-------------------+--------+-----------+------+-----------+----------------------------------+ + + +Updating and creating a second module for a redis cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To update a module you should have another file ready to update the +module with: + +.. code-block:: console + + $ echo "message=Module.V2" > ping2.dat + $ trove module-update mymod --file ping2.dat + + +----------------------+--------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------+ + | apply_order | 5 | + | auto_apply | False | + | created | 2017-06-02T17:06:21 | + | datastore | all | + | datastore_id | None | + | datastore_version | all | + | datastore_version_id | None | + | description | None | + | id | 0065a8ed-0668-4db5-a4ad-d88d0a166388 | + | is_admin | True | + | live_update | True | + | md5 | ba7c204979c8de54be6efb70a17d40b9 | + | name | mymod | + | priority_apply | False | + | tenant | eac1e46e5f7840e39012aff46a92073a | + | tenant_id | eac1e46e5f7840e39012aff46a92073a | + | type | ping | + | updated | 2017-06-02T17:56:12 | + | visible | True | + +----------------------+--------------------------------------+ + +Now to show the usage with a redis cluster, create as follows: + +.. code-block:: console + + $ trove cluster-create myclust redis 3.2.6 \ + --instance=flavor=15,volume=1,module=mymod \ + --instance=flavor=15,volume=1,module=mymod \ + --instance=flavor=15,volume=1,module=mymod + + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | created | 2017-06-02T18:00:17 | + | datastore | redis | + | datastore_version | 3.2.6 | + | id | e4d91ca6-5980-430c-94d0-bf7abc63f712 | + | instance_count | 3 | + | name | myclust | + | task_description | Building the initial cluster. | + | task_name | BUILDING | + | updated | 2017-06-02T18:00:17 | + +-------------------+--------------------------------------+ + +The original :command: ``count`` command will show the first instance, +unless the ``--include_clustered`` option is used. You can see the +MD5 from each applied module, and you know that the single instance +one is not current. + +.. code-block:: console + + $ trove module-instance-count mymod + + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + + $ trove module-instance-count mymod --include_clustered + + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 | + | mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | True | 3 | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + +Update the module again. By doing this, it will cause the instances +to report their module is not current. + +.. code-block:: console + + $ echo "message=Module.V3" > ping3.dat + $ trove module-update mymod --file ping3.dat + + +----------------------+--------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------+ + | apply_order | 5 | + | auto_apply | False | + | created | 2017-06-02T17:06:21 | + | datastore | all | + | datastore_id | None | + | datastore_version | all | + | datastore_version_id | None | + | description | None | + | id | 0065a8ed-0668-4db5-a4ad-d88d0a166388 | + | is_admin | True | + | live_update | True | + | md5 | 869744bdd18e306a96c145df562065ab | + | name | mymod | + | priority_apply | False | + | tenant | eac1e46e5f7840e39012aff46a92073a | + | tenant_id | eac1e46e5f7840e39012aff46a92073a | + | type | ping | + | updated | 2017-06-02T18:06:53 | + | visible | True | + +----------------------+--------------------------------------+ + + $ trove module-instance-count mymod --include_clustered + + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 | + | mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | False | 3 | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + +To update an instance in a cluster you can use the +:command:`trove module-apply` command: + +.. code-block:: console + + $ trove cluster-instances myclust + + +--------------------------------------+------------------+-----------+------+--------+ + | ID | Name | Flavor ID | Size | Status | + +--------------------------------------+------------------+-----------+------+--------+ + | 393462d5-906d-4214-af0d-538b7f618b2d | myclust-member-2 | 15 | 1 | ACTIVE | + | a3fc5326-e1b6-456a-a8b1-08ad6bbb2278 | myclust-member-3 | 15 | 1 | ACTIVE | + | cba31d4b-d038-42c2-ab03-56c6c176b49d | myclust-member-1 | 15 | 1 | ACTIVE | + +--------------------------------------+------------------+-----------+------+--------+ + + $ trove module-apply 393462d5-906d-4214-af0d-538b7f618b2d mymod + + +-------+------+-----------+---------+--------+-----------+ + | Name | Type | Datastore | Version | Status | Message | + +-------+------+-----------+---------+--------+-----------+ + | mymod | ping | all | all | OK | Module.V3 | + +-------+------+-----------+---------+--------+-----------+ + + $ trove module-instance-count mymod --include_clustered + + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 | + | mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | False | 2 | + | mymod | 2017-06-02T18:18:37 | 2017-06-02T18:18:37 | 869744bdd18e306a96c145df562065ab | True | 1 | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + +For variety in this example, create one more instance and module: + +.. code-block:: console + + $ trove create myinst_2 15 --size 1 --module mymod + + +-------------------------+--------------------------------------+ + | Property | Value | + +-------------------------+--------------------------------------+ + | created | 2017-06-02T18:21:56 | + | datastore | redis | + | datastore_version | 3.2.6 | + | encrypted_rpc_messaging | True | + | flavor | 15 | + | id | cdd85d94-13a0-4d90-89eb-9c05523d2ac6 | + | name | myinst_2 | + | region | RegionOne | + | server_id | None | + | status | BUILD | + | tenant_id | eac1e46e5f7840e39012aff46a92073a | + | updated | 2017-06-02T18:21:56 | + | volume | 1 | + | volume_id | None | + +-------------------------+--------------------------------------+ + + $ echo "message=Module.V4" > ping4.dat + $ trove module-update mymod --file ping4.dat + + +----------------------+--------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------+ + | apply_order | 5 | + | auto_apply | False | + | created | 2017-06-02T17:06:21 | + | datastore | all | + | datastore_id | None | + | datastore_version | all | + | datastore_version_id | None | + | description | None | + | id | 0065a8ed-0668-4db5-a4ad-d88d0a166388 | + | is_admin | True | + | live_update | True | + | md5 | 6e2c81c1547d640b4c6e7752ed0e33ab | + | name | mymod | + | priority_apply | False | + | tenant | eac1e46e5f7840e39012aff46a92073a | + | tenant_id | eac1e46e5f7840e39012aff46a92073a | + | type | ping | + | updated | 2017-06-02T18:26:22 | + | visible | True | + +----------------------+--------------------------------------+ + +Now we have 2 single instances, and 3 cluster instances on various +versions of the module, none current. + +.. code-block:: console + + $ trove list + + +--------------------------------------+----------+-----------+-------------------+--------+-----------+------+-----------+ + | ID | Name | Datastore | Datastore Version | Status | Flavor ID | Size | Region | + +--------------------------------------+----------+-----------+-------------------+--------+-----------+------+-----------+ + | 6221b30c-8292-4378-b624-c7e9b0f8ba9e | myinst | mysql | 5.6 | ACTIVE | 15 | 1 | RegionOne | + | cdd85d94-13a0-4d90-89eb-9c05523d2ac6 | myinst_2 | redis | 3.2.6 | ACTIVE | 15 | 1 | RegionOne | + +--------------------------------------+----------+-----------+-------------------+--------+-----------+------+-----------+ + + $ trove module-instance-count mymod --include_clustered + + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 | + | mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | False | 2 | + | mymod | 2017-06-02T18:18:37 | 2017-06-02T18:21:57 | 869744bdd18e306a96c145df562065ab | False | 2 | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + +When the latest module was created, the ``--include_clustered`` was +not used. Use the :command:`trove module-reapply` command: + +.. code-block:: console + + $ trove module-reapply mymod --md5=869744bdd18e306a96c145df562065ab --include_clustered + $ trove module-instance-count mymod --include_clustered + + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 | + | mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | False | 2 | + | mymod | 2017-06-02T18:38:48 | 2017-06-02T18:38:48 | 6e2c81c1547d640b4c6e7752ed0e33ab | True | 2 | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + +Now they are both updated. If the ``--force`` flag is used, it can +reapply to already applied instances. Notice that the only thing that +changes is the minimum and maximum updated date fields. + +.. code-block:: console + + $ trove module-reapply mymod --md5=6e2c81c1547d640b4c6e7752ed0e33ab --include_clustered --force + $ trove module-instance-count mymod --include_clustered + + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | mymod | 2017-06-02T17:22:25 | 2017-06-02T17:22:25 | 7f700cc7b99606615f8b51946f6d3228 | False | 1 | + | mymod | 2017-06-02T18:00:18 | 2017-06-02T18:00:18 | ba7c204979c8de54be6efb70a17d40b9 | False | 2 | + | mymod | 2017-06-02T18:40:45 | 2017-06-02T18:40:46 | 6e2c81c1547d640b4c6e7752ed0e33ab | True | 2 | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + +To bring every instance to the current version, use some of the +optional arguments to control how many instances are updated at the +same time. This is useful to avoid potential network issues, if the +module payload is large. Since we are not using the ``--force`` flag, +the minimum updated date will not change. + +.. code-block:: console + + $ trove module-reapply mymod --include_clustered --batch_size=1 --delay=3 + $ trove module-instance-count mymod --include_clustered + + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | Module Name | Min Updated Date | Max Updated Date | Module MD5 | Current | Count | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + | mymod | 2017-06-02T18:40:45 | 2017-06-02T18:44:10 | 6e2c81c1547d640b4c6e7752ed0e33ab | True | 5 | + +-------------+---------------------+---------------------+----------------------------------+---------+-------+ + diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 344bfc4555..1b990cca96 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -5,6 +5,8 @@ .. toctree:: :maxdepth: 2 - building_guest_images.rst - guest_cloud_init.rst - secure_oslo_messaging.rst + basics + building_guest_images + database_module_usage + guest_cloud_init + secure_oslo_messaging