CLI Commands ============ Users can access any OpenStack CLI command that they have permission to use. For example, once a node is assigned to an owner or lessee they can use Ironic CLI commands to work with that node as limited by Ironic policy; see the `Ironic CLI reference`_ for more information. These commands may be of particular interest to ESI users. Assigning Owners ---------------- +---------------------+---------------------------------------------------------------------------+ | | **Admin Actions** | +---------------------+---------------------------------------------------------------------------+ | Assign Node Owner | ``openstack baremetal node set --owner `` | +---------------------+---------------------------------------------------------------------------+ | Unassign Node Owner | ``openstack baremetal node unset --owner `` | +---------------------+---------------------------------------------------------------------------+ Leasing Workflows ----------------- There are two possible node leasing workflows. Simple Workflow ~~~~~~~~~~~~~~~ In the simple case, node lessees are managed directly by admins and owners, who assign and unassign nodes to a project as they see fit. This workflow does not require any custom ESI services. +----------------------+----------------------------------------------------------------------------+ | | **Admin/Owner Actions** | +----------------------+----------------------------------------------------------------------------+ | Assign Node Lessee | ``openstack baremetal node set --lessee `` | +----------------------+----------------------------------------------------------------------------+ | Unassign Node Lessee | ``openstack baremetal node unset --lessee `` | +----------------------+----------------------------------------------------------------------------+ ESI Leasing Workflow ~~~~~~~~~~~~~~~~~~~~ If `ESI Leap`_ is installed, then node leases can also be managed as follows: **Owner Actions** Node owners can lease a node directly to a lessee, or offer up their nodes for lease for a given time period. Unoffered nodes cannot be seen by lessees. +--------------+---------------------------------------------------------------------------------------------------------------------+ | | **Owner Actions** | +--------------+---------------------------------------------------------------------------------------------------------------------+ | Create Lease | ``openstack esi lease create --start-time --end-time `` | +--------------+---------------------------------------------------------------------------------------------------------------------+ | Show Lease | ``openstack esi lease show `` | +--------------+---------------------------------------------------------------------------------------------------------------------+ | Delete Lease | ``openstack esi lease delete `` | +--------------+---------------------------------------------------------------------------------------------------------------------+ | Create Offer | ``openstack esi offer create --start-time --end-time `` | +--------------+---------------------------------------------------------------------------------------------------------------------+ | View Offer | ``openstack esi offer show `` | +--------------+---------------------------------------------------------------------------------------------------------------------+ | Delete Offer | ``openstack esi offer delete `` | +--------------+---------------------------------------------------------------------------------------------------------------------+ **Lessee Actions** Users can view available offers and claim an offer to create a lease. +--------------+--------------------------------------------------------------------------------------------+ | | **Lessee Actions** | +--------------+--------------------------------------------------------------------------------------------+ | List Offers | ``openstack esi offer list`` | +--------------+--------------------------------------------------------------------------------------------+ | Claim Offer | ``openstack esi offer claim --start-time --end-time `` | +--------------+--------------------------------------------------------------------------------------------+ | List Leases | ``openstack esi lease list`` | +--------------+--------------------------------------------------------------------------------------------+ | Show Lease | ``openstack esi lease show `` | +--------------+--------------------------------------------------------------------------------------------+ | Delete Lease | ``openstack esi lease delete `` | +--------------+--------------------------------------------------------------------------------------------+ **Admin Actions** Admins can update the end time of a lease. +--------------+-----------------------------------------------------------------------+ | | **Admin Actions** | +--------------+-----------------------------------------------------------------------+ | Update Lease | ``openstack esi lease update --end-time `` | +--------------+-----------------------------------------------------------------------+ Subleases ~~~~~~~~~ A lessee can perform owner actions on a node that they have leased, effectively subleasing a node. Note that a sublessee cannot further sublease a node. Limited Offers and Subprojects ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An offer can be made available to a limited number of projects by using the ``--lessee`` option when creating the offer. +----------------------+------------------------------------------------------------------------------------------------------------------------------+ | | **Owner Actions** | +----------------------+------------------------------------------------------------------------------------------------------------------------------+ | Create Limited Offer | ``openstack esi offer create --start-time --end-time --lessee `` | +----------------------+------------------------------------------------------------------------------------------------------------------------------+ An offer created in such a way is available not only to the lessee project, but to the entire subtree of projects beneath the lessee project. As a result, using this feature effectively requires projects to be carefully organized. Resource Isolation and Sharing ------------------------------ ESI provides bare metal isolation through the use of owners and lessees. It may be useful to isolate or share additional OpenStack resources. Networks ~~~~~~~~ By default, a network is only viewable and usable by the project that created it. Public networks can be created using the ``--share`` flag. A private network can also be shared on a project-by-project basis: +--------------------+--------------------------------------------------------------------------------------------------------------------------------+ | | **Network Owner Actions** | +--------------------+--------------------------------------------------------------------------------------------------------------------------------+ | List RBAC Policies | ``openstack network rbac list`` | +--------------------+--------------------------------------------------------------------------------------------------------------------------------+ | Share Network | ``openstack network rbac create --action access_as_shared --type network --target-project `` | +--------------------+--------------------------------------------------------------------------------------------------------------------------------+ | Unshare Network | ``openstack network rbac delete `` | +--------------------+--------------------------------------------------------------------------------------------------------------------------------+ Volumes ~~~~~~~ A volumes is only viewable and usable by the project that created it. Volumes cannot be shared; however, they can be transferred. First, the owner of the volume must create a volume transfer request: +--------------------------------+--------------------------------------------------------------+ | | **Volume Owner Actions** | +--------------------------------+--------------------------------------------------------------+ | Create Volume Transfer Request | ``openstack volume transfer request create volume-bootable`` | +--------------------------------+--------------------------------------------------------------+ The output of this command includes an ``id`` and an ``auth_key``. The volume owner sends these values to the desired project, who can then accept the transfer: +--------------------------------+---------------------------------------------------------------------------------+ | | **Target Volume Owner Actions** | +--------------------------------+---------------------------------------------------------------------------------+ | Accept Volume Transfer Request | ``openstack volume transfer request accept --auth-key `` | +--------------------------------+---------------------------------------------------------------------------------+ Images ~~~~~~ By default, an image is only viewable and usable by the project that created it. Administrators can create a public image by using the ``--public`` flag. A private image can also be shared on a project-by-project basis: +----------------------+------------------------------------------------------+ | | **Image Owner Actions** | +----------------------+------------------------------------------------------+ | Share Image | ``openstack image add project `` | +----------------------+------------------------------------------------------+ | Unshare Image | ``openstack image remove project `` | +----------------------+------------------------------------------------------+ Note that the image owner must send the target project the image ID, and the target project must accept the image share: +----------------------+---------------------------------------------+ | | **Target Project Actions** | +----------------------+---------------------------------------------+ | Accept Image Share | ``openstack image set --accept `` | +----------------------+---------------------------------------------+ Provisioning a Node ------------------- There are multiple ways for a non-admin to provision a node. Image ~~~~~ Image-based provisioning can be accomplished through the use of `Metalsmith`_. It requires the image to be uploaded into OpenStack Glance. Once that's done, a non-admin can run the following: +----------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | | **Actions** | +----------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | Provision Node | ``metalsmith deploy --resource-class --image --network --candidate --ssh-public-key `` | +----------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | Undeploy Node | ``metalsmith undeploy `` | +----------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ Volume ~~~~~~ If you'd like to create a volume from an image, run the following: +--------------------------+------------------------------------------------------------------------------------------+ | | **Actions** | +--------------------------+------------------------------------------------------------------------------------------+ | Create Volume from Image | ``openstack volume create --image --bootable --size `` | +--------------------------+------------------------------------------------------------------------------------------+ In order to boot a node from a volume, two node attributes must be set as follows: * The node owner or admin should set the `iscsi_boot` node capability prior to leasing the node. * The node lessee should not be allowed to edit the `storage_interface` node attribute. Instead, they can run the following command to temporarily override that value (until the node is cleaned): +----------------------------+----------------------------------------------------------------------------------+ | | **Actions** | +----------------------------+----------------------------------------------------------------------------------+ | Override Storage Interface | ``openstack baremetal node set --instance-info storage_interface=cinder `` | +----------------------------+----------------------------------------------------------------------------------+ The process for booting a node from a volume is described in the `Ironic boot-from-volume documentation`_. You can also use `python-esiclient`_ to run that workflow with a single command: +-----------------------+--------------------------------------------------------------------------------------------+ | | **Actions** | +-----------------------+--------------------------------------------------------------------------------------------+ | Boot Node from Volume | ``openstack esi node volume attach (--network | --port ) `` | +-----------------------+--------------------------------------------------------------------------------------------+ External Provisioning ~~~~~~~~~~~~~~~~~~~~~ In order to use an external provisioning service, start by moving the node to the ``manageable`` state: +-------------+--------------------------------------------+ | | **Actions** | +-------------+--------------------------------------------+ | Manage Node | ``openstack baremetal node manage `` | +-------------+--------------------------------------------+ Next, mark the node as ``active`` with the `adopt` command. This is required for the subsequent networking action. +------------+-------------------------------------------+ | | **Actions** | +------------+-------------------------------------------+ | Adopt Node | ``openstack baremetal node adopt `` | +------------+-------------------------------------------+ If you would like the node to pxe boot, set the boot device: +----------------------+------------------------------------------------------------------------+ | | **Actions** | +----------------------+------------------------------------------------------------------------+ | Set Node Boot Device | ``openstack baremetal node boot device set pxe (--persistent)`` | +----------------------+------------------------------------------------------------------------+ Now simply attach the node to the appropriate network. You can do so through OpenStack Neutron and Ironic CLI commands, or through `python-esiclient`_: +------------------------+------------------------------------------------------------------------------------------------------+ | | **Actions** | +------------------------+------------------------------------------------------------------------------------------------------+ | Attach Network to Node | ``openstack esi node network attach (--network | --port | --trunk ) `` | +------------------------+------------------------------------------------------------------------------------------------------+ Finally, power the node on: +---------------+----------------------------------------------+ | | **Actions** | +---------------+----------------------------------------------+ | Power Node On | ``openstack baremetal node power on `` | +---------------+----------------------------------------------+ Serial Console Access --------------------- In order to access a node using a serial console, the admin or owner must configure the node's console interface. Instructions for this can be found under `Configuring Web or Serial Console`_ in Ironic's documentation. Once the node is properly configured, the console can be enabled and disabled as needed. The following are prerequisites: * The ``ipmi_terminal_port`` port must be unique. Only the admin or node owner can set this value. * The admin must open the firewall on the controller to allow TCP connections on the port. The exact configuration depends on the desired access method. * The serial console must be enabled: +-----------------+-----------------------------------------------------+ | | **Actions** | +-----------------+-----------------------------------------------------+ | Enable Console | ``openstack baremetal node console enable `` | +-----------------+-----------------------------------------------------+ | Disable Console | ``openstack baremetal node console disable `` | +-----------------+-----------------------------------------------------+ * Only one user may access the console at a time. Default Access ~~~~~~~~~~~~~~ Default access requires the firewall to allow access to the IPMI port from anywhere. This can be *very* dangerous. After the console is enabled, run the following: +---------------------------+--------------------------------------------------+ | | **Actions** | +---------------------------+--------------------------------------------------+ | Show Console Information | ``openstack baremetal node console show `` | +---------------------------+--------------------------------------------------+ This command will generate the following output: +-----------------+----------------------------------------------------------------------+ | Property | Value | +-----------------+----------------------------------------------------------------------+ | console_enabled | True | +-----------------+----------------------------------------------------------------------+ | console_info | {u'url': u'``tcp://:``', u'type': u'socat'} | +-----------------+----------------------------------------------------------------------+ You can now access the serial console with the following command: ``socat - tcp::`` Note that this console is publicly accessible; for that reason, please disable the console once you are finished with it. ESI Serial Console Proxy Access ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the ESI serial console proxy service is running, then you can use an alternative token-based method of accessing the serial console. Only the controller running the serial console proxy service needs access to the IPMI port, making this method far more secure. After the console is enabled, run the following: +----------------------+----------------------------------------------------+ | | **Actions** | +----------------------+----------------------------------------------------+ | Create Console Token | ``openstack esi console auth token create `` | +----------------------+----------------------------------------------------+ This command will generate the following output: +------------+--------------------------------------------------------------------+ | Field | Value | +------------+--------------------------------------------------------------------+ | access_url | ws:///?token= | +------------+--------------------------------------------------------------------+ | node_uuid | | +------------+--------------------------------------------------------------------+ | token | | +------------+--------------------------------------------------------------------+ You can now connect to the console using `websocat`_ by running the following command: ``websocat -b `` To delete the token, run the following: +----------------------+----------------------------------------------------+ | | **Actions** | +----------------------+----------------------------------------------------+ | Delete Console Token | ``openstack esi console auth token delete `` | +----------------------+----------------------------------------------------+ This will disable token access to the serial console proxy. However, it is still recommended that you disable the console. Rescue Mode ----------- A node can be booted in rescue mode, potentially allowing for some form of remediation if some aspect of the node fails. Doing so puts the node on the rescue network temporarily to allow the rescue image to boot; then the node is returned to its original network configuration. If the node has an external floating IP attached, you can then access the node by running ``ssh rescue@`` and using the password specified in the rescue command. For that reason, please specify a strong password. Nodes should only be put into rescue mode temporarily. When you are finished, it is *highly* recommended that you unrescue the node for security purposes. +---------------+-------------------------------------------------------------------------+ | | **Actions** | +---------------+-------------------------------------------------------------------------+ | Rescue Node | ``openstack baremetal node rescue --rescue-password `` | +---------------+-------------------------------------------------------------------------+ | Unrescue Node | ``openstack baremetal node unrescue `` | +---------------+-------------------------------------------------------------------------+ Additional ESI CLI Actions -------------------------- `python-esiclient`_ and `python-esileapclient`_ provide additional commands that combine multiple OpenStack CLI functions into a single action. Switch Information ~~~~~~~~~~~~~~~~~~ +-------------------------------+-----------------------------------------------------------------------------+ | | **Actions** | +-------------------------------+-----------------------------------------------------------------------------+ | List Switches | ``openstack esi switch list`` | +-------------------------------+-----------------------------------------------------------------------------+ | List Switch Ports | ``openstack esi switch port list `` | +-------------------------------+-----------------------------------------------------------------------------+ | List Switch VLANs | ``openstack esi switch vlan list `` | +-------------------------------+-----------------------------------------------------------------------------+ | Add VLAN to Switch Trunk | ``openstack esi switch trunk add vlan `` | +-------------------------------+-----------------------------------------------------------------------------+ | Remove VLAN from Switch Trunk | ``openstack esi switch trunk remove vlan `` | +-------------------------------+-----------------------------------------------------------------------------+ | Enable Switch Port Trunk | ``openstack esi switch port enable trunk `` | +-------------------------------+-----------------------------------------------------------------------------+ | Disable Switch Port Trunk | ``openstack esi switch port disable trunk `` | +-------------------------------+-----------------------------------------------------------------------------+ | Enable Switch Port Access | ``openstack esi switch port enable access `` | +-------------------------------+-----------------------------------------------------------------------------+ | Disable Switch Port Access | ``openstack esi switch port disable access `` | +-------------------------------+-----------------------------------------------------------------------------+ Node/Lease Information ~~~~~~~~~~~~~~~~~~~~~~ +------------------------------+-----------------------------+ | | **Actions** | +------------------------------+-----------------------------+ | List Nodes with Lease Status | ``openstack esi node list`` | +------------------------------+-----------------------------+ Node/Network Management ~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------+------------------------------------------------------------------------------------------------------+ | | **Actions** | +-------------------------------+------------------------------------------------------------------------------------------------------+ | List Node/Network Attachments | ``openstack esi node network list`` | +-------------------------------+------------------------------------------------------------------------------------------------------+ | Attach Network to Node | ``openstack esi node network attach (--network | --port | --trunk ) `` | +-------------------------------+------------------------------------------------------------------------------------------------------+ | Detach Network from Node | ``openstack esi node network detach --port `` | +-------------------------------+------------------------------------------------------------------------------------------------------+ Boot Node from Volume ~~~~~~~~~~~~~~~~~~~~~ +-----------------------+--------------------------------------------------------------------------------------------+ | | **Actions** | +-----------------------+--------------------------------------------------------------------------------------------+ | Boot Node from Volume | ``openstack esi node volume attach (--network | --port ) `` | +-----------------------+--------------------------------------------------------------------------------------------+ Set Node Boot Device ~~~~~~~~~~~~~~~~~~~~ +----------------------+-----------------------------------------------------------------------------------------------------+ | | **Actions** | +----------------------+-----------------------------------------------------------------------------------------------------+ | Set Node Boot Device | ``openstack baremetal node boot device set bios|cdrom|disk|pxe|safe|wanboot (--persistent)`` | +----------------------+-----------------------------------------------------------------------------------------------------+ If the ``--persistent`` flag is not used, the node will only boot from the specified device once. If the ``--persistent`` flag is used, the node will boot from the specified device until the node is cleaned. Trunk Ports ~~~~~~~~~~~ +--------------------------------+------------------------------------------------------------------------------------------------------------+ | | **Actions** | +--------------------------------+------------------------------------------------------------------------------------------------------------+ | List Trunk Ports | ``openstack esi trunk list`` | +--------------------------------+------------------------------------------------------------------------------------------------------------+ | Create Trunk Port | ``openstack esi trunk create --native-network --tagged-networks `` | +--------------------------------+------------------------------------------------------------------------------------------------------------+ | Add Network to Trunk Port | ``openstack esi trunk add network --tagged-networks `` | +--------------------------------+------------------------------------------------------------------------------------------------------------+ | Remove Network from Trunk Port | ``openstack esi trunk remove network --tagged-networks `` | +--------------------------------+------------------------------------------------------------------------------------------------------------+ | Delete Trunk Port | ``openstack esi trunk delete `` | +--------------------------------+------------------------------------------------------------------------------------------------------------+ .. _Ironic CLI reference: https://docs.openstack.org/python-ironicclient/latest/cli/osc_plugin_cli.html .. _ESI Leap: https://github.com/CCI-MOC/esi-leap .. _Metalsmith: https://docs.openstack.org/metalsmith/latest/ .. _Ironic boot-from-volume documentation: https://docs.openstack.org/ironic/latest/admin/boot-from-volume.html .. _websocat: https://pypi.org/project/websocat/ .. _python-esiclient: https://github.com/CCI-MOC/python-esiclient .. _python-esileapclient: https://github.com/CCI-MOC/python-esileapclient .. _Configuring Web or Serial Console: https://docs.openstack.org/ironic/latest/admin/console.html