ecsminion 0.6.8

ECS Minion
==========

ECS Minion is a Python library for interacting with the ECS 2.x Management API
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. image:: https://travis-ci.org/chadlung/ecsminion.svg?branch=master
:target: https://travis-ci.org/chadlung/ecsminion

**Note:** `ECS <https://www.emc.com>`__ is an EMC product,
trademarked, copyrighted, etc.

This library follows the ECS API documentation `located here. <https://www.emc.com/techpubs/api/ecs/v2-0-0-0/index.htm>`__

Using this library is pretty straight forward. ECSMinion can be installed
from `PyPi <http://pypi.python.org/>`__:

::

$ pip install ecsminion

Creating an instance of the ECSMinion class allows the following
arguments:

+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Required | Default Value | Description |
+=======================+============+===================+===============================================================================================================================================+
| ``username`` | No | None | The username used to fetch the ECS token |
+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``password`` | No | None | The password used to fetch the ECS token |
+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``token`` | No | None | Pass a token to ECSMinion (username/password are ignored then) |
+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``ecs_endpoint`` | Yes | None | The ECS API endpoint, ex: ``https://192.168.0.149:4443`` |
+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``token_endpoint`` | Yes | None | The ECS API endpoint, ex: ``https://192.168.0.149:4443/login`` |
+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``verify_ssl`` | No | False | Whether to check a host's SSL certificate |
+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``token_filename`` | No | ``ecstoken.tkn`` | The filename of the temporary token |
+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``token_location`` | No | ``/tmp`` | The location to store the temporary token file |
+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``request_timeout`` | No | 15.0 | Stop waiting for a response after a given number of seconds, this is a decimal value. Ex: 10.0 is ten seconds |
+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``cache_token`` | No | True | Whether to cache the token, by default this is true you should only switch this to false when you want to directly fetch a token for a user |
+-----------------------+------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+

Here is an example that goes through most of the API calls. Please note
that some calls take longer to complete than others. Sometimes you may
need to set your ``request_timeout`` to ``60.0``.

::

from ecsminion import ECSMinion, ECSMinionException

try:
client = ECSMinion(username='ecsadmin@internal',
password='PASSWORD',
token_endpoint='https://192.168.0.149:4443/login',
ecs_endpoint='https://192.168.0.149:4443',
request_timeout=15.0)

print(client.user_info.whoami())

# Configuration
print(client.certificate.get_certificate_chain())
print(client.configuration_properties.get_properties(category='ALL'))
print(client.configuration_properties.get_properties_metadata())
print(client.licensing.add_license(license=data_dict))
print(client.licensing.get_license())

# User Management
print(client.secret_key.create_new_secret_key('user1'))
print(client.secret_key.get_user_secret_keys(uid='user1'))
print(client.secret_key.get_user_secret_keys(
uid='user1', namespace='namespace1'))
print(client.user_object.get_object_users('namespace1'))
print(client.user_object.get_object_user_info('user1'))
print(client.user_object.get_object_user_info('user1', 'namespace1'))
print(client.user_object.add_object_user(
uid='user2', namespace='namespace1', tags=['mytag1', 'mytag1']))
print(client.user_object.deactivate_object_user(
uid='user2', namespace='namespace1'))
print(client.user_object.get_object_user_info('user1'))
print(client.user_object.lock_object_user('user1', True, 'namespace1'))
print(client.user_object.get_object_user_lock('user1', 'namespace1'))
print(client.user_object.lock_object_user('user1', False, 'namespace1'))
print(client.user_object.get_object_user_lock('user1', 'namespace1'))
print(client.authentication_provider.get_authentication_providers())
print(client.authentication_provider.get_authentication_provider(
'urn:AuthProvider:317843ad-71eb-4a86-b1bd-806f4275008a'))

# Support
print(client.call_home.get_connectemc_config())

# Multi-tenancy
print(client.namespace.get_namespaces())
print(client.namespace.get_namespaces('namespace1'))
print(client.namespace.get_retention_classes('namespace1'))
print(client.namespace.create_retention_class('the-name', 2, 'namespace2'))
print(client.namespace.update_retention_class('the-name', 199, 'namespace2'))
print(client.namespace.get_namespace_quota('namespace1'))
print(client.namespace.update_namespace_quota(2, 2, 'namespace1'))

# Monitoring
print(client.capacity.get_cluster_capacity())
print(client.events.get_audit_events(
'2015-06-08T01:00', '2015-06-09T00:00', 'namespace1'))
# With a marker and a limit param (marker has been shortened)
print(client.events.get_audit_events(
'2015-06-08T01:00', '2015-06-09T00:00', 'namespace1', limit=3,
marker='CIbS7YbdKRI4dXJuOnN0bTRkYzYtOWUxNy03MGFkYzAzMWUxNDQ='))
# Only a few of the dashboard APIs are shown, there are more
print(client.dashboard.get_local_zone())
print(client.dashboard.get_local_zone_replication_groups())
print(client.dashboard.get_local_zone_rglinks_failed())
print(client.dashboard.get_local_zone_storage_pools())
print(client.dashboard.get_local_zone_nodes())
print(client.dashboard.get_node_processes('172.29.3.148'))
print(client.dashboard.get_local_zone_replication_group_bootstrap_links())

