Clean up database section of admin docs
The db.rst file had two top level headings and the second wasn't being rendered in the html pages. Separated the zero downtime section into its own section to fix this and made a few updates to the text. Change-Id: I913326653642d8f19173f18868d4e8cbb89a5b77
This commit is contained in:
Brian Rosmaita
parent
1041c1f983
commit
62ee9e7390
@ -95,7 +95,7 @@ specified VERSION or to the latest migration level if VERSION is not specified.
|
||||
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.
|
||||
:ref:`zero-downtime` for more information.
|
||||
|
||||
|
||||
Determining the Database Version
|
||||
@ -118,132 +118,10 @@ This will take an existing database and upgrade it to the specified VERSION.
|
||||
Downgrading an Existing Database
|
||||
--------------------------------
|
||||
|
||||
Downgrading an existing database is **NOT SUPPORTED**.
|
||||
|
||||
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 :ref:`rolling-upgrades`.
|
||||
|
||||
.. 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.
|
||||
the OpenStack Kilo release (April 2013), database downgrades are not supported,
|
||||
and the only method available to get back to a prior database version is to
|
||||
restore from backup.
|
||||
|
||||
@ -17,6 +17,7 @@
|
||||
flows
|
||||
db
|
||||
db-sqlalchemy-migrate
|
||||
zero-downtime-db-upgrade
|
||||
rollingupgrades
|
||||
troubleshooting
|
||||
manage-images
|
||||
|
||||
134
doc/source/admin/zero-downtime-db-upgrade.rst
Normal file
134
doc/source/admin/zero-downtime-db-upgrade.rst
Normal file
@ -0,0 +1,134 @@
|
||||
..
|
||||
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.
|
||||
|
||||
.. _zero-downtime:
|
||||
|
||||
Zero-Downtime Database Upgrades
|
||||
===============================
|
||||
|
||||
.. warning::
|
||||
This feature is EXPERIMENTAL in the Ocata and Pike releases.
|
||||
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 :ref:`rolling-upgrades`.
|
||||
|
||||
.. 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.
|
||||
Loading…
Reference in New Issue
Block a user