Add documentation for rescue mode

This adds documentation for rescue mode, including the finalize_rescue
command as well as upstream support in agent images.

Change-Id: Id0834941ee4dacf2e7c0feaa65126d63e8a97c39
Partial-Bug: 1526449
This commit is contained in:
Mario Villaplana 2017-02-09 15:57:53 +00:00 committed by Shivanand Tendulker
parent 56c33deb88
commit 689dbf6b5c
4 changed files with 94 additions and 0 deletions

View File

@ -17,6 +17,7 @@ Index
.. toctree:: .. toctree::
how_it_works how_it_works
rescue
troubleshooting troubleshooting
Indices and tables Indices and tables

View File

@ -0,0 +1,53 @@
.. _admin_rescue:
===========
Rescue mode
===========
Overview
========
Rescue mode is a feature that can be used to boot a ramdisk for a tenant in
case the machine is otherwise inaccessible. For example, if there's a disk
failure that prevents access to another operating system, rescue mode can be
used to diagnose and fix the problem.
Support in ironic-python-agent images
=====================================
Rescue is initiated when ironic-conductor sends the ``finalize_rescue``
command to ironic-python-agent. A user `rescue` is created with a password
provided as an argument to this command. DHCP is then configured to
facilitate network connectivity, thus enabling a user to login to the machine
in rescue mode.
.. warning:: Rescue mode exposes the contents of the ramdisk to the tenant.
Ensure that any rescue image you build does not contain secrets
(e.g. sensitive clean steps, proprietary firmware blobs).
The below has information about supported images that may be built to use
rescue mode.
CoreOS
------
The CoreOS image supports rescue mode when used with DHCP tenant networks. You
may follow the normal process for `building a CoreOS ironic-python-agent
image`_ to create an image that supports rescue mode.
After the ``finalize_rescue`` command completes, DHCP will be configured on all
network interfaces, and a `rescue` user will be created with the specified
``rescue_password``.
TinyIPA
-------
The TinyIPA image supports rescue mode when used with DHCP tenant networks.
No special action is required to `build a TinyIPA image`_ with this support.
After the ``finalize_rescue`` command completes, DHCP will be configured on all
network interfaces, and a `rescue` user will be created with the specified
``rescue_password``.
.. _`building a CoreOS ironic-python-agent image`: https://github.com/openstack/ironic-python-agent/tree/master/imagebuild/coreos/README.rst
.. _`build a TinyIPA image`: https://github.com/openstack/ironic-python-agent/tree/master/imagebuild/tinyipa/README.rst

View File

@ -19,6 +19,7 @@ Index
hardware_managers hardware_managers
metrics metrics
rescue
Generated Developer Documentation Generated Developer Documentation
================================= =================================

View File

@ -0,0 +1,39 @@
.. rescue:
===========
Rescue Mode
===========
Ironic supports putting nodes in rescue mode using hardware types that
support rescue interfaces. A rescue operation can be used to boot nodes
into a rescue ramdisk so that the ``rescue`` user can access the node.
This provides the ability to access the node when normal access is not
possible. For example, if there is a need to perform manual password
reset or data recovery in the event of some failure, a rescue operation
can be used. IPA rescue extension exposes a command ``finalize_rescue``
(that is used by Ironic) to set the password for the ``rescue`` user
when the rescue ramdisk is booted.
finalize_rescue command
=======================
The rescue extension exposes the command ``finalize_rescue``; when
invoked, it triggers rescue mode::
POST /v1/commands
{"name": "rescue.finalize_rescue",
"params": {
"rescue_password": "p455w0rd"}
}
``rescue_password`` is a required parameter for this command.
If successful, this synchronous command will:
1. Write the salted and crypted ``rescue_password`` to
``/etc/ipa-rescue-config/ipa-rescue-password`` in the chroot or filesystem
that ironic-python-agent is running in.
2. Stop the ironic-python-agent process after completing these actions and
returning the response to the API request.