openstack/deb-python-ironic-inspector-client
Code Issues Proposed changes
6364bc93cd
deb-python-ironic-inspector.../README.rst
Dmitry Tantsur 7bfaca1597 Deprecate global functions in favor of ClientV1 methods 
These are bulky and hard to update. Using a client instance is also
more in line with other OpenStack clients.

Change-Id: I60efeb1b54ea44e59382a2c9f6537677cff07597
2016-08-19 12:24:10 +02:00

7.1 KiB
Raw Blame History

Ironic Inspector Client

This is a client library and tool for Ironic Inspector.

Please follow usual OpenStack Gerrit Workflow to submit a patch, see Inspector contributing guide for more detail.

Python API

To use Python API first create a ClientV1 object:

import ironic_inspector_client
client = ironic_inspector_client.ClientV1(session=keystone_session)

This code creates a client with API version 1.0 and a given Keystone session. The service URL is fetched from the service catalog in this case. Optional arguments service_type, interface and region_name can be provided to modify how the URL is looked up.

If the catalog lookup fails, the local host with port 5050 is tried. However, this behaviour is deprecated and should not be relied on. Also an explicit inspector_url can be passed to bypass service catalog.

Optional api_version argument is a minimum API version that a server must support. It can be a tuple (MAJ, MIN), string "MAJ.MIN" or integer (only major, minimum supported minor version is assumed).

See Usage for the list of available calls.

API Versioning

Starting with version 2.1.0 Ironic Inspector supports optional API versioning. Version is a tuple (X, Y), where X is always 1 for now.

The server has maximum and minimum supported versions. If no version is requested, the server assumes the maximum it's supported.

Two constants are exposed for convenience:

  • DEFAULT_API_VERSION server API version used by default, always (1, 0) for now.
  • MAX_API_VERSION maximum API version this client was designed to work with. This does not mean that other versions won't work at all - the server might still support them.

Usage

CLI tool is based on OpenStackClient with prefix openstack baremetal introspection. Accepts optional argument --inspector-url with the Ironic Inspector API endpoint.

Refer to the HTTP API reference for information on the Ironic Inspector HTTP API.

Detect server API versions

client.server_api_versions()

Returns a tuple (minimum version, maximum version). See API Versioning for details.

Start introspection on a node

client.introspect(uuid, new_ipmi_username=None, new_ipmi_password=None)

  • uuid - Ironic node UUID;
  • new_ipmi_username and new_ipmi_password - if these are set, Ironic Inspector will switch to manual power on and assigning IPMI credentials on introspection. See Setting IPMI Credentials for details.

CLI:

$ openstack baremetal introspection start [--wait] [--new-ipmi-password=PWD [--new-ipmi-username=USER]] UUID [UUID ...]

Note that the CLI call accepts several UUID's and will stop on the first error.

Note

This CLI call doesn't rely on Ironic, and the introspected node will be left in MANAGEABLE state. This means that the Ironic node is not protected from other operations being performed by Ironic, which could cause inconsistency in the node's state, and lead to operational errors.

With --wait flag it waits until introspection ends for all given nodes, then displays the results as a table.

Query introspection status

client.get_status(uuid)

  • uuid - Ironic node UUID.

Returns a dict with keys:

  • finished - whether introspection has finished for this node;
  • error - last error, None if introspection ended without an error.

CLI:

$ openstack baremetal introspection status UUID

Retrieving introspection data

client.get_data(uuid[, raw])

  • uuid - Ironic node UUID;
  • raw - whether to return raw data or parsed JSON data (the default).

CLI:

$ openstack baremetal introspection data save [--file=file_name] UUID

If file name is not provided, the data is dumped to stdout.

Note

This feature requires Swift support to be enabled in Ironic Inspector by setting [processing]store_data configuration option to swift.

Aborting introspection

client.abort(uuid)

  • uuid - Ironic node UUID.

CLI:

$ openstack baremetal introspection abort UUID

Reprocess stored introspection data

client.reprocess(uuid)

  • uuid - Ironic node UUID.

CLI:

$ openstack baremetal introspection reprocess UUID

Note

This feature requires Swift store to be enabled for Ironic Inspector by setting [processing]store_data configuration option to swift.

Introspection Rules API

All functions related to introspection rules are grouped under rules attribute of the ClientV1 object.

Creating a rule

client.rules.create(conditions, actions[, uuid][, description])

  • conditions and actions are lists of dictionaries with rule conditions and actions accordingly. Please refer to the introspection rules documentation for details on.
  • uuid rule UUID, will be generated, if missing.
  • description optional rule description.

This call is not directly represented in CLI, use import below.

client.rules.from_json(rule_json)

  • rule_json dictionary with a rule representation.

CLI:

$ openstack baremetal introspection rule import <JSON FILE>

Listing all rules

client.rules.list()

Returns list of short rule representations, containing only description, UUID and links.

CLI:

$ openstack baremetal introspection rule list

Getting rule details

client.rules.get(uuid)

  • uuid rule UUID.

Returns a full rule representation as a dictionary.

This call is currently not represented in CLI.

Deleting all rules

client.rules.delete_all()

CLI:

$ openstack baremetal introspection rule purge

Deleting a rule

client.rules.delete(uuid)

  • uuid rule UUID.

CLI:

$ openstack baremetal introspection rule delete <UUID>

Using names instead of UUID

Starting with baremetal introspection API 1.5 (provided by Ironic Inspector 3.3.0) it's possible to use node names instead of UUIDs in all Python and CLI calls.