1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
.. _build_guest_images:
.. 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::
Overview
========
When Trove receives a command to create a database instance, it does so by
launching a Nova instance based on the appropriate guest image that is
stored in Glance. This document shows you the steps to build the guest images.
.. note::
For testing purpose, the Trove guest images of some specific databases are
periodically built and published in
http://tarballs.openstack.org/trove/images/ in Trove upstream CI.
Additionally, if you install Trove in devstack environment, a MySQL image
is created and registered in Glance automatically, unless it's disabled by
setting ``TROVE_ENABLE_IMAGE_BUILD=false`` in devstack local.conf file.
High Level Overview of a Trove Guest Instance
=============================================
At the most basic level, a Trove Guest Instance is a Nova instance
launched by Trove in response to a create command. For most of this
document, we will confine ourselves to single instance databases; in
other words, without the additional complexity of replication or
mirroring. Guest instances and Guest images for replicated and
mirrored database instances will be addressed specifically in later
sections of this document.
This section describes the various components of a Trove Guest
Instance.
-----------------------------
Operating System and Database
-----------------------------
A Trove Guest Instance contains at least a functioning Operating
System and the database software that the instance wishes to provide
(as a Service). For example, if your chosen operating system is Ubuntu
and you wish to deliver MySQL version 5.7, then your guest instance is
a Nova instance running the Ubuntu operating system and will have
MySQL version 5.7 installed on it.
-----------------
Trove Guest Agent
-----------------
Trove supports multiple databases, some of them are relational (RDBMS)
and some are non-relational (NoSQL). In order to provide a common
management interface to all of these, the Trove Guest Instance has on
it a 'Guest Agent'. The Trove Guest Agent is a component of the
Trove system that is specific to the database running on that Guest
Instance.
The purpose of the Trove Guest Agent is to implement the Trove Guest
Agent API for the specific database. This includes such things as the
implementation of the database 'start' and 'stop' commands. The Trove
Guest Agent API is the common API used by Trove to communicate with
any guest database, and the Guest Agent is the implementation of that
API for the specific database.
The Trove Guest Agent runs inside the Trove Guest Instance.
------------------------------------------
Injected Configuration for the Guest Agent
------------------------------------------
When TaskManager launches the guest VM it injects config files into the
VM, including:
* ``/etc/trove/conf.d/guest_info.conf``: Contains some information about
the guest, e.g. the guest identifier, the tenant ID, etc.
* ``/etc/trove/conf.d/trove-guestagent.conf``: The config file for the
guest agent service.
------------------------------
Persistent Storage, Networking
------------------------------
The database stores data on persistent storage on Cinder (if
``CONF.volume_support=True``) or ephemeral storage on the Nova instance. The
database service is accessible over the tenant network provided when creating
the database instance.
The cloud administrator is able to config management
networks(``CONF.management_networks``) that is invisible to the cloud tenants,
but used for communication between database instance and the control plane
services(e.g. the message queue).
Building Guest Images
=====================
-----------------------------
Build images using trovestack
-----------------------------
``trovestack`` is the recommended tooling provided by Trove community to build
the guest images. Before running ``trovestack`` command, go to the scripts
folder:
.. code-block:: console
git clone https://opendev.org/openstack/trove
cd trove/integration/scripts
The trove guest agent image could be created by running the following command:
.. code-block:: console
$ ./trovestack build-image \
${datastore_type} \
${guest_os} \
${guest_os_release} \
${dev_mode} \
${guest_username} \
${imagepath}
* Currently, only ``guest_os=ubuntu`` and ``guest_os_release=xenial`` are fully
tested and supported.
* Default input values:
.. code-block:: ini
datastore_type=mysql
guest_os=ubuntu
guest_os_release=xenial
dev_mode=true
guest_username=ubuntu
imagepath=$HOME/images/trove-${guest_os}-${guest_os_release}-${datastore_type}.qcow2
* ``dev_mode=true`` is mainly for testing purpose for trove developers and it's
necessary to build the image on the trove controller host, because the host
and the guest VM need to ssh into each other without password. In this mode,
when the trove guest agent code is changed, the image doesn't need to be
rebuilt which is convenient for debugging. Trove guest agent will ssh into
the controller node and download trove code during the service initialization.
* if ``dev_mode=false``, the trove code for guest agent is injected into the
image at the building time. Now ``dev_mode=false`` is still in experimental
and not considered production ready yet.
* Some other global variables:
* ``HOST_SCP_USERNAME``: Only used in dev mode, this is the user name used by
guest agent to connect to the controller host, e.g. in devstack
environment, it should be the ``stack`` user.
* ``GUEST_WORKING_DIR``: The place to save the guest image, default value is
``$HOME/images``.
* ``TROVE_BRANCH``: Only used in dev mode. The branch name of Trove code
repository, by default it's master, use other branches as needed such as
stable/train.
* The image type can be easily changed by specifying a different image file
extension, e.g. to build a raw image, you can specify
``$your-image-name.raw`` as the ``imagepath`` parameter.
For example, in order to build a MySQL image for Ubuntu Xenial operating
system in development mode:
.. code-block:: console
$ ./trovestack build-image mysql ubuntu xenial true
Once the image build is finished, the cloud administrator needs to register the
image in Glance and register a new datastore or version in Trove using
``trove-manage`` command, e.g. after building an image for MySQL 5.7.1:
.. code-block:: console
$ openstack image create ubuntu-mysql-5.7.1-dev \
--public \
--disk-format qcow2 \
--container-format bare \
--file ~/images/ubuntu-xenial-mysql.qcow2
$ trove-manage datastore_version_update mysql 5.7.1 mysql $image_id "" 1
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
openstack-discuss@lists.openstack.org mailing list.
|
