From d57354942eff0faff3c40d1b8dcda7a465ff1d75 Mon Sep 17 00:00:00 2001 From: Lingxian Kong Date: Mon, 13 Jan 2020 18:37:23 +1300 Subject: Add running trove in production guide Change-Id: I18654091cc39a0a5de17ff9822f14d6c41facf42 --- doc/source/admin/basics.rst | 492 --------------------------- doc/source/admin/datastore.rst | 492 +++++++++++++++++++++++++++ doc/source/admin/index.rst | 5 +- doc/source/admin/run_trove_in_production.rst | 323 ++++++++++++++++++ 4 files changed, 818 insertions(+), 494 deletions(-) delete mode 100644 doc/source/admin/basics.rst create mode 100644 doc/source/admin/datastore.rst create mode 100644 doc/source/admin/run_trove_in_production.rst diff --git a/doc/source/admin/basics.rst b/doc/source/admin/basics.rst deleted file mode 100644 index 70f57f50..00000000 --- a/doc/source/admin/basics.rst +++ /dev/null @@ -1,492 +0,0 @@ -.. _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 - 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/datastore.rst b/doc/source/admin/datastore.rst new file mode 100644 index 00000000..f026d562 --- /dev/null +++ b/doc/source/admin/datastore.rst @@ -0,0 +1,492 @@ +.. _database: + +========= +Datastore +========= + +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 + 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/index.rst b/doc/source/admin/index.rst index bbab75c5..b03c0d25 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -5,7 +5,8 @@ .. toctree:: :maxdepth: 2 - basics + run_trove_in_production + datastore building_guest_images - database_module_usage secure_oslo_messaging + database_module_usage diff --git a/doc/source/admin/run_trove_in_production.rst b/doc/source/admin/run_trove_in_production.rst new file mode 100644 index 00000000..58f1667f --- /dev/null +++ b/doc/source/admin/run_trove_in_production.rst @@ -0,0 +1,323 @@ +.. + Copyright (c) 2020 Catalyst Cloud + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +=========================== +Running Trove in production +=========================== + +This document is not a definitive guide for deploying Trove in every production +environment. There are many ways to deploy Trove depending on the specifics and +limitations of your situation. We hope this document provides the cloud +operator or distribution creator with a basic understanding of how the Trove +components fit together practically. Through this, it should become more +obvious how components of Trove can be divided or duplicated across physical +hardware in a production cloud environment to aid in achieving scalability and +resiliency for the database as a service software. + +In the interest of keeping this guide somewhat high-level and avoiding +obsolescence or operator/distribution-specific environment assumptions by +specifying exact commands that should be run to accomplish the tasks below, we +will instead just describe what needs to be done and leave it to the cloud +operator or distribution creator to "do the right thing" to accomplish the task +for their environment. If you need guidance on specific commands to run to +accomplish the tasks described below, we recommend reading through the +``plugin.sh`` script in devstack subdirectory of this project. The devstack +plugin exercises all the essential components of Trove in the right order, and +this guide will mostly be an elaboration of this process. + + +Environment Assumptions +----------------------- +The scope of this guide is to provide a basic overview of setting up all +the components of Trove in a production environment, assuming that the +default in-tree drivers and components are going to be used. + +For the purposes of this guide, we will therefore assume the following core +components have already been set up for your production OpenStack environment: + +* RabbitMQ +* MySQL +* Keystone +* Nova +* Cinder +* Neutron +* Glance +* Swift + + +Production Deployment Walkthrough +--------------------------------- + + +Create Trove Service User +~~~~~~~~~~~~~~~~~~~~~~~~~ +By default Trove will use the 'trove' user with 'admin' role in 'service' +tenant for both keystone authentication and interactions with all other +services. + + +Service Tenant Deployment +~~~~~~~~~~~~~~~~~~~~~~~~~ +In production, almost all the cloud resources(except the Swift objects for +backup data) created for a Trove instance should be only visible to the Trove +service user. As DBaaS users, they should only see a Trove instance after +creating, and know nothing about the Nova VM, Cinder volume, Neutron management +network and security groups under the hood. The only way to operate Trove +instance is to interact with `Trove API +`_. + +Service tenant deployment is the default configuration in Trove since Ussuri +release. + + +Install Trove Controller Software +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Trove controller services should be put somewhere that has access to the +database, the oslo messaging system, and other OpenStack services. Trove uses +the standard python setuptools, so installation of the software itself should +be straightforward. + +Running multiple instances of the individual Trove controller components on +separate physical hosts is recommended in order to provide scalability and +availability of the controller software. + + +Management Network +~~~~~~~~~~~~~~~~~~ +Trove makes use of a "Management Network" exclusively that the controller uses +to talk to guest agent running inside Trove instance and vice versa. All the +instances that Trove deploys will have interfaces on this network. Therefore, +it's important that the subnet deployed on this network be sufficiently large +to allow for the maximum number of instances and controllers likely to be +deployed throughout the lifespan of the cloud installation. + +Usually, after a Trove instance is created, there are 2 nics attached to the +instance VM, one for the database traffic on user-defined network, one for +management purpose. Trove will check if the user's subnet conflicts with the +management network. + +You can also create a management Neutron security group that will be applied to +the management port. Basically, nothing needs to be allowed to access the +management port, most of the network communication within the Trove instance is +egress traffic(e.g. the guest agent initiates connection with RabbitMQ). +However, It can be helpful to allow SSH access to the Trove instance from the +controller for troubleshooting purposes (ie. TCP port 22), though this is not +strictly necessary in production environments. + +In order to SSH into the Trove instance(as mentioned above, it's helpful but +not necessary), the cloud administrators need to create and config a Nova +keypair. + +Finally, you need to add routing or interfaces to this network so that the +Trove guest agent running inside the instance is able to connect with RabbitMQ. + + +RabbitMQ Considerations +~~~~~~~~~~~~~~~~~~~~~~~ +Both trove-taskmanager and trove-conductor talk to guest agent inside Trove +instance via the messaging system, ie. RabbitMQ. Once the guest agent is up and +running, it's listening on a message queue named ``guestagent.`` +specifically set up for that particular instance, receiving requests from +trove-taskmanager for operations like set up the database software, create +databases and users, restart database service etc. At the mean while, +trove-guestagent periodically sends status update information to +trove-conductor through the messaging system. + +With all that said, a proper RabbitMQ user name and password need to be +configured in the trove-guestagent config file, which may bring security +concern for the cloud deployers. If the guest instance is compromised, then +guest credentials are compromised, which means the messaging system is +compromised. + +As part of the solution, Trove introduced a `security enhancement +`_ in +Ocata release, using encryption keys to protect the messages between the +control plane and the guest instances, which guarantees that one compromised +guest instance doesn't affect other instances nor other cloud users. + + +Configuring Trove +~~~~~~~~~~~~~~~~~ +The default Trove configuration file location is ``/etc/trove/trove.conf``. The +typical config options (not a full list) are: + +DEFAULT group + enable_secure_rpc_messaging + Should RPC messaging traffic be secured by encryption. + + taskmanager_rpc_encr_key + The key (OpenSSL aes_cbc) used to encrypt RPC messages sent to + trove-taskmanager, used by trove-api. + + instance_rpc_encr_key + The key (OpenSSL aes_cbc) used to encrypt RPC messages sent to guest + instance from trove-taskmanager and the messages sent from guest instance + to trove-conductor. This key is generated by trove-taskmanager + automatically and is injected into the guest instance when creating. + + inst_rpc_key_encr_key + The database encryption key to encrypt per-instance PRC encryption key + before storing to Trove database. + + management_networks + The management network, currently only one management network is allowed. + + management_security_groups + List of the management security groups that are applied to the management + port of the database instance. + + cinder_volume_type + Cinder volume type used to create volume that is attached to Trove + instance. + + nova_keypair + Name of a Nova keypair to inject into a database instance to enable SSH + access. + + default_datastore + The default datastore id or name to use if one is not provided by the user. + If the default value is None, the field becomes required in the instance + create request. + + max_accepted_volume_size + The default maximum volume size (in GB) for an instance. + + max_instances_per_tenant + Default maximum number of instances per tenant. + + max_backups_per_tenant + Default maximum number of backups per tenant. + + transport_url + The messaging server connection URL, e.g. + ``rabbit://stackrabbit:password@10.0.119.251:5672/`` + + control_exchange + The Trove exchange name for the messaging service, could be overridden by + an exchange name specified in the transport_url option. + + reboot_time_out + Maximum time (in seconds) to wait for a server reboot. + + usage_timeout + Maximum time (in seconds) to wait for Trove instance to become ACTIVE for + creation. + + restore_usage_timeout + Maximum time (in seconds) to wait for Trove instance to become ACTIVE for + restore. + + agent_call_high_timeout + Maximum time (in seconds) to wait for Guest Agent 'slow' requests (such as + restarting the instance server) to complete. + +keystone_authtoken group + Like most of other OpenStack services, Trove uses `Keystone Authentication + Middleware + `_ + for authentication and authorization. + +service_credentials group + Options in this section are pretty much like the options in + ``keystone_authtoken``, but you can config another service user for Trove to + communicate with other OpenStack services like Nova, Neutron, Cinder, etc. + + * auth_url + * region_name + * project_name + * username + * password + * project_domain_name + * user_domain_name + +database group + connection + The SQLAlchemy connection string to use to connect to the database, e.g. + ``mysql+pymysql://root:password@127.0.0.1/trove?charset=utf8`` + +The cloud administrator also needs to provide a policy file +``/etc/trove/policy.json`` if the default API access policies don't satisfy the +requirement. To generate a sample policy file with all the default policies, +run ``tox -egenpolicy`` in the repo folder and the new file will be located in +``etc/trove/policy.yaml.sample``. + + +Initialize Trove Database +~~~~~~~~~~~~~~~~~~~~~~~~~ +This is controlled through `sqlalchemy-migrate +`_ scripts under the +trove/db/sqlalchemy/migrate_repo/versions directory in this repository. The +script ``trove-manage`` (which should be installed together with Trove +controller software) could be used to aid in the initialization of the Trove +database. Note that this tool looks at the ``/etc/trove/trove.conf`` file for +its database credentials, so initializing the database must happen after Trove +is configured. + + +Launching the Trove Controller +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +We recommend using upstart / systemd scripts to ensure the components of the +Trove controller are all started and kept running. + + +Preparing the Guest Images +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Now that the Trove system is installed, the next step is to build the images +that we will use for the DBaaS to function properly. This is possibly the most +important step as this will be the gold standard that Trove will use for a +particular data store. + +.. note:: + + For the sake of simplicity and especially for testing, we can use the + prebuilt images that are available from OpenStack itself. These images + should strictly be used for testing and development use and should not be + used in a production environment. The images are available for download and + are located at http://tarballs.openstack.org/trove/images/. + +For use with production systems, it is recommended to create and maintain your +own images in order to conform to standards set by the company's security team. +In Trove community, we use `Disk Image Builder(DIB) +`_ to create Trove +images, all the elements are located in ``integration/scripts/files/elements`` +folder in the repo. + +Trove provides a script named ``trovestack`` to help build the image, refer to +`Build images using trovestack +`_ +for more information. Make sure to use ``dev_mode=false`` for production +environment. + +After image is created successfully, the cloud administrator needs to upload +the image to Glance and make it only accessible to service users. + + +Preparing the Datastore +~~~~~~~~~~~~~~~~~~~~~~~ +After image is uploaded, the cloud administrator should create datastores, +datastore versions and the configuration parameters for the particular version. + +It's recommended to config a default version for each datastore. + + +Trove Deployment Verfication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If all of the above instructions have been followed, it should now be possible +to deploy Trove instances using the OpenStack CLI, communicating with the Trove +V1 API. + +Refer to `Create and access a database +`_ for detailed +steps. -- cgit v1.2.1