Source Documentation

Submodules

netapp.api module

exception netapp.api.APIError(message='', errno='{no error #}', failing_query=None)

Bases: Exception

An Exception logging an api-related error and its context. Note that an APIError typically occurs after a successful transfer of a command to the API itself.

Noteworthy properties are errno (error number), msg (error message) and failing_query (the XML query that was processed as the error occurred, if available).

__init__(message='', errno='{no error #}', failing_query=None)

class netapp.api.Aggregate(name, node_names, bytes_used, bytes_available)

Bases: tuple

bytes_available

Alias for field number 3

bytes_used

Alias for field number 2

name

Alias for field number 0

node_names

Alias for field number 1

netapp.api.DEFAULT_TIMEOUT = 4

Only consider these data fields for volumes

class netapp.api.Event(raw_event)

Bases: object

A nicer representation of a logging event. Should only be instantiated by the API functions (don’t roll your own!).

__init__(raw_event)

about = None

A string describing the event further.

arguments = {}

A dictionary representing key-value arguments. May vary between events.

category = None

The category of the event

condition = None

What condition the event is in

datetime = None

A timezone-aware datetime object describing the same date as timestamp

event_type = None

The type of the event

id = None

The internal ID of the event as given by the logger

impact_area = None

The event’s impact area

impact_level = None

The event’s impact level

name = None

The event’s canonical name

severity = None

The severity of the event: warning, information, critical, or error

source_name = None

The name of the resource that produced the event

source_resource_key = None

The key of the resource that produced the event

source_type = None

The type of source that produced the event

state = None

The current state of the event: NEW, OBSOLETE etc

timestamp = None

The UNIX timestamp the event was reported (as reported by the API)

netapp.api.LOCAL_TIMEZONE = 'Europe/Zurich'

The default connection timeout, in seconds

class netapp.api.Lock(volume, state, client_address)

Bases: tuple

client_address

Alias for field number 2

state

Alias for field number 1

volume

Alias for field number 0

class netapp.api.Server(hostname, username, password, port=443, transport_type='HTTPS', server_type='OCUM', app_name='netapp-api-python', timeout_s=4, vserver='')

Bases: object

The Server is a stateless, connectionless configuration container for a netapp monitoring system. There is no need for closing it, but if you want to, a close() function is available to terminate the connection. All API calls are made on event access etc.

It implements a subset of the official NetApp API related to events.

See docstrings for __init__ for more information on instantiation.

class EventLog(server)

Bases: object

An iterator over all the storage engine’s events. Will (by default) iterate over all events, but may optionally filter out events by ID.

__init__(server)

filter(**kwargs)

Return an Iterator over items matching the specified filter queries, passed in as keyword arguments. Available filters/keywords are:

Parameters:

• severities – information, warning, error, critical. Raises an Exception if none of these. Options are case-insensetive strings.
• states – NEW, OBSOLETE etc
• greater_than_id – only show events with ID:s greater than (e.g. logged after) the given one.
• time_range – tuple of start, end timestamp in local time Unix timestamps. Timestamps are inclusive.
• max_records – paginate results with max_records as the maximum number of entries. Will make several queries!
• source – Lists events against the specified source resource key. If the provided resource key specifies a group, lists events against all members in that group.
• timout – Timeout in seconds, after which the query will return an empty results if nothing was found. Defaults to 0 if not provided, or if a time interval was provided.

single_by_id(id)

Return a specific single event with a given ID. Raises a KeyError if no such event exists.

class ExportPolicy(name, server)

Bases: object

A wrapper object for an export policy with the sole purpose of providing lazy access to rules.

Very internal.

__init__(name, server)

name = None

rules

class VolumeList(server)

Bases: object

__init__(server)

filter(max_records=None, **query)

Usage:

filter(name=’my-volume’)

An empty filter matches every volume.

It is only possible to match on volume-id-attributes, most notably ‘uuid’, ‘junction_path’ and ‘name’. Underscores will be converted to hyphens.

max_records is (analogous to the same option for events.filter) the maximum number of entries to return in each fetch operation. Pagination and incremental fetch will be done automatically under the hood.

make_volume(attributes_list)

single(volume_name, vserver=None)

Return a single volume, raising a IndexError if no volume matched.

__init__(hostname, username, password, port=443, transport_type='HTTPS', server_type='OCUM', app_name='netapp-api-python', timeout_s=4, vserver='')

Instantiate a new server connection. Provided details are:

Parameters:

