diff --git a/README.rst b/README.rst index 018f6297e..e23198627 100644 --- a/README.rst +++ b/README.rst @@ -21,15 +21,18 @@ packages. Documentation ------------- -* `Documentation ` +`Documentation Overview `_ Installation ------------ +`Installation Page `_ + The OTC Extensions are hosted as the package `otcextensions` on PyPI and can be installed by pip as .. code-block: console + $ pip install otcextensions There are several options @@ -38,10 +41,11 @@ installation as well as installation from operating system packets or directly from source. Refer to the installation instructions_ in the projects documentation. - Configuration ------------- +`Configuration Page `_ + Acessing the Open Telekom Cloud APIs requires authentication and authorization. For both there are several options available: @@ -58,26 +62,28 @@ authorization. For both there are several options available: .. code-block:: yaml - clouds: - otc: - profile: otc - auth: - username: "*username*" - password: "*password*" - project_name: "eu-de" - auth_url: "https://iam.eu-de.otc.t-systems.com:443/v3" - user_domain_name: "*OTC00000000001000000xxx*" - interface: "public" - identity_api_version: 3 - ak: "*40 digit access key*" - sk: "*20 digit secure key*" + clouds: + otc: + profile: otc + auth: + username: '' + password: '' + project_name: '' + # or project_id: '<123456_PROJECT_ID>' + user_domain_name: 'OTC00000000001000000xxx' + # or user_domain_id: '<123456_DOMAIN_ID>' + auth_url: 'https://iam.eu-de.otc.t-systems.com:443/v3' + interface: 'public' + identity_api_version: 3 # !Important + ak: '' # AK/SK pair for access to OBS + sk: '' With this configuration you can start using the CLI with ``openstack --os-cloud otc *command*`` or by ``export OS_CLOUD=otc; openstack *command*``. * **Environment variables:** Authentication using username/password is often - used: + used:: export OS_AUTH_URL= export OS_IDENTITY_API_VERSION=3 @@ -89,7 +95,6 @@ authorization. For both there are several options available: export S3_ACCESS_KEY_ID= export S3_SECRET_ACCESS_KEY= - * **Command-Line Options:** The corresponding command-line options look very similar:: @@ -111,7 +116,7 @@ authorization. For both there are several options available: export OS_TOKEN= export OS_URL= -The corresponding command-line options look very similar:: +* The corresponding command-line options look very similar:: --os-token --os-url @@ -123,16 +128,20 @@ https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html or https://developer.openstack.org/sdks/python/openstacksdk/users/config +OTC Extensions CLI Usage +------------------------ + +`OTCE CLI Command Overview `_ -Writing Own Code ----------------- +OTC Extensions SDK Guides +------------------------- -XXX Example XXXX +`OTCE SDK Guides `_ Contributing ------------ -See CONTRIBUTING.rst +* `Contribution Page `_ Further Links ------------- @@ -140,4 +149,3 @@ Further Links * `Issue Tracker `_ .. _instructions: http://python-otcextensions.readthedocs.io/en/latest/install/ - diff --git a/doc/source/cli/ces.rst b/doc/source/cli/ces.rst new file mode 100644 index 000000000..640e381b7 --- /dev/null +++ b/doc/source/cli/ces.rst @@ -0,0 +1,43 @@ +Cloud Eye Service (CES) +======================= + +The CES client is the command-line interface (CLI) for +the Cloud Eye Service (CES) API and its extensions. + +For help on a specific `ces` command, enter: + +.. code-block:: console + + $ openstack ces help SUBCOMMAND + +.. _alarm: + +Alarm Rule Operations +--------------------- + +.. autoprogram-cliff:: openstack.ces.v1 + :command: ces alarm * + +.. _metric: + +Metric Operations +----------------- + +.. autoprogram-cliff:: openstack.ces.v1 + :command: ces metric * + +.. _quota: + +Quota Operations +---------------- + +.. autoprogram-cliff:: openstack.ces.v1 + :command: ces quota * + +.. _event_data: + +Event Data Operations +--------------------- + +.. autoprogram-cliff:: openstack.ces.v1 + :command: ces event data * diff --git a/doc/source/cli/identity.rst b/doc/source/cli/identity.rst new file mode 100644 index 000000000..d87454569 --- /dev/null +++ b/doc/source/cli/identity.rst @@ -0,0 +1,19 @@ +Identity Service (IAM) +====================== + +The Identity client is the command-line interface (CLI) for +the Identity Service (IAM) API and its extensions. + +For help on a specific `identity` command, enter: + +.. code-block:: console + + $ openstack identity help SUBCOMMAND + +.. _identity_credential: + +Identity Credential Operations +------------------------------ + +.. autoprogram-cliff:: openstack.identity.v3 + :command: identity credential * diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index 57414f124..7cd2bca7a 100644 --- a/doc/source/cli/index.rst +++ b/doc/source/cli/index.rst @@ -26,11 +26,13 @@ documentation of these services: anti_ddos auto_scaling cce_v2 + ces cts dcs deh dms dns + identity kms load_balancer nat diff --git a/doc/source/coverage.rst b/doc/source/coverage.rst index 7a92a6940..48fd4548b 100644 --- a/doc/source/coverage.rst +++ b/doc/source/coverage.rst @@ -44,8 +44,8 @@ under several service tags. This may change in future. * - ces - Cloudeye - X - - - - + - X + - X - * - cts - Clout Trace Service diff --git a/doc/source/enforcer.py b/doc/source/enforcer.py index 7c6d46953..9d17ff323 100644 --- a/doc/source/enforcer.py +++ b/doc/source/enforcer.py @@ -42,6 +42,7 @@ def get_proxy_methods(): names = ["otcextensions.sdk.anti_ddos.v1._proxy", "otcextensions.sdk.auto_scaling.v1._proxy", "otcextensions.sdk.cce.v1._proxy", + "otcextensions.sdk.ces.v1._proxy", "otcextensions.sdk.cts.v1._proxy", "otcextensions.sdk.dcs.v1._proxy", "otcextensions.sdk.dms.v1._proxy", diff --git a/doc/source/sdk/guides/ces.rst b/doc/source/sdk/guides/ces.rst new file mode 100644 index 000000000..f4916caea --- /dev/null +++ b/doc/source/sdk/guides/ces.rst @@ -0,0 +1,115 @@ +Cloud Eye Service (CES) +========================= + +Cloud Eye (CES) is a high-performance monitoring service with integrated +alarm functions. Open Telekom Cloud users benefit from a dashboard with +a basic overview of resources and their current status. Users can +configure the alarm function in such a way that they receive +notifications via SMS or email. Monitoring with the Cloud Eye Service +is activated by default; the free service does not need to be booked +or activated. + +.. contents:: Table of Contents + :local: + +CES Alarm Rule +-------------- + +The alarm function is based on collected metrics. You can set alarm rules for +key metrics of cloud services. When the metric data triggers the conditions +set in the alarm rule, Cloud Eye sends emails, or text messages, to you, or +sends HTTP/HTTPS requests to the servers. In this way, you are immediately +informed of cloud service exceptions and can quickly handle the faults to +avoid service losses. + +Cloud Eye uses the SMN service to notify users. This +requires you to create a topic and add subscriptions to this topic on the +SMN console first. Then when you create alarm rules, you can enable the +Alarm Notification function and select the created topic. When an error +occurs, Cloud Eye can broadcast alarm information to those subscriptions in +real time. + + +Create Alarm Rule +^^^^^^^^^^^^^^^^^ + +This interface is used to create a CES alarm with parameters. + +.. literalinclude:: ../examples/ces/create_alarm.py + :lines: 16-89 + +Get Alarm Rule +^^^^^^^^^^^^^^ + +This interface is used to get a CES alarm rule by name or ID or an instance of +class :class:`~otcextensions.sdk.ces.v1.alarm.Alarm`. + +.. literalinclude:: ../examples/ces/get_alarm.py + :lines: 16-24 + +Delete Alarm Rule +^^^^^^^^^^^^^^^^^ + +This interface is used to delete a CES Alarm Rule instance by id +or an instance of class +:class:`~otcextensions.sdk.cts.v1.tracker.Tracker`. + +.. literalinclude:: ../examples/ces/delete_alarm.py + :lines: 16-25 + +Switch Alarm Rule State +^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to switch the Alarm Rule State by using name or id. + +.. literalinclude:: ../examples/ces/switch_alarm_state.py + :lines: 16-25 + + +Monitoring Data Management +-------------------------- + +Monitoring / Metric data is used to generate and query custom monitoring +data. + +List Metric Data +^^^^^^^^^^^^^^^^ + +This interface is used to query all CES metric data and to filter +the output with query parameters. + +.. literalinclude:: ../examples/ces/list_metric_data.py + :lines: 16-34 + + +Miscellaneous +------------- + +List Metrics +^^^^^^^^^^^^ + +This API is used to query the metric list. You can specify the namespace, +metric, dimension, sorting order, start records, and the maximum number of +records when using this API to query metrics. + +.. literalinclude:: ../examples/ces/list_metrics.py + :lines: 16-23 + +List Quotas +^^^^^^^^^^^ + +This API is used to query a resource quota and the used amount. The current +resource refers to alarm rules only. + +.. literalinclude:: ../examples/ces/list_quotas.py + :lines: 16-23 + +List Host Configuration / Event Data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This API is used to query the host configuration for a specified event type +in a specified period of time. You can specify the dimension of data to be +queried. + +.. literalinclude:: ../examples/ces/list_event_data.py + :lines: 16-32 diff --git a/doc/source/sdk/guides/index.rst b/doc/source/sdk/guides/index.rst index 04f39aab3..9aab4c3cc 100644 --- a/doc/source/sdk/guides/index.rst +++ b/doc/source/sdk/guides/index.rst @@ -10,6 +10,7 @@ Open Telekom Cloud related User Guides anti_ddos auto_scaling cce + ces cts dcs deh diff --git a/doc/source/sdk/proxies/ces.rst b/doc/source/sdk/proxies/ces.rst new file mode 100644 index 000000000..d3e71f29f --- /dev/null +++ b/doc/source/sdk/proxies/ces.rst @@ -0,0 +1,34 @@ +CES API +======= + +.. automodule:: otcextensions.sdk.ces.v1._proxy + +The Cloud Eye Service Class +--------------------------- + +The CES high-level interface is available through the ``ces`` +member of a :class:`~openstack.connection.Connection` object. The +``ces`` member will only be added if the +``otcextensions.sdk.register_otc_extensions(conn)`` method is called. + +Alarm Rule Operations +^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: otcextensions.sdk.ces.v1._proxy.Proxy + :noindex: + :members: alarms, get_alarm, create_alarm, delete_alarm, find_alarm, + switch_alarm_state + +Monitoring Data Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: otcextensions.sdk.ces.v1._proxy.Proxy + :noindex: + :members: metric_data + +Miscellaneous Operations +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: otcextensions.sdk.ces.v1._proxy.Proxy + :noindex: + :members: metrics, quotas, event_data diff --git a/doc/source/sdk/proxies/cts.rst b/doc/source/sdk/proxies/cts.rst index 7148a9ca2..77a70f6e7 100644 --- a/doc/source/sdk/proxies/cts.rst +++ b/doc/source/sdk/proxies/cts.rst @@ -3,8 +3,8 @@ CTS API .. automodule:: otcextensions.sdk.cts.v1._proxy -The Distributed Message Service Class -------------------------------------- +The Cloud Trace Service Class +----------------------------- The CTS high-level interface is available through the ``cts`` member of a :class:`~openstack.connection.Connection` object. The diff --git a/doc/source/sdk/proxies/index.rst b/doc/source/sdk/proxies/index.rst index 6d3c27ed8..65ad58c75 100644 --- a/doc/source/sdk/proxies/index.rst +++ b/doc/source/sdk/proxies/index.rst @@ -8,6 +8,7 @@ Service Proxies AutoScaling Service (AS) Cloud Container Engine v1 (CCEv1) Cloud Container Engine v2 (CCE) + Cloud Eye Service (CES) Cloud Trace Service (CTS) Distributed Cache Service (DCS) Dedicated Host Service (DeH) diff --git a/doc/source/sdk/resources/ces/index.rst b/doc/source/sdk/resources/ces/index.rst new file mode 100644 index 000000000..ddd5b338e --- /dev/null +++ b/doc/source/sdk/resources/ces/index.rst @@ -0,0 +1,11 @@ +CES Resources +============= + +.. toctree:: + :maxdepth: 1 + + v1/alarm + v1/event_data + v1/metric + v1/metric_data + v1/quota diff --git a/doc/source/sdk/resources/ces/v1/alarm.rst b/doc/source/sdk/resources/ces/v1/alarm.rst new file mode 100644 index 000000000..99d858100 --- /dev/null +++ b/doc/source/sdk/resources/ces/v1/alarm.rst @@ -0,0 +1,13 @@ +otcextensions.sdk.ces.v1.alarm +============================== + +.. automodule:: otcextensions.sdk.ces.v1.alarm + +The CES Alarm Rule Class +------------------------ + +The ``Alarm`` class inherits from +:class:`~otcextensions.sdk.sdk_resource.Resource`. + +.. autoclass:: otcextensions.sdk.ces.v1.alarm.Alarm + :members: diff --git a/doc/source/sdk/resources/ces/v1/event_data.rst b/doc/source/sdk/resources/ces/v1/event_data.rst new file mode 100644 index 000000000..d53ff12f3 --- /dev/null +++ b/doc/source/sdk/resources/ces/v1/event_data.rst @@ -0,0 +1,13 @@ +otcextensions.sdk.ces.v1.event_data +=================================== + +.. automodule:: otcextensions.sdk.ces.v1.event_data + +The CES Event Data Class +------------------------ + +The ``Event Data`` class inherits from +:class:`~otcextensions.sdk.sdk_resource.Resource`. + +.. autoclass:: otcextensions.sdk.ces.v1.event_data.EventData + :members: diff --git a/doc/source/sdk/resources/ces/v1/metric.rst b/doc/source/sdk/resources/ces/v1/metric.rst new file mode 100644 index 000000000..859d6ed28 --- /dev/null +++ b/doc/source/sdk/resources/ces/v1/metric.rst @@ -0,0 +1,13 @@ +otcextensions.sdk.ces.v1.metric +=============================== + +.. automodule:: otcextensions.sdk.ces.v1.metric + +The CES Metric Class +-------------------- + +The ``Metric`` class inherits from +:class:`~otcextensions.sdk.sdk_resource.Resource`. + +.. autoclass:: otcextensions.sdk.ces.v1.metric.Metric + :members: diff --git a/doc/source/sdk/resources/ces/v1/metric_data.rst b/doc/source/sdk/resources/ces/v1/metric_data.rst new file mode 100644 index 000000000..247fe19fc --- /dev/null +++ b/doc/source/sdk/resources/ces/v1/metric_data.rst @@ -0,0 +1,13 @@ +otcextensions.sdk.ces.v1.metric_data +==================================== + +.. automodule:: otcextensions.sdk.ces.v1.metric_data + +The CES Metric Data Class +------------------------- + +The ``Metric Data`` class inherits from +:class:`~otcextensions.sdk.sdk_resource.Resource`. + +.. autoclass:: otcextensions.sdk.ces.v1.metric_data.MetricData + :members: diff --git a/doc/source/sdk/resources/ces/v1/quota.rst b/doc/source/sdk/resources/ces/v1/quota.rst new file mode 100644 index 000000000..9b777988b --- /dev/null +++ b/doc/source/sdk/resources/ces/v1/quota.rst @@ -0,0 +1,13 @@ +otcextensions.sdk.ces.v1.quota +============================== + +.. automodule:: otcextensions.sdk.ces.v1.quota + +The CES Quota Class +------------------- + +The ``Quota`` class inherits from +:class:`~otcextensions.sdk.sdk_resource.Resource`. + +.. autoclass:: otcextensions.sdk.ces.v1.quota.Quota + :members: diff --git a/doc/source/sdk/resources/index.rst b/doc/source/sdk/resources/index.rst index 6a858cb05..982188c84 100644 --- a/doc/source/sdk/resources/index.rst +++ b/doc/source/sdk/resources/index.rst @@ -10,6 +10,7 @@ Open Telekom Cloud Resources Anti DDoS Service (Anti-DDoS) AutoScaling Service (AS) Cloud Container Engine (CCE) + Cloud Eye Service (CES) Cloud Trace Service (CTS) Distributed Cache Service (DCS) Dedicated Host Service (DeH) diff --git a/otcextensions/sdk/ces/v1/_proxy.py b/otcextensions/sdk/ces/v1/_proxy.py index 9b5bc565b..ab60f2e26 100644 --- a/otcextensions/sdk/ces/v1/_proxy.py +++ b/otcextensions/sdk/ces/v1/_proxy.py @@ -37,8 +37,7 @@ def get_alarm(self, alarm): """Return a single alarm :param alarm: The value can be the ID of a alarm or a - :class:`~otcextensions.sdk.ces.v1.alarm.Alarm` - instance. + :class:`~otcextensions.sdk.ces.v1.alarm.Alarm` instance. :returns: A generator of alarm objects :rtype: :class:`~otcextensions.sdk.ces.v1.alarm.Alarm` """