Merge "Add documentation for rescue mode"

This commit is contained in:
Zuul 2018-02-07 16:14:23 +00:00 committed by Gerrit Code Review
commit cd13cb1c1b
4 changed files with 94 additions and 0 deletions

View File

@ -17,6 +17,7 @@ Index
.. toctree::
how_it_works
rescue
troubleshooting
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
metrics
rescue
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.