Skip to main content

A library for interacting with the ECS 2.x Management API

Project description

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for ecsminion, version 0.6.8
Filename, size File type Python version Upload date Hashes
Filename, size ecsminion-0.6.8.tar.gz (31.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page