• hostname – the hostname of the server (or IP number)
• transport_type – HTTP or HTTPS (default is HTTPS)
• server_type – only OCUM currently supported
• app_name – the name of the calling app, as reported to the server
• timeout_s – The timeout in seconds for each connection to a NetApp filer. Passed as-is to Requests.
• vserver – The virtual server to use, if any.

add_export_rule(policy_name, rule, index=1)

Add a new export rule to policy_name.

If no index is provided, add the rule to the head of the list (lowest priority).

aggregates

A Generator of named tuples describing aggregates on the cluster.

If in vserver mode, list that vserver’s aggregates. If in cluster mode, list the entire cluster’s aggregates.

break_lock(volume_name, client_address)

Break any locks on volume_name held by client_address.

Raises an APIError if there was no such lock or no such volume.

clone_volume(parent_volume_name, clone_name, junction_path, parent_snapshot=None)

Clone an existing volume parent_volume_name into clone_name and onto junction_path.

If parent_snapshot is true, use that snapshot as the base for the clone.

close()

Close any open connection to the server. The Server object becomes unusable after this.

create_export_policy(policy_name, rules=None)

Create a new export policy named policy_name, optionally with rules rules (otherwise, use whatever is default).

create_snapshot(volume_name, snapshot_name)

Create a new snapshot (if possible).

Raises APIError if there is no more room to create snapshots.

create_volume(name, size_bytes, aggregate_name, junction_path, export_policy_name=None, percentage_snapshot_reserve=0, compression=True, inline_compression=True, caching_policy=None)

Create a new volume on the NetApp cluster

size_bytes is assumed to be in bytes, but if given as a string with a suffix (“k”, “m”, “g” or “t” for kilobytes, megabytes, gigabytes and terabytes respectively), use that suffix.

delete_export_policy(policy_name)

Delete the export policy named policy_name, and all its rules.

delete_snapshot(volume_name, snapshot_name)

Delete the snapshot named snapshot_name.

destroy_volume(volume_name)

Permamently delete a volume. Must be offline.

events

A gettable-only property representing all events known to the server. Performs eager HTTP fetch on every read. Corresponds to an empty filter call.

export_policies

Read-only-property: return a list of registered export policy names.

export_rules_of(policy_name)

Return the rules of the policy as a list of index, rule tuples. Note that order matters here!

Access to the property is lazy, but the list of rules is materialised immediately.

extract_failures(result)

In the case of a call (as returned from perform_call()) that returns a <failure-list>, extract these as a generator.

Returns (well, generates):

a list of tuples of error_code, message, if any. Empty list if not.

locks_on(volume_name)

Return a list of locks (possibly empty) held on the volume volume_name.

ocum_version

The OCUM API version as a string.

ontap_system_version

The system version as a string.

ontapi_version

Return the ONTAPI version as major.minor.

perform_call(api_call, api_url)

Perform an API call as represented by the provided XML data, returning a tuple of next_tag, records, where next_tag is None if there were no further pages.

It is assumed that the response will be a list of entries in container_tag:

<container_tag>

<data-entry></data-entry> <data-entry></data-entry>

</container_tag>

If container_tag is not provided, perform a fire-and-forget call that will discard any returned data and not perform any extraction.

Raises an APIError on erroneous API calls. Please note that calls performing batch-operations that return errors in a <failure-list> will return their results without triggering APIErrors, as the call itself has technically (by NetApp’s definition) succeeded.

raise_on_non_single_answer(result)

remove_export_rule(policy_name, index)

Remove an export rule with a given index and re-number the following indices (e.g. decrement by one).

resize_volume(volume_name, new_size)

Resize the volume. Size follows the same conventions as for create_volume.

restrict_volume(volume_name)

Unmount and restrict a volume.

rollback_volume_from_snapshot(volume_name, snapshot_name)

Roll back volume_name to its previous state snapshot_name.

set_compression(volume_name, enabled=True, inline=True)

set_volume_autosize(volume_name, autosize_enabled, max_size_bytes=None, increment_bytes=None)

Update the autosize properties of volume_name.

set_volume_caching_policy(volume_name, policy_name)

Set a volume’s caching policy. Note that this is _different_ from flexcache policies. The NetApp manual is not exactly clear on this, but this is the same attribute as cache-policy when creating volumes.

set_volume_export_policy(volume_name, policy_name)

Set the export policy of a given volume

set_volume_snapshot_reserve(volume_name, reserve_percent)

Set a volume’s reserved snapshot space (in percent).

snapshots_of(volume_name)

A generator over names of snapshots of the given volume.

Might return no elements if there are no snapshots.

supported_apis

Return the list of API names supported by the server.

Only works on ONTAPI servers.