# Provisioning
print(client.node.get_nodes())
print(client.bucket.create_bucket(bucket_name='bucket-test1', namespace='namespace1'))
print(client.bucket.deactivate_bucket(bucket_name='bucket-test1', namespace='namespace1'))
print(client.bucket.get_buckets(namespace='namespace1'))
print(client.bucket.set_bucket_retention(bucket_name='bucket-test1', namespace='namespace1'))
print(client.bucket.get_bucket_retention(bucket_name='bucket-test1', namespace='namespace1'))
print(client.bucket.get_bucket_info(bucket_name='bucket-test1', namespace='namespace1'))
print(client.bucket.update_bucket_owner(bucket_name='bucket-test1', new_owner='user2', namespace='namespace1'))
print(client.bucket.update_bucket_is_stale_allowed(bucket_name='bucket-test1', is_stale_allowed=False, namespace='namespace1'))
print(client.bucket.get_bucket_lock(bucket_name='bucket-test1', namespace='namespace1'))
# For the following is_locked must be passed as 'true' or 'false', not True/False
print(client.bucket.set_lock_bucket(bucket_name='bucket-test1', is_locked='false', namespace='namespace1'))
print(client.bucket.update_bucket_quota(bucket_name='bucket-test1', block_size=1, notification_size=2, namespace='namespace1'))
print(client.bucket.get_bucket_quota(bucket_name='bucket-test1', namespace='namespace1'))
print(client.bucket.delete_bucket_quota(bucket_name='bucket-test1', namespace='namespace1'))
print(client.bucket.get_bucket_acl(bucket_name='bucket-test1', namespace='namespace1'))
print(client.bucket.get_acl_permissions())
print(client.bucket.get_acl_groups())
print(client.base_url.get_all_configured_base_urls())
print(client.base_url.get_base_url('urn:ObjectBaseUrl:6c74e6fb-a2a1-4386-bc25-b4399a6e74ce'))
print(client.base_url.create_base_url('TestBaseURL', 'test.com', False))
print(client.base_url.modify_base_url('urn:ObjectBaseUrl:19c391eb-37f4-4c65-a7a9-474668f71607',
'SomeBaseURL', 'test.org', False))
print(client.base_url.delete_base_url('urn:ObjectBaseUrl:19c391eb-37f4-4c65-a7a9-474668f71607'))
print(client.data_store.get_data_store_list())
print(client.data_store.get_commodity_data_store_associated_wth_storage_pool('192.29.3.51'))
print(client.data_store.get_commodity_data_store_associated_wth_varray('urn:storageos:VirtualArray:3c4e8cca-2e3d-4f8d-b183-1c69ce2d5b37'))
print(client.storage_pool.get_virtual_array('urn:storageos:VirtualArray:3c4e8cca-2e3d-4f8d-b183-1c69ce2d5b37'))
print(client.storage_pool.get_virtual_arrays('urn:storageos:VirtualDataCenterData:a9faea85-d377-4a42-b5f1-fa15829f0c33'))
print(client.virtual_data_center.get_all_vdcs())
print(client.virtual_data_center.get_vdc_by_id('urn:storageos:VirtualDataCenterData:a9faea85-d377-4a42-b5f1-fa15829f0c33'))
print(client.virtual_data_center.get_local_vdc())
print(client.virtual_data_center.get_local_vdc_secret_key())
print(client.virtual_data_center.get_vdc_by_name('tiva01'))
print(client.virtual_data_center.insert_vdc_attributes('vdc1', '10.247.179.200', '1234secret'))
print(client.virtual_data_center.deactivate_vdc('urn:storageos:VirtualDataCenterData:a9faea85-d377-4a42-b5f1-fa15829f0c33'))
print(client.management_object.create_local_user_info('newadminuser', 'password', True, True))
print(client.management_object.modify_local_user_info('newadminuser', 'password2', False, True))
print(client.management_object.delete_local_user_info('newadminuser'))
print(client.management_object.get_local_management_users())
print(client.management_object.get_local_user_info('admin'))

