redfish

Redfish module.

exception spicerack.redfish.RedfishError

Bases: spicerack.exceptions.SpicerackError

General errors raised by this module.

exception spicerack.redfish.RedfishTaskNotCompletedError

Bases: spicerack.redfish.RedfishError

Raised when a Redfish task is not found on the server.

class spicerack.redfish.ChassisResetPolicy(value)

Bases: enum.Enum

Subset of available Chassis.Reset policies compatible with all supported vendors (at this moment only Dell).

FORCE_OFF: str = 'ForceOff'

Turn off the unit immediately (nongraceful shutdown).

FORCE_RESTART: str = 'ForceRestart'

Shut down immediately and nongracefully and restart the system.

GRACEFUL_RESTART: str = 'GracefulRestart'

Shut down gracefully and power on.

GRACEFUL_SHUTDOWN: str = 'GracefulShutdown'

Shut down gracefully and power off.

ON: str = 'On'

Turn on the unit.

class spicerack.redfish.DellSCP(config: Dict, target: spicerack.redfish.DellSCPTargetPolicy, *, allow_new_attributes: bool = False)

Bases: object

Reprenset a Dell System Configuration Profile configuration as returned by Redfish API.

Parse the Redfish API response.

Parameters

• config (dict) -- the configuration as returned by Redfish API.

• target (spicerack.redfish.DellSCPTargetPolicy) -- describe which sections of the configuration are represented in the loaded configuration.

• allow_new_attributes (bool) -- when set to True it allows the creation of new attributes not already present in the provided configuration that otherwise would raise an exception. This is useful for example when changing the boot mode between Uefi and Bios that changes the keys present.

empty_components() → None

Empty the current Components from the configuration, allowing to create a new configuration from scratch.

After calling this method is possible to set values for non-existing components that would otherwise raise an exception.

set(component_name: str, attribute_name: str, attribute_value: str) → bool

Update the current configuration setting to the new value for the given key in the given component.

Notes

This updates only the instance representation of the instance. To push and apply the changes to the server see spicerack.redfish.RedfishDell.scp_push(). In order to add attributes not present the instance must have been created with allow_new_attributes set to True or the spicerack.redfish.DellSCP.empty_component() method called. This last one allows to automatically create any missing component while setting attributes.

Parameters

• component_name (str) -- the name of the component the settings belongs to.

• attribute_name (str) -- the attribute name whose value needs to be updated.

• attribute_value (str) -- the new value for the attribute to set.

Returns

True if the value was added or changed, False if it had already the correct value.

Return type

bool

Raises

• spicerack.redfish.RedfishError -- if unable to find the given component or attribute and the creation of new

• items is not allowed. --

update(changes: Dict[str, Dict[str, str]]) → bool

Bulk update the current configuration with the set of changes provided.

Notes

This updates only the instance representation of the instance. To push and apply the changes to the server see spicerack.redfish.RedfishDell.scp_push().

Parameters

changes (dict) -- a dictionary of changes to apply in the same format of the one returned by spicerack.redfish.DellSCP.components().

Returns

True if any of the values produced a change, False if no change was made.

Return type

bool

Raises

spicerack.redfish.RedfishError -- if unable to apply all the changes.

property comments: List[str]

Getter for the comments associated with the configuration.

property components: Dict[str, Dict[str, str]]

Getter for the components present in the configuration in a simplified view.

The returned dictionary where all the keys are recursively sorted and has the following format:

{
    '<component name>': {
        'key1': 'value1',
        'key2': 'value2',
    },
}

property config: Dict

Getter for the whole configuration in Dell's format.

property model: str

Getter for the device Dell's model.

property service_tag: str

Getter for the device Dell's Service Tag.

property target: spicerack.redfish.DellSCPTargetPolicy

Getter for the target that the current configuration represents.

property timestamp: datetime.datetime

Getter for the timestamp when the configuration dump was generated.

class spicerack.redfish.DellSCPPowerStatePolicy(value)

Bases: enum.Enum

Available Dell SCP (Server Configuration Profiles) final power state after an operation policies.

OFF: str = 'Off'

Keep the host powered off after the operation.

ON: str = 'On'

Turn the host power back on after the operation.

class spicerack.redfish.DellSCPRebootPolicy(value)

Bases: enum.Enum

Available Dell SCP (Server Configuration Profiles) reboot policies.

FORCED: str = 'Forced'

Issue an immediate hard reboot without notifying the operating system.

GRACEFUL: str = 'Graceful'

Issue a reboot notifying the operating system.

NO_REBOOT: str = 'NoReboot'

Do not reboot right now, the Redfish task will be pending the next reboot to apply the changes.

class spicerack.redfish.DellSCPTargetPolicy(value)

Bases: enum.Enum

Available sections of the Dell SCP (Server Configuration Profiles) to target.

ALL = 'ALL'

All settings.

BIOS = 'BIOS'

Only BIOS settings.

IDRAC = 'IDRAC'

Only iDRAC settings.

NIC = 'NIC'

Only network interfaces settings.

RAID = 'RAID'

Only RAID controller settings.

class spicerack.redfish.Redfish(fqdn: str, username: str, password: str, *, dry_run: bool = True)

Bases: object

Manage Redfish operations on a specific device.

Initialize the instance.

Parameters

