Image tags support in datastore version

Change-Id: I0e51d08515c121e3a7b0e82b6e4c4161bb4fbc4a

6 files changed, 70 insertions, 200 deletions

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
    <https://docs.openstack.org/trove/latest/admin/building_guest_images.html#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 <version-id> --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
    <http://docs.openstack.org/user-guide/create_db.html>`_.