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:
parent
56c33deb88
commit
689dbf6b5c
@ -17,6 +17,7 @@ Index
|
|||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
how_it_works
|
how_it_works
|
||||||
|
rescue
|
||||||
troubleshooting
|
troubleshooting
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
|
53
doc/source/admin/rescue.rst
Normal file
53
doc/source/admin/rescue.rst
Normal 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
|
@ -19,6 +19,7 @@ Index
|
|||||||
|
|
||||||
hardware_managers
|
hardware_managers
|
||||||
metrics
|
metrics
|
||||||
|
rescue
|
||||||
|
|
||||||
Generated Developer Documentation
|
Generated Developer Documentation
|
||||||
=================================
|
=================================
|
||||||
|
39
doc/source/contributor/rescue.rst
Normal file
39
doc/source/contributor/rescue.rst
Normal 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.
|
Loading…
Reference in New Issue
Block a user