• fqdn (str) -- the FQDN of the management console to connect to.

• username (str) -- the API username.

• password (str) -- the API password.

• dry_run (bool, optional) -- whether this is a DRY-RUN.

change_user_password(username: str, password: str) → None

Change the password for the account with the given username.

If the username matches the one used by the instance to connect to the API, automatically updates the instance value so that the instance will keep working.

Parameters

• username (str) -- the username to search for.

• password (str) -- the new password to set.

Raises

spicerack.redfish.RedfishError -- if unable to find the user or update its password.

chassis_reset(action: spicerack.redfish.ChassisResetPolicy) → None

Perform a reset of the chassis power status.

Parameters

action (spicerack.redfish.ChassisResetPolicy) -- the reset policy to use.

Raises

spicerack.redfish.RedfishError -- if unable to perform the reset.

check_connection() → None

Check the connection with the Redfish API.

Raises

spicerack.redfish.RedfishError -- if unable to connect to Redfish API.

find_account(username: str) → Tuple[str, str]

Find the account for the given username and return its URI.

Parameters

username (str) -- the username to search for.

Returns

a 2-element tuple with the the URI for the account and the ETag header value of the GET response.

Return type

tuple

Raises

spicerack.redfish.RedfishError -- if unable to find the account.

get_power_state() → str

Return the current power state of the device.

Returns

the power state.

Return type

str

poll_task(uri: str) → Dict

Poll a Redfish task until the results are available.

Parameters

uri (str) -- the URI of the task, usually returned as Location header by the originating API call.

Returns

the task results.

Return type

dict

Raises

• RedfishError -- if the response from the server is outside the expected values of HTTP 200 or 202.

• RedfishTaskNotCompletedError -- if the task is not yet completed.

request(method: str, uri: str, *, data: Optional[Dict] = None, headers: Optional[Dict] = None) → requests.models.Response

Perform a request against the target Redfish instance with the provided HTTP method and data.

Parameters

• uri (str) -- the relative URI to request.

• method (str) -- the HTTP method to use (e.g. "post").

• data (dict, optional) -- the data to send as JSON in the request.

• data -- the custom headers to set in the request.

Returns

the response.

Return type

requests.models.Response

Raises

• RedfishError -- if the response status code is between 400 and 600 or if the given uri does not start with

• a slash (/) or if the request couldn't be performed. --

submit_task(uri: str, data: Optional[Dict] = None) → str

Submit a request that generates a task, return the URI of the submitted task.

Parameters

• uri (str) -- the relative URI to request.

• data (dict, optional) -- the data to send in the POST request, if no data is provided a GET request is made.

Returns

the URI of the task ID to poll the results.

Return type

str

Raises

spicerack.redfish.RedfishError -- if the response status code is not 202 or there is no Location header.

class spicerack.redfish.RedfishDell(fqdn: str, username: str, password: str, *, dry_run: bool = True)

Bases: spicerack.redfish.Redfish

Dell specific Redfish support.

Initialize the instance.

Parameters

• fqdn (str) -- the FQDN of the management console to connect to.

• username (str) -- the API username.

• password (str) -- the API password.

• dry_run (bool, optional) -- whether this is a DRY-RUN.

scp_dump(target: spicerack.redfish.DellSCPTargetPolicy = DellSCPTargetPolicy.ALL, *, allow_new_attributes: bool = False) → spicerack.redfish.DellSCP

Dump and return the SCP (Server Configuration Profiles) configuration.

Parameters

• target (spicerack.redfish.DellSCPTargetPolicy, optional) -- choose which sections to dump.

• allow_new_attributes (bool) -- when set to True it allows the creation of new attributes not already present in the retrieved configuration that otherwise would raise an exception. This is useful for example when changing the boot mode between Uefi and Bios that changes the keys present.

Returns

the server's configuration.

Return type

spicerack.redfish.DellSCP

Raises

• spicerack.redfish.RedfishError -- if the API call fail.

• spicerack.redfish.RedfishTaskNotCompletedError -- if unable to fetch the dumped results.

scp_push(scp: spicerack.redfish.DellSCP, *, reboot: spicerack.redfish.DellSCPRebootPolicy = DellSCPRebootPolicy.NO_REBOOT, power_state: spicerack.redfish.DellSCPPowerStatePolicy = DellSCPPowerStatePolicy.ON, preview: bool = True) → Dict

Push the SCP (Server Configuration Profiles) configuration.

Parameters

• scp (spicerack.redfish.DellSCP) -- the configuration that will pushed to the server.

• reboot (spicerack.redfish.DellSCPRebootPolicy, optional) -- which reboot policy to use to apply the changes.

• power_state (spicerack.redfish.DellSCPPowerStatePolicy, optional) -- which final power state policy to use to apply to the host after the changes have been applied.

• preview (bool, optional) -- if True perform a test push of the SCP data. This will tell if the file parses correctly and would not result in any writes. The comments will tell if the new configuration would not produce any changes. Forces the reboot parameter to be spicerack.redfish.DellSCPRebootPolicy.NO_REBOOT.

Returns

the results of the push operation.

Return type

dict

Raises

• spicerack.redfish.RedfishError -- if the API call fail.

• spicerack.redfish.RedfishTaskNotCompletedError -- if unable to fetch the dumped results.