Improve image building doc
Change-Id: Icf86fd2a7d2692707449cfb11edbd936b0b79aa6
This commit is contained in:
Lingxian Kong
parent
d244c9d666
commit
619967e093
@ -16,23 +16,15 @@ Building Guest Images for OpenStack Trove
|
|||||||
Overview
|
Overview
|
||||||
========
|
========
|
||||||
|
|
||||||
When Trove receives a command to create a guest instance, it does so
|
When Trove receives a command to create a database instance, it does so by
|
||||||
by launching a Nova instance based on the appropriate guest image that
|
launching a Nova instance based on the appropriate guest image that is
|
||||||
is stored in Glance.
|
stored in Glance. This document shows you the steps to build the guest images.
|
||||||
|
|
||||||
To operate Trove it is vital to have a properly constructed guest
|
.. note::
|
||||||
image, and while tools are provided that help you build them,
|
|
||||||
the Trove project itself does not distribute guest images. This
|
|
||||||
document shows you how to build guest images for use with Trove.
|
|
||||||
|
|
||||||
It is assumed that you have a working OpenStack deployment with the
|
For testing purpose, the Trove guest images of some specific databases are
|
||||||
key services like Keystone, Glance, Swift, Cinder, Nova and networking
|
periodically built and published in
|
||||||
through either Nova Networks or Neutron where you will deploy the
|
http://tarballs.openstack.org/trove/images/ in Trove upstream CI.
|
||||||
guest images. It is also assumed that you have Trove functioning and
|
|
||||||
all the Trove services operating normally. If you don't have these
|
|
||||||
prerequisites, this document won't help you get them. Consult the
|
|
||||||
appropriate documentation for installing and configuring OpenStack for
|
|
||||||
that.
|
|
||||||
|
|
||||||
High Level Overview of a Trove Guest Instance
|
High Level Overview of a Trove Guest Instance
|
||||||
=============================================
|
=============================================
|
||||||
@ -83,168 +75,112 @@ The Trove Guest Agent runs inside the Trove Guest Instance.
|
|||||||
Injected Configuration for the Guest Agent
|
Injected Configuration for the Guest Agent
|
||||||
------------------------------------------
|
------------------------------------------
|
||||||
|
|
||||||
When TaskManager launches the guest VM it injects the specific settings
|
When TaskManager launches the guest VM it injects config files into the
|
||||||
for the guest into the VM, into the file /etc/trove/conf.d/guest_info.conf.
|
VM, including:
|
||||||
The file is injected one of three ways.
|
|
||||||
|
|
||||||
If ``use_nova_server_config_drive=True``, it is injected via ConfigDrive.
|
* ``/etc/trove/conf.d/guest_info.conf``: Contains some information about
|
||||||
Otherwise it is passed to the nova create call as the 'files' parameter and
|
the guest, e.g. the guest identifier, the tenant ID, etc.
|
||||||
will be injected based on the configuration of Nova; the Nova default is to
|
* ``/etc/trove/conf.d/trove-guestagent.conf``: The config file for the
|
||||||
discard the files. If the settings in guest_info.conf are not present on the
|
guest agent service.
|
||||||
guest Guest Agent will fail to start up.
|
|
||||||
|
|
||||||
------------------------------
|
------------------------------
|
||||||
Persistent Storage, Networking
|
Persistent Storage, Networking
|
||||||
------------------------------
|
------------------------------
|
||||||
|
|
||||||
The database stores data on persistent storage on Cinder (if
|
The database stores data on persistent storage on Cinder (if
|
||||||
configured, see trove.conf and the volume_support parameter) or
|
``CONF.volume_support=True``) or ephemeral storage on the Nova instance. The
|
||||||
ephemeral storage on the Nova instance. The database service is accessible
|
database service is accessible over the tenant network provided when creating
|
||||||
over the tenant network provided when creating the database instance.
|
the database instance.
|
||||||
|
|
||||||
The cloud administrator is able to config a management
|
The cloud administrator is able to config management
|
||||||
networks(``CONF.management_networks``) that is invisible to the cloud tenants,
|
networks(``CONF.management_networks``) that is invisible to the cloud tenants,
|
||||||
database instance can talk to the control plane services(e.g. the message
|
but used for communication between database instance and the control plane
|
||||||
queue) via that network.
|
services(e.g. the message queue).
|
||||||
|
|
||||||
Building Guest Images using DIB
|
Building Guest Images
|
||||||
===============================
|
=====================
|
||||||
|
|
||||||
A Trove Guest Image can be built with any tool that produces an image
|
|
||||||
accepted by Nova. In this document we describe how to build guest
|
|
||||||
images using the
|
|
||||||
`'Disk Image Builder' (DIB) <https://docs.openstack.org/diskimage-builder/latest/>`_
|
|
||||||
tool, and we focus on building qemu images.
|
|
||||||
|
|
||||||
DIB uses a chroot'ed environment to construct the image. The goal is
|
|
||||||
to build a bare machine that has all the components required for
|
|
||||||
launch by Nova.
|
|
||||||
|
|
||||||
----------------------------
|
|
||||||
Build image using trovestack
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
Trove provides a script called ``trovestack`` that could do most of the
|
|
||||||
management and test tasks. Refer to
|
|
||||||
`trovestack document <https://docs.openstack.org/trove/latest/admin/trovestack.html#build-guest-agent-image>`_
|
|
||||||
for the steps to build trove guest agent images.
|
|
||||||
|
|
||||||
-----------------------------
|
-----------------------------
|
||||||
Disk Image Builder 'Elements'
|
Build images using trovestack
|
||||||
-----------------------------
|
-----------------------------
|
||||||
|
|
||||||
DIB Elements are 'executed' by the disk-image-create command to
|
``trovestack`` is the recommended tooling provided by Trove community to build
|
||||||
produce the guest image. An element consists of a number of bash
|
the guest images. Before running ``trovestack`` command, go to the scripts
|
||||||
scripts that are executed by DIB in a specific order to generate the
|
folder:
|
||||||
image. You provide the names of the elements that you would like
|
|
||||||
executed, in order, on the command line to disk-image-create.
|
|
||||||
|
|
||||||
DIB comes with some
|
.. code-block:: console
|
||||||
`built-in elements <https://docs.openstack.org/diskimage-builder/latest/elements.html>`_.
|
|
||||||
In addition, projects like
|
|
||||||
`TripleO <https://github.com/openstack/tripleo-image-elements>`_ provide
|
|
||||||
elements as well.
|
|
||||||
|
|
||||||
Trove also provides a set of its own elements. In keeping with the philosophy
|
git clone https://opendev.org/openstack/trove
|
||||||
of making elements 'layered', Trove provides two sets of elements. The first
|
cd trove/integration/scripts
|
||||||
implements the guest agent for various operating systems and the second
|
|
||||||
implements the database for these operating systems.
|
|
||||||
|
|
||||||
-------------------------------------------------------------------
|
The trove guest agent image could be created by running the following command:
|
||||||
Contributing Reference Elements When Implementing a New 'Datastore'
|
|
||||||
-------------------------------------------------------------------
|
|
||||||
|
|
||||||
When contributing a new datastore, you should contribute elements
|
.. code-block:: console
|
||||||
that will allow any user of Trove to be able to build a guest image
|
|
||||||
for that datastore.
|
|
||||||
|
|
||||||
Considerations in Building a Guest Image
|
$ ./trovestack build-image \
|
||||||
========================================
|
${datastore_type} \
|
||||||
|
${guest_os} \
|
||||||
|
${guest_os_release} \
|
||||||
|
${dev_mode} \
|
||||||
|
${guest_username} \
|
||||||
|
${imagepath}
|
||||||
|
|
||||||
In building a guest image, there are several considerations that one
|
* Currently, only ``guest_os=ubuntu`` and ``guest_os_release=xenial`` are fully
|
||||||
must take into account. Some of the ones that we have encountered are
|
tested and supported.
|
||||||
described below.
|
|
||||||
|
|
||||||
---------------------------------------
|
* Default input values:
|
||||||
Speed of Launch and Start-up Activities
|
|
||||||
---------------------------------------
|
|
||||||
|
|
||||||
The actions performed on first boot can be very expensive and may
|
.. code-block:: ini
|
||||||
impact the time taken to launch a new guest instance. So, for example,
|
|
||||||
guest images that don't have the database software pre-installed and
|
|
||||||
instead download and install during launch could take longer to
|
|
||||||
launch.
|
|
||||||
|
|
||||||
In building a guest image, therefore care should be taken to ensure
|
datastore_type=mysql
|
||||||
that activities performed on first boot are traded off against the
|
guest_os=ubuntu
|
||||||
demands for start-time.
|
guest_os_release=xenial
|
||||||
|
dev_mode=true
|
||||||
|
guest_username=ubuntu
|
||||||
|
imagepath=$HOME/images/trove-${guest_os}-${guest_os_release}-${datastore_type}
|
||||||
|
|
||||||
---------------------------------------------------------
|
* ``dev_mode=true`` is mainly for testing purpose for trove developers and it's
|
||||||
Database licensing, and Database Software Download Issues
|
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.
|
||||||
|
|
||||||
Some database software downloads are licensed and manual steps are
|
* if ``dev_mode=false``, the trove code for guest agent is injected into the
|
||||||
required in order to obtain the installable software. In other
|
image at the building time. Now ``dev_mode=false`` is still in experimental
|
||||||
instances, no repositories may be setup to serve images of a
|
and not considered production ready yet.
|
||||||
particular database. In these cases, it is suggested that an extra
|
|
||||||
step be used to build the guest image.
|
|
||||||
|
|
||||||
User Manually Downloads Database Software
|
* Some other global variables:
|
||||||
-----------------------------------------
|
|
||||||
|
|
||||||
The user manually downloads the database software in a suitable format
|
* ``HOST_SCP_USERNAME``: Only used in dev mode, this is the user name used by
|
||||||
and places it in a specified location on the machine that will be used
|
guest agent to connect to the controller host, e.g. in devstack
|
||||||
to build the guest image.
|
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.
|
||||||
|
|
||||||
An environment variable 'DATASTORE_PKG_LOCATION' is set to point
|
For example, in order to build a MySQL image for Ubuntu Xenial operating
|
||||||
to this location. It can be a single file (for example new_db.deb)
|
system in development mode:
|
||||||
or a folder (for example new_db_files) depending on what the elements
|
|
||||||
expect. In the latter case, the folder would need to contain all the
|
|
||||||
files that the elements need in order to install the database software
|
|
||||||
(a folder would typically be used only if more than one file was
|
|
||||||
required).
|
|
||||||
|
|
||||||
Use an extra-data.d Folder
|
.. code-block:: console
|
||||||
--------------------------
|
|
||||||
|
|
||||||
Use an extra-data.d folder for the element and copy the file
|
$ ./trovestack build-image mysql ubuntu xenial true
|
||||||
into the image
|
|
||||||
|
|
||||||
Steps in extra-data.d are run first, and outside the DIB chroot'ed
|
Once the image build is finished, the cloud administrator needs to register the
|
||||||
environment. The step here can copy the installable from
|
image in Glance and register a new datastore or version in Trove using
|
||||||
DATASTORE_PKG_LOCATION into the image
|
``trove-manage`` command, e.g. after building an image for MySQL 5.7.1:
|
||||||
(typically into TMP_HOOKS_PATH).
|
|
||||||
|
|
||||||
For example, if DATASTORE_PKG_LOCATION contains the full path to an
|
.. code-block:: console
|
||||||
installation package, an element in this folder could contain the
|
|
||||||
following line:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
$ 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
|
||||||
|
|
||||||
dd if=${DATASTORE_PKG_LOCATION} of=${TMP_HOOKS_PATH}/new_db.deb
|
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
|
||||||
Use an install.d Step to Install the Software
|
openstack-discuss@lists.openstack.org mailing list.
|
||||||
---------------------------------------------
|
|
||||||
|
|
||||||
A standard install.d step can now install the software from
|
|
||||||
TMP_HOOKS_DIR.
|
|
||||||
|
|
||||||
For example, an element in this folder could contain:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
dpkg -i ${TMP_HOOKS_PATH}/new_db.deb
|
|
||||||
|
|
||||||
Once elements have been set up that expect a package to be available,
|
|
||||||
the guest image can be created by executing the following:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
DATASTORE_PKG_LOCATION=/path/to/new_db.deb ./script_to_call_dib.sh
|
|
||||||
|
|
||||||
Assuming the elements for new_db are available in the trove
|
|
||||||
repository, this would equate to:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
DATASTORE_PKG_LOCATION=/path/to/new_db.deb ./trovestack kick-start new_db
|
|
||||||
|
|||||||
@ -9,4 +9,3 @@
|
|||||||
building_guest_images
|
building_guest_images
|
||||||
database_module_usage
|
database_module_usage
|
||||||
secure_oslo_messaging
|
secure_oslo_messaging
|
||||||
trovestack
|
|
||||||
|
|||||||
@ -1,105 +0,0 @@
|
|||||||
..
|
|
||||||
Copyright 2019 Catalyst IT Ltd
|
|
||||||
All Rights Reserved.
|
|
||||||
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.
|
|
||||||
|
|
||||||
Trove integration script - trovestack
|
|
||||||
=====================================
|
|
||||||
|
|
||||||
``trovestack`` in ``integration/scripts`` folder is a shell script that
|
|
||||||
contains lots of useful functionalities via sub-commands including ``install``
|
|
||||||
(trove development environment installation), ``unit-tests``, ``gate-tests``
|
|
||||||
(functional test), ``build-image``, etc. This guide introduces some of them.
|
|
||||||
|
|
||||||
Before running ``trovestack`` command, go to the scripts folder:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
git clone https://opendev.org/openstack/trove
|
|
||||||
cd trove/integration/scripts
|
|
||||||
|
|
||||||
Build guest agent image
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
For testing purpose, the Trove guest images of some specific databases are
|
|
||||||
periodically built and published in
|
|
||||||
http://tarballs.openstack.org/trove/images/.
|
|
||||||
|
|
||||||
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}
|
|
||||||
|
|
||||||
* ``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 host 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.
|
|
||||||
|
|
||||||
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. you've built 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-mysql.qcow2
|
|
||||||
$ trove-manage datastore_version_update mysql 5.7.1 mysql $image_id "" 1
|
|
||||||
Loading…
Reference in New Issue
Block a user