glance/doc/source/db.rst
Brian Rosmaita 5393599e0b Update developer docs for rolling upgrades
Add more detailed information about Alembic migrations and the
EXPERIMENTAL zero-downtime database upgrade process introduced
in Ocata plus initial rolling upgrade operator docs.

Change-Id: Ic30cd5872962df0fdfa9064391d1f7d04104bc49
2017-02-15 15:30:37 -05:00

248 lines
10 KiB
ReStructuredText

..
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.
Database Management
===================
The default metadata driver for Glance uses `SQLAlchemy`_, which implies there
exists a backend database which must be managed. The ``glance-manage`` binary
provides a set of commands for making this easier.
The commands should be executed as a subcommand of 'db':
glance-manage db <cmd> <args>
.. note::
In the Ocata release (14.0.0), the database migration engine was changed
from *SQLAlchemy Migrate* to *Alembic*. This necessitated some changes in
the ``glance-manage`` tool. While the user interface has been kept as
similar as possible, the ``glance-manage`` tool included with the Ocata and
more recent releases is incompatible with the "legacy" tool. If you are
consulting these documents for information about the ``glance-manage`` tool
in the Newton or earlier releases, please see the
:doc:`db-sqlalchemy-migrate` page.
.. _`SQLAlchemy`: http://www.sqlalchemy.org/
Migration Scripts
-----------------
The migration scripts are stored in the directory:
``glance/db/sqlalchemy/alembic_migrations/versions``
As mentioned above, these scripts utilize the Alembic migration engine, which
was first introduced in the Ocata release. All database migrations up through
the Liberty release are consolidated into one Alembic migration script named
``liberty_initial``. Mitaka migrations are retained, but have been rewritten
for Alembic and named using the new naming convention.
A fresh Glance installation will apply the following
migrations:
* ``liberty-initial``
* ``mitaka01``
* ``mitaka02``
* ``ocata01``
.. note::
The "old-style" migration scripts have been retained in their `current
directory`_ in the Ocata release so that interested operators can correlate
them with the new migrations. This directory will be removed in future
releases.
In particular, the "old-style" script for the Ocata migration,
`045_add_visibility.py`_ is retained for operators who are conversant in
SQLAlchemy Migrate and are interested in comparing it with a "new-style"
Alembic migration script. The Alembic script, which is the one actually
used to do the upgrade to Ocata, is
`ocata01_add_visibility_remove_is_public.py`_.
.. _`current directory`: http://git.openstack.org/cgit/openstack/glance/tree/glance/db/sqlalchemy/migrate_repo/versions?h=stable/ocata
.. _`045_add_visibility.py`: http://git.openstack.org/cgit/openstack/glance/tree/glance/db/sqlalchemy/migrate_repo/versions/045_add_visibility.py?h=stable/ocata
.. _`ocata01_add_visibility_remove_is_public.py`: http://git.openstack.org/cgit/openstack/glance/tree/glance/db/sqlalchemy/alembic_migrations/versions/ocata01_add_visibility_remove_is_public.py?h=stable/ocata
Sync the Database
-----------------
glance-manage db sync [VERSION]
Place an existing database under migration control and upgrade it to the
specified VERSION or to the latest migration level if VERSION is not specified.
.. note::
Prior to Ocata release the database version was a numeric value. For
example: for the Newton release, the latest migration level was ``44``.
Starting with Ocata, database version is a revision name corresponding to
the latest migration included in the release. For the Ocata release, there
is only one database migration and it is identified by revision
``ocata01``. So, the database version for Ocata release is ``ocata01``.
This naming convention will change slightly with the introduction of
zero-downtime upgrades, which is EXPERIMENTAL in Ocata, but is projected to
be the official upgrade method beginning with the Pike release. See
:ref:`zero-downtime` below for more information.
Determining the Database Version
--------------------------------
glance-manage db version
This will print the current migration level of a Glance database.
Upgrading an Existing Database
------------------------------
glance-manage db upgrade [VERSION]
This will take an existing database and upgrade it to the specified VERSION.
.. _downgrades:
Downgrading an Existing Database
--------------------------------
Upgrades involve complex operations and can fail. Before attempting any
upgrade, you should make a full database backup of your production data. As of
Kilo, database downgrades are not supported, and the only method available to
get back to a prior database version is to restore from backup [1].
[1]: http://docs.openstack.org/ops-guide/ops-upgrades.html#perform-a-backup
.. _zero-downtime:
Zero-Downtime Database Upgrades
===============================
.. warning::
This feature is EXPERIMENTAL in the Ocata release. We encourage operators
to try it out, but its use in production environments is currently NOT
SUPPORTED.
A zero-downtime database upgrade enables true rolling upgrades of the Glance
nodes in your cloud's control plane. At the appropriate point in the upgrade,
you can have a mixed deployment of release *n* (for example, Ocata) and release
*n-1* (for example, Newton) Glance nodes, take the *n-1* release nodes out of
rotation, allow them to drain, and then take them out of service permanently,
leaving all Glance nodes in your cloud at release *n*.
That's a rough sketch of how a rolling upgrade would work. For full details,
see :doc:`rollingupgrades`.
.. note::
Downgrading a database is not supported. See :ref:`downgrades` for more
information.
The Expand-Migrate-Contract Cycle
---------------------------------
For Glance, a zero-downtime database upgrade has three phases:
1. **Expand**: in this phase, new columns, tables, indexes, or triggers are
added to the database.
2. **Migrate**: in this phase, data is migrated to the new columns or tables.
3. **Contract**: in this phase, the "old" tables or columns (and any database
triggers used during the migration), which are no longer in use, are removed
from the database.
The above phases are abbreviated as an **E-M-C** database upgrade.
New Database Version Identifiers
--------------------------------
In order to perform zero-downtime upgrades, the version identifier of a
database becomes more complicated since it must reflect knowledge of what point
in the E-M-C cycle the upgrade has reached. To make this evident, the
identifier explicitly contains 'expand' or 'contract' as part of its name.
Thus the ``ocata01`` migration (that is, the migration that's currently used in
the fully supported upgrade path) has two identifiers associated with it for
zero-downtime upgrades: ``ocata_expand01`` and ``ocata_contract01``.
During the upgrade process, the database is initially marked with
``ocata_expand01``. Eventually, after completing the full upgrade process, the
database will be marked with ``ocata_contract01``. So, instead of one database
version, an operator will see a composite database version that will have both
expand and contract versions. A database will be considered at Ocata version
only when both expand and contract revisions are at the latest revisions. For
a successful Ocata zero-downtime upgrade, for example, the database will be
marked with both ``ocata_expand01``, ``ocata_contract01``.
In the case in which there are multiple changes in a cycle, the database
version record would go through the following progression:
+-------+--------------------------------------+-------------------------+
| stage | database identifier | comment |
+=======+======================================+=========================+
| E | ``bexar_expand01`` | upgrade begins |
+-------+--------------------------------------+-------------------------+
| E | ``bexar_expand02`` | |
+-------+--------------------------------------+-------------------------+
| E | ``bexar_expand03`` | |
+-------+--------------------------------------+-------------------------+
| M | ``bexar_expand03`` | bexar_migrate01 occurs |
+-------+--------------------------------------+-------------------------+
| M | ``bexar_expand03`` | bexar_migrate02 occurs |
+-------+--------------------------------------+-------------------------+
| M | ``bexar_expand03`` | bexar_migrate03 occurs |
+-------+--------------------------------------+-------------------------+
| C | ``bexar_expand03, bexar_contract01`` | |
+-------+--------------------------------------+-------------------------+
| C | ``bexar_expand03, bexar_contract02`` | |
+-------+--------------------------------------+-------------------------+
| C | ``bexar_expand03, bexar_contract03`` | upgrade completed |
+-------+--------------------------------------+-------------------------+
Database Upgrade
----------------
In order to enable the E-M-C database upgrade cycle, and to enable Glance
rolling upgrades, the ``glance-manage`` tool has been augmented to include the
following operations.
Expanding the Database
----------------------
glance-manage db expand
This will run the expansion phase of a rolling upgrade process. Database
expansion should be run as the first step in the rolling upgrade process before
any new services are started.
Migrating the Data
------------------
glance-manage db migrate
This will run the data migrate phase of a rolling upgrade process. Database
migration should be run after database expansion but before any new services
are started.
Contracting the Database
------------------------
glance-manage db contract
This will run the contraction phase of a rolling upgrade process.
Database contraction should be run as the last step of the rolling upgrade
process after all old services are upgraded to new ones.