# Geo Replication
print(client.replication_group.get_replication_groups())
print(client.replication_group.get_replication_group(
'urn:storageos:ReplicationGroupInfo:c2b0d3c4-c778-4a24-8da5-6a89784c4eeb:global'))
print(client.replication_group.update_replication_group(
'urn:storageos:ReplicationGroupInfo:c2b0d3c4-c778-4a24-8da5-6a89784c4eeb:global',
'a-name' 'the-description', True)
print(client.temp_failed_zone.get_all_temp_failed_zones())
print(client.temp_failed_zone.get_temp_failed_zone(
'urn:storageos:ReplicationGroupInfo:c2b0d3c4-c778-4a24-8da5-6a89784c4eeb:global'))

# Metering/Billing
print(client.billing.get_bucket_billing_info('bucket-test', 'namespace1'))
print(client.billing.get_namespace_billing_info('namespace1', include_bucket_detail=True))
print(client.billing.get_namespace_billing_sample(
'namespace1', start_time='2015-06-15T00:00',
end_time='2015-06-15T1:00', include_bucket_detail=True))
print(client.billing.get_bucket_billing_sample(
'bucket-test', 'namespace1',
start_time='2015-06-15T00:00', end_time='2015-06-15T1:00'))

except ECSMinionException as ecsminion_ex:
print('Message: {0}'.format(ecsminion_ex.message))
print('Status Code Returned: {0}\n'.format(ecsminion_ex.http_status_code))
print('ECS API Message: {0}'.format(ecsminion_ex.ecs_message))
except Exception as ex:
print(ex.message)

Example: Uploading an ECS license
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

According to ECS API documentation, a call to ``POST /license`` should contain
a payload like the following:

::

{
"license_feature": [
{
"serial": "",
"version": "",
"issued_date": "",
"expiration_date": "",
"model": "",
"product": "",
"site_id": "",
"issuer": "",
"notice": "",
"licensed_ind": "",
"expired_ind": "",
"license_id_indicator": "",
"error_message": "",
"storage_capacity_unit": "",
"storage_capacity": "",
"trial_license_ind": ""
}
],
"license_text": ""
}

Thus, if you consume a JSON file with such license data, you may upload it
using the ``licensing.add_license()`` method:

::

import json
import pprint

pp = pprint.PrettyPrinter()

try:
with open("ECS2.1_License.json") as data:
license = json.load(data)

pp.pprint(client.licensing.add_license(license))

except ValueError as val_ex: # includes simplejson.decoder.JSONDecodeError
print("Couldn't parse JSON data: {0}".format(val_ex.message))
except ECSMinionException as ecsminion_ex:
print('Message: {0}'.format(ecsminion_ex.message))
print('Status Code Returned: {0}\n'.format(ecsminion_ex.http_status_code))
print('ECS API Message: {0}'.format(ecsminion_ex.ecs_message))
except Exception as ex:
print(ex.message)

Example: Enable logging output
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ECSMinion leverages the Python ``logging`` module. Enable it from your
application like so:

::

import logging

# Default to INFO level logging
logging.basicConfig()
logging.getLogger().setLevel(logging.INFO)

Now ECSMinion will tell you about what it's doing (and so will the
``requests`` library). If you'd like even more information about the
HTTP requests and headers, use the following:

::

import logging
import httplib

# Default to DEBUG level logging
logging.basicConfig()
logging.getLogger().setLevel(logging.DEBUG)

# Show HTTP headers and payloads
httplib.HTTPConnection.debuglevel = 1

If you don't want to see *any* ``requests`` logging, either filter it with
a ``logging`` filter or change the logging level for just that library:

::

import logging

# Default to INFO level logging
logging.basicConfig()
logging.getLogger().setLevel(logging.INFO)

# Only show errors from requests lib
logging.getLogger('requests.packages.urllib3').setLevel(logging.ERROR)


Example: Use a valid token instead of supplying a username and password
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You pass an authentication token directly to ECSMinion which means you
don't need to supply a username/password. Here is an example (the token
has been shortened):

::

client = ECSMinion(token='ALAcbGZtbjh6eVB3eUF1TzFEZWNmc0M2VVl2QjBVPQM',
token_endpoint='https://192.168.1.146:4443/login',
ecs_endpoint='https://192.168.1.146:4443',
request_timeout=15.0)

Example: Fetching tokens
^^^^^^^^^^^^^^^^^^^^^^^^

Fetching a token for a user can be done as follows by setting the
``cache_token`` parameter to false and then calling ``get_token``:

::

from ecsminion import ECSMinion, ECSMinionException


if __name__ == "__main__":
try:
client = ECSMinion(username='someone',
password='password',
token=None,
token_endpoint='https://192.168.1.146:4443/login',
ecs_endpoint='https://192.168.1.146:4443',
request_timeout=15.0,
cache_token=False)

print(client.get_token())

except ECSMinionException as ecsminion_ex:
print('Message: {0}'.format(ecsminion_ex.message))
print('Status Code Returned: {0}\n'.format(ecsminion_ex.http_status_code))
print('ECS API Message: {0}'.format(ecsminion_ex.ecs_message))
except Exception as ex:
print(ex.message)

Example: Removing a cached token
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

from ecsminion import ECSMinion, ECSMinionException


if __name__ == "__main__":
try:
client = ECSMinion(username='someone',
password='password',
token=None,
token_endpoint='https://192.168.1.146:4443/login',
ecs_endpoint='https://192.168.1.146:4443',
request_timeout=15.0,
cache_token=False)

print(client.remove_cached_token())

except ECSMinionException as ecsminion_ex:
print('Message: {0}'.format(ecsminion_ex.message))
print('Status Code Returned: {0}\n'.format(ecsminion_ex.http_status_code))
print('ECS API Message: {0}'.format(ecsminion_ex.ecs_message))
except Exception as ex:
print(ex.message)

License
^^^^^^^

This software library is released to you under the Apache License 2.0. See
`LICENSE <https://github.com/chadlung/ecsminion/blob/master/LICENSE>`__
for more information.