From 1d24b65052bbfb8f7dff5744c7bb44a58a2336c6 Mon Sep 17 00:00:00 2001 From: Lingxian Kong Date: Wed, 7 Oct 2020 18:50:53 +1300 Subject: Image tags support in datastore version Change-Id: I0e51d08515c121e3a7b0e82b6e4c4161bb4fbc4a --- doc/source/admin/building_guest_images.rst | 18 +-- doc/source/admin/datastore.rst | 212 +++++---------------------- doc/source/admin/run_trove_in_production.rst | 19 +-- doc/source/admin/upgrade.rst | 2 +- doc/source/cli/trove-manage.rst | 9 +- doc/source/install/verify.rst | 10 +- 6 files changed, 70 insertions(+), 200 deletions(-) (limited to 'doc') diff --git a/doc/source/admin/building_guest_images.rst b/doc/source/admin/building_guest_images.rst index 6f6dd2fa..df5f49ee 100644 --- a/doc/source/admin/building_guest_images.rst +++ b/doc/source/admin/building_guest_images.rst @@ -3,15 +3,9 @@ .. role:: bash(code) :language: bash -========================================= -Building Guest Images for OpenStack Trove -========================================= - -.. If section numbers are desired, unindent this - .. sectnum:: - -.. If a TOC is desired, unindent this - .. contents:: +==================== +Building guest image +==================== Overview ======== @@ -199,14 +193,16 @@ image in Glance and register a new datastore or version in Trove using --private \ --disk-format qcow2 \ --container-format bare \ + --tag trove --tag mysql \ --file ~/images/trove-guest-ubuntu-bionic-dev.qcow2 - $ trove-manage datastore_version_update mysql 5.7.29 mysql $image_id "" 1 + $ openstack datastore version create 5.7.29 mysql mysql "" \ + --image-tags trove,mysql \ + --active --default $ trove-manage db_load_datastore_config_parameters mysql 5.7.29 ${trove_repo_dir}/trove/templates/mysql/validation-rules.json .. note:: The command ``trove-manage`` needs to run on Trove controller node. - Otherwise, you can use ``openstack datastore version create`` CLI. If you see anything error or need help for the image creation, please ask help either in ``#openstack-trove`` IRC channel or sending emails to diff --git a/doc/source/admin/datastore.rst b/doc/source/admin/datastore.rst index 9ca9e40a..d98fdef4 100644 --- a/doc/source/admin/datastore.rst +++ b/doc/source/admin/datastore.rst @@ -4,44 +4,44 @@ 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. +A datastore is typically created as a type of database. For each datastore, +there could be multiple datastore versions. For example, for MySQL database, +Trove could support 5.7.29, 5.7.30 or 5.8. + +Admin user needs to create datastore and its versions as required. -The Database service provides resource isolation at high performance -levels, and automates complex administrative tasks such as deployment, -configuration, patching, backups, restores, and monitoring. +A datastore version is always associated with a Glance image, either by image +ID or image tags. If the image ID is not provided, the image can be retrieved +by the image tags. The tags are used for filtering as a whole rather than +separately. Using image tags is more flexible than ID especially when a new +guest image is uploaded to Glance, Trove can pick up the latest image +automatically for creating instances. -Create datastore -~~~~~~~~~~~~~~~~ +Create datastore version +~~~~~~~~~~~~~~~~~~~~~~~~ -An administrative user can create datastores for a variety of databases. +When creating a datastore version, Trove will create the datastore first if it +doesn't exist. -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. +When using image tags, make sure the image with the tags exists before creating +the datastore version. .. note:: From Victoria release, all the datastores can be configured with a same - Glance image but with different datastore name and version number. + Glance image but with different datastore name and version name. -**To create a data store** +To create a datastore version: -#. **Create a trove image** +#. Create a trove guest image Refer to `Build images using trovestack `_ -#. **Register image with Image service** +#. Register image with Image service You need to register your guest image with the Image service as cloud admin. @@ -53,133 +53,17 @@ data store version. --disk-format qcow2 --container-format bare \ --file $image_file \ --property hw_rng_model='virtio' \ - --tag trove - -#. **Create the datastore** - - Create the data store that configured with 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** + --tag trove --tag mysql - 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: +#. Create the datastore version .. code-block:: console - $ trove-manage --config-file=/etc/trove/trove.conf datastore_version_update mysql mysql-5.5 mysql GLANCE_ID "" 1 + openstack datastore version create 5.7.29 mysql mysql "" \ + --image-tags trove,mysql \ + --active --default - **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** +#. Load validation rules for configuration groups **Background.** You can manage database configuration tasks by using configuration groups. Configuration groups let you set configuration @@ -200,21 +84,20 @@ data store version. * - Ubuntu 18.04 - :file:`/usr/lib/python3/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``. + - DATASTORE_NAME is the name of the datastore, e.g. ``mysql`` + or ``postgresql``. * - RHEL 7, CentOS 7, Fedora 20, and Fedora 21 - :file:`/usr/lib/python3/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``. + - DATASTORE_NAME is the name of the datastore, e.g. ``mysql`` + or ``postgresql``. | 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: + :command:`db_load_datastore_config_parameters` command on trove controller + node. This command takes the following arguments: * Data store name * Data store version @@ -227,30 +110,15 @@ data store version. .. code-block:: console - $ trove-manage db_load_datastore_config_parameters mysql mysql-5.5 /usr/lib/python3/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-manage db_load_datastore_config_parameters mysql 5.7.29 /usr/lib/python3/dist-packages/trove/templates/mysql/validation-rules.json - $ openstack datastore list - +--------------------------------------+--------------+ - | id | name | - +--------------------------------------+--------------+ - | 10000000-0000-0000-0000-000000000001 | Legacy MySQL | - | e5dc1da3-f080-4589-a4c2-eff7928f969a | mysql | - +--------------------------------------+--------------+ +Hide a datastore version +~~~~~~~~~~~~~~~~~~~~~~~~ - Show the versions of a specific datastore: +Sometimes, it's needed to make a datastore version invisible to the cloud +users, e.g when a datastore version is deprecated or creating a datastore +version for testing purpose, to do that: .. code-block:: console - $ openstack datastore version list mysql - +--------------------------------------+-----------+ - | id | name | - +--------------------------------------+-----------+ - | 36a6306b-efd8-4d83-9b75-8b30dd756381 | mysql-5.5 | - +--------------------------------------+-----------+ + $ openstack datastore version --disable diff --git a/doc/source/admin/run_trove_in_production.rst b/doc/source/admin/run_trove_in_production.rst index 53d5cfab..7f0120a7 100644 --- a/doc/source/admin/run_trove_in_production.rst +++ b/doc/source/admin/run_trove_in_production.rst @@ -313,7 +313,8 @@ 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. +the image to Glance and make it only accessible to service users. It's +recommended to use tags when creating Glance image. Preparing the Datastore @@ -323,18 +324,18 @@ datastore versions and the configuration parameters for the particular version. It's recommended to config a default version for each datastore. +``trove-manage`` can be only used on trove controller node. + Command examples: .. code-block:: console - # Create a new datastore 'mysql' - trove-manage datastore_update mysql "" - # Create a new datastore version 5.7.29 for 'mysql' - trove-manage datastore_version_update mysql 5.7.29 mysql $imageid "" 1 - # Use 5.7.29 as the default datastore version for 'mysql' - trove-manage datastore_update mysql 5.7.29 - # Register configuration parameters for 5.7.29 version of datastore 'mysql' - trove-manage db_load_datastore_config_parameters mysql 5.7.29 ${trove_repo_dir}}/trove/templates/mysql/validation-rules.json + $ # Creating datastore 'mysql' and datastore version 5.7.29. + $ openstack datastore version create 5.7.29 mysql mysql "" \ + --image-tags trove,mysql \ + --active --default + $ # Register configuration parameters for the datastore version + $ trove-manage db_load_datastore_config_parameters mysql 5.7.29 ${trove_repo_dir}}/trove/templates/mysql/validation-rules.json Quota Management diff --git a/doc/source/admin/upgrade.rst b/doc/source/admin/upgrade.rst index 24d553f0..a9883c28 100644 --- a/doc/source/admin/upgrade.rst +++ b/doc/source/admin/upgrade.rst @@ -157,7 +157,7 @@ Upgrade Trove services --property hw_rng_model='virtio' \ --tag trove \ -c id -f value) - $ trove-manage datastore_version_update mysql 5.7.29 mysql $imageid "" 1 + $ trove-manage datastore_version_update mysql 5.7.29 mysql $imageid "" "" 1 $ trove-manage db_load_datastore_config_parameters mysql 5.7.29 $stackdir/trove/trove/templates/mysql/validation-rules.json Upgrade Trove guest agent diff --git a/doc/source/cli/trove-manage.rst b/doc/source/cli/trove-manage.rst index c9f50284..568c56fb 100644 --- a/doc/source/cli/trove-manage.rst +++ b/doc/source/cli/trove-manage.rst @@ -200,7 +200,7 @@ trove-manage datastore_version_update usage: trove-manage datastore_version_update [-h] datastore version_name manager - image_id packages active + image_id image_tags packages active Add or update a datastore version. If the datastore version already exists, all values except the datastore name and version will be updated. @@ -219,6 +219,13 @@ all values except the datastore name and version will be updated. ``image_id`` ID of the image used to create an instance of the datastore version. +``image_tags`` + List of image tags separated by comma. If the image ID is not provided + explicitly, the image can be retrieved by the image tags. Multiple image tags + are separated by comma, e.g. trove,mysql. Using image tags is more flexible + than ID especially when new guest image is uploaded to Glance, Trove can pick + up the latest image automatically for creating instances. + ``packages`` Packages required by the datastore version that are installed on the guest image. diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst index ffeedff6..a607ee58 100644 --- a/doc/source/install/verify.rst +++ b/doc/source/install/verify.rst @@ -27,15 +27,13 @@ Verify operation of the Database service. Create an image for the type of database you want to use, for example, MySQL, MariaDB, etc. - * Create a datastore. You need to create a separate datastore for - each type of database you want to use, for example, MySQL, MongoDB, - Cassandra. This example shows you how to create a datastore for a - MySQL database: + * Create a datastore. You need to create at least one datastore version for + each type of database supported. This example creates a datastore version + for MySQL 5.7.29: .. code-block:: console - $ trove-manage datastore_update mysql "" - $ trove-manage datastore_version_update mysql 5.7 mysql $imageid "" 1 + $ openstack datastore version create 5.7.29 mysql mysql "" trove,mysql --active --default #. Create a database `instance `_. -- cgit v1.2.1