take_volume_offline(volume_name)

Take a volume offline. Must be unmounted first.

Warning: will take all volumes with that name offline. Make sure you are on the correct vserver using with_vserver() or similar!

unmount_volume(volume_name)

Unmount a volume

volume_modify_iter(volume_name, *attributes)

Make a call to volume-modify-iter with the provided attributes.

volumes

A gettable-only porperty representing all the volumes on the filer.

vservers

A Generator of named tuples describing vservers on the cluster.

with_vserver(vserver)

A Context to temporarily set the vserver/vfiler (it’s the same thing) during a set of operations, and then reset it to cluster mode (or whatever vserver it was configured to use previously) again.

Needed for several operations, among others volume creation.

Example:

# Assumption: s is a ONTAPI server object with no vserver set.

with s.with_vserver("vsrac11"):
    s.create_volume(...) # succeeds
    s.aggregates # fails

s.create_volume(...) # fails
s.aggregates # succeeds

If vserver is none or the empty string, switch to cluster mode.

class netapp.api.Snapshot(name, creation_time, size_kbytes)

Bases: tuple

creation_time

Alias for field number 1

name

Alias for field number 0

size_kbytes

Alias for field number 2

class netapp.api.Volume(raw_object, compression, inline)

Bases: object

A volume in the NetApp storage system.

Do not roll your own.

__init__(raw_object, compression, inline)

class netapp.api.Vserver(name, state, uuid, aggregate_names)

Bases: tuple

aggregate_names

Alias for field number 3

name

Alias for field number 0

state

Alias for field number 1

uuid

Alias for field number 2

netapp.vocabulary module

This is an XML vocabulary for generating queries against NetApp’s API.

It has intentionally been kept very close to the original representation, and syntactic sugar or wrapping has been kept to a minimum to avoid confusion in the event of API changes.

Examples

The following Python code:

netapp(event_iter(event_id("17"),
                  timetout("4")),
       xmlns="http//my-namespace.com/xml",
       version="1.0"
       nmsdk_app="test-app")

Will produce this XML:

<netapp xmlns="http://my-namespace.com/xml" version="1.0"
        nmsdk_app="test-app">
    <event-iter>
        <event-id>17</event-id>
        <timeout>4</timeout>
    </event-iter>
</netapp>

netapp.vocabulary.end_time(end_timestamp)

A container tag for an ending timestamp. See time_range for examples.

netapp.vocabulary.event_id(id)

Value container for an event ID: <event-id>17</event-id>.

netapp.vocabulary.event_iter(*children)

Generate an <event-iter>[children]</event-iter> tag.

netapp.vocabulary.event_severities(*severities)

One or more event severities, returns something like:

<event-severity>
    <obj-status>critical</obj-status>
    <obj-status>important</obj-status>
</event-severity>

Children needs to be <obj-status>:es containing Severity strings.

Cannot be empty.

netapp.vocabulary.event_state(state_description)

Value container for an event state: <event-state>NEW</event-state>.

netapp.vocabulary.event_state_filter_list(*states)

A container for at least one <event-state> tag to filter on.

netapp.vocabulary.event_timestamp_range(start_time, end_time)

The inner wrapper tag for an event time range. See time_range for example!

netapp.vocabulary.greater_than_id(id)

Generate an <greater-than-id>id</greater-than-id> tag.

netapp.vocabulary.max_records(max_number_records)

Value container for a maximum number of records option: <max-records>17</max-records>.

netapp.vocabulary.netapp = functools.partial(<lxml.builder.ElementMaker object>, 'netapp')

The root element for any query.

netapp.vocabulary.obj_status(status)

The contents of an <event-severity> tag, a String representing a status.

Example values:

• <obj-status>CRITICAL</obj-status>
• <obj-status>WARNING</obj-status>

netapp.vocabulary.source = functools.partial(<lxml.builder.ElementMaker object>, 'source')

Resource or group.

netapp.vocabulary.start_time(start_timestamp)

A container tag for a starting timestamp. See time_range for examples.

netapp.vocabulary.tag = functools.partial(<lxml.builder.ElementMaker object>, 'tag')

The tag from the last call, if processing paginated data.

netapp.vocabulary.time_range(timestamp_range)

The outer wrapper (!) for an <event-timestamp-range> element.

Example:

<time-range>
    <event-timestamp-range>
        <end-time>17</end-time>
        <start-time>23</start-time>
    </event-timestamp-range>
</time-range>

netapp.vocabulary.timeout = functools.partial(<lxml.builder.ElementMaker object>, 'timeout')

The timeout for an operation: <timeout>x</timeout>.