Merge "Clean up database section of admin docs"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
0ef045d7bd
@ -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
|
This naming convention will change slightly with the introduction of
|
||||||
zero-downtime upgrades, which is EXPERIMENTAL in Ocata, but is projected to
|
zero-downtime upgrades, which is EXPERIMENTAL in Ocata, but is projected to
|
||||||
be the official upgrade method beginning with the Pike release. See
|
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
|
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
|
||||||
--------------------------------
|
--------------------------------
|
||||||
|
|
||||||
|
Downgrading an existing database is **NOT SUPPORTED**.
|
||||||
|
|
||||||
Upgrades involve complex operations and can fail. Before attempting any
|
Upgrades involve complex operations and can fail. Before attempting any
|
||||||
upgrade, you should make a full database backup of your production data. As of
|
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
|
the OpenStack Kilo release (April 2013), database downgrades are not supported,
|
||||||
get back to a prior database version is to restore from backup [1].
|
and the only method available to get back to a prior database version is to
|
||||||
|
restore from backup.
|
||||||
[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.
|
|
||||||
|
|||||||
@ -18,6 +18,7 @@
|
|||||||
interoperable-image-import
|
interoperable-image-import
|
||||||
db
|
db
|
||||||
db-sqlalchemy-migrate
|
db-sqlalchemy-migrate
|
||||||
|
zero-downtime-db-upgrade
|
||||||
rollingupgrades
|
rollingupgrades
|
||||||
troubleshooting
|
troubleshooting
|
||||||
manage-images
|
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