openstack/keystone
Code Issues Proposed changes

Doc db_sync --expand incurring downtime in upgrades to Newton

Browse Source 
The current implementation of db_sync --expand automatically runs any
outstanding legacy operations to ensure it's safety. However, that
behavior also means that legacy migrations may violate the safety
assumptions around --expand.

This is only true for Mitaka to Newton upgrades, as there should not be
any newer migrations in the legacy repository to be triggered by this
behavior.

[1] 0ebd557325/keystone/common/sql/upgrades.py (L269-L271)

Change-Id: Ib175f7fce96011d77eb4783123cb2d265d60aa42
Closes-Bug: 1676925
This commit is contained in:
Dolph Mathews 2017-03-28 15:40:30 +00:00
parent 30faacc5d0
commit e6ef702f22
1 changed files with 21 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
doc/source/upgrading.rst
View File

@ -155,6 +155,17 @@ downtime if it is required.
Upgrading without downtime Upgrading without downtime
-------------------------- --------------------------
.. NOTE:
Upgrading without downtime is only supported in deployments upgrading
*from* Newton or a newer release.
If upgrading a Mitaka deployment to Newton, the commands described here
will be available as described below, but the ``keystone-manage db_sync
--expand`` command will incur downtime (similar to running
``keystone-manage db_sync``), as it runs legacy (downtime-incurring)
migrations prior to running schema expansions.
This is a high-level description of our upgrade strategy built around This is a high-level description of our upgrade strategy built around
additional options in ``keystone-manage db_sync``. Although it is much more additional options in ``keystone-manage db_sync``. Although it is much more
complex than the upgrade process described above, it assumes that you are not complex than the upgrade process described above, it assumes that you are not
@ -180,9 +191,10 @@ authenticate requests normally.
diagnose symptoms of common deployment issues and receive instructions for diagnose symptoms of common deployment issues and receive instructions for
resolving them. resolving them.
#. Run ``keystone-manage db_sync --expand`` on the first node to expand the #. (*New in Newton*) Run ``keystone-manage db_sync --expand`` on the first node
database schema to a superset of what both the previous and next release can to expand the database schema to a superset of what both the previous and
utilize, and create triggers to facilitate the live migration process. next release can utilize, and create triggers to facilitate the live
migration process.
.. warning:: .. warning::
@ -198,10 +210,10 @@ authenticate requests normally.
triggers will live migrate the data to the new schema so it can be read by triggers will live migrate the data to the new schema so it can be read by
the next release. the next release.
#. Run ``keystone-manage db_sync --migrate`` on the first node to forcefully #. (*New in Newton*) Run ``keystone-manage db_sync --migrate`` on the first
perform data migrations. This process will migrate all data from the old node to forcefully perform data migrations. This process will migrate all
schema to the new schema while the previous release continues to operate data from the old schema to the new schema while the previous release
normally. continues to operate normally.
When this process completes, all data will be available in both the new When this process completes, all data will be available in both the new
schema and the old schema, so both the previous release and the next release schema and the old schema, so both the previous release and the next release
@ -218,8 +230,8 @@ authenticate requests normally.
As the next release begins writing to the new schema, database triggers will As the next release begins writing to the new schema, database triggers will
also migrate the data to the old schema, keeping both data schemas in sync. also migrate the data to the old schema, keeping both data schemas in sync.
#. Run ``keystone-manage db_sync --contract`` to remove the old schema and all #. (*New in Newton*) Run ``keystone-manage db_sync --contract`` to remove the
data migration triggers. old schema and all data migration triggers.
When this process completes, the database will no longer be able to support When this process completes, the database will no longer be able to support
the previous release. the